Inputs and Configuration Configuration Files

Configuration files

To run Osmose, specifying the path to an Osmose configuration file is required. An Osmose configuration file is a text based file that will gather all essential parameters required for the model.

The configuration file name does not matter, but we recommend avoiding any special characters and spaces in the file name as it may cause IO errors when running Osmose from the command line, or when calibrating the model in a UNIX environment. The file extension does not matter either to run the model, even though the .R format file is currently the preferred extension.

Configuration files can contain comments, empty lines and parameters. When running, Osmose will scan each line of the configuration file looking for parameters and will automatically discard empty lines (regardless of blank or tab characters) and lines that start with a punctuation character, such as !"#$%&'()*+,-./:;<=>?@[\]^_{|}~.

Tip

For comments, it is recommended to start the line with # or //

Parameters

Any parameter in the configuration file is formed by the combination of three elements: a key, a separator and a value.

Key

Parameter keys can be any sequence of characters, without spaces or special characters (dot, hyphen and underscore are accepted). Example of keys:

simulation.ncpu
predation.ingestion.rate.max.sp6

Osmose makes no difference between upper and lower cases in key names; all of simulation.ncpu, simulation.Ncpu, Simulation.nCPU and SIMULATION.NCPU refer to the same key.

Separators

Separators can be any of the following:

• equals =
• semicolon ;
• comma ,
• colon :
• tab \\t

Parameters in the same configuration file can have different separators (although it is advisable to be consistent and use the same one). The configuration manager will work out what the delimiter is for each parameter.

Value

The value can be any sequence of characters (even empty). The configuration manager does not attempt to interpret the value when loading the configuration files. It simply stores it as a string object. A value can be passed to the configuration manager as:

• a string
• an integer
• a float
• a double
• a boolean
• an array of strings
• an array of integers
• an array of floats
• an array of doubles
• a resolved path

An array of values is a sequence of values with a separator in between. Accepted separators for an array of values are the same as the characters listed above. The separator for an array of values can either be the same or distinct from the separator between the key and the value. The following examples are valid entries:

movement.map0.season;0;1;2;3;4;5
movement.map0.season=0;1;2;3;4;5
movement.map0.season = 0, 1, 2, 3, 4, 5
movement.map0.season : 0 ; 1 ; 2;3;4;5

These examples are all identical to the configuration manager, and can be summarised as:

key separator1 value1 separator2 value2 separator2 value3 separator2 value4

with separator1 either equal or different from separator2.

Specific cases

Decimal separator

Osmose is quite flexible in terms of separators for the configuration files (automatically detected), the CSV output files (user-defined by parameter output.csv.separator) and the CSV input files (automatically detected). On the contrary it restricts the decimal separator to dot, and only dot.

Example given: 3.14159265 or 1.618

Any other decimal separator (COMMA for instance as in French locale) will be misunderstood and will unmistakably lead to errors. One must be careful when editing CSV input files (either parameters or time series) with tools, such as spreadsheets or excel, that may automatically replace decimal separator depending on the locale settings. Future Osmose releases may allow the use of a specific locale but for now remember that DOT is the only accepted decimal separator.

CSV input file separator

Many Osmose parameters are paths to CSV file, for instance:

movement.map0.file
mortality.fishing.rate.byDt.byAge.file.sp#
reproduction.season.file.sp#

CSV input file separators can be any of the following characters:

• equals =
• semicolon ;
• comma ,
• colon :
• tab \\t

Osmose will detect the separator automatically and independently for every CSV file. It means that one CSV input file may be comma separated and another one may be tab-separated.

Single or multiple configuration files

Finally, Osmose offers users the choice to either structure the model parameters into either an unique configuration file or into multiple configuration files. As Osmose requires a large number of parameters that can quickly increase according to the number of species involved in the model; the module or modules implemented, or other specificities, splitting the configuration file into multiple smaller ones can be more convenient. This can improve the ease of use, for example by grouping similar parameters together into a specific configuration file.

This procedure is done by using specific keys starting with osmose.configuration. in a main configuration file. These keys have a special meaning for the configuration manager as their values refer to the path of other auxiliary Osmose configuration files. When running Osmose, the configuration manager will therefore load all parameters from these auxiliary configuration files and other linked configuration files.

Warning

Path parameters are always defined relative to the configuration file where they are defined

Tip

Find the guideline to build your own Osmose configuration script here (Guideline for an Osmose configuration v4.3.3).