2. FluidX file(s) format

This part of the manual describes the FluidX file(s) format. Refer to the "Usage" part of this manual to run the simulation.

2.1 Overview

The FluidX file format is an XML based format for OpenFLUID input file(s). The OpenFLUID input information can be provided by a one or many files using the FluidX format.
Whatever the input information is put into one or many files, the following sections must be defined in the input file set:

• The model section defined by the <model> tag
• The spatial domain section defined by the <domain> tag
• The run configuration section defined by the <run> tag
• The outputs configuration section defined by the <output> tag

The order of the sections is not significant. All of these sections must be inclosed into an openfluid section defined by the <openfluid> tag.

2.2 Sections

2.2.1 Model

The flux model is defined by an ordered set of data generators and simulations functions that will be plugged to the OpenFLUID kernel. It defines the model for the simulation. It can also include a global parameters section which applies to all simulation functions and generators. The global parameters may be overridden by local parameters of simulation functions or generators.
The flux model must be defined in a section delimited by the <model> tag, and must be structured following these rules:

• Inside the <model> tag, there must be a set of <function>, <generator> and <gparams> tags
• Each <function> tag must bring a fileID attribute giving the identifier of the simulation function; the value of the fileID attribute must match the file name (without extension) of a reachable and pluggable simulation function.
• Each <function> tag may include zero to many <param> tags giving parameters to the function. 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 ; (semicolon).
• Each <generator> tag must bring a varname attribute giving the name of the produced variable, a unitclass 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.
• Each <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.
• A generator using the fixed method must provide a param named fixedvalue for the value to produce.
• A generator using the random method must provide a param named min and a param named max delimiting the random range for the value to produce.
• A generator using the 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 appendix).
• A generator using the inject 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 appendix).
• Each <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.

Warning: There must be only one model definition in the input dataset.

Warning: The order of the simulation functions and data generators in the <model> section is very important : the same order will be used for execution on the same time step

2.2.2 Spatial domain

2.2.2.1 Definition and relationships

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:

• Inside the <definition> tag, there must be a set of <unit> tags
• Each <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
• Each <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
• Each <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

2.2.2.2 Input data

The spatial domain input data are static data brought by units, usually properties and initial conditions for each unit.
The spatial domain input data must be defined in a section delimited by the <inputdata> tag, which is a sub-section of the domain tag, and must be structured following these rules:

• The <inputdata> tag must bring a unitclass attribute giving the unit class to which input data must be attached, and a colorder attribute giving the order of the contained column-formatted data
• Inside the <inputdata> tag, there must be the input data as row-column text. As a rule, the first column is the ID of the unit in the class given through the the unitclass attribute of <inputdata> tag, the following columns are values following the column order given through the colorder attribute of the <inputdata> tag. Values for the data can be real, integer or string.

Note: Old inputdata format, with <columns> and <data> tags are still useable. However, you are encouraged to use the new FluidX file format.

2.2.2.3 Discrete events

The discrete events are events occuring on units, and that can be processed by simulation functions. 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:

• Inside the <calendar> tag, there must be a set of <event> tags
• Each <event> tag must bring a unitID and a unitclass 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". The <event> tag may bring a name attribute and a a category attribute, but they are actually ignored.
• Each <event> tag may include zero to many <info> tags.
• Each <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.

2.2.3 Run configuration

The configuration of the simulation gives the simulation period, the data exchange time step, and the optionnal progressive output parameters.
The run configuration must be defined in a section delimited by the <run> tag, and must be structured following these rules:

• Inside the <run> tag, there must be a <deltat> tag giving the data exchange time step (in seconds)
• Inside the <run> tag, there must be a <period> tag giving the simulation period.
• The <period> tag must bring a begin and an end attributes, giving the dates of the beginning and the end of the simulation period. The dates formats for these attributes must be YYYY-MM-DD hh:mm:ss
• Inside the <run> tag, there may be a <valuesbuffer> tag for the number of time steps kept in memory. The number of step is given through a steps attribute. If not present, all values are kept in memory.
• Inside the <run> tag, there may be a <filesbuffer> tag for the size of the memory buffer for each file of results. The size is given in kilobytes through a kbytes attribute. If not present, the default value is 2KB.

2.2.4 Outputs configuration

The configuration of the simulation outputs gives the description of the saved results.
The outputs configuration must be defined in a section delimited by the <output> tag, and must be structured following these rules:

• Inside the <output> tag, there must be one to many <files> tags, defining files formats for saved data.
• These <files> tags must bring a colsep attribute defining the separator strings between columns, a dtformat attribute defining the date time format used (it could be 6cols, iso or user defined using strftime() format whis is described in the appendix part of this document), a commentchar attribute defining the string prefixing lines of comments in output files. A header attribute may be added giving the type of header in files. The values for this attribute can be none for no header, info for a header giving commented information about the data contained in the produced file(s), colnames-as-data for a first line in file giving names of each column, full for a complete header including both info and colnames-as-data headers (see appendix for examples). If no header attribute is present, info header is used.
• Inside the <files> tags, there must be one to many <set> tags. Each <set> tag will lead to a set of files.
• Each <set> tag must bring a name attribute defining the name of the set (this will be used as a suffix for generated output files), a unitsclass attribute and a unitsIDs attribute defining the processed units, a vars attribute defining the processed variables. It may also bring an a precision attribute giving the number of significant digits for the values in the outputs files. The IDs for the unitsIDs attribute are semicolon-separated, the wildcard character ('*') can be used to include all units IDs for the given class. The variables names for the vars attribute are semicolon-separated, the wildcard character ('*') can be used to include all variables for the given units class. The value for the precision attribute must be $\geq$ 0. If not provided, the default value for the precision is 5.