1. File formats

This part of this manual describes the file formats. Refer to the "Usage" part of this manual to run the simulation.

1.1 Spatial domain definition (*.ddef.xml)

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 preocessing 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.
This information is defined through XML files that must end with the suffix .ddef.xml. All the files in the dataset named using this suffix will be read and considered as spatial domain definition files, and must be structured following these rules:

• These files are XML files
• The root tag must be <openfluid>
• Inside the <openfluid> tag, there must be a <domain> tag
• Inside the <domain> tag, there must be a <definition> tag
• 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 <class>
• 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

<?xml version="1.0" standalone="yes"?>
<openfluid>
  <domain>
    <definition>
      <unit class="SU" ID="1" pcsorder="1">
        <to class="SU" ID="2" />
      </unit>
      <unit class="SU" ID="2" pcsorder="2">
        <to class="RS" ID="1" />
      </unit>
      <unit class="SU" ID="3" pcsorder="1">
        <to class="RS" ID="2" />
      </unit>
      <unit class="RS" ID="1" pcsorder="1">
        <to class="RS" ID="2" />
      </unit>
      <unit class="RS" ID="2" pcsorder="1">
      </unit>
    </definition>
  </domain>
</openfluid>

1.2 Flux model definition (model.xml)

The flux model is defined by an ordered set of simulations functions that will be plugged to the OpenFLUID-Engine kernel. It defines the model for the simulation.
The flux model must be defined in a file named model.xml, and must be structured following these rules:

• The model.xml file is an XML file
• The root tag must be <openfluid>
• Inside the <openfluid> tag, there must be a <model> tag
• Inside the <domain> tag, there must be a set of <function> tags
• Each <function> tag must bring a <fileID> attr
• ibute 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).

The order of the simulation functions in the model.xml is very important : the same order will be used for executions on the same time step

<?xml version="1.0" standalone="yes"?>
<openfluid>
    <model>
   
      <function fileID="water.atm-surf.rain-su.files" />

      <function fileID="water.surf-uz.runoff-infiltration.mseytoux" >
        <param name="resstep" value="0.000005" />          
      </function>

      <function fileID="water.surf.transfer-su.hayami"> 
        <param name="maxsteps" value="100" />
        <param name="meancel" value="0.045" />
        <param name="meansigma" value="500" />                                                                                   
      </function>   
    
  </model>
</openfluid>

1.3 Spatial domain input data (*.ddata.xml)

The spatial domain input data are static data brought by units, usually properties and initial conditions for each unit.
This information is defined through XML files that must end with the suffix .ddata.xml. All the files in the dataset named using this suffix will be read and considered as spatial domain input data files, and must be structured following these rules:

• These files are XML files
• The root tag must be <openfluid>
• Inside the <openfluid> tag, there must be a <domain> tag
• Inside the <domain> tag, there must be one (and only one) <inputdata> tag
• The <inputdata> tag must bring a <unitclass> attribute giving the unit class to which input data must be attached
• Inside the <inputdata> tag, there must be one (and only one) <columns> tag
• The <columns> tag must bring a <order> attribute defining the order of the columns in the <data> tag.
• Inside the <inputdata> tag, there must be one (and only one) <data> tag containing 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 <inputdata> tag, the following columns are values following the column order given through the <columns> tag.

<?xml version="1.0" standalone="yes"?>
<openfluid>
  <domain>
    <inputdata unitclass="SU">
      <columns order="ks;hc;betaMS;thetares;thetasat;nmanning" />
      <data>

1	0.000001	0.1	1.3	0.02	0.36	0.05
2	0.000001	0.1	1.3	0.02	0.36	0.05
3	0.000001	0.1	1.3	0.02	0.36	0.05
4	0.000001	0.1	1.3	0.02	0.36	0.05
5	0.000001	0.1	1.3	0.02	0.36	0.05
6	0.000001	0.1	1.3	0.02	0.36	0.05
7	0.000001	0.1	1.3	0.02	0.36	0.05

      </data>
    </inputdata>
  </domain>  
</openfluid>

1.4 Discrete events (*.events.xml)

The discrete events are events occuring on units, and that can be processed by simulation functions. They are defined through calendars in XML files that must end with the suffix .events.xml. All the files in the dataset named using this suffix will be read and considered as spatial domain input data files, and must be structured following these rules:

• These files are XML files
• The root tag must be <openfluid>
• Inside the <openfluid> tag, there must be a <calendar> tag
• 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.

<?xml version="1.0" standalone="yes"?>
<openfluid>
  <calendar>
  
    <event name="" category="test" unitclass="SU" unitID="1" date="1999-12-31 23:59:59">
      <info key="when" value="before"/>
      <info key="where" value="1"/>
      <info key="var1" value="1.13"/>
      <info key="var2" value="EADGBE"/>
    </event>
    <event name="" category="test" unitclass="RS" unitID="1" date="1999-12-01 12:00:00">
      <info key="when" value="before"/>
      <info key="where" value="1"/>
      <info key="var3" value="152.27"/>
      <info key="var4" value="XYZ"/>
    </event>        
    <event name="" category="test" unitclass="SU" unitID="2" date="1999-12-01 12:00:00">
      <info key="when" value="before"/>
      <info key="where" value="7"/>
      <info key="var1" value="1.15"/>
      <info key="var2" value="EADG"/>
    </event>    

  </calendar>
</openfluid>

1.5 Run configuration(run.xml)

The configuration of the simulation gives the simulation period, the data exchange time step, and the optionnal progressive output parameters.
The configuration of the simulation must be defined in a file named run.xml, and must be structured following these rules:

• The run.xml file is an XML file
• The root tag must be <openfluid>
• Inside the <openfluid> tag, there must be a <run> tag
• 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 <progressout> tag giving the configuration for the progressive output mode. This <progressout> tag must bring a packet attribute giving the size (in number of time steps) of the saved packets, and a keep attribute giving the number of time steps kept in memory.

<?xml version="1.0" standalone="yes"?>
<openfluid>
  <run>

    <deltat>3600</deltat>
    <period begin="2000-01-01 00:00:00" end="2000-03-27 01:12:37" />
    
    <progressout packet="10" keep="2" />
    
  </run>
</openfluid>

1.6 Outputs configuration(output.xml)

The configuration of the simulation outputs gives the description of the saved results.
The configuration of the outputs must be defined in a file named output.xml, and must be structured following these rules:

• The run.xml file is an XML file
• The root tag must be <openfluid>
• Inside the <openfluid> tag, there must be a <output> tag
• 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), a commentchar attribute defining the string prefixing lines of comments in output files.
• 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. 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 class.

<?xml version="1.0" standalone="yes"?>
<openfluid>
  <output>

    <!-- dtformat can be predefined (6cols,iso) or using the strftime() format, default is iso -->
    <!-- colsep default is \t -->
    <files colsep=" " dtformat="%Y %m %d %H %M %S" commentchar="%">     
      <set name="testRS" unitsclass="RS" unitsIDs="51;232" vars="*" />-->
      <set name="full" unitsclass="SU" unitsIDs="*" vars="*" />
    </files>  

  </output>
</openfluid>