#include <WaveField.h>

Inheritance diagram for marenv::wave::WaveField:

Collaboration diagram for marenv::wave::WaveField:

Classes
struct	InsecureDatapointers
	Pointers to wave component details. More...

Public Member Functions
virtual	~WaveField ()=default

virtual std::string	SpectrumName () const =0

virtual std::string	WaveTheoryName () const =0

virtual marenv::Status	ComputeSurfaceElevation (double time, const double pos[2], double &elevationOut)=0

virtual marenv::Status	ComputeDynamicPressure (double time, const double pos[3], double &pressureOut)=0

virtual marenv::Status	ComputeTotalPressure (double time, const double pos[3], double &pressureOut)=0

virtual marenv::Status	ComputeSurfaceUnitNormal (double time, const double pos[2], double unitNormalOut[3])=0

virtual marenv::Status	ComputeParticleVelocity (double time, const double pos[3], double velOut[3])=0

virtual marenv::Status	ComputeParticleAcceleration (double time, const double pos[3], double accOut[3])=0

virtual 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)=0

virtual InsecureDatapointers	GetWaveComponents () const =0

virtual marenv::wave::WaveComponentData	GetWaveComponentsCopy () const =0

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

virtual double	MaxWaveElevation () const

Protected Member Functions
	WaveField ()=default
	Constructor.

Detailed Description

The interface for a field representing waves.

The linear wave classes (AiryWavesScalar, AiryWavesSimd, GerstnerWaves) use deep-water dispersion and decay (k = omega^2/g, e^{-kz}); they are valid for kh > pi (h the depth). Finite-depth waves are not implemented (MENV issue filed). Every Compute* query returns marenv::Status::ERROR_NOT_SET, with zero outputs, for a non-finite time or position (MENV-0092).

Constructor & Destructor Documentation

◆ ~WaveField()

virtual marenv::wave::WaveField::~WaveField ( )

virtualdefault

Virtual destructor.

Threading contract, for every implementation: the Compute* queries may be called from several threads at once (a visualiser sampling in parallel while the simulation waits), so they must not change the field's state; they are non-const for historical reasons only. EnvironmentFacade::SetWaves() happens during setup.

Member Function Documentation

◆ ComputeDynamicPressure()

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

pure virtual

Returns the dynamic pressure at a specific position.

Parameters

[in]	time	Current simulation time.
[in]	pos	Position (x,y,z) for which the pressure is desired.
[out]	pressureOut	The pressure at pos.

Returns: marenv::Status::OK on success. See marenv::Status for other values.

Implemented in marenv::wave::AiryWavesScalar, marenv::wave::GerstnerWaves, and marenv::wave::NullWaveField.

◆ ComputeParticleAcceleration()

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

pure virtual

Returns the particle acceleration at a specific position.

Parameters

[in]	time	Current simulation time.
[in]	pos	Position (x,y,z) for which the particle acceleration is desired.
[out]	accOut	The particle acceleration at pos.

Returns: marenv::Status::OK on success. See marenv::Status for other values.

The wave particle acceleration only; a current is not included.

Implemented in marenv::wave::AiryWavesScalar, marenv::wave::GerstnerWaves, and marenv::wave::NullWaveField.

◆ ComputeParticleVelocity()

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

pure virtual

Returns the particle velocity at a specific position.

Parameters

[in]	time	Current simulation time.
[in]	pos	Position (x,y,z) for which the particle velocity is desired.
[out]	velOut	The particle velocity at pos.

Returns: marenv::Status::OK on success. See marenv::Status for other values.

The wave particle velocity only; a current is not included (EnvironmentFacade adds it).

Implemented in marenv::wave::AiryWavesScalar, marenv::wave::GerstnerWaves, and marenv::wave::NullWaveField.

◆ ComputePointQuery()

virtual marenv::Status marenv::wave::WaveField::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
	)

pure virtual

Calculates multiple properties of the environment in one call.

Parameters

[in]	time	Simulation time.
[in]	pos	Position.
[out]	surface_elevation	The surface elevation above this point.
[out]	surface_unit_normal	The surface unit normal above this point.
[out]	particle_velocity	The particle velocity in this point.
[out]	particle_acceleration	The particle acceleration in this point.
[out]	pressure	The pressure. The pressure in this point.

Returns: marenv::Status::OK on success. See marenv::Status for other values.

Implemented in marenv::wave::AiryWavesScalar, marenv::wave::GerstnerWaves, and marenv::wave::NullWaveField.

◆ ComputeSurfaceElevation()

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

pure virtual

Returns the surface elevation at a specific position.

Parameters

[in]	time	Current simulation time.
[in]	pos	Position (x,y) for which surface elevation is desired.
[out]	elevationOut	Surface elevation at pos.

Returns: marenv::Status::OK on success. See marenv::Status for other values.

Implemented in marenv::wave::AiryWavesScalar, marenv::wave::GerstnerWaves, and marenv::wave::NullWaveField.

◆ ComputeSurfaceUnitNormal()

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

pure virtual

Returns the unit normal vector of the surface at a specific position.

Parameters

[in]	time	Current simulation time.
[in]	pos	Position (x,y) for which the unit normal surface vector is desired.
[out]	unitNormalOut	The unit normal surface vector at pos.

Returns: marenv::Status::OK on success. See marenv::Status for other values.

Implemented in marenv::wave::AiryWavesScalar, marenv::wave::GerstnerWaves, and marenv::wave::NullWaveField.

◆ ComputeTotalPressure()

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

pure virtual

Returns the total (gauge) pressure at a specific position.

Parameters

[in]	time	Current simulation time.
[in]	pos	Position (x,y,z) for which the pressure is desired.
[out]	pressureOut	The pressure at pos, relative to the atmosphere.

Returns: marenv::Status::OK on success. See marenv::Status for other values.

Owner ruling D8: the total pressure is rho g z + the dynamic pressure of ComputeDynamicPressure() (z positive down), and 0 for a point above the free surface. The dynamic pressure already holds the free-surface elevation, so the elevation is not added again.

Implemented in marenv::wave::AiryWavesScalar, marenv::wave::GerstnerWaves, and marenv::wave::NullWaveField.

◆ GetWaveComponents()

virtual InsecureDatapointers marenv::wave::WaveField::GetWaveComponents ( ) const

pure virtual

Getter for wave component pointers.

Returns: A structure with pointers to wave component data.

Their use focus on efficiency. The views live as long as the field: its component snapshot is set only in the constructor, so the pointers stay valid until the field is destroyed. Do not use them after that.

Implemented in marenv::wave::LinearWaveTheory, and marenv::wave::NullWaveField.

◆ GetWaveComponentsCopy() [1/2]

virtual marenv::wave::WaveComponentData marenv::wave::WaveField::GetWaveComponentsCopy ( ) const

pure virtual

Getter for a copy of wave component specifications.

Returns: A structure with wave component data.

Implemented in marenv::wave::LinearWaveTheory, and marenv::wave::NullWaveField.

◆ GetWaveComponentsCopy() [2/2]

virtual marenv::wave::WaveComponentData marenv::wave::WaveField::GetWaveComponentsCopy	(	double	time,
		size_t	maxComponents = `0`
	)		const

virtual

Getter for a copy of wave component specifications at a given time.

Parameters

[in]	time	Simulation time used to evaluate the interpolation factor.
[in]	maxComponents	Maximum number of components to return (0 = all).

Returns: A structure with wave component data.

During a transition this may return the merged components from both source and destination fields with amplitudes scaled by the interpolation factor. The default implementation ignores time: it takes the components of the time-independent overload and returns them sorted by descending amplitude (a signed zetaA, with std::sort or std::partial_sort, so components of equal amplitude come in an unspecified order). When limited, the components with the largest amplitudes are kept.

◆ MaxWaveElevation()

virtual double marenv::wave::WaveField::MaxWaveElevation ( ) const

virtual

Returns an upper bound of |elevation| at every position and time (owner ruling R66).

Returns: B >= |eta(t, x, y)| for the wave components published by the field, which never changes them. A point at depth z > B + h (NED, z down), with h the half-size of a body around it, is submerged whatever the waves, so its wave elevation need not be evaluated.

The linear theories (AiryWavesScalar, AiryWavesSimd, GerstnerWaves) return the sum of the component amplitudes |zeta_A|, with a relative margin of 1e-10 for rounding; the Gerstner surface is the same sum at the Lagrangian point. NullWaveField returns 0. The default, for a wave field that cannot tell (an imported or gridded surface), is +infinity, which never skips an evaluation. Cheap: one pass over the components.

0 means no waves: no elevation, particle velocity or particle acceleration anywhere, so a caller may skip evaluating them (MENV-0064). A wave field that returns 0 must give zero for all three.

Reimplemented in marenv::wave::LinearWaveTheory, and marenv::wave::NullWaveField.

◆ SpectrumName()

virtual std::string marenv::wave::WaveField::SpectrumName ( ) const

pure virtual

Getter for the name of the wave spectrum used for the realisation of the waves.

Returns: Ittc or Jonswap.

Implemented in marenv::wave::LinearWaveTheory, and marenv::wave::NullWaveField.

◆ WaveTheoryName()

virtual std::string marenv::wave::WaveField::WaveTheoryName ( ) const

pure virtual

Getter for the name of the wave theory used for the realisation of the waves.

Returns: Airy or Gerstner.

Implemented in marenv::wave::LinearWaveTheory, and marenv::wave::NullWaveField.

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

webfhsim/reloadrepos/marenv/include/marenv/wave/WaveField.h

Classes

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~WaveField()

Member Function Documentation

◆ ComputeDynamicPressure()

◆ ComputeParticleAcceleration()

◆ ComputeParticleVelocity()

◆ ComputePointQuery()

◆ ComputeSurfaceElevation()

◆ ComputeSurfaceUnitNormal()

◆ ComputeTotalPressure()

◆ GetWaveComponents()

◆ GetWaveComponentsCopy() [1/2]

◆ GetWaveComponentsCopy() [2/2]

◆ MaxWaveElevation()

◆ SpectrumName()

◆ WaveTheoryName()