27. ComFLOW XML format specification¶

This chapter explains the XML input format used by ComFLOW and GEODEF.

Note

In versions 3.9.x it is still possible to use the old-style input file (${INPUT}/comflow.in). This feature is included for backwards compatibility only. Settings provided in the new-style XML input files (${INPUT}/grid.cfi and/or ${INPUT}/comflow.cfi) always get higher priority over the settings already provided in the old-style input file. It is therefore recommended to use the XML format whenever possible.

27.1. Getting started¶

If present, the program loads an additional (XML) input file ${INPUT}/comflow.cfi ¹. The basic format of this file is as follows:

<?xml version="1.0" encoding="utf-8"?>
<comflow version="@CURRENT_COMFLOW_VERSION@">
   <!-- ... -->
</comflow>

The first line denotes the XML version and character encoding of the file. All ComFLOW settings are specified inside the key /comflow/. For example, the grid settings are specified in the sub-key /comflow/grid/, the post-processing settings are specified in the sub-key /comflow/output/, etc.:

<?xml version="1.0" encoding="utf-8"?>
<comflow version="@CURRENT_COMFLOW_VERSION@">

<!--==============================================
==== GRID SETUP
===============================================-->
   <grid>
                       <!-- ... -->
   </grid>

<!--==============================================
==== POST-PROCESSING SETUP
===============================================-->
   <output>
                       <!-- ... -->
   </output>

<!--==============================================
==== ET CETERA
===============================================-->

</comflow>

As of version 4.1.1 it is possible (and recommended) to specify all simulation settings by means of the XML input format. Legacy input files are still supported for most of the functionality that was available in previous version. However, a large part of new functionality introduced in versions 4.0 and later is only supported by means of XML input.

ComFLOW makes no assumptions about the ordering of the individual XML keys, as long as they are nested properly as described in the examples and in the overview. All the keys and attributes are case insensitive.

If XML keys or attributes are omitted, default values are used where possible, otherwise an error message is produced pointing at the missing input data. For your own convenience, XML comments () can be added which will be ignored by ComFLOW.

During startup ComFLOW checks for the presence of any unknown or invalid key or attribute names and issues a warning if necessary. The output is printed to the console window and stored in the file ${OUTPUT}/comflow.out. We recommend the use of a text editor that supports XML syntax highlighting or utilities such as Microsoft XML Notepad.

A lot of parameters receive default values during startup of the ComFLOW program and therefore do not need to be specified in the XML input file. For example, if no gravitational field is specified, the default Earth’s gravity is used. This allows you to significantly reduce the size of the input file and focus on the settings that do matter most.

Any setting can be temporarily disabled by adding the postfix BAK or ORIG, for example:

<key attr="1" attrBAK="0"> </key>
<keyBAK> </keyBAK>

In this example the key keyBAK/ and the attribute @attrBAK are ignored by the ComFLOW XML parser, but are still available for back-up purposes.

27.2. Time intervals¶

Time intervals for simulation output (snapshots, monitors, restart files, etc.) are all specified using the same group of attributes:

`@nr`	Total number of requested output instances between `@tmin` and `@tmax`, i.e. this results in `@dt` = (`@tmax`-`@tmin`)/`@nr`.
`@dt`	Output interval. Setting this attribute overrules any input for the attribute `@nr`. Choosing `@dt` equal to 0 results in output for every simulation time step. A negative value is interpreted as undefined, in which case output is determined by `@nr`.
`@tmin`	Starting time for output
`@tmax`	End time for output.

27.3. Documentation of all XML statements¶

Note

Work in progress.

In the near future documentation will be available in the form of an XML schema file (.xsd) as well as a separate documentation web page based on this same schema file.

Footnotes

[1]	In several previous versions it was also possible to name the input file `${INPUT}/grid.cfi`. This is still supported for backwards compatibility.