DeltaSource¶
class nmeasim::core::simulation::DeltaSource · Library API
Endless source whose values drift at random around their seeds.
#include <nmeasim/core/simulation/delta_source.hpp>
Inherits nmeasim::core::simulation::Source
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp (line 119)
Each advance by dt, in this order: moves time_utc on by dt; moves the heading (following the rudder in steering mode, held by an override, or drifting) and derives the rate of turn from the change; drifts the speed over ground, depth, water temperature and true wind unless overridden; sets the speed through water to the speed over ground unless overridden, because the model has no current or leeway; sets course over ground to the heading; moves the position along that course by speed times dt on the WGS 84 ellipsoid; and recomputes the apparent wind from the true wind and the motion through the water.
Altitude, rudder angle, GNSS quality and every other field keep their seed or the last value set by the host. Overrides and nudges take effect at once, without an advance.
See also
- docs/explanation/simulation-model.md, section "Delta mode".
- GeographicLib::Geodesic
Summary¶
Public member functions
| Name | Description |
|---|---|
DeltaSource() |
Creates a source whose state is config.seed, with the generator seeded from config.random_seed, no overrides and steering mode off. |
advance() |
Advances the drift, the steering and the position by dt, as the class description lists. |
current() |
Returns the current state. |
reset() |
Returns to the seed state, clears every override and reseeds the generator, so that the run repeats exactly. |
set_override() |
Pins a parameter to a fixed value, which the state takes at once; the random drift stops for it. |
clear_override() |
Releases an override so that the value is simulated again from where it is. |
override_value() |
Returns the value an overridden parameter holds, which is the value the simulation uses. |
nudge() |
Adds delta to a parameter's current value and pins it there. |
set_steering_mode() |
Switches steering mode on or off. |
steering_mode() |
Returns whether the heading follows the rudder. |
set_position() |
Moves the vessel to a position at once; the position does not survive reset. |
set_destination() |
Sets or clears the destination; the change survives reset. |
set_engine() |
Replaces or adds one engine; the change survives reset. |
remove_engine() |
Removes one engine; the change survives reset. |
set_fix() |
Simulates losing or regaining the GNSS fix; the change does not survive reset. |
set_satellites() |
Sets the satellite counts; the change does not survive reset. |
config() |
Returns the configuration. |
Private member functions
| Name | Description |
|---|---|
read() |
Returns the current value of a parameter from the state. |
write() |
Writes a parameter into the state, normalised or clamped as Parameter states. |
drift() |
Moves a value one random step of its bounded walk. |
update_derived_values() |
Updates the values that follow from the others: course over ground, position and apparent wind. |
Private data members
| Name | Description |
|---|---|
config_ |
Configuration, including the destination and engines set since construction. |
state_ |
The current state. |
overrides_ |
Whether each parameter is overridden, indexed by the enumerator's value; false when the parameter is simulated. |
steering_mode_ |
Whether the heading follows the rudder. |
generator_ |
Pseudo-random generator of the drift, seeded from DeltaConfig::random_seed. |
Public member functions¶
DeltaSource()¶
explicit DeltaSource(DeltaConfig config)
Creates a source whose state is config.seed, with the generator seeded from config.random_seed, no overrides and steering mode off.
Parameters
| Name | Type | Description |
|---|---|---|
config |
DeltaConfig |
The seed state and drift settings. |
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:125 · defined in src/core/src/simulation/delta_source.cpp:29
advance()¶
const model::VesselState& advance(std::chrono::milliseconds dt) override
Advances the drift, the steering and the position by dt, as the class description lists.
Parameters
| Name | Type | Description |
|---|---|---|
dt |
std::chrono::milliseconds |
Simulated time to advance by. |
Returns const model::VesselState&: The new state.
Preconditions
dtis not negative.
Overrides advance · Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:133 · defined in src/core/src/simulation/delta_source.cpp:172
current()¶
const model::VesselState& current() const noexcept override
Returns the current state.
Returns const model::VesselState&: The state owned by the source, valid for its lifetime.
Overrides current · Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:137
reset()¶
void reset() override
Returns to the seed state, clears every override and reseeds the generator, so that the run repeats exactly.
The destination and the engines set since construction survive, because they are stored in the seed; the steering mode also survives. A position, fix or satellite count set by the host is lost.
Overrides reset · Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:144 · defined in src/core/src/simulation/delta_source.cpp:32
set_override()¶
void set_override(Parameter parameter, double value)
Pins a parameter to a fixed value, which the state takes at once; the random drift stops for it.
Parameters
| Name | Type | Description |
|---|---|---|
parameter |
Parameter |
The value to pin. |
value |
double |
The value in the parameter's unit; it is normalised or clamped as Parameter states before it enters the state. |
Note
In steering mode the heading follows the rudder even when it is overridden; the override then holds the heading where the rudder left it once steering mode is switched off.
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:155 · defined in src/core/src/simulation/delta_source.cpp:95
clear_override()¶
void clear_override(Parameter parameter)
Releases an override so that the value is simulated again from where it is.
A drifting value continues its walk from where it was pinned. A value pinned outside [seed - amplitude, seed + amplitude] drifts back gradually: each advance moves it towards that band by the full step of its Variation until it is inside, and it stays where it is when its variation is zero. The speed through water follows the speed over ground again; altitude and rudder angle stay where they are. Releasing a parameter that is not overridden does nothing.
Parameters
| Name | Type | Description |
|---|---|---|
parameter |
Parameter |
The value to release. |
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:166 · defined in src/core/src/simulation/delta_source.cpp:100
override_value()¶
std::optional<double> override_value(Parameter parameter) const
Returns the value an overridden parameter holds, which is the value the simulation uses.
Parameters
| Name | Type | Description |
|---|---|---|
parameter |
Parameter |
The value to query. |
Returns std::optional<double>: The value given to set_override or computed by nudge, after normalising or clamping as Parameter states, or std::nullopt when the parameter is not overridden. In steering mode an overridden heading is the heading the rudder has turned the vessel to, because steering takes precedence over the override.
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:175 · defined in src/core/src/simulation/delta_source.cpp:104
nudge()¶
void nudge(Parameter parameter, double delta)
Adds delta to a parameter's current value and pins it there.
The desktop application's arrow keys are nudges of speed and heading, or of the rudder in steering mode.
Parameters
| Name | Type | Description |
|---|---|---|
parameter |
Parameter |
The value to nudge. |
delta |
double |
The change, in the parameter's unit; negative to decrease. The result is normalised or clamped as Parameter states. |
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:184 · defined in src/core/src/simulation/delta_source.cpp:113
set_steering_mode()¶
void set_steering_mode(bool enabled) noexcept
Switches steering mode on or off.
In steering mode the heading follows the rudder instead of drifting: the rate of turn is the rudder angle times DeltaConfig::turn_rate_per_rudder_deg, positive (to starboard) for a positive rudder angle, and it takes precedence over a heading override.
Parameters
| Name | Type | Description |
|---|---|---|
enabled |
bool |
True to steer with the rudder, false to let the heading drift again. |
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:194
steering_mode()¶
bool steering_mode() const noexcept
Returns whether the heading follows the rudder.
Returns bool: True in steering mode.
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:198
set_position()¶
void set_position(geo::Position position)
Moves the vessel to a position at once; the position does not survive reset.
Parameters
| Name | Type | Description |
|---|---|---|
position |
geo::Position |
The new position of the GNSS antenna. |
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:203 · defined in src/core/src/simulation/delta_source.cpp:117
set_destination()¶
void set_destination(std::optional<model::Destination> destination) override
Sets or clears the destination; the change survives reset.
Parameters
| Name | Type | Description |
|---|---|---|
destination |
std::optional<model::Destination> |
The new destination, or std::nullopt to clear it and stop the autopilot sentences. |
Overrides set_destination · Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:208 · defined in src/core/src/simulation/delta_source.cpp:121
set_engine()¶
void set_engine(std::size_t index, model::Engine engine)
Replaces or adds one engine; the change survives reset.
Parameters
| Name | Type | Description |
|---|---|---|
index |
std::size_t |
Position in the engine list; an index at or past the end appends the engine at the end instead. |
engine |
model::Engine |
The engine data. |
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:214 · defined in src/core/src/simulation/delta_source.cpp:127
remove_engine()¶
void remove_engine(std::size_t index)
Removes one engine; the change survives reset.
Parameters
| Name | Type | Description |
|---|---|---|
index |
std::size_t |
Position in the engine list; an index at or past the end is ignored. |
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:218 · defined in src/core/src/simulation/delta_source.cpp:138
set_fix()¶
void set_fix(bool has_fix) noexcept
Simulates losing or regaining the GNSS fix; the change does not survive reset.
Parameters
| Name | Type | Description |
|---|---|---|
has_fix |
bool |
False to report no fix, true to report a fix again. |
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:223
set_satellites()¶
void set_satellites(int in_use, int in_view) noexcept
Sets the satellite counts; the change does not survive reset.
Parameters
| Name | Type | Description |
|---|---|---|
in_use |
int |
Number of satellites used in the fix; not checked. |
in_view |
int |
Number of satellites in view; raised to in_use when smaller. |
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:228 · defined in src/core/src/simulation/delta_source.cpp:146
config()¶
const DeltaConfig& config() const noexcept
Returns the configuration.
Returns const DeltaConfig&: The configuration given to the constructor, with the destination and engines set since then in its seed.
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:234
Private member functions¶
read()¶
double read(Parameter parameter) const noexcept
Returns the current value of a parameter from the state.
Parameters
| Name | Type | Description |
|---|---|---|
parameter |
Parameter |
The value to read. |
Returns double: The value in the parameter's unit.
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:241 · defined in src/core/src/simulation/delta_source.cpp:38
write()¶
void write(Parameter parameter, double value) noexcept
Writes a parameter into the state, normalised or clamped as Parameter states.
Parameters
| Name | Type | Description |
|---|---|---|
parameter |
Parameter |
The value to write. |
value |
double |
The value in the parameter's unit. |
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:246 · defined in src/core/src/simulation/delta_source.cpp:62
drift()¶
double drift(double current, double seed, const Variation& variation, double seconds)
Moves a value one random step of its bounded walk.
Parameters
| Name | Type | Description |
|---|---|---|
current |
double |
The value now. |
seed |
double |
The centre of the band the value must stay in. |
variation |
const Variation& |
The half-width of the band and the step rate. |
seconds |
double |
Length of the step in simulated seconds. |
Returns double: current moved by a uniform random amount within plus or minus variation.step_per_second * seconds and clamped to seed plus or minus variation.amplitude; when current lies outside that band, current moved by the full step towards the band, stopping at its edge; current unchanged when either member of variation is zero or negative.
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:258 · defined in src/core/src/simulation/delta_source.cpp:151
update_derived_values()¶
void update_derived_values(double seconds)
Updates the values that follow from the others: course over ground, position and apparent wind.
Parameters
| Name | Type | Description |
|---|---|---|
seconds |
double |
Length of the step in simulated seconds, over which the vessel moves. |
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:264 · defined in src/core/src/simulation/delta_source.cpp:236
Private data members¶
config_¶
DeltaConfig config_
Configuration, including the destination and engines set since construction.
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:267
state_¶
model::VesselState state_
The current state.
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:269
overrides_¶
std::array<bool, 9> overrides_{}
Whether each parameter is overridden, indexed by the enumerator's value; false when the parameter is simulated.
The pinned value itself is the one in state_. The size is the number of Parameter enumerators.
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:273
steering_mode_¶
bool steering_mode_{false}
Whether the heading follows the rudder.
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:275
generator_¶
std::mt19937 generator_
Pseudo-random generator of the drift, seeded from DeltaConfig::random_seed.
Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:277
Inherited members¶
From nmeasim::core::simulation::DeltaSource: duration(), finished(), operator=(), operator=(), position(), provides_sentences(), seek(), Source(), Source(), Source(), step_once(), take_sentences(), ~Source()