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
| 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]. (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 |
| 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. (Default: 4) |
| Waves.Hs | 1 | Significant wave height of wave spectrum. (Default: 1) |
| Waves.MainDirectionDeg | 1 | Mean wave direction of wave spectrum. (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. (Default: 0.5) |
| Waves.OmegaNormalizedMax | 1 | Upper non-dimensional angular frequency limit used during spectrum discretization. (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 |
| Waves.Amplitudes | <Waves.NumWaves> | Amplitude of each wave component |
| Waves.DirectionsDeg | <Waves.NumWaves> | Direction of each wave component in degrees |
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) and "Parametric". |
SumOfSines model
| Name | Width | Description |
| Bathymetry.Depth | 1 | Mean water depth [m]. |
| Bathymetry.NumStructures | 1 | Number of sinusoidal features. (Default: 0, a flat seabed at Bathymetry.Depth.) |
| Bathymetry.StructureMaxHeight | 1 | Maximum combined height of structures [m]. |
| Bathymetry.StructureLengthMin | 1 | Minimum horizontal feature length [m]. |
| Bathymetry.StructureLengthMax | 1 | Maximum horizontal feature length [m]. |
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)).
| 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). Higher resolves fine features at higher cost. (Default: 256, 256.) |
| Visual.SeafloorMode | 1 | Seabed renderer selection: "auto" (mesh for non-sum-of-sines, projected shader otherwise), "mesh", or "projected". (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]. (Default: the visual domain.) |
| Bathymetry.DiagnosticsDelta | 2 | Sampling step [dN, dE] [m]; a single value applies to both directions. (Default: 1, 1.) |
Seafloor forces
| Name | Width | Description |
| SeafloorForces.Model | 1 | Seafloor force model. (Currently only "Model1" is supported. |
| Seafloor.DampingHorizontal | 1 | Horizontal damping coefficient. |
| Seafloor.DampingVertical | 1 | Vertical damping coefficient. |
| Seafloor.Hardness | 1 | Seafloor hardness parameter. |
| Seafloor.Density | 1 | Seafloor density parameter. |
| Seafloor.CableDampingTangential | 1 | Tangential damping coefficient for cables. |
| Seafloor.CableDampingNormal | 1 | Normal damping coefficient for cables. |
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
| Name | Width | Description |
| Current.Velocity | <N> | Current speed [m/s] at each depth layer. |
| Current.DirectionDeg | <N> | Current direction [deg] at each depth layer. |
| Current.DirectionRad | <N> | Current direction [rad] at each depth layer (alternative to Current.DirectionDeg) |
| Current.Depth | <N> | Absolute depth [m] for each velocity layer. |
NetCDF current
| Name | Width | Description |
| Current.NetCDFFile | 1 | Path to the SINMOD-format NetCDF file containing 3-D current-velocity data. |
</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". |
| 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.) |
</table>
- See also
- marenv::Environment, marenv::EnvironmentFacade, marenv::wave::WaveField
-
environment::EnvironmentProvider, environment::SeafloorForces
This SimObject is referred to as Environment
Collaboration diagram for Environment:
1.9.8