Microsimulation API: Microsimulation C++ API Documentation

Microsimulation API

Microsimulation C++ API Documentation

This documentation describes the C++ application programming interface to Microsimulation, a very simple discrete-event sequential simulation library for R and C++. The C++ simulations build upon the to Ssim simulation library. The simulator implemented by ssim executes process objects. Process objects can be programmed either as reactive or sequential processes. A reactive process is programmed by a "callback" function that defines the discrete execution steps of that process, performed in response to an event. A sequential process is programmed as a traditional sequential thread that can explicitly receive events.

The events received by a process represent interactions with other processes, activities scheduled by the process itself, or timeouts. The simulation proceeds by scheduling the responses of each process to the event signalled to that process. During these execution steps, a process may signal events to itself and to other processes, immediately or with a delay, thereby scheduling other execution steps. The simulation terminates when no more actions are scheduled.

The ssim library consists of essentially two classes defined within the ssim namespace: Sim, which defines the interface to the simulator and Process, which defines the interface and base class for a reactive process. User processes can be programmed by extending Process.

Sim offers the basic primitives for signaling events, and for creating, starting, and stopping processes. Process declares the execution steps scheduled when a process is started, signaled, and stopped. Notice that Sim defines a single, static simulation module, rather than a class for simulation objects. (See Sim for more detailed comments.)

The execution of the simulation is based on a virtual clock that represents the time in the simulated world. The virtual clock is simply a counter, therefore the time unit is determined by the semantics of the simulated processes. The initial value of the virtual clock is 0. The passage of (virtual) time in the simulated world is explicitly controlled by each process, essentially in three ways:

- by "sleeping". That is, by scheduling a "timeout" event for itself after a given interval. The library does not provide an explicit timeout event class, but rather it leaves that to the application. The easiest way to implement a timeout is to signal a NULL event;

- by signaling events to other processes with a given delay (see signal_event());

- by explicitly declaring the duration of an action or an execution step using the Sim::advance_delay(Time delay) method.

The documentation of advance_delay provides an in-depth discussion of the semantics of the simulation in relation to virtual time.

In addition to the basic Process class, the library provides a utility class ProcessWithPId, that automates some common procedures for process implementations.