SIMBA Module API

Contents:

Introduction

Synopsis

SIMBA module API is the interface the SIMBA driver calls and interacts with the modules executable.

The SIMBA Driver calls each module at the start and end of the simulation as well as for each step, for which the module is scheduled. A module is expected to be an executable callable from the command line. The module is called with just one positional argument, which is the path to a JSON formatted config file. Each module is expected provide a Module Status file returning the modules success state. It may also provide information back to the driver. This information comprises module specific data and common data. The later is shared with all modules but only trusted modules may update it. The returned information must be provided in a JSON files alongside the config file.

Specification

Synopsis

Specification: The API for a modules comprising configuration and return status.

The API for a SIMBA module comprises two files the configuration and return status files. The JSON configuration file may contain 3 sections, which are: Driver provided Data, Common Data, and Module Specific Data. In case the module updates common or module specific data this must be done in a file alongside the configuration file, i.e., in the same directory. The file should contain the JSON objects commonData, moduleData, or both.

Driver provided Data

This data provides information about the situation in which the module is called by the driver. The module will be called with 3 modes which are: start, step, and end. The normative JSON schema can be found at: Module Config Schema

start: The module is expected to initialize itself and the state of the system for the given currentTick and currentTime

Table 6 Start Information.
Name
Type
Description
mode
const start
The modules is called in mode start.
statusFile
string
The file containing status, updated common, and module data.
currentTick
integer
The current (initial) tick
currentTime
string
The current (initial) time (ISO data time format)

step: The module is expected to progress the systems state from the lastRunTime to the targetTime. The currentTime is provided since the time increments may not be uniform (see: SIMBA Driver)

Table 7 Step Information.
Name
Type
Description
mode
const step
The modules is called in mode step.
statusFile
string
The file containing status, updated common, and module data.
lastRunTick
integer
The tick the module was last executed
lastRunTime
string
The time the module was last executed (ISO data time format)
currentTick
integer
The current tick
currentTime
string
The current time (ISO data time format)
targetTick
integer
The target tick
targetTime
string
The target time (ISO data time format)

end: The module is expected to progress the systems state from the lastRunTime to the currentTime if that is appropriate. Furthermore, it is expected that it does complete all required shutdown procedures

Table 8 End Information.
Name
Type
Description
mode
const end
The modules is called in mode end.
statusFile
string
The file containing status, updated common, and module data.
lastRunTick
integer
The tick the module was last executed
lastRunTime
string
The time the module was last executed (ISO data time format)
currentTick
integer
The current tick
currentTime
string
The current time (ISO data time format)

Common Data

Common data, e.g., database connection information is provided to all modules. Since the host on which the database may not be know before the start of the driver it is necessary that the module providing the database returns the information to the driver and all modules. The attributes of the common data or provided as part of the SIMBA Schedule. No further information will be made available the modules.

Table 9 Module Common Data.
Name
Type
Description
commonData
object
Common data provided to all modules.

As an example if the following is provided in the schedule file:

 "commonData": {
  "dbHost": null
}

The following should be contained in the status file from the module providing the database host:

 "commonData": {
  "dbHost": "128.1.1.223"
}

Module Specific Data

A module may require additional configuration options beyond the driver provided information and common data. The module specific data object is providing the means to define and modify it.

Table 10 Module Specific Data.
Name
Type
Description
moduleData
object
Module specific data.

Module Status

As a minimum the status file contains the return status: success or fail. In case the module updates common or module specific data the file should also contain the JSON objects commonData, moduleData, or both. The normative JSON schema can be found at: Module Status Schema

Table 11 Module Status.
Name
Type
Description
status
string
The return status: success or fail.
commonData
object
Updated common data provided to all modules.
moduleData
object
Updated module specific data.

Examples

Please see Examples