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:

0115 — Fully buried bodies are pushed out by the soil; no stick/consolidation model

0116 — Resting anchors creep (v_reg 0.01 m/s): add a stiction rule 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).

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.