2 Ichthyop configuration

2.1 Simulation configuration file

Ichthyop simulations are configured using XML configuration files. It should always start as follows:

<icstructure>
<long_name>Generic Ichthyop configuration file</long_name>
<description>The file has few pre-defined parameters.</description>

</icstructure>

2.1.1 Configuration blocks

Ichthyop is configured by blocks, each block managing a specific aspect of the model. The blocks are as follows:

ACTION: Block of parameters related to the action classes (cf. {numref}process).
RELEASE: Block of parameters related to the release classes (cf. {numref}release)
DATASET: Block of parameters related to the datasets classes.
OPTION: Block of parameters related to the remaining parameters.

New blocks can be added in the XML file as follows:

<block type="option">
        <key>app.transport</key>
        <enabled>true</enabled>
        <tree_path>Transport/General</tree_path>
        <description>Set the general transport options of the simulation.</description>
</block>

The key tag is used to identify the configuration block. The tree_path tag is used in the Ichthyop console to create the parameter tree. The description field is used to display the block description in the Ichthyop console.

The enabled tag specifies whether the block should be considered by Ichthyop or not. By default, all blocks are enabled. But for the RELEASE and DATASET, one and only one block must be activated.

2.1.2 Configuration parameters

To each block is associated a list of parameters. This list of parameter is added in the XML as follows:

<parameters>
</parameters>

Inside the parameters tags, new parameters are defined as follows:

<parameter>
    <key>output_path</key>
    <value>output</value>
    <long_name>Output path</long_name>
    <format>path</format>
    <default>output</default>
    <description>Select the folder where the simulation NetCDF output file should be saved.</description>
</parameter>

The key tag allows to identify the parameter, while the value tag specifies the value of the parameter. The remaining tags are only used by the Ichthyop console. The long_name and description tags are used by the console to provide informations about the parameter.

The format tag specifies the parameter format, which will be used by the console parameter editor. The accepted values are:

path: For files and folders
date: For dates (format must be year YYYY month MM day at HH:MM)
duration: For duration (format must be ###### day(s) ### hour(s) ### minute(s))
float: For real values
integer: For integer values.
class: For class parameters. It allow the user to choose an existing Ichthyop class in the configuration file.
list: For a list of string parameters, separated by ,
boolean: For boolean parameters. It allows the user to select true or false using a simple combo box.
combo: For parameters with a limited set of values, which can be selected in the console with a combo box.
lonlat: For geographical coordinates.

In the case of combo parameters, the list of accepted parameters is specified by providing as many accepted tags as necessary. For instance:

<parameter>
    <key>time_arrow</key>
    <long_name>Direction of the simulation</long_name>
    <value>forward</value>
    <format>combo</format>
    <accepted>backward</accepted>
    <accepted>forward</accepted>
    <default>forward</default>
    <description>Run the simulation backward or forward in time.</description>
</parameter>

If a parameter should appear as hidden in the Ichthyop console, it can be specified by adding the hidden="true" argument to the parameter tag, as shown below:

<parameter hidden="true">
</parameter>

2.1.3 Serial parameters

In order to test different values for a given parameter, a serial tag can be added as follows:

<parameter type="serial">
</parameter>

Different values are provided by replicating the value parameter as follows:

<parameter type="serial">
  <key>initial_time</key>
  <long_name>Beginning of simulation</long_name>
  <value>year 2001 month 10 day 20 at 00:00</value>
  <value>year 2001 month 10 day 21 at 00:00</value>
  <format>date</format>
  <description>Set the beginning date and time of the simulation. Format: year ###### month ### day ### at HH:mm.</description>
</parameter>

Caution

Using the GUI, additionnal values can be provided to serial parameters only when hidden parameters are displayed

When simulations are run with serial parameters, all possible combinations of parameters will be run. Output files will contain a _sX suffix, with X the simulation number. The parameters used in the simulation are provided as global NetCDF attributes.

2.2 Zone configuration file

Zone configuration files are also managed via a dedicated XML file. The file must be as follows:

<?xml version="1.0" encoding="UTF-8"?>
<zones>

</zones>

Each zone is defined on a zone tag, which contain the following tags:

key is the name of the zone
enabled specifies whether this zone must be considered or not.
type specifies whether the zone should be used for release (see :numref:, ``release value) or recruitment processes (recruitment value)
polygon specifies the different points used to define the area
bathy_mask specifies the bathymetric zone (for instance 0 to 200m, i.e. continental shelf) where the zone is defined.
thickness specifies the upper and lower depths where this zone is defined (only valid for 3D runs).
color specifies the display color of the zone (format is [r=102,g=51,b=255]).
proportion_particles specifies the proportion (values in \([0-1]\)) of particles to be released in the area. Only used when type is release and if the user_defined_nparticles parameter is set to True (cf. {numref}zone-release)

An example of a zone definition is provided below.

<zone>
    <key>Release zone 2</key>
    <enabled>true</enabled>
    <type>release</type>
    <polygon>
        <point>
            <index>0</index>
            <lon>54.0</lon>
            <lat>-11.5</lat>
        </point>
        <point>
            <index>1</index>
            <lon>54.0</lon>
            <lat>-12.5</lat>
        </point>
        <point>
            <index>2</index>
            <lon>53.0</lon>
            <lat>-12.5</lat>
        </point>
        <point>
            <index>3</index>
            <lon>53.0</lon>
            <lat>-11.5</lat>
        </point>
    </polygon>
    <bathy_mask>
        <enabled>true</enabled>
        <line_inshore>0.0</line_inshore>
        <line_offshore>12000.0</line_offshore>
    </bathy_mask>
    <thickness>
        <enabled>true</enabled>
        <upper_depth>0.0</upper_depth>
        <lower_depth>50.0</lower_depth>
        </thickness>
    <color>[r=102,g=51,b=255]</color>
    <proportion_particles>0.2</proportion_particles>
</zone>

2.3 Time configuration

2.3.1 Beginning of the simulation

In Ichthyop, the user provides the time at which the simulation should start. This initial_time parameter, which must be defined in the app.time option block, must be formatted as year YYYY month MM day DD at HH:MM, with YYYY the year, MM the month, DD the day, HH the hour and MM the minutes where the simulation should start.

2.3.2 Reading NetCDF times

When reading a NetCDF file (ocean currents, temperature, wind, wave, etc.), Ichthyop will determine the units in which NetCDF time is stored. These units must meet the CF Metadata Conventions and therefore be provided as follows:

UNITS since YYYY-MM-DD HH:MM:SS

with UNITS the units in which the time is stored (usually seconds, days or hours), YYYY the year, MM the month, DD the day, HH the hour, MM the minutes and SS the seconds of the reference date.

If a NetCDF time::units attribute is defined, Ichthyop will try to infer the NetCDF reference date and time units using this convention.

If it fails (i.e. the time::units attribute does not follow the convention) or if no time::units attribute is found, Ichthyop will read the time_origin parameter from the app.time option block, which must be defined following the CF conventions.

Caution

When reading two datasets (an ocean currents dataset and a wind dataset for instance), if none meets the CF convention, Ichthyop will apply the units defined in the time_origin parameter to both datasets, even though they may have different time units. Therefeore, in this case, it is strongly recommended to manually include CF-like time units attributes to each dataset (cf. below).

Manually updating the units attribute can be done by using the ncatted command (Linux users):

#!/bin/bash
for file in *nc
do
    ncatted -O -a units,time,o,s,"seconds since 1900-01-01 00:00:00" $file
done

This can also be done by using Python as follows:

from glob import glob
import xarray as xr

units = 'seconds since 1900-01-01 00:00:00'
time = 'time'

filelist = glob('*nc')

for f in filelist:

    data = xr.open_dataset(f)
    data[time].attrs['units'] = units
    data[time]

    data.to_netcdf(f)

Note

The user must replace time by the name of the time variable which is used by Ichthyop. Common values are time, scrum_time, time_counter, ocean_time.

The units value must also be chosen consistently with the dataset