Usage

The main purpose of fhsim_environment is to provide one single, shared source of truth when it comes to the environment which FhSim models interact with. It contains methods for both querying and change this environment. This means that if one simObject incorporates a change (e.g. a wake field or a transition in sea state), all other simObjects are affected. They all operate in the same environment, and they don't need to know about each other or share any knowledge about each others implementations.

Review issues:

0130 — NetCDF variables are read in the order (time, zc, yc, xc) without checking it Known review issues are listed in Review issues — fhsim_environment. Test coverage and Jacobian verification are summarised in Testing report. Wakes, how to place one and who sees them, are summarised in Wakes; every wake parameter (CastWake, Wake*, ExternalWakeUpdate) is listed once in Wake parameters. The laws by which the water loads a body (net panels, spheres, discs, cable elements) and its submerged fraction are in Hydrodynamics: shape and panel load laws; the panel load laws are validated against measurements in Panel load laws: validation report.

This codebase contains a collection of SimObjects and classes to this end, as well as some simObjects for testing (and demonstrating) its abilities. The set of available SimObjects can be found in modules. The most fundamental ones are:

• EnvironmentProvider is the underlying class which handles all aspects of the environment, such as setting parameters or answering to queries. This is the class most simObjects will use for environment access.
• Environment is the simObject which instantiates and registers the EnvironmentProvider for use by other simObjects. It is also responsible for its visualisation.
• SeafloorForcesInterface is the bound evaluator of the soil law family: one method per contact shape (sphere, cable element, rigid cylinder, plate, trawl door, anchor shank) that returns the load of the seabed on a body. Models pass geometry and kinematics and apply the load; the soil is the bathymetry's (ADR 0004).

The soil laws behind SeafloorForcesInterface are pure functions of pose and velocity: they keep no state per contact. Two limitations follow (owner rulings 2026-10-21; both are to be designed together, with a state per contact, when a model needs it):

• A fully buried body is pushed out (ENV-0115). Once a body is deeper than its own height, the soil pushes it up with its full bearing capacity. The uplift resistance acts only while the body moves up, so it is zero at rest. The body rises until it rests on the bed. A body placed deep in the soil, or an anchor that has dug in, does not stay embedded. Start a body on the bed, not inside the sediment.
• A resting body creeps (ENV-0116). Below 1 cm/s the soil friction is only a fraction of its limit, so a small steady side force is balanced by a slow slide, not by a hold. Measured in fhsim_base: a FlukeAnchor creeps 1 to 4 cm/s and yaws 0.013 rad/s, a TorpedoAnchor creeps 7 mm/s. A test that expects a stationary anchor must accept this drift. There is no stiction yet.

A NetCDF file gives the Environment a seabed (Bathymetry.Model = "NetCDF") and a current (Current.Model = "NetCDF"); both read the SINMOD layout and are centred on the origin. Two things to know:

• The NetCDF current is constant in time. The field has no time axis, so the file's last time record is the current for the whole run, however many records the file holds. The log names the record (using time record 24 of 24). A time-varying current needs a time axis in marenv's CurrentField3DArray, which does not exist yet.
• A fill value or NaN is missing data. In the depth grid it is land (depth -1 m, the same in every build; a visual build draws terrain over it from a separate copy, seeded by RandomSeed). In a velocity it is 0. A position outside the grid has the depth 11034 m; a body whose position is NaN has no seabed depth and no seabed contact, and the first such point is reported once in the log.

When the simObject Environment is created, it creates an instance of EnvironmentProvider and registers it within FhSim for use by other simObjects. Other simObjects can then access the environment through the EnvironmentProvider. This enables them to both query the environment and to change it.

Two simObjects draw a field of the environment on the GPU, and a third draws where the wakes come from (3.2.2; they replace VisualFlowPlane, VisualScalarPlane and VisualScalarVolume):

• VisualFieldPlane shows one flat slice. It is placed by Position, tilted freely through LocalX and LocalY, sized by Size, and may move back and forth to Position2 or spin (RotationPeriodX, RotationPeriodY).
• VisualFieldVolume shows a whole NED axis-aligned box of water semi-transparently, ray-marched from a 3-D texture. BoxCentre and BoxSize place the box, ReferenceLength is the path length AlphaRange is stated over, and CentreOnCamera lets the box follow the camera.
• VisualWakeSources draws every registered wake source, jet axis and wake grid as lines, again whenever the wakes change.

What the plane and the volume show is Quantity: Speed or Component (along Axis) of the water velocity parts named by Terms (any of Current, Waves, Wake, Jet; Wake is the change the wakes make to the current, d (u_s - u_amb), Jet the propellers' excess velocity), the wake Deficit, the wave Pressure or TotalPressure, the wave Elevation (plane only), or a registered scalar field (Scalar, with FieldName, the name it was registered under in the ScalarField.* group; a FieldName alone selects it).

The field is sampled onto a grid (Resolution or Spacing, never both) on every core while the simulation waits, and drawn from a texture the shaders read per fragment. Refresh says when it is sampled again: Auto, the default, samples a time-invariant scalar field once, a quantity of the wakes and jets alone (Deficit, or Terms of Wake and Jet) when a wake is published or blends or a moving wake travels (OnChange, at most every RefreshPeriod), and anything with the current or the waves every frame; Once, Period and EveryFrame can be asked for. A moored structure's wake therefore costs nothing between its rebuilds. A field sampled more than once gets the default ColorRange 0, 1 (and VisibleRange equal to it); a field sampled once is probed for a range not configured. ColorRange, VisibleRange and AlphaRange fix the encoding at the first sample. Scrubbing back through the history shows the fields as they are now.

No field provider offers a gradient or any other derivative, and this is by design. A simObject that needs a spatial sensitivity computes it itself, by finite differences of the field's value. Two normals are already available: the sea surface's through GetSurfaceUnitNormal on the environment, and the seabed's through ComputeSurfaceUnitNormal on its bathymetry field.