FhSim  3.1.0
Marine systems simulation
Loading...
Searching...
No Matches
marenv::wave::TransitioningWaveField Class Reference

#include <TransitioningWaveField.h>

+ Inheritance diagram for marenv::wave::TransitioningWaveField:
+ Collaboration diagram for marenv::wave::TransitioningWaveField:

Public Member Functions

 TransitioningWaveField (std::shared_ptr< WaveField > initial)
 
void StartTransition (std::shared_ptr< WaveField > newField, double startTime, double duration)
 
std::shared_ptr< WaveField > GetCurrentField () const
 
bool IsSettled (double time) const
 
std::string SpectrumName () const override
 Returns the spectrum name of the current destination wave field.
 
std::string WaveTheoryName () const override
 Returns the wave theory name of the current destination wave field.
 
marenv::Status ComputeSurfaceElevation (double time, const double pos[2], double &elevationOut) override
 Computes surface elevation; interpolates between source and destination during a transition.
 
double MaxWaveElevation () const override
 
marenv::Status ComputeSurfaceUnitNormal (double time, const double pos[2], double unitNormalOut[3]) override
 Computes surface unit normal; interpolates component-wise and renormalises during a transition.
 
marenv::Status ComputeParticleVelocity (double time, const double pos[3], double velOut[3]) override
 Computes particle velocity; interpolates between source and destination during a transition.
 
marenv::Status ComputeParticleAcceleration (double time, const double pos[3], double accOut[3]) override
 Computes particle acceleration; interpolates between source and destination during a transition.
 
marenv::Status ComputeDynamicPressure (double time, const double pos[3], double &pressureOut) override
 Computes dynamic pressure; interpolates between source and destination during a transition.
 
marenv::Status ComputeTotalPressure (double time, const double pos[3], double &pressureOut) override
 Computes total pressure; interpolates between source and destination during a transition.
 
marenv::Status ComputePointQuery (double time, const double pos[3], double &surface_elevation, double surface_unit_normal[3], double particle_velocity[3], double particle_acceleration[3], double &pressure) override
 Computes a full point query; all outputs are interpolated during a transition.
 
InsecureDatapointers GetWaveComponents () const override
 
marenv::wave::WaveComponentData GetWaveComponentsCopy () const override
 
marenv::wave::WaveComponentData GetWaveComponentsCopy (double time, size_t maxComponents=0) const override
 
- Public Member Functions inherited from marenv::wave::WaveField
virtual ~WaveField ()=default
 

Additional Inherited Members

- Protected Member Functions inherited from marenv::wave::WaveField
 WaveField ()=default
 Constructor.
 

Detailed Description

Decorator that cross-fades between two WaveField instances in output space.

When no transition is active, all queries delegate directly to the current (destination) wave field. During a transition the decorator evaluates both the source and destination fields at the queried (time, position) and returns the linearly interpolated result:

\[ result(t) = (1 - \alpha(t)) \cdot from(t) + \alpha(t) \cdot to(t), \quad \alpha(t) = \mathrm{clamp}\!\big((t - t_0) / (t_1 - t_0),\, 0,\, 1\big) \]

Surface normals are interpolated component-wise and renormalised.

Thread safety follows the same snapshot pattern used elsewhere in the library: a TransitionSnapshot is published atomically so that in-flight Compute* calls see a consistent view while StartTransition() swaps in a new snapshot without blocking readers.

Note
The blend is of outputs, not of waves: it is not kinematically consistent (the blended elevation, velocity and acceleration do not obey the wave equations of either field while α changes). Make the transition time long compared with the wave periods (N5).
Performance: during an active transition every Compute* call evaluates both wave fields (2x cost). Outside the transition window the cost is a single shared_ptr load plus one virtual dispatch.

Constructor & Destructor Documentation

◆ TransitioningWaveField()

marenv::wave::TransitioningWaveField::TransitioningWaveField ( std::shared_ptr< WaveField >  initial)
explicit

Construct a transitioning wave field wrapping an initial wave field.

Parameters
[in]initialThe initial (current) wave field. Must not be null.
Exceptions
std::invalid_argumentif initial is null.

Member Function Documentation

◆ ComputeDynamicPressure()

marenv::Status marenv::wave::TransitioningWaveField::ComputeDynamicPressure ( double  time,
const double  pos[3],
double &  pressureOut 
)
overridevirtual

◆ ComputeParticleAcceleration()

marenv::Status marenv::wave::TransitioningWaveField::ComputeParticleAcceleration ( double  time,
const double  pos[3],
double  accOut[3] 
)
overridevirtual

◆ ComputeParticleVelocity()

marenv::Status marenv::wave::TransitioningWaveField::ComputeParticleVelocity ( double  time,
const double  pos[3],
double  velOut[3] 
)
overridevirtual

