FhSim  3.1.0
Marine systems simulation
Loading...
Searching...
No Matches
marenv::field::ScalarField Class Referenceabstract

#include <ScalarField.h>

+ Inheritance diagram for marenv::field::ScalarField:
+ Collaboration diagram for marenv::field::ScalarField:

Public Member Functions

virtual ~ScalarField ()=default
 Virtual destructor.
 
virtual marenv::Status GetValue (double time, const double position[3], double &value) const =0
 
virtual bool IsTimeInvariant () const
 
virtual bool IsThreadSafe () const
 
virtual void GetValues (double time, std::span< const std::array< double, 3 > > positions, std::span< double > values, std::span< marenv::Status > statuses) const
 
const std::string & Name () const
 
Quantity GetQuantity () const
 
const std::string & Unit () const
 
const std::vector< Property > & Properties () const
 
bool Has (const std::string &key) const
 
double Get (const std::string &key, double fallback=0.0) const
 
const std::string & Species () const
 
void SetSpecies (std::string species)
 

Protected Member Functions

 ScalarField (std::string name, Quantity quantity, std::string unit, std::vector< Property > properties)
 

Detailed Description

A named scalar quantity varying over space and time.

Implementations return a single value at a position in the NED frame (x North, y East, z Down) at a simulation time. One instance models one quantity: a temperature profile, a salinity profile, or the concentration of a single species. Each instance carries its own name, an advisory Quantity tag, a unit string and a set of static properties, so the same class serves every quantity and no per-quantity subclass is needed.

This class deliberately computes no derived physics. In particular, a species concentration field does not compute an acoustic signature: it reports how much of the species is present and what its static properties are, leaving the frequency-dependent backscatter to the observer that needs it.

Nor does it offer a gradient or any other derivative, by design. A consumer that needs a spatial sensitivity finite-differences GetValue itself.

Note
Implementations are not required to be thread-safe. A field that is safe for concurrent GetValue calls declares it by overriding IsThreadSafe.
GetValue must be side-effect free. It is reached from a const OdeFcn and is therefore evaluated at rejected integrator trial states as well as at accepted ones, so a field that cached or mutated anything per call would make its results depend on the step sequence.
Registered temperature and salinity fields do not affect marenv::EnvironmentFacade::GetDensity, which keeps returning marenv::seawaterDensity.
See also
fhsim_environment EnvironmentProvider (the registry of scalar fields)

Constructor & Destructor Documentation

◆ ScalarField()

marenv::field::ScalarField::ScalarField ( std::string  name,
Quantity  quantity,
std::string  unit,
std::vector< Property >  properties 
)
protected

Constructs the shared identity and metadata of a scalar field.

Parameters
[in]nameUnique field name. Must not be empty.
[in]quantityAdvisory tag describing what the field measures.
[in]unitUnit of the values returned by GetValue. May be empty.
[in]propertiesStatic properties. Keys must be unique and non-empty.
Exceptions
std::invalid_argumentif name is empty, or if a property key is empty or repeated.

Member Function Documentation

◆ Get()

double marenv::field::ScalarField::Get ( const std::string &  key,
double  fallback = 0.0 
) const

Returns a property value, or a fallback when the key is absent.

Parameters
[in]keyProperty key to look for.
[in]fallbackValue returned when the key is absent.
Returns
The property value, or fallback.

◆ GetQuantity()

Quantity marenv::field::ScalarField::GetQuantity ( ) const
inline

The advisory tag describing what this field measures.

Returns
The quantity tag.

◆ GetValue()

virtual marenv::Status marenv::field::ScalarField::GetValue ( double  time,
const double  position[3],
double &  value 
) const
pure virtual

Returns the scalar value at a given position and time.

Parameters
[in]timeSimulation time [s].
[in]positionPosition in the NED frame [x, y, z] [m].
[out]valueThe value at the given time and position.
Returns
marenv::Status::OK on success, or marenv::Status::OUT_OF_RANGE_INACCURATE when the position lay outside the field's domain and the returned value was clamped to the domain edge, or (a ParametricScalarField with mask_below_seabed) lay below the seabed and the value is 0. A status that is not usable (marenv::IsUsable), such as marenv::Status::ERROR_NOT_SET from a bathymetry without a depth there, comes with the value 0 (ENV-0061), and so does a depth profile at a NaN depth (marenv::Status::ERROR_NOT_SET, W-30). See marenv::Status for other values.

Implemented in util::EnvironmentQuantityField, marenv::field::ConstantScalarField, marenv::field::DepthLayeredScalarField, and marenv::field::ParametricScalarField.

◆ GetValues()

virtual void marenv::field::ScalarField::GetValues ( double  time,
std::span< const std::array< double, 3 > >  positions,
std::span< double >  values,
std::span< marenv::Status >  statuses 
) const
virtual

Returns the values at many points at one time: GetValue() at each.

Parameters
[in]timeSimulation time [s].
[in]positionsPositions in the NED frame [m].
[out]valuesOne value per position; as many as positions.
[out]statusesOne status per position; as many as positions.

The default calls GetValue() at each point. A field that samples a row more cheaply overrides it, as util::EnvironmentQuantityField does (each wake field is loaded once per call instead of once per point); util::BakeScalarField samples its grid row by row.

◆ Has()

bool marenv::field::ScalarField::Has ( const std::string &  key) const

Returns true if the given property key is present.

Parameters
[in]keyProperty key to look for.
Returns
True when a property with that key exists.

◆ IsThreadSafe()

virtual bool marenv::field::ScalarField::IsThreadSafe ( ) const
inlinevirtual

True when GetValue may be called concurrently from several threads.

Defaults to false, so the class-level note that implementations need not be thread-safe stays true for every field that does not opt in. A field delegating to a marenv::seafloor::BathymetryField may only return true when that bathymetry is itself safe for concurrent GetDepth calls, which BathymetryField.h does not guarantee.

Returns
True when concurrent GetValue calls are safe.

Reimplemented in util::EnvironmentQuantityField, marenv::field::ConstantScalarField, marenv::field::DepthLayeredScalarField, and marenv::field::ParametricScalarField.

◆ IsTimeInvariant()

virtual bool marenv::field::ScalarField::IsTimeInvariant ( ) const
inlinevirtual

True when the field's value at a given position never changes with time.

A caller may evaluate a time-invariant field once and reuse the result for the whole simulation. Defaults to false, so a field that does vary with time needs no change.

Returns
True when GetValue ignores its time argument.

Reimplemented in marenv::field::ConstantScalarField, marenv::field::DepthLayeredScalarField, and marenv::field::ParametricScalarField.

◆ Name()

const std::string & marenv::field::ScalarField::Name ( ) const
inline

The field's unique name, which is also its identifier in the registry.

Returns
The field name.

◆ Properties()

const std::vector< Property > & marenv::field::ScalarField::Properties ( ) const
inline

All static properties of this field, in the order they were declared.

Returns
The properties.

◆ SetSpecies()

void marenv::field::ScalarField::SetSpecies ( std::string  species)
inline

Names the species this field holds (parameter ScalarField.<Name>.Species); call before registering the field.

Parameters
[in]speciesThe species key, e.g. "mackerel". May be empty.

◆ Species()

const std::string & marenv::field::ScalarField::Species ( ) const
inline

The species this field holds, a key of the echosounder's Parameter library such as "herring".

Returns
The species key; empty for a field that is not a species, or names none.

◆ Unit()

const std::string & marenv::field::ScalarField::Unit ( ) const
inline

The unit of the values returned by GetValue, e.g. "degC", "PSU" or "kg/m^3".

Returns
The unit string. Advisory only and possibly empty; nothing validates that the returned values are in this unit.

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