nmeasim::core::simulation¶

namespace nmeasim::core::simulation · Library API

The simulation engine of the Qt-free core library: the sources that produce the vessel state over time, the schedule that turns it into sentences, and the Simulation that ties them together.

A Source produces the vessel state in one of three modes: DeltaSource lets seed values drift at random within bounds, with operator overrides and rudder steering; TrackSource sails a GPX or KML track leg by leg; ReplaySource sends the sentences of a recorded log again with their original timing. The SentenceScheduler holds each sentence's enable flag, talker and period, together with the operator's CustomSentence list, and encodes whatever is due; the result is a list of EmittedSentence values. Simulation owns a source and a scheduler and advances both.

Time is simulated: it advances only when the host calls Simulation::step with the duration to advance by, which the host usually measures on a wall clock. Nothing in this namespace starts threads, sleeps, reads a clock or performs I/O, so a test can run hours of simulated time in milliseconds.

See also

docs/explanation/simulation-model.md

Types¶

Type	Description
`CustomSentence`	One operator-defined sentence and its schedule.
`DeltaConfig`	Configuration of a `DeltaSource`: the seed state and the drift of each value.
`DeltaSource`	Endless source whose values drift at random around their seeds.
`EmittedSentence`	One sentence produced by a simulation step, together with the id that produced it.
`ReplayConfig`	Configuration of a `ReplaySource`.
`ReplaySource`	Replays the entries of a log as the replay clock passes their offsets.
`SentenceScheduler`	The per-sentence enable flags, talkers and periods, plus the operator's custom sentences, with the time each one is next due.
`SentenceSetting`	The settings of one registry sentence that an operator can change.
`Simulation`	A source and a sentence schedule, advanced together by the host on a simulated clock.
`Source`	Base class of the simulation modes: delta drift, track following and log replay.
`TrackConfig`	Configuration of a `TrackSource`.
`TrackSource`	Follows a track leg by leg, one leg per pair of consecutive points.
`Variation`	How far a value may wander from its seed and how fast.

Summary¶

Enumerations

Name	Description
`Parameter`	A value the operator can override or nudge while the simulation runs.
`EndBehaviour`	What a finite source does when it reaches its end.

Functions

Name	Description
`frame_custom_sentence()`	Frames a custom sentence body into a complete sentence with a freshly computed checksum.
`validate_custom_sentence()`	Checks whether `frame_custom_sentence` accepts a body and explains why not.
`effective_custom_id()`	Returns the id a custom sentence is scheduled, filtered and shown under.
`find_duplicate_custom_id()`	Finds the first custom sentence whose id is already used by an earlier one.
`is_valid_talker()`	Returns whether a text is acceptable as the talker of a `SentenceSetting`.
`next_due_after()`	Returns the next due time of a periodic message that was due at `due` and is sent at `now`.

Enumerations¶

Parameter¶

enum class Parameter

A value the operator can override or nudge while the simulation runs.

Each enumerator names a field of model::VesselState. A value written through an override or a nudge is normalised or clamped as stated for each enumerator.

Enumerator	Value	Description
`HeadingTrue`		`navigation.heading_true_deg`, degrees true, normalised into [0, 360).
`SpeedOverGround`		`navigation.speed_over_ground_kn`, knots; a negative value is raised to zero.
`SpeedThroughWater`		`navigation.speed_through_water_kn`, knots; a negative value is raised to zero. It follows the speed over ground unless overridden.
`Altitude`		`navigation.altitude_m`, metres above mean sea level; it never drifts.
`Depth`		`water.depth_below_transducer_m`, metres; a negative value is raised to zero.
`WaterTemperature`		`water.temperature_c`, degrees Celsius.
`WindDirectionTrue`		`wind.true_direction_deg`, the direction the true wind blows from, degrees true, normalised into [0, 360).
`WindSpeedTrue`		`wind.true_speed_kn`, knots; a negative value is raised to zero.
`RudderAngle`		`steering.rudder_angle_deg`, degrees, positive to starboard, clamped to plus or minus `DeltaConfig::max_rudder_angle_deg`; it never drifts.

Declared in src/core/include/nmeasim/core/simulation/delta_source.hpp:27

EndBehaviour¶

enum class EndBehaviour

What a finite source does when it reaches its end.

Enumerator	Value	Description
`Stop`		Stay at the end and report `Source::finished()`; a track holds its last point with zero speed.
`Loop`		Start again from the beginning, carrying all the time that ran past the end into the next pass; a step that spans several passes plays them all. A track without duration stays at its point instead.

Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:23

Functions¶

frame_custom_sentence()¶

std::optional<std::string> frame_custom_sentence(std::string_view body)

Frames a custom sentence body into a complete sentence with a freshly computed checksum.

Surrounding white space, the line terminator and any existing *hh checksum are removed; the start delimiter is kept when present and $ is added otherwise; the checksum is then appended.

Parameters

