libcosim  0.7.0
C++ library for distributed co-simulation
Public Member Functions | List of all members
cosim::execution Class Reference

A class which represents an execution, i.e., a co-simulation run. More...

#include <cosim/execution.hpp>

Public Member Functions

 execution (time_point startTime, std::shared_ptr< algorithm > algo)
 Constructor. More...
 
 execution (const execution &)=delete
 
executionoperator= (const execution &)=delete
 
 execution (execution &&) noexcept
 
executionoperator= (execution &&) noexcept
 
simulator_index add_slave (std::shared_ptr< async_slave > slave, std::string_view name, duration stepSizeHint=duration::zero())
 Adds a slave to the execution. More...
 
function_index add_function (std::shared_ptr< function > fun)
 Adds a function to the execution.
 
void add_observer (std::shared_ptr< observer > obs)
 Adds an observer to the execution.
 
void add_manipulator (std::shared_ptr< manipulator > man)
 Adds a manipulator to the execution.
 
void connect_variables (variable_id output, variable_id input)
 Connects a simulator output variable to a simulator input variable. More...
 
void connect_variables (variable_id output, function_io_id input)
 Connects a simulator output variable to a function input variable. More...
 
void connect_variables (function_io_id output, variable_id input)
 Connects a function output variable to a simulator input variable. More...
 
time_point current_time () const noexcept
 Returns the current logical time.
 
boost::fibers::future< bool > simulate_until (std::optional< time_point > targetTime)
 Advance the co-simulation forward to the given logical time. More...
 
duration step ()
 Advance the co-simulation forward one single step. More...
 
void stop_simulation ()
 Stops the co-simulation temporarily.
 
bool is_running () const noexcept
 Is the simulation loop currently running.
 
void enable_real_time_simulation ()
 Enables real time simulation.
 
void disable_real_time_simulation ()
 Disables real time simulation.
 
void set_real_time_factor_target (double realTimeFactor)
 Sets the custom real time factor for the simulation.
 
bool is_real_time_simulation () const
 Returns if this is a real time simulation.
 
double get_measured_real_time_factor () const
 Returns the current real time factor.
 
double get_real_time_factor_target () const
 Returns the current real time factor target.
 
std::shared_ptr< const simulatorget_simulator (simulator_index index) const
 Returns the simulator with the given index.
 
std::vector< variable_idget_modified_variables () const
 Returns a map of currently modified variables.
 
void set_real_initial_value (simulator_index sim, value_reference var, double value)
 Set initial value for a variable of type real. Must be called before simulation is started.
 
void set_integer_initial_value (simulator_index sim, value_reference var, int value)
 Set initial value for a variable of type integer. Must be called before simulation is started.
 
void set_boolean_initial_value (simulator_index sim, value_reference var, bool value)
 Set initial value for a variable of type boolean. Must be called before simulation is started.
 
void set_string_initial_value (simulator_index sim, value_reference var, const std::string &value)
 Set initial value for a variable of type string. Must be called before simulation is started.
 

Detailed Description

A class which represents an execution, i.e., a co-simulation run.

The execution class manages all the entities involved in an execution and provides a high-level API for driving the co-simulation algorithm forward.

Constructor & Destructor Documentation

◆ execution()

cosim::execution::execution ( time_point  startTime,
std::shared_ptr< algorithm algo 
)

Constructor.

Parameters
startTimeThe logical time at which the simulation will start.
algoThe co-simulation algorithm which will be used. One algorithm object may only be used with one execution.

Member Function Documentation

◆ add_slave()

simulator_index cosim::execution::add_slave ( std::shared_ptr< async_slave slave,
std::string_view  name,
duration  stepSizeHint = duration::zero() 
)

Adds a slave to the execution.

Parameters
slaveAn object that provides asynchronous communication with the slave.
nameAn execution-specific name for the slave.
stepSizeHintThe recommended co-simulation step size for this slave. Whether and how this is taken into account is algorithm dependent. If zero, the algorithm will attempt to choose a sensible default.

◆ connect_variables() [1/3]

void cosim::execution::connect_variables ( function_io_id  output,
variable_id  input 
)

Connects a function output variable to a simulator input variable.

After this, the values of the output variable will be passed to the input value at the co-simulation algorithm's discretion. Different algorithms may handle this in different ways, and could for instance choose to extrapolate or correct the variable value during transfer.

When calling this method, the validity of both variables are checked against the metadata of their respective simulators. If either is found to be invalid (i.e. not found, wrong type or causality, an exception will be thrown.

◆ connect_variables() [2/3]

void cosim::execution::connect_variables ( variable_id  output,
function_io_id  input 
)

Connects a simulator output variable to a function input variable.

After this, the values of the output variable will be passed to the input value at the co-simulation algorithm's discretion. Different algorithms may handle this in different ways, and could for instance choose to extrapolate or correct the variable value during transfer.

When calling this method, the validity of both variables are checked against the metadata of their respective simulators. If either is found to be invalid (i.e. not found, wrong type or causality, an exception will be thrown.

◆ connect_variables() [3/3]

void cosim::execution::connect_variables ( variable_id  output,
variable_id  input 
)

Connects a simulator output variable to a simulator input variable.

After this, the values of the output variable will be passed to the input value at the co-simulation algorithm's discretion. Different algorithms may handle this in different ways, and could for instance choose to extrapolate or correct the variable value during transfer.

When calling this method, the validity of both variables are checked against the metadata of their respective simulators. If either is found to be invalid (i.e. not found, wrong type or causality, an exception will be thrown.

◆ simulate_until()

boost::fibers::future<bool> cosim::execution::simulate_until ( std::optional< time_point targetTime)

Advance the co-simulation forward to the given logical time.

This function returns immediately, and its actions will be performed asynchronously. As it is not possible to perform more than one asynchronous operation at a time per execution object, client code must verify that the operation completed before calling the function again (e.g. by calling boost::fibers::future::get() on the result).

Parameters
targetTimeThe logical time at which the co-simulation should pause (optional). If specified, this must always be greater than the value of current_time() at the moment the function is called. If not specified, the co-simulation will continue until stop_simulation() is called.
Returns
true if the co-simulation was advanced to the given time, or false if it was stopped before this. In the latter case, current_time() may be called to determine the actual end time.

◆ step()

duration cosim::execution::step ( )

Advance the co-simulation forward one single step.

Returns
The actual duration of the step. current_time() may be called to determine the actual time after the step completed.

The documentation for this class was generated from the following file: