Declaration of the simulator signature

Table of Contents

• Identification
• Informations about scientific application
• Data and spatial graph
  • Simulator parameters
  • Spatial attributes
  • Simulation variables
  • Discrete events
  • Extra files
  • Spatial units graph
• Complete signature example

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:

• the simulator name, declared through the DECLARE_NAME instruction, allowing to assign a long name to the simulator
• the simulator description, declared through the DECLARE_DESCRIPTION instruction, allowing to provide a detailed description of what the simulator actually does
• the name(s) of the author(s) and corresponding email address(es), declared through the DECLARE_AUTHOR instruction. There may be multiple DECLARE_AUTHOR instructions in the signature in case of multiple authors
• the software version of the simulator, declared through the DECLARE_VERSION instruction
• the software status of the simulator, declared through the DECLARE_STATUS instruction. The value can be openfluid::ware::EXPERIMENTAL, openfluid::ware::BETA or openfluid::ware::STABLE

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 :

• the domain in which the simulator can be applied, declared through the DECLARE_DOMAIN instruction
• the processes simulated by the simulator, declared through the DECLARE_PROCESS instruction
• the numerical methods used by the simulator, declared through the DECLARE_METHOD instruction

Data and spatial graph

The data used by the simulators can be:

• Parameters that are attached to the simulator
• Spatial attributes that are attached to spatial units, giving properties about the spatial units
• Simulation variables that are attached to spatial units, representing the resulting dynamics of modeled processes over the spatial units
• Discrete events that are attached to spatial units, representing the events occurring at a given date and time on a given spatial unit
• Specific file(s) loaded by the simulator

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:

• REQUIRED, this means that the data must be available or already produced
• USED, this means that the data are used only if they are available or already produced

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

• the name of the parameter
• the description of the parameter (may be empty)
• the SI unit of the parameter (may be empty)

Example of a declaration of a required simulator parameter:

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:

• the name of the attribute
• the units class
• the description of the attribute (may be empty)
• the SI unit of the attribute (may be empty)

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:

• the name of the variable
• the concerned unit class
• the description of the variable (may be empty)
• the SI unit of the variable (may be empty)

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:

• boolean for boolean values
• integer for long integer values
• double for double precision values
• string for string values
• vector for vector data
• matrix for matrix data
• map for associative key-value data
• tree for hierarchical key-value data

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

• simulator A produces an untyped variable var1, simulator B requires/uses/updates an untyped variable var1
• simulator A produces a typed variable var1, simulator B requires/uses/updates an untyped variable var1
• simulator A produces a typed variable var1 of type double, simulator B requires/uses/updates a typed variable var1 of type double

These scenarios of variable exchanges between two simulators are failing:

• simulator A produces an untyped variable var1, simulator B requires/uses/updates a typed variable var1
• simulator A produces a typed variable var1 of type double, simulator B requires/uses/updates a typed variable var1 of type matrix

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:

• the units class
• the description of the update (may be empty)

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("help.snippets.signature")

  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