◆ ComputePointQuery()

marenv::Status marenv::wave::TransitioningWaveField::ComputePointQuery ( double  time,
const double  pos[3],
double &  surface_elevation,
double  surface_unit_normal[3],
double  particle_velocity[3],
double  particle_acceleration[3],
double &  pressure 
)
overridevirtual

◆ ComputeSurfaceElevation()

marenv::Status marenv::wave::TransitioningWaveField::ComputeSurfaceElevation ( double  time,
const double  pos[2],
double &  elevationOut 
)
overridevirtual

◆ ComputeSurfaceUnitNormal()

marenv::Status marenv::wave::TransitioningWaveField::ComputeSurfaceUnitNormal ( double  time,
const double  pos[2],
double  unitNormalOut[3] 
)
overridevirtual

◆ ComputeTotalPressure()

marenv::Status marenv::wave::TransitioningWaveField::ComputeTotalPressure ( double  time,
const double  pos[3],
double &  pressureOut 
)
overridevirtual

◆ GetCurrentField()

std::shared_ptr< WaveField > marenv::wave::TransitioningWaveField::GetCurrentField ( ) const

Returns the current destination wave field.

Returns
Never returns null: the initial field supplied to the constructor

Outside a transition this is the only active field. During a transition this is the "to" field (the target). remains the destination for the lifetime of this object.

◆ GetWaveComponents()

InsecureDatapointers marenv::wave::TransitioningWaveField::GetWaveComponents ( ) const
overridevirtual

Returns pointers into the current field's internal data.

Returns
Raw pointers into the current field's internal wave component data.
Warning
The returned pointers are only valid while the current field is unchanged. Do not use them across a call to StartTransition().

Implements marenv::wave::WaveField.

◆ GetWaveComponentsCopy() [1/2]

marenv::wave::WaveComponentData marenv::wave::TransitioningWaveField::GetWaveComponentsCopy ( ) const
overridevirtual

Returns a copy of the current destination field's wave components.

Returns
Deep copy of the wave component data; safe to hold across transitions.

Implements marenv::wave::WaveField.

◆ GetWaveComponentsCopy() [2/2]

marenv::wave::WaveComponentData marenv::wave::TransitioningWaveField::GetWaveComponentsCopy ( double  time,
size_t  maxComponents = 0 
) const
overridevirtual

Returns a copy of up to maxComponents wave components evaluated at time.

Parameters
[in]timeSimulation time [s] used to phase-shift components.
[in]maxComponentsMaximum number of components to return (0 = all).
Returns
Deep copy of the (possibly truncated) wave component data.

Reimplemented from marenv::wave::WaveField.

◆ IsSettled()

bool marenv::wave::TransitioningWaveField::IsSettled ( double  time) const

True when no blend is running or still to come at time: an immediate swap, or time >= the end of the last transition. Then every query passes straight to GetCurrentField() and the wrapper may be dropped (marenv::EnvironmentFacade::SettleSeaState).

Parameters
[in]timeSimulation time [s].

◆ MaxWaveElevation()

double marenv::wave::TransitioningWaveField::MaxWaveElevation ( ) const
overridevirtual

Upper bound of |elevation| at every position and time (owner ruling R66).

Returns
The destination field's bound without a transition; during one, the larger of the two fields' bounds, which bounds (1 − α) η_from + α η_to for every α in [0, 1].

Reimplemented from marenv::wave::WaveField.

◆ SpectrumName()

std::string marenv::wave::TransitioningWaveField::SpectrumName ( ) const
overridevirtual

◆ StartTransition()

void marenv::wave::TransitioningWaveField::StartTransition ( std::shared_ptr< WaveField >  newField,
double  startTime,
double  duration 
)

Begin a cross-fade from the current wave field to a new one.

Parameters
[in]newFieldThe target wave field. Must not be null.
[in]startTimeSimulation time at which the cross-fade begins (α = 0). Must not be NaN.
[in]durationDuration of the cross-fade in seconds. Must be >= 0.
Exceptions
std::invalid_argumentif newField is null, startTime is NaN, or duration is NaN or negative.

A duration of 0 is an immediate swap: newField is in force at once (at every query time, also before startTime), with no blend and no chain of earlier fields kept.

If a transition is already in progress at startTime, the new transition starts from the blend as it is at that time (owner ruling D19, as MENV-0010 for the wakes): the weight of the running blend is frozen at its value at startTime and the two fields go on moving, so the output is continuous across the retarget. Before the running transition starts the source is the field in force, A; after it ended, its destination. Each retarget during a transition adds one frozen blend to the chain of fields that are kept alive until the new transition ends.

◆ WaveTheoryName()

std::string marenv::wave::TransitioningWaveField::WaveTheoryName ( ) const
overridevirtual

The documentation for this class was generated from the following file: