#include <EnvironmentFacade.h>

Inheritance diagram for marenv::EnvironmentFacade:

Collaboration diagram for marenv::EnvironmentFacade:

Public Member Functions
	EnvironmentFacade ()

void	SetWaves (std::shared_ptr< wave::WaveField > wave)

void	SetWaves (const wave::WaveEnergySpectrum::SpectrumParameters &params, wave::WaveTheory waveTheory, int numWaves, uint32_t seed)

void	SetBathymetry (std::shared_ptr< seafloor::BathymetryField > bathymetry)

std::shared_ptr< wave::WaveField >	GetWaves ()

double	MaxWaveElevation () const

std::shared_ptr< seafloor::BathymetryField >	GetBathymetry ()

void	AddCurrentField (const std::string &id, std::shared_ptr< current::CurrentField > field)

void	RemoveCurrentField (const std::string &id)

bool	HasCurrentField (const std::string &id) const

std::shared_ptr< current::CurrentField >	GetCurrentField (const std::string &id) const

void	AddWakeField (const std::string &id, std::shared_ptr< wake::WakeField > field)

void	RemoveWakeField (const std::string &id)

bool	HasWakeField (const std::string &id) const

std::shared_ptr< wake::WakeField >	GetWakeField (const std::string &id) const

std::vector< std::string >	GetWakeFieldIds () const

std::vector< std::string >	GetCurrentFieldIds () const

Status	GetSubmergence (double time, const double pos[3], double &submergence) override

Status	GetSurfaceElevation (double time, const double pos[2], double &elevationOut) override

Status	GetSurfaceUnitNormal (double time, const double pos[2], double *unitNormalOut) override

Status	GetParticleVelocity (double time, const double pos[3], double *velOut) override

Status	GetParticleAcceleration (double time, const double pos[3], double *accOut) override

Status	GetDynamicPressure (double time, const double pos[3], double &pressureOut) override

Status	GetTotalPressure (double time, const double pos[3], double &pressureOut) override

Status	GetSeaDepth (const double pos[2], double &depthOut) override

Status	ComputeRayIntersection (const double origin[3], const double direction[3], double &distanceOut, double maxSearchDistance=100, double startSearchDistance=-1, double stepSize=1.0, double convergenceTolerance=0.01) override

Status	GetCurrentVelocity (double time, const double pos[3], double *velOut) override

Status	GetDensity (double time, const double pos[3], double &density) override

Status	PointEnvironmentQuery (double time, const double pos[3], EnvironmentQuery &queryResult) override

Status	GetWakedFlow (double time, const double pos[3], WakedFlow &out) const

Status	GetWakedFlow (double time, const double pos[3], const wake::WakeQuery &query, WakedFlow &out) const

std::vector< std::shared_ptr< const wake::WakeField > >	SelectReachingWakeFields (const wake::WakeQueryRegion &region, const wake::WakeField *exclude=nullptr) const

Public Member Functions inherited from marenv::Environment
virtual	~Environment ()=0
	Virtual destructor.

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

virtual Status	GetParticleVelocity (double time, const double pos[3], double velOut[3])=0

virtual Status	GetParticleAcceleration (double time, const double pos[3], double accOut[3])=0

virtual Status	GetCurrentVelocity (double time, const double pos[3], double velOut[3])=0

Protected Member Functions
Status	ComputeTotalCurrent (double time, const double pos[3], double vel[3]) const

Protected Member Functions inherited from marenv::Environment
	Environment ()=default
	The constructor is protected.

Protected Attributes
std::shared_ptr< wave::WaveField >	m_waves
	Wave field model providing wave-induced quantities.

std::unordered_map< std::string, std::shared_ptr< current::CurrentField > >	m_currentFields
	Registry of current fields indexed by unique identifier; velocities are summed for the total current.

std::shared_ptr< seafloor::BathymetryField >	m_depths
	Bathymetry field model providing seafloor geometry and properties.

wake::WakeRegistry	m_wakes
	The registered wake fields in registration order (MENV-0035: the composition order is the same on every platform), and their composition.

Detailed Description

Defines an environment.

Some methods are at the moment simple stubs.

Constructor & Destructor Documentation

◆ EnvironmentFacade()

marenv::EnvironmentFacade::EnvironmentFacade ( )

inline

Default constructor. Initialises with null/default field implementations:

NullWaveField (no waves), FlatSeafloor (200 m flat bottom). No current fields are registered by default.

Member Function Documentation

◆ AddCurrentField()

void marenv::EnvironmentFacade::AddCurrentField	(	const std::string &	id,
		std::shared_ptr< current::CurrentField >	field
	)

Adds a current field with the given identifier. The velocities of all registered current

Parameters

[in]	id	Unique identifier for this current field.
[in]	field	The current field to add.

fields are summed to produce the total ambient current.

Exceptions

std::invalid_argument if a current field with the given id already exists.

◆ AddWakeField()

void marenv::EnvironmentFacade::AddWakeField	(	const std::string &	id,
		std::shared_ptr< wake::WakeField >	field
	)

Adds a wake field with the given identifier.

Parameters

[in]	id	Unique identifier for this wake field.
[in]	field	The wake field to add.

Exceptions

std::invalid_argument if a wake field with the given id already exists.

◆ ComputeRayIntersection()

Status marenv::EnvironmentFacade::ComputeRayIntersection	(	const double	origin[3],
		const double	direction[3],
		double &	distanceOut,
		double	maxSearchDistance = `100`,
		double	startSearchDistance = `-1`,
		double	stepSize = `1.0`,
		double	convergenceTolerance = `0.01`
	)

overridevirtual

Returns the distance a ray must travel before intercepting the seafloor: the first crossing along the ray (owner ruling R132; see seafloor::BathymetryField::ComputeRayIntersection). An origin at the seafloor or inside it is a hit at distance 0 (owner ruling R133).

Parameters

[in]	origin	Position (x,y,z) of the origin of the ray
[in]	direction	The unit direction (x,y,z) of the ray
[out]	distanceOut	The distance the beam travelled before reaching the seabed; -1 without an intersection.
[in]	maxSearchDistance	The maximum distance from the origin to search for an intersection.
[in]	startSearchDistance	The distance that anchors the search grid; negative for the flat-seabed estimate. It does not move the result away from the first crossing.
[in]	stepSize	The search step size.
[in]	convergenceTolerance	The vertical error tolerance between a computed point on the ray and a point on the seafloor to consider an intersection found.

Returns: marenv::Status::OK on success; marenv::Status::NOT_APPLICABLE_NOT_SET when the ray does not cross the seafloor within maxSearchDistance (owner ruling R134); marenv::Status::ERROR_NOT_SET for an invalid direction or range, or without a seafloor.

Implements marenv::Environment.

◆ ComputeTotalCurrent()

Status marenv::EnvironmentFacade::ComputeTotalCurrent	(	double	time,
		const double	pos[3],
		double	vel[3]
	)		const

protected

Sums the velocities of the current fields whose status at pos is usable (IsUsable(): OK or OUT_OF_RANGE_INACCURATE, R122) into vel[3].

Returns: The first status that is not usable, else OUT_OF_RANGE_INACCURATE if a field returned it, else OK.

◆ GetBathymetry()

std::shared_ptr< seafloor::BathymetryField > marenv::EnvironmentFacade::GetBathymetry ( )

Gets the bathymetry to be used.

Returns: Bathymetry to be used.

◆ GetCurrentField()

std::shared_ptr< current::CurrentField > marenv::EnvironmentFacade::GetCurrentField ( const std::string & id ) const

Returns the current field with the given identifier.

Parameters

[in] id Identifier of the current field.

Returns: Shared pointer to the current field.

Exceptions

std::invalid_argument if the identifier does not exist.

◆ GetCurrentFieldIds()

std::vector< std::string > marenv::EnvironmentFacade::GetCurrentFieldIds ( ) const

Returns a list of all registered current field identifiers.

Returns: Vector of identifiers.

◆ GetCurrentVelocity()

Status marenv::EnvironmentFacade::GetCurrentVelocity	(	double	time,
		const double	pos[3],
		double *	velOut
	)

override

Returns the water current velocity at a specific position.

Parameters

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

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

Includes effects of only currents, not waves, modified by any registered wake fields (composition in EnvironmentFacade).

The wake composition is u = u_amb + d_tot (u_s - u_amb) (see GetWakedFlow()). It runs also when no current field is registered: then u_amb = 0 and a moving wake source gives u = d_tot u_s. u_amb is the sum of the current fields whose status at pos is usable (IsUsable(): Status::OK, or Status::OUT_OF_RANGE_INACCURATE for a value clamped at the edge of a depth profile, owner ruling R122); the first status of a current field that is not usable is returned, else Status::OUT_OF_RANGE_INACCURATE if a field returned it (MENV-0013, MENV-0053).

◆ GetDensity()

Status marenv::EnvironmentFacade::GetDensity	(	double	time,
		const double	pos[3],
		double &	density
	)

overridevirtual

Returns the water density at a specific position

Parameters

[in]	time	Current simulation time.
[in]	pos	Position (x,y,z) for which the water current velocity producer is desired.
[out]	density	The water density at given position and time.

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

Implements marenv::Environment.

◆ GetDynamicPressure()

Status marenv::EnvironmentFacade::GetDynamicPressure	(	double	time,
		const double	pos[3],
		double &	pressureOut
	)

overridevirtual

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.

Implements marenv::Environment.

◆ GetParticleAcceleration()

Status marenv::EnvironmentFacade::GetParticleAcceleration	(	double	time,
		const double	pos[3],
		double *	accOut
	)

override

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.

Includes effects of both current and waves.

◆ GetParticleVelocity()

Status marenv::EnvironmentFacade::GetParticleVelocity	(	double	time,
		const double	pos[3],
		double *	velOut
	)

override

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.

Includes effects of both current and waves. The current part is modified by any registered wake fields (composition in EnvironmentFacade), as in GetCurrentVelocity.

The current part is the ambient current with the wake composition applied (see GetWakedFlow()); the wave particle velocity is not waked. Equals GetWakedFlow().waked.

◆ GetSeaDepth()

Status marenv::EnvironmentFacade::GetSeaDepth	(	const double	pos[2],
		double &	depthOut
	)

overridevirtual

Returns the sea depth at a specific position.

Parameters

[in]	pos	Position (x,y) for which sea depth is desired.
[out]	depthOut	The sea depth at pos.

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

Implements marenv::Environment.

◆ GetSubmergence()

Status marenv::EnvironmentFacade::GetSubmergence	(	double	time,
		const double	pos[3],
		double &	submergence
	)

overridevirtual

Calculates the submergence of a specific position.

Parameters

[in]	time	Time
[in]	pos	Position
[out]	submergence	The submergence of the position

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

Implements marenv::Environment.

◆ GetSurfaceElevation()

Status marenv::EnvironmentFacade::GetSurfaceElevation	(	double	time,
		const double	pos[2],
		double &	elevationOut
	)

overridevirtual

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.

Implements marenv::Environment.

◆ GetSurfaceUnitNormal()

Status marenv::EnvironmentFacade::GetSurfaceUnitNormal	(	double	time,
		const double	pos[2],
		double *	unitNormalOut
	)

override

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.

◆ GetTotalPressure()

Status marenv::EnvironmentFacade::GetTotalPressure	(	double	time,
		const double	pos[3],
		double &	pressureOut
	)

overridevirtual

Returns the total 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.

Includes both dynamic and static pressure.

Implements marenv::Environment.

◆ GetWakedFlow() [1/2]

Status marenv::EnvironmentFacade::GetWakedFlow	(	double	time,
		const double	pos[3],
		const wake::WakeQuery &	query,
		WakedFlow &	out
	)		const

Returns the ambient and the waked flow at a point, with one field excluded and one added (contract C5).

Parameters

[in]	time	Simulation time, s.
[in]	pos	Position (x,y,z) to query, m, NED.
[in]	query	The registered field to skip and the unregistered field to add.
[out]	out	Ambient velocity, waked velocity, combined deficit and source count.

Returns: marenv::Status::OK on success.

As GetWakedFlow(time, pos, out), except that the registered field query.exclude is not sampled and the field query.own is sampled after the registered ones and multiplied onto their composition D, d_tot = 1 - (1 - D) (1 - d_own) (R88, R95): the own field is a net's private per-panel field, whose sources are normalised by their local, already shaded inflow (doc/wake.md section 4). out.deficit and out.numSources include it. query.own must not be registered, or it counts twice. GetWakedFlow(time, pos, out) and GetParticleVelocity() equal this call with WakeQuery{}.

◆ GetWakedFlow() [2/2]

Status marenv::EnvironmentFacade::GetWakedFlow	(	double	time,
		const double	pos[3],
		WakedFlow &	out
	)		const

Returns the ambient and the waked flow at a point (contract C5).

Parameters

[in]	time	Simulation time, s.
[in]	pos	Position (x,y,z) to query, m, NED.
[out]	out	Ambient velocity, waked velocity, combined deficit and source count.

Returns: marenv::Status::OK on success; else the wave status if it is not OK, else the current status as GetCurrentVelocity() (a clamped depth profile gives Status::OUT_OF_RANGE_INACCURATE and is summed, a failing current field is skipped).

Every registered wake field is sampled at pos. A field that returns a status other than Status::OK (Status::ERROR_NOT_SET outside the field) contributes nothing; a returned deficit is clamped to [0, 1], and a NaN deficit contributes nothing. The fields compose by the momentum-flux rule, d_tot (1 - d_tot) = sum d_i (1 - d_i) where that has a root below the branch deficit, else the capped linear sum or 1/2 (owner ruling R95, replacing R88's min(1, sum d_i); wake::MomentumFluxSum), with the source velocity u_s the deficit-weighted mean of the u_s,i, and the waked current is u = u_amb + d_tot (u_s - u_amb).

out.waked equals GetParticleVelocity(). The wake composition runs whether or not a current field is registered; with none, the ambient current is zero.

◆ GetWakeField()

std::shared_ptr< wake::WakeField > marenv::EnvironmentFacade::GetWakeField ( const std::string & id ) const

Returns the wake field with the given identifier.

Parameters

[in] id Identifier of the wake field.

Returns: Shared pointer to the wake field.

Exceptions

std::invalid_argument if the identifier does not exist.

◆ GetWakeFieldIds()

std::vector< std::string > marenv::EnvironmentFacade::GetWakeFieldIds ( ) const

Returns a list of all registered wake field identifiers.

Returns: Vector of identifiers, in registration order.

◆ GetWaves()

std::shared_ptr< wave::WaveField > marenv::EnvironmentFacade::GetWaves ( )

Gets the wave to be used.

Returns: Wave to be used.

◆ HasCurrentField()

bool marenv::EnvironmentFacade::HasCurrentField ( const std::string & id ) const

Returns true if a current field with the given identifier exists.

Parameters

[in] id Identifier to check.

◆ HasWakeField()

bool marenv::EnvironmentFacade::HasWakeField ( const std::string & id ) const

Returns true if a wake field with the given identifier exists.

Parameters

[in] id Identifier to check.

◆ MaxWaveElevation()

double marenv::EnvironmentFacade::MaxWaveElevation ( ) const

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

Returns: wave::WaveField::MaxWaveElevation() of the wave field set now, 0 without one.

A point at depth z > MaxWaveElevation() + h, h the half-size of a body around it, is submerged whatever the waves (GetSubmergence() > h), so a caller can skip the wave elevation there. The bound holds for the waves set and published at the call; SetWaves() or a blend of the wave components voids it.

0 means no waves: no wave elevation, particle velocity or particle acceleration anywhere (MENV-0064), so GetWaves()->ComputeParticleVelocity() and ComputeParticleAcceleration() need not be called.

◆ PointEnvironmentQuery()

Status marenv::EnvironmentFacade::PointEnvironmentQuery	(	double	time,
		const double	pos[3],
		EnvironmentQuery &	queryResult
	)

overridevirtual

Calculates multiple properties of the environment in one call.

Parameters

[in]	time	Simulation time.
[in]	pos	Position.
[out]	queryResult	The result of the query.

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

With a wave field set (the default is a NullWaveField), current_velocity is the waked current, as GetCurrentVelocity(), particle_velocity is the wave particle velocity plus the waked current, as GetParticleVelocity(), and the status is that of GetCurrentVelocity(). Without a wave field (SetWaves() with a null pointer) every member keeps its default (EnvironmentQuery::SetZero(): no current and no wave velocity, whatever the current fields) and the status is Status::ERROR_NOT_SET; use GetCurrentVelocity() or GetWakedFlow() for the current then (MENV-0054).

Implements marenv::Environment.

◆ RemoveCurrentField()

void marenv::EnvironmentFacade::RemoveCurrentField ( const std::string & id )

Removes the current field with the given identifier.

Parameters

[in] id Identifier of the current field to remove.

Exceptions

std::invalid_argument if no current field with the given id exists.

◆ RemoveWakeField()

void marenv::EnvironmentFacade::RemoveWakeField ( const std::string & id )

Removes the wake field with the given identifier.

Parameters

[in] id Identifier of the wake field to remove.

Exceptions

std::invalid_argument if no wake field with the given id exists.

◆ SelectReachingWakeFields()

std::vector< std::shared_ptr< const wake::WakeField > > marenv::EnvironmentFacade::SelectReachingWakeFields	(	const wake::WakeQueryRegion &	region,
		const wake::WakeField *	exclude = `nullptr`
	)		const

Returns the registered wake fields that may reach a region, read-only (owner decision R47, MENV-0058).

See wake::WakeRegistry::SelectReaching(). A structure calls it once per step and composes the fields, sampled at its points, with a wake::WakeAccumulator.

◆ SetBathymetry()

void marenv::EnvironmentFacade::SetBathymetry ( std::shared_ptr< seafloor::BathymetryField > bathymetry )

Sets the bathymetry to be used.

Parameters

[in] bathymetry Bathymetry to be used.

◆ SetWaves() [1/2]

void marenv::EnvironmentFacade::SetWaves	(	const wave::WaveEnergySpectrum::SpectrumParameters &	params,
		wave::WaveTheory	waveTheory,
		int	numWaves,
		uint32_t	seed
	)

Creates the wave model based on spectrum parameters. Automatically selects between scalar and simd implementations for Airy waves.

Parameters

[in]	params	The spectrum parameters.
[in]	waveTheory	The wave theory to use.
[in]	numWaves	The number of waves to create.
[in]	seed	The random seed to use.

◆ SetWaves() [2/2]

void marenv::EnvironmentFacade::SetWaves ( std::shared_ptr< wave::WaveField > wave )

Sets the wave to be used.

Parameters

[in] wave Wave to be used.

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

webfhsim/reloadrepos/marenv/include/marenv/EnvironmentFacade.h

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ EnvironmentFacade()

Member Function Documentation

◆ AddCurrentField()

◆ AddWakeField()

◆ ComputeRayIntersection()

◆ ComputeTotalCurrent()

◆ GetBathymetry()

◆ GetCurrentField()

◆ GetCurrentFieldIds()

◆ GetCurrentVelocity()

◆ GetDensity()

◆ GetDynamicPressure()

◆ GetParticleAcceleration()

◆ GetParticleVelocity()

◆ GetSeaDepth()

◆ GetSubmergence()

◆ GetSurfaceElevation()

◆ GetSurfaceUnitNormal()

◆ GetTotalPressure()

◆ GetWakedFlow() [1/2]

◆ GetWakedFlow() [2/2]

◆ GetWakeField()

◆ GetWakeFieldIds()

◆ GetWaves()

◆ HasCurrentField()

◆ HasWakeField()

◆ MaxWaveElevation()

◆ PointEnvironmentQuery()

◆ RemoveCurrentField()

◆ RemoveWakeField()

◆ SelectReachingWakeFields()

◆ SetBathymetry()

◆ SetWaves() [1/2]

◆ SetWaves() [2/2]