Simulation¶

class nmeasim::core::simulation::Simulation · Library API

A source and a sentence schedule, advanced together by the host on a simulated clock.

#include <nmeasim/core/simulation/simulation.hpp>

Declared in src/core/include/nmeasim/core/simulation/simulation.hpp (line 51)

Each step advances the source by dt and returns the sentences due at the new time: either those the scheduler encodes from the new state, or, for a source that provides sentences (a log replay), the recorded sentences that became due. The simulation keeps its own elapsed time for the scheduler, which is independent of the source's position: a seek or a looping source does not change it.

The simulation owns its source and its scheduler. It is movable but not copyable, because it owns the source through a std::unique_ptr.

Summary¶

Public member functions

Name	Description
`Simulation()`	Creates a simulation at elapsed time zero from a source and a schedule.
`step()`	Advances simulated time by `dt` and returns the sentences due at the new time.
`step_once()`	Takes the smallest step a host can take while paused.
`seek()`	Moves the source to `position` and makes every sentence due again at the next step.
`elapsed()`	Returns the simulated time since construction or the last reset.
`state()`	Returns the source's current state.
`source()`	Returns the source, for mode-specific controls such as overrides or a seek.
`source()`	Returns the source, read-only.
`scheduler()`	Returns the sentence schedule, for changing settings while running.
`scheduler()`	Returns the sentence schedule, read-only.
`finished()`	Returns whether the source has nothing more to produce.
`reset()`	Restarts the source and the schedule and sets the elapsed time back to zero.

Private data members

Name	Description
`source_`	The source being advanced; never null.
`scheduler_`	The schedule consulted when the source does not provide sentences.
`elapsed_`	Simulated time since construction or the last reset, the clock of the schedule.

Public member functions¶

Simulation()¶

Simulation(std::unique_ptr<Source> source, SentenceScheduler scheduler)

Creates a simulation at elapsed time zero from a source and a schedule.

Parameters

Name	Type	Description
`source`	`std::unique_ptr<Source>`	The source to advance; the simulation takes ownership of it.
`scheduler`	`SentenceScheduler`	The sentence schedule, with its settings and custom sentences already applied or to be changed later through `scheduler()`. Its registry must outlive the simulation.

Preconditions

source is not null.

Declared in src/core/include/nmeasim/core/simulation/simulation.hpp:60 · defined in src/core/src/simulation/simulation.cpp:10

step()¶

std::vector<EmittedSentence> step(std::chrono::milliseconds dt)

Advances simulated time by dt and returns the sentences due at the new time.

The elapsed time grows by dt and the source advances by dt. For a source that provides sentences, the recorded sentences that became due are returned and the schedule is not consulted; otherwise the scheduler encodes every sentence due at the new elapsed time from the new state. Everything enabled is due on the first step.

Once a finite source is finished, stepping still works: the elapsed time keeps growing and a track source's final state keeps being encoded on schedule, while a finished replay returns nothing. The host decides what to do when finished() becomes true.

Parameters

Name	Type	Description
`dt`	`std::chrono::milliseconds`	Simulated time to advance by. `io::SimulationRunner` passes the wall-clock time since its previous tick in whole milliseconds, capped at one second, and carries the sub-millisecond remainder into the next tick so that the simulated clock keeps pace with the real one.

Returns std::vector<EmittedSentence>: The due sentences in order: registry sentences in registry order, then custom sentences, or the recorded sentences in log order. Empty when nothing is due.

Preconditions

dt is not negative.

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

step_once()¶

std::vector<EmittedSentence> step_once(std::chrono::milliseconds dt)

Takes the smallest step a host can take while paused.

For a source that provides sentences, this emits exactly the next recorded sentence and moves the source's clock to its offset; dt is ignored and the elapsed time does not change. For any other source it is the same as step(dt).

Parameters

Name	Type	Description
`dt`	`std::chrono::milliseconds`	Simulated time to advance a source that does not provide sentences by.

Returns std::vector<EmittedSentence>: The sentences produced: at most one recorded sentence (none at the end of a replay that stops), or what step(dt) returns.

Preconditions

dt is not negative.

Declared in src/core/include/nmeasim/core/simulation/simulation.hpp:92 · defined in src/core/src/simulation/simulation.cpp:24

seek()¶

void seek(std::chrono::milliseconds position)

Moves the source to position and makes every sentence due again at the next step.

The elapsed time is not changed. An endless source ignores the seek, but the schedule is still reset.

Parameters

Name	Type	Description
`position`	`std::chrono::milliseconds`	`Position` within the source, clamped by the source to [0, `source().duration()`].

Declared in src/core/include/nmeasim/core/simulation/simulation.hpp:101 · defined in src/core/src/simulation/simulation.cpp:32

elapsed()¶

std::chrono::milliseconds elapsed() const noexcept

Returns the simulated time since construction or the last reset.

Returns std::chrono::milliseconds: The sum of every dt passed to step, including through step_once for a source that does not provide sentences. It is simulated time, not wall-clock time.

Declared in src/core/include/nmeasim/core/simulation/simulation.hpp:107

state()¶

const model::VesselState& state() const noexcept

Returns the source's current state.

Returns const model::VesselState&: The state owned by the source. The reference stays valid as long as the simulation; the object changes with every step, seek and reset.

Declared in src/core/include/nmeasim/core/simulation/simulation.hpp:113

source()¶

Source& source() noexcept

Returns the source, for mode-specific controls such as overrides or a seek.

Returns Source&: The owned source, valid as long as the simulation. Seeking through it directly does not reset the schedule, unlike seek.

Declared in src/core/include/nmeasim/core/simulation/simulation.hpp:118

source()¶

const Source& source() const noexcept

Returns the source, read-only.

Returns const Source&: The owned source, valid as long as the simulation.

Declared in src/core/include/nmeasim/core/simulation/simulation.hpp:122

scheduler()¶

SentenceScheduler& scheduler() noexcept

Returns the sentence schedule, for changing settings while running.

Returns SentenceScheduler&: The owned scheduler, valid as long as the simulation.

Declared in src/core/include/nmeasim/core/simulation/simulation.hpp:126

scheduler()¶

const SentenceScheduler& scheduler() const noexcept

Returns the sentence schedule, read-only.

Returns const SentenceScheduler&: The owned scheduler, valid as long as the simulation.

Declared in src/core/include/nmeasim/core/simulation/simulation.hpp:130

finished()¶

bool finished() const noexcept

Returns whether the source has nothing more to produce.

Returns bool: Source::finished() of the source: true once a finite source that stops at its end has reached it, always false for an endless or looping source.

Declared in src/core/include/nmeasim/core/simulation/simulation.hpp:136