Declaration of the simulator signature

Table of Contents

The signature has to be defined between the BEGIN_SIMULATOR_SIGNATURE and the END_SIMULATOR_SIGNATURE instructions. The signature is usually placed in the upper part of the simulator main source file, before the C++ class of the simulator.

Identification

The identification part of the signature must contain at least the ID of the simulator. This ID will be used by the framework to load simulators. It is declared in the signature as an argument of the BEGIN_SIMULATOR_SIGNATURE instruction. Other optional informations can be included for better description of the simulator:

See the Complete signature example part for detailed example.

Informations about scientific application

The informations about scientific applications are only indicative. It has no effects on simulator consistency or computational code. These informations can be :

Data and spatial graph

The data used by the simulators can be:

These data can be accessed, appended and/or modified by the simulator.
The spatial graph representing the landscape can also be accessed or modified by simulators during simulations.
The declarations of spatial data access include constraint levels:

Simulator parameters

Simulator parameters are values provided to each simulator, and are declared using the DECLARE_REQUIRED_PARAMETER or DECLARE_USED_PARAMETER instructions. These instructions takes 3 arguments

Example of a simulator parameter declaration:

DECLARE_REQUIRED_PARAMETER("meanspeed","mean speed to use","m/s")

Spatial attributes

Spatial attributes are constant properties attached to each spatial units, and are declared using DECLARE_REQUIRED_ATTRIBUTE, DECLARE_USED_ATTRIBUTE or DECLARE_PRODUCED_ATTRIBUTE instructions

These instructions take 4 arguments:

Example of attributes declaration:

DECLARE_REQUIRED_ATTRIBUTE("area","TU","area of the Test Units","m")
DECLARE_USED_ATTRIBUTE("landuse","OU","landuse of the Other Units","")

Simulation variables

Simulation variables are attached to spatial units. They are produced, accessed and modified by simulators during simulations. Accessed variables are declared using DECLARE_REQUIRED_VARIABLE or DECLARE_USED_VARIABLE instructions, produced variables are declared using DECLARE_PRODUCED_VARIABLE instruction, updated variables are declared using DECLARE_UPDATED_VARIABLE instruction.

These instructions take 4 arguments:

These variables can be typed or untyped. When they are declared in the signature, the variable names suffixed by the [] symbol with a type name enclosed are typed, i.e. each value for the variable must match the type of the variable. If no type is mentioned, values for the variable can be of any type. In case of typed variables, the type of a required or used variable by a simulator must match the type of the variable set when it is produced.

The type name for a declaration of a variable can be:

These scenarios of variable exchanges between two A and B simulators run successfully:

These scenarios of variable exchanges between two simulators are failing:

Example of variable declarations:

DECLARE_REQUIRED_VARIABLE("varA[double]","TU","","m")
DECLARE_USED_VARIABLE("varB","OU","simple var on Other Units","kg")
DECLARE_PRODUCED_VARIABLE("VarB[vector]","TU","vectorized var on Test Units","kg")
DECLARE_UPDATED_VARIABLE("VarC","TU","","")

Discrete events

Discrete events are attached to spatial units, They are accessed or appended by simulators during simulations, and are declared using the DECLARE_USED_EVENTS instruction.

The declaration instruction takes 1 argument: the units class.

Example of events declaration:

DECLARE_USED_EVENTS("TU")

Extra files

Simulators can declare files that they load and manage. This helps users to provide the needed files, and also notifies the OpenFLUID framework to check the presence of the file if it is required. These files are declared using the DECLARE_USED_EXTRAFILE or DECLARE_REQUIRED_EXTRAFILE instructions.

The declaration instruction takes 1 argument: the file name with relative path to the dataset path.

Example of extra file declarations:

DECLARE_USED_EXTRAFILE("fileA.dat")
DECLARE_REQUIRED_EXTRAFILE("geo/zone.shp")

Spatial units graph

The spatial units graph representing the landscape can be modified by simulators. These modifications are declared in the signature function using two instructions.

The DECLARE_UPDATED_UNITSGRAPH instruction is used for declaration of the global units graph modification that will occur during simulation. It is for information purpose only, and takes a description as a single argument.

The DECLARE_UPDATED_UNITSCLASS instruction is used for declaration of units classes that will be affected, and how. It takes two arguments:

Example of declarations for spatial units graph:

DECLARE_UPDATED_UNITSGRAPH("update of the spatial graph for ...")
DECLARE_UPDATED_UNITSCLASS("TU","")

Complete signature example

The signature code below shows an example of a possible signature for a simulator.

BEGIN_SIMULATOR_SIGNATURE("example.simulator")
DECLARE_NAME("Example simulator");
DECLARE_DESCRIPTION("This simulator is an example");
DECLARE_VERSION("13.05");
DECLARE_STATUS(openfluid::ware::EXPERIMENTAL);
DECLARE_AUTHOR("John","john@foobar.org");
DECLARE_AUTHOR("Dave","dave@foobar.org");
DECLARE_AUTHOR("Mike","mike@foobar.org");
DECLARE_USED_PARAMETER("meanspeed","mean speed to use","m/s")
DECLARE_REQUIRED_ATTRIBUTE("area","TU","area of the Test Units","m")
DECLARE_USED_ATTRIBUTE("landuse","OU","landuse of the Other Units","")
DECLARE_REQUIRED_VARIABLE("varA[double]","TU","","m")
DECLARE_USED_VARIABLE("varB","OU","simple var on Other Units","kg")
DECLARE_PRODUCED_VARIABLE("VarB[vector]","TU","vectorized var on Test Units","kg")
DECLARE_UPDATED_VARIABLE("VarC","TU","","")
DECLARE_USED_EVENTS("TU")
END_SIMULATOR_SIGNATURE