 |
|
This part of the manual describes the FluidX file(s) format used to define a simulation dataset. Refer to the Overview of OpenFLUID applications part of this manual to run the simulations.
An OpenFLUID input dataset includes different informations, defined in one or many files:
All files must be placed into a directory that can be reached by the OpenFLUID program used.
As OpenFLUID-Builder uses the FluidX format natively, the entire input dataset can be created through the OpenFLUID-Builder software.
Out of OpenFLUID-Builder, these FluidX files can be created by hand or using external tools. In this case, it is encouraged to write custom scripts in dedicated software, such as Geographic Information Systems (GIS) or scientific environments such as R.
The FluidX file format is an XML based format for OpenFLUID input datasets. The OpenFLUID input information can be provided by a one or many files using this FluidX formatn with the .fluidx file extension.
Whatever the input information is put into one or many files, the following sections must be defined in the input file(s) set:
<model> tag <domain> tag <run> tag <monitoring> tag The order of these sections is not significant. All of these sections must be inclosed into an openfluid section defined by the <openfluid> tag.
Summary view of the XML structure of FluidX files:
The coupled model is defined by an ordered set of simulators and/or data generators that will be automatically plugged and run by the OpenFLUID environment. It can also include a section for global parameters which apply to all simulators and generators. The global parameters may be overridden by local parameters of simulators or generators.
The coupled model must be defined in a section delimited by the <model> tag, and must be structured following these rules:
<model> tag, there must be a set of <simulator>, <generator> and <gparams> tags <simulator> tag must bring an ID attribute giving the identifier of the simulator; the value of the ID attribute must match the ID of an available and pluggable simulator. <simulator> tag may include zero to many <param> tags giving parameters to the simulator. Each <param> tag must bring a name attribute giving the name of the parameter and a value attribute giving the value of the parameter. These parameters can be scalar or vector of integer values, floating point values, string values. In case of vector, the values of the vector are separated by a <generator> tag must bring a varname attribute giving the name of the produced variable, a unitsclass attribute giving the unit class of the produced variable, a method attribute giving the method used to produce the variable (fixed for constant value, random for random value in a range, interp for a time-interpolated value from given data series, inject for an injected value -no time interpolation- from given data series). An optional <varsize> attribute can be set in order to produce a vector variable instead of a scalar variable. <generator> tag may include zero to many <param> tags giving parameters to the generator. Each <param> tag must bring a name attribute giving the name of the parameter and a value attribute giving the value of the parameter. fixed method must provide a param named fixedvalue for the value to produce. random method must provide a param named min and a param named max delimiting the random range for the value to produce. inject or interp method must provide a param named sources giving the data sources filename and a param named distribution giving the distribution filename for the value to produce (see also File formats for "interp" or "inject" generators). <gparams> tag may include zero to many <param> tags giving the global parameters. Each <param> tag must bring a name attribute giving the name of the parameter and a value attribute giving the value of the parameter. <model> section is important : this order will be the call order at initialization time, and the permanent call order in synchronized coupled model (not applicable for variable time coupled models)The spatial domain is defined by a set of spatial units that are connected each others. These spatial units are defined by a numerical identifier (ID) and a class. They also include information about the processing order of the unit in the class. Each unit can be connected to zero or many other units from the same or a different unit class. The spatial domain definition must be defined in a section delimited by the <definition> tag, which is a sub-section of the domain tag, and must be structured following these rules:
<definition> tag, there must be a set of <unit> tags <unit> tag must bring an ID attribute giving the identifier of the unit, a class attribute giving the class of the unit, a pcsorder attribute giving the process order in the class of the unit <unit> tag may include zero or many <to> tags giving the outgoing connections to other units. Each <to> tag must bring an ID attribute giving the identifier of the connected unit and a class attribute giving the class of the connected unit <unit> tag may include zero or many <childof> tags giving the parent units. Each <childof> tag must bring an ID attribute giving the identifier of the parent unit and a class attribute giving the class of the parent unit The spatial attributes are static data associated to each spatial unit, usually properties and initial conditions.
The spatial domain attributes must be defined in a section delimited by the <attributes> tag, which is a sub-section of the domain tag, and must be structured following these rules:
<attributes> tag must bring an unitsclass attribute giving the unit class to which the attributes must be attached, and a colorder attribute giving the order of the contained column-formatted data <attributes> tag, there must be the attributes as row-column text. As a rule, the first column is the ID of the unit in the class given through the unitsclass attribute of <attributes> tag, the following columns are values following the column order given through the colorder attribute of the <attributes> tag. Values for the data can be real, integer, string, vector or matrix. The discrete events are events occurring on units, and can be processed by simulators. The spatial events must be defined in a section delimited by the <calendar> tag, which is a sub-section of the <domain> tag, and must be structured following these rules:
<calendar> tag, there must be a set of <event> tags <event> tag must bring an unitID and an unitsclass attribute giving the unit on which occurs the event, a date attribute giving the date and time of the event. The date format must be "YYYY-MM-DD hh:mm:ss". <event> tag may include zero to many <info> tags. <info> tag give information about the event and must bring a key attribute giving the name (the "key") of the info, and a value attribute giving the value for this key. The datastore lists external data which is available during the simulation. The datastore content must be defined in a section delimited by the <datastore> tag, and must be structured following these rules:
<datastore> tag, there must be a set of <dataitem> tags <dataitem> tag must bring an ID attribute giving the unique identifier of the dataitem, a type attribute giving the type of the dataitem (only the geovector and georaster types are currently available), and a source attribute giving the source of the dataitem. An optional unitsclass attribute is possible for giving the spatial unit class associated to the data. The monitoring is defined by a set of observers that will be automatically plugged and executed by the OpenFLUID environment. Observers are usually used for exporting formatted data from the simulation or performs continuous control during the simulation.
The monitoring must be defined in a section delimited by the <monitoring> tag, and must be structured following these rules:
<monitoring> tag, there may be a set of <observer> tags <observer> tag must bring an ID attribute giving the identifier of the observer; the value of the ID attribute must match the ID of an available and pluggable observer. <observer> tag may include zero to many <param> tags giving parameters to the observer. Each <param> tag must bring a name attribute giving the name of the parameter and a value attribute giving the value of the parameter. These parameters can be scalar or vector of integer values, floating point values, string values. The configuration of the simulation gives the simulation period, the default coupling time step and the optional coupling constraint. The run configuration must be defined in a section delimited by the <run> tag, and must be structured following these rules:
<run> tag, there must be a <scheduling> tag giving the scheduling informations of the model coupling. <scheduling> tag must bring a deltat attribute giving the number of second for the default DeltaT time step, and a constraint attribute giving an optional constraint applied to the coupling. The values for the constraint attribute can be none for no constraint, dt-checked to check that coupling is synchronized with the default DeltaT time step, dt-forced to force coupling at the default DeltaT time step ignoring the scheduling requests from simulators or generators. <run> tag, there must be a <period> tag giving the simulation period. <period> tag must bring a begin and an end attributes, giving the dates of the beginning and the end of the simulation period. The date format for these attributes must be YYYY-MM-DD hh:mm:ss <run> tag, there may be a <valuesbuffer> tag for the number of produced values kept in memory. The number of values is given through a size attribute. If not present, all values are kept in memory. Parameters of simulators and observers can include variables that will be replaced by corresponding values at runtime. These variables are :
${dir.input} is replaced by the complete path to the input dataset directory ${dir.output} is replaced by the complete path to the output results directory ${dir.temp} is replaced by the complete path to the directory dedicated to temporary files
1.8.13