The signature can be automatically generated through the OpenFLUID plugin for Eclipse. However it is possible to write the signature de novo, or complete it manually.
The signature has to be defined between the BEGIN_SIMULATOR_SIGNATURE and the END_SIMULATOR_SIGNATURE macros.
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 macro.
Other optional informations can be included for better description of the simulator:
See the Complete signature example part for detailed example.
The informations about scientific applications is only indicative. It has no effects on simulator consistency or computational code. These informations can be :
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 rules:
Simulator parameters are values provided to each simulator, and are declared using the DECLARE_SIMULATOR_PARAM macro. This macro takes 3 arguments
Example of simulator parameter declaration:
DECLARE_SIMULATOR_PARAM("meanspeed","mean speed to use","m/s")
Spatial attributes are constant properties attached to each spatial units, and are declared using #DECLARE_REQUIRED_ATTRIBUTEor DECLARE_USED_ATTRIBUTE macros
These macros 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 are attached to spatial units. They are produced, accessed and modified by simulators during simulations.
Accessed variables are declared using #DECLARE_REQUIRED_VARor DECLARE_USED_VAR macros, produced variables are declared using DECLARE_PRODUCED_VAR macro, updated variables are declared using DECLARE_UPDATED_VAR macro.
These macros 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:
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 keys-value data These scenarios of variable exchanges between two A and B simulators run successfully:
double
, simulator B requires/uses/updates a typed variable var1 of type double
These scenarios of variable exchanges between two simulators are failing:
double
, simulator B requires/uses/updates a typed variable var1 of type matrix
Example of variable declarations
DECLARE_REQUIRED_VAR("varA[double]","TU","","m") DECLARE_USED_VAR("varB","OU","simple var on Other Units","kg") DECLARE_PRODUCED_VAR("VarB[vector]","TU","vectorized var on Test Units","kg") DECLARE_UPDATED_VAR("VarC","TU","","")
Discrete events are attached to spatial units, They are accessed or appended by simulators during simulations, and are declared using the DECLARE_USED_EVENTS macro.
The declaration macro takes 1 argument: the units class.
Example of events declaration:
DECLARE_USED_EVENTS("TU")
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 macros.
The declaration macro 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")
The spatial units graph representing the landscape can be modified by simulators. These modifications are declared in the signature function using two macros.
The DECLARE_UPDATED_UNITSGRAPH macro 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 macro 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","")
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_SIMULATOR_PARAM("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_VAR("varA[double]","TU","","m") DECLARE_USED_VAR("varB","OU","simple var on Other Units","kg") DECLARE_PRODUCED_VAR("VarB[vector]","TU","vectorized var on Test Units","kg") DECLARE_UPDATED_VAR("VarC","TU","","") DECLARE_USED_EVENTS("TU") END_SIMULATOR_SIGNATURE