FhSim  3.1.0
Marine systems simulation
Loading...
Searching...
No Matches
marenv::field::ParametricScalarField Class Reference

#include <ParametricScalarField.h>

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

Public Member Functions

 ParametricScalarField (std::string name, Quantity quantity, std::string unit, ParametricFieldSpec spec, std::shared_ptr< marenv::seafloor::BathymetryField > seafloor, std::vector< Property > properties={})
 
 ~ParametricScalarField () override=default
 Default destructor.
 
marenv::Status GetValue (double time, const double position[3], double &value) const override
 
bool IsTimeInvariant () const override
 
bool IsThreadSafe () const override
 
- Public Member Functions inherited from marenv::field::ScalarField
virtual ~ScalarField ()=default
 Virtual destructor.
 
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)
 

Additional Inherited Members

- Protected Member Functions inherited from marenv::field::ScalarField
 ScalarField (std::string name, Quantity quantity, std::string unit, std::vector< Property > properties)
 

Detailed Description

A scalar field built from an analytic background plus a sum of analytic features.

Fills the gap between ConstantScalarField, which is uniform, and DepthLayeredScalarField, which varies only with depth: a ParametricScalarField varies in all three dimensions and may optionally be referenced to the seafloor, which is what a demersal species distribution needs.

The value at a position is built up in a fixed order:

  1. If ZReference::Seafloor is selected, or the below-seabed mask is on, the bottom depth d is looked up once. With ZReference::Seafloor the working vertical coordinate becomes zEff = d - z, the height above the bottom, positive up; otherwise zEff = z, the NED depth. A bathymetry status that is not usable (marenv::IsUsable, e.g. ERROR_NOT_SET) is returned as it is, with the value 0 (ENV-0061).
  2. With the mask on and z > d, that is below the seabed, the value is 0 and the status is marenv::Status::OUT_OF_RANGE_INACCURATE.
  3. The background is evaluated at zEff.
  4. Every feature's contribution at the position is added.
  5. The sum is clamped to the configured limits.
  6. The status is marenv::Status::OK, or marenv::Status::OUT_OF_RANGE_INACCURATE when the query lay outside the optional domain box or a depth profile background was clamped at its shallowest or deepest layer.

The field is analytic rather than gridded because the distributions it is meant for are static and synthetic. A sum of Gaussians expresses them exactly, is C-infinity so a derived echogram has no facet artefacts, and is reviewable as a short JSON document where a resampled grid would be a binary artefact of tens of megabytes.

Warning
With ZReference::Seafloor the configured vertical coordinates are heights above the bottom, positive up: a blob centre[2] of 5 sits 5 m above the seabed, and a background profile entry at 0 is the seabed itself. This is the single easiest thing to misread in a configuration file.
Note
GetValue is side-effect free and reads no mutable state, as ScalarField::GetValue requires: it is reached from a const OdeFcn and is evaluated at rejected integrator trial states.
See also
ConstantScalarField, DepthLayeredScalarField, and ReadParametricScalarField() of fhsim_environment, which builds one from a JSON document

Constructor & Destructor Documentation

◆ ParametricScalarField()

marenv::field::ParametricScalarField::ParametricScalarField ( std::string  name,
Quantity  quantity,
std::string  unit,
ParametricFieldSpec  spec,
std::shared_ptr< marenv::seafloor::BathymetryField >  seafloor,
std::vector< Property >  properties = {} 
)

Constructs a parametric scalar field from a validated specification.

Parameters
[in]nameUnique field name. Must not be empty.
[in]quantityAdvisory tag describing what the field measures. It also sets the default lower clamp limit.
[in]unitUnit of the field values, e.g. "degC". May be empty.
[in]specThe field configuration.
[in]seafloorBathymetry used for seafloor-relative coordinates and for the below-seabed mask. Must not be null when either is in use. The XML builder passes the Environment's bathymetry, fixed at construction (by default flat at 200 m; Bathymetry.Model = "NetCDF" for a NetCDF seabed, R124); a bathymetry set later (EnvironmentProvider::SetBathymetry) is not seen.
[in]propertiesStatic properties. Keys must be unique and non-empty.
Exceptions
std::invalid_argumentif name is empty, if a property key is empty or repeated, if a used sigma or a front width is not positive, if a depth profile background is malformed, or if the configuration needs a bathymetry field and seafloor is null.

Member Function Documentation

◆ GetValue()

marenv::Status marenv::field::ParametricScalarField::GetValue ( double  time,
const double  position[3],
double &  value 
) const
overridevirtual

Returns the field value at a position, as described in the class documentation.

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.

Implements marenv::field::ScalarField.

◆ IsThreadSafe()

bool marenv::field::ParametricScalarField::IsThreadSafe ( ) const
inlineoverridevirtual

GetValue reads only the immutable specification, plus the bathymetry when one is configured.

Returns
Always true.
Note
This is true only because the two bathymetries of the FhSim stack, NetCdfSeafloorBathymetry (fhsim_environment) and marenv::seafloor::ParametricBathymetry, hold no mutable caches and are therefore safe for concurrent GetDepth calls. An out-of-repo bathymetry injected here that does cache would make concurrent GetValue calls unsafe; marenv::seafloor::BathymetryField itself guarantees nothing.

Reimplemented from marenv::field::ScalarField.

◆ IsTimeInvariant()

bool marenv::field::ParametricScalarField::IsTimeInvariant ( ) const
inlineoverridevirtual

The specification is fixed at construction, so the value ignores time.

Returns
Always true.

Reimplemented from marenv::field::ScalarField.


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