Name	Type	Description
`body`	`std::string_view`	The body as typed by the operator, in the format described at `CustomSentence::body`.

Returns std::optional<std::string>: The framed sentence without line terminator, for example $PXYZ,1,2,3*17 for PXYZ,1,2,3, or std::nullopt when validate_custom_sentence refuses body.

See also

NMEA 0183 (IEC 61162-1), sentence structure and checksum.

Declared in src/core/include/nmeasim/core/simulation/custom_sentence.hpp:62 · defined in src/core/src/simulation/custom_sentence.cpp:114

validate_custom_sentence()¶

std::optional<std::string> validate_custom_sentence(std::string_view body)

Checks whether frame_custom_sentence accepts a body and explains why not.

After surrounding white space is trimmed, a body is refused when:

it is empty;
it contains a * that is not followed by exactly two hexadecimal digits at the end;
apart from the leading delimiter, it contains a character outside printable ASCII (0x20 to 0x7E) or one of the reserved characters $, !, \\endiskip, ^ and ~;
its address, the text before the first comma, is shorter than three characters or contains anything but letters and digits;
the framed sentence would be longer than 80 characters with its checksum and without its line terminator, the NMEA 0183 limit of 82 characters including CR LF. The message then reads The sentence exceeds 80 characters with its checksum.

Parameters

Name	Type	Description
`body`	`std::string_view`	The body as typed by the operator.

Returns std::optional<std::string>: std::nullopt when the body is acceptable, otherwise an English sentence for the operator saying what is wrong.

Declared in src/core/include/nmeasim/core/simulation/custom_sentence.hpp:80 · defined in src/core/src/simulation/custom_sentence.cpp:110

effective_custom_id()¶

std::string effective_custom_id(const CustomSentence& sentence, std::size_t index)

Returns the id a custom sentence is scheduled, filtered and shown under.

Parameters

Name	Type	Description
`sentence`	`const CustomSentence&`	The sentence.
`index`	`std::size_t`	The 0-based position of the sentence in its list.

Returns std::string: sentence.id when it is not empty, otherwise CUSTOM-n with n equal to index + 1.

Declared in src/core/include/nmeasim/core/simulation/custom_sentence.hpp:88 · defined in src/core/src/simulation/custom_sentence.cpp:122

find_duplicate_custom_id()¶

std::optional<std::size_t> find_duplicate_custom_id(
    const std::vector<CustomSentence>& sentences)

Finds the first custom sentence whose id is already used by an earlier one.

The ids compared are those of effective_custom_id, so an explicit CUSTOM-2 clashes with an unnamed second sentence. The comparison is exact and case-sensitive; a profile upper-cases its ids before.

Parameters

Name	Type	Description
`sentences`	`const std::vector<CustomSentence>&`	The custom sentences, in list order.

Returns std::optional<std::size_t>: The 0-based index of the first sentence whose id equals the id of a sentence before it, or std::nullopt when every id is unique.

Declared in src/core/include/nmeasim/core/simulation/custom_sentence.hpp:99 · defined in src/core/src/simulation/custom_sentence.cpp:126

is_valid_talker()¶

bool is_valid_talker(std::string_view talker) noexcept

Returns whether a text is acceptable as the talker of a SentenceSetting.

Parameters

Name	Type	Description
`talker`	`std::string_view`	The talker as typed.

Returns bool: True when talker is empty, which selects the registry default, or consists of exactly two upper-case ASCII letters A to Z; false otherwise, including for lower-case letters, digits and the user-configured U0 to U9.

See also

NMEA 0183 (IEC 61162-1), talker identifier.

Declared in src/core/include/nmeasim/core/simulation/sentence_scheduler.hpp:47 · defined in src/core/src/simulation/sentence_scheduler.cpp:74

next_due_after()¶

std::chrono::milliseconds next_due_after(
    std::chrono::milliseconds due,
    std::chrono::milliseconds now,
    std::chrono::milliseconds period) noexcept

Returns the next due time of a periodic message that was due at due and is sent at now.

The next due time is one period after the slot, due + period, so that the cadence follows the simulated clock even though each step that sends the message arrives a little after its slot: a 1000 ms sentence sent by 99 ms steps still goes out once per second without drifting. When due + period is not later than now, the message has fallen a whole period or more behind (the host stalled), and the next due time is now + period instead, so that the message is sent once rather than in a burst of catch-up copies.

Parameters

Name	Type	Description
`due`	`std::chrono::milliseconds`	The time the message was due, in simulated time since the start.
`now`	`std::chrono::milliseconds`	The time it is being sent, in simulated time since the start; at or after `due`.
`period`	`std::chrono::milliseconds`	The message's interval; positive.

Returns std::chrono::milliseconds: due + period when that is later than now, otherwise now + period.

Declared in src/core/include/nmeasim/core/simulation/sentence_scheduler.hpp:64 · defined in src/core/src/simulation/sentence_scheduler.cpp:14