Collaboration diagram for Environment:

Main environment SimObject (waves, currents, seafloor).

Constructs and owns the EnvironmentProvider resource that other SimObjects retrieve by name to query wave kinematics, wake attenuation, and seafloor forces. All physical state (wave field, bathymetry, currents) is set up from XML parameters during construction.

The implementation provides:

Spectral wave realization from established ocean wave spectra (e.g., JONSWAP, ISSC)
Component-based wave specification for full user control
Configurable wave theory (Airy or Gerstner)
Independent environment features: currents, bathymetry and seafloor interaction models

The environment simobject registers resources used by other simulation modules to query environment properties such as water particle kinematics, sea surface elevation, currents, and depths.

Simulation of a deep-sea wave environment supporting both regular and irregular seas, including short-crested and long-crested wave fields.

Note

The wave model does not include refraction, diffraction, or wave–current interaction.
The wave model assumes deep-water conditions and is invalid when water depth is less than half** the largest significant wavelength.
Only gravity-driven waves are supported; thus the model does not apply to wavelengths shorter than approx. 5 cm.

Configuration Parameters

Potential environment configuration parameters are listed below. Due to their large number, these are divided into separate sections. Examples of environment configuration files:

Main parameters

Name	Width	Description
RandomSeed	1	Random number generator seed for the probabilistic models, so that two runs of one input file give the same numbers. (Default: 1)

Visual parameters

Read only in a visual build (FH_VISUALIZATION); a headless run does not read or check them. The exception is Visual.WorldRadius, which also sets the default seabed diagnostics bounds when Bathymetry.DiagnosticsCsv is set.

Name	Width	Description
Visual.PhysicalWaves	1	Enable physical wave rendering in visualization. (Default: "True")
Visual.Quality	1	Rendering quality level. Should be an integer between 0 and 10. (Default: 10)
Visual.Sky	1	Sky rendering mode (case-insensitive). Supported: "cloudydome" ,"cloudyplane", "cloudy", "mountains", "morning" and "stormy". (Default: "cloudy")
Visual.Vertices	2	Number of vertices for ocean surface and seafloor mesh `[u, v]`, at least 2 each. (Default: 100, 130)
Visual.WorldRadius	1	World rendering radius. (Default: 1000)

Wave parameters used for both seatstate and component-based wave models

Name	Width	Description
Waves.Spectrum	1	Value of either "Components", "JONSWAP" or "ISSC". Specifies if wave components are defined by a wave component vector or a continuous spectrum. (Required when `Waves.NumWaves` is not 0)
Waves.Theory	1	Value of either "Airy" or "Gerstner" which specify the underlying wave theory used to compute wave elevation, velocities of acceleration. Mandatory when Waves.NumWaves is not 0.
Waves.NumWaves	1	Number of wave components in wave energy spectrum or specified by individual components. (Default: 1, max 52 inclusive)

Seastate spectrums (JONSWAP and ISSC)

Name	Width	Description
Waves.MeanPeriod	1	Mean period of wave spectrum [s], finite and > 0. (Default: 4)
Waves.Hs	1	Significant wave height of wave spectrum [m], finite and >= 0. (Default: 1)
Waves.MainDirectionDeg	1	Direction the sea comes from, in degrees from north towards east: 0 is a sea from the north, travelling south. (Default : 0)
Waves.OmegaNormalizedMin	1	Lower non-dimensional angular frequency limit used during spectrum discretization. Values below 0.5 are silently raised to 0.5; it must be finite. (Default: 0.5)
Waves.OmegaNormalizedMax	1	Upper non-dimensional angular frequency limit used during spectrum discretization; finite and above the lower limit (at least 0.5), otherwise setup fails. (Default: 3.0)
Waves.DirectionBinning	1	Method for distributing wave directions among components. Supported:\ "Random" — directions assigned randomly with probability proportional to the directional density. "Sequential" — componentons assigned according to the spreading spectrum and so that the smaller the amlitude, the further away from the mean direction. (Default: "Sequential").
Waves.FrequencyBinning	1	Method for sampling the frequency distribution into discrete components. Supported: "EqualEnergy" — bins chosen so each has equal energy contribution. "EqualSqrtEnergy" — bins scaled by sqrt(energy). (Default: "EqualSqrtEnergy").
Waves.DirectionCosinePower	1	Directional spreading exponent used in the directional distribution. Higher values yield narrower wave propagation around the mean direction. (Default: 2).

Wave components

Name	Width	Description
Waves.Periods	<Waves.NumWaves>	Period of each wave component [s], finite and > 0
Waves.Amplitudes	<Waves.NumWaves>	Amplitude of each wave component [m], finite and >= 0
Waves.DirectionsDeg	<Waves.NumWaves>	Direction each wave component travels to, in degrees from north towards east: 0 travels north, 90 east. (This is the opposite of `Waves.MainDirectionDeg`, which names where the sea comes from.)

Bathymetry

The seabed frame is SNAME: x = North, y = East, z = Down (depth positive downward).

Name	Width	Description
Bathymetry.Model	1	Bathymetry model type. Supported: `"SumOfSines"` (default), `"Parametric"` and `"NetCDF"`.

The bathymetry is fixed at construction: the facade (GetBathymetry, GetSeaDepth), SeafloorForces (the seabed contact of every body) and the seafloor-referenced scalar fields all use it.

NetCDF model

Name	Width	Description @addoption{Bathymetry.NetCDFFile,1, Path to a SINMOD-style NetCDF file; its `depthMatrix` is the depth grid\, centred on the origin\, `xc` north and `yc` east\, bilinear between the nodes and 11034 m outside the grid (owner ruling R124; replaces the NetCdfSeafloor SimObject, removed by owner ruling R129). (Required when `Bathymetry.Model` is `"NetCDF"`)}

SumOfSines model

Name	Width	Description
Bathymetry.Depth	1	Mean water depth [m], finite and > 0. (Default: 200)
Bathymetry.NumStructures	1	Number of sinusoidal features, 0 to 16 (the limit of the GPU seabed; more is an error). (Default: 0, a flat seabed at `Bathymetry.Depth`.)
Bathymetry.StructureMaxHeight	1	Maximum combined height of structures [m], >= 0. (Default: 3. Used with `Bathymetry.NumStructures` > 0.)
Bathymetry.StructureLengthMin	1	Minimum horizontal feature length [m], > 0 and not above the maximum. (Default: 10. Used with `Bathymetry.NumStructures` > 0.)
Bathymetry.StructureLengthMax	1	Maximum horizontal feature length [m]. (Default: 100. Used with `Bathymetry.NumStructures` > 0.)

Parametric model

Configurable seabed built from primitives (constant\, slope\, transversal incline\, valley\, peak\, bump\, and transversal_interp -- a cross-track profile interpolated through user points via linear\, cubic spline\, or canonical polynomial)\, spatial validity intervals and blend operators\, plus an along-track segment sequence with configurable transitions (hard\, linear\, smoothstep\, raised_cosine). The seabed is described by a JSON document (see the bathymetry JSON schema and examples).

Name	Width	Description
Bathymetry.ConfigFile	1	Path to a JSON file describing the parametric seabed.
Bathymetry.Config	1	Inline JSON describing the parametric seabed (alternative to `Bathymetry.ConfigFile`).

Parametric seabed visualization

The non-sum-of-sines seabed is drawn as a static world-space mesh sampled from the physics field. These parameters control the sampled domain and the sampling rate (grid spacing = VisualExtent / (VisualVertices - 1)). Visual.SeafloorMode is read only in a visual build. The Bathymetry.Visual* parameters are also read by the seabed diagnostics (default bounds) when they are enabled.

Name	Width	Description
Bathymetry.VisualExtent	1	Side length of the square sampled seabed domain [m]. (Default: 2 x Visual.WorldRadius.)
Bathymetry.VisualCenter	2	Centre of the sampled domain `[north, east]` [m]. (Default: 0, 0.)
Bathymetry.VisualVertices	2	Number of mesh vertices `[north, east]` (the sampling rate), at least 2 each. Higher resolves fine features at higher cost. (Default: 256, 256.)
Visual.SeafloorMode	1	Seabed renderer selection (case-insensitive): "auto" (mesh for non-sum-of-sines, projected shader otherwise), "mesh", or "projected". "projected" draws the sum-of-sines seabed, so it is an error with another `Bathymetry.Model`; any other value is an error. (Default: "auto".)

Seabed diagnostics (CSV export)

When enabled\, samples the active seabed over a regular grid and writes a N,E,D CSV (SNAME frame; D is depth positive-down) for visualization in an external tool. Runs once at setup\, for any bathymetry model. Relative paths resolve against the current working directory.

Name	Width	Description
Bathymetry.DiagnosticsCsv	1	Output CSV path. A non-empty value enables the export; empty/absent disables it. (Default: disabled.)
Bathymetry.DiagnosticsBounds	4	Sampling bounding box `[N_min, N_max, E_min, E_max]` [m], finite. (Default: the visual domain.)
Bathymetry.DiagnosticsDelta	2	Sampling step `[dN, dE]` [m], finite and > 0; a single value applies to both directions. A grid of more than 10 million cells is an error. (Default: 1, 1.)

Seafloor forces

Name	Width	Description
SeafloorForces.Model	1	Seafloor force model. The only value is `"Soil"` (default): the soil law family of `seabed/SeabedContact.h` for every body, the soil is the bathymetry's. `"Model1"` (the removed old laws) is an error. The old `Seafloor.*` parameters are removed.

Currents

Current model selection

Name	Width	Description
Current.Model	1	Current model type. Supported values: `"Constant"` (default), `"DepthVarying"`, `"NetCDF"`.

Constant current

Name	Width	Description
Current.Velocity	3	Constant current vector `[Ux, Uy, Uz]` [m/s]. (Default: 0, 0, 0)
Current.Vector	3	Legacy alias for Current.Velocity. Read first; Current.Velocity overrides it when both are given.

Depth varying current

The north and east components of the layers, v cos(θ) and v sin(θ), are interpolated linearly in depth. Above the first layer and below the last the current is that of the nearest layer, with the status OUT_OF_RANGE_INACCURATE: a usable value that every consumer sums (nets, bodies, cables and the wake casters alike; owner ruling R122, marenv MENV-0053, ENV-0064). Above the surface the surface value applies. The three lists must have the same number of entries, at least two, finite, with strictly increasing depths; otherwise setup fails.

Name	Width	Description
Current.Velocity	<N>	Current speed [m/s] at each depth layer.
Current.DirectionDeg	<N>	Direction the current flows towards [deg] at each depth layer, from North towards East.
Current.DirectionRad	<N>	Direction the current flows towards [rad] at each depth layer, from North towards East (alternative to `Current.DirectionDeg`)
Current.Depth	<N>	Absolute depth [m] for each velocity layer, strictly increasing.

NetCDF current

Name	Width	Description
Current.NetCDFFile	1	Path to the SINMOD-format NetCDF file containing 3-D current-velocity data (`u-velocity` north, `v-velocity` east, `xc` north and `yc` east, `zc` the layers; the same `horizontal_resolution` and `_FillValue` attributes as `Bathymetry.NetCDFFile`). The current is the file's last time record, the same for the whole run: the field has no time axis, and the chosen record is logged. A fill value or NaN velocity counts as 0. (Required when `Current.Model` is `"NetCDF"`)

</table>

Scalar fields (temperature\, salinity\, biology)

Named scalar quantities that vary over space and time. One field models one quantity: a temperature profile\, a salinity profile\, or the concentration of a single species. Each name in ScalarField.Names becomes both a registry identifier and a parameter sub-prefix\, so the field named Herring is configured by ScalarField.Herring.*. Consumers resolve a name to a handle with environment::EnvironmentProvider::FindScalarField and query it with environment::EnvironmentProvider::GetScalarValue.

Units are conventional and advisory: degrees Celsius for temperature\, PSU for salinity\, and kilograms per cubic metre of biomass for a species concentration. Nothing validates the values against the declared unit\, and registered temperature and salinity fields do not affect the water density returned by the environment.

A species field reports how much of the species is present and carries its static properties. It computes no acoustic signature: deriving a frequency-dependent target strength from these properties is the job of the observer that needs it.

Scalar field declaration

Name	Width	Description
ScalarField.Names	<N>	Comma separated unique field names. Omit to register no scalar fields. Names must not contain whitespace, a comma or a dot, because they are used to build parameter names.

Per-field parameters

Name	Width	Description
ScalarField.<Name>.Quantity	1	Advisory tag describing what the field measures. Values: "Temperature", "Salinity", "SpeciesConcentration", "Other" (default).
ScalarField.<Name>.Unit	1	Unit of the field values. (Default: "degC", "PSU" or "kg/m^3" according to Quantity, otherwise empty)
ScalarField.<Name>.Model	1	Spatial model for the field. Values: "Constant" (default), "DepthLayered", "Parametric", "Aggregation".
ScalarField.<Name>.Species	1	The species the field holds, a key of the echosounder's Parameter library such as herring or calanus_finmarchicus. (Optional)
ScalarField.<Name>.PropertyNames	<M>	Comma separated static property keys, e.g. species properties used by an acoustic observer. (Optional)
ScalarField.<Name>.PropertyValues	<M>	Numeric value of each property key. Must have the same number of entries as PropertyNames.

Constant scalar field

Name	Width	Description
ScalarField.<Name>.Value	1	The value returned everywhere and at all times. Required when Model is "Constant"; there is no default, because a silent zero would look like a plausible reading.

Depth layered scalar field

Name	Width	Description
ScalarField.<Name>.Depth	<N>	Depth [m] of each layer, positive down, strictly increasing. At least two entries.
ScalarField.<Name>.Values	<N>	Field value at each layer. Must have the same number of entries as Depth. Values are interpolated linearly between layers and clamped outside the layer range.

Parametric scalar field

An analytic\, fully three-dimensional field: a horizontally uniform background (constant or a piecewise-linear vertical profile) plus a sum of features (gaussian_blob\, horizontal_front\, depth_band)\, clamped to optional limits. The field is described by a JSON document; see the scalar field JSON schema (schema/scalarfield.schema.json) and examples/input/auv_ocean_fields.json.

With "z_reference": "seafloor" every vertical coordinate in the document -- the background profile's depth entries\, a blob's centre[2]\, a band's centre_z and the domain box -- is a height above the bottom\, positive up\, not a depth below the surface. That is what a demersal distribution needs\, and it is the easiest thing in the document to misread.

Name	Width	Description
ScalarField.<Name>.ConfigFile	1	Path to a JSON file describing the field. Exactly one of ConfigFile and Config must be given.
ScalarField.<Name>.Config	1	Inline JSON describing the field (alternative to ConfigFile).
ScalarField.<Name>.ConfigKey	1	Entry to select when the document has a top-level "fields" object, which lets every field share one file. (Default: the field's own name.)

Aggregation scalar field

A species concentration made of compact 3D bumps (environment::field::AggregationField), for a school or a plankton layer that moves. The field also integrates itself over disks\, beam bins\, circles and rectangles (environment::field::IntegrableField); find it with environment::EnvironmentProvider::GetScalarField and dynamic_cast. The quantity is always "SpeciesConcentration" in "kg/m^3". The aggregations are generated at setup (or read from a file) and move once per update interval; between updates the field is frozen and GetValue ignores its time. The field has no output ports. All positions are NED\, the seabed depth is positive down. Each aggregation is a rotated ellipsoid with the semi-axes a\, b (horizontal) and c (vertical); its centre stays at least c below the surface and c above the seabed.

Field and box:

Name	Width	Description
ScalarField.<Name>.Seed	1	Seed of the random stream of this field, at least 0. Same seed, same state on one platform (not bit-identical between platforms). (Default: 1)
ScalarField.<Name>.UpdateInterval	1	Interval between updates [s], > 0. (Default: 1)
ScalarField.<Name>.Box	4	Horizontal box `[north min, north max, east min, east max]` [m] that holds every centre. A centre that would leave it is reflected, and that velocity component flips. (Required)
ScalarField.<Name>.InitialStateFile	1	JSON file with the aggregations; replaces the generator (the generator parameters below are then ignored), motion still applies. A list of objects with `centre` `[north, east, z]`, `a`, `b`, `c`, `phi` [rad], `biomass` [kg] and `vertical_reference` ("surface" or "seabed"); z is the depth below the surface, or the height above the seabed, positive up, for "seabed". (Optional)
ScalarField.<Name>.DumpFile	1	JSON file that receives the initial state, in the same format. (Optional)

Generator (used without InitialStateFile):

Name	Width	Description
ScalarField.<Name>.Count	1	Number of aggregations N, at least 1. (Required)
ScalarField.<Name>.TotalBiomass	1	Total biomass [kg], > 0, split among the aggregations so that the shares sum to it exactly. (Required)
ScalarField.<Name>.BiomassSigmaLog	1	Standard deviation of the logarithm of the lognormal biomass shares, >= 0. (Default: 1)
ScalarField.<Name>.SupportVolumePerBiomass	1	Mean of k in V = k B, the support volume (4/3 pi a b c) per kg of biomass [m^3/kg], > 0. (Required)
ScalarField.<Name>.SupportVolumePerBiomassSigma	1	Standard deviation of k [m^3/kg], >= 0. (Default: 0.2 times the mean)
ScalarField.<Name>.SupportVolumePerBiomassMin	1	k is redrawn until it is at least this [m^3/kg], > 0. (Default: 0.1 times the mean)
ScalarField.<Name>.AspectBMin	1	b/a is uniform in [AspectBMin, 1], in (0, 1]. (Default: 0.3)
ScalarField.<Name>.AspectCMin	1	c/a is uniform in [AspectCMin, AspectCMax], > 0. (Default: 0.1)
ScalarField.<Name>.AspectCMax	1	Upper limit of c/a, not below AspectCMin. (Default: 0.5)
ScalarField.<Name>.PatchCount	1	Number of patch centres of the Thomas process (uniform in the box), at least 1. (Default: 1)
ScalarField.<Name>.PatchSigma	1	Horizontal standard deviation of the aggregations around their patch centre [m], >= 0. (Default: 100)
ScalarField.<Name>.Depth.Reference	1	"Surface" (depth below the surface) or "Seabed" (height above the seabed; the aggregation follows the seabed). (Default: "Surface")
ScalarField.<Name>.Depth.Mean	1	Mean of the depth or height [m]. (Required)
ScalarField.<Name>.Depth.Sigma	1	Standard deviation of the depth or height [m], >= 0; a normal truncated to the limits above. (Default: 0)

Motion (an Ornstein-Uhlenbeck velocity\, drawn from its stationary distribution at the start):

Name	Width	Description
ScalarField.<Name>.Velocity.Horizontal.Mean	2	Mean drift `[north, east]` [m/s]. (Default: 0, 0)
ScalarField.<Name>.Velocity.Horizontal.Sigma	1	Stationary standard deviation of each horizontal component [m/s], >= 0. (Default: 0)
ScalarField.<Name>.Velocity.Horizontal.Tau	1	Correlation time [s], > 0. (Default: 60)
ScalarField.<Name>.Velocity.Vertical.Mean	1	Mean vertical velocity, positive down [m/s]. (Default: 0)
ScalarField.<Name>.Velocity.Vertical.Sigma	1	Stationary standard deviation of the vertical velocity [m/s], >= 0. (Default: 0)
ScalarField.<Name>.Velocity.Vertical.Tau	1	Correlation time [s], > 0. (Default: 60)

If the seabed depth is unavailable at an update\, a seabed-referenced aggregation keeps its z and a warning is written once per field.

See also: marenv::Environment, marenv::EnvironmentFacade, marenv::wave::WaveField; environment::EnvironmentProvider, environment::SeafloorForces

This SimObject is referred to as Environment