Advanced users may want to change the configuration files directly rather than via the graphic interface.
Ichthyop simulations are configured using XML configuration files. These files should always start as follows:
<icstructure>
<long_name>Generic Ichthyop configuration file</long_name>
<description>The file has few pre-defined parameters.</description>
</icstructure>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. Chapter 6).RELEASE: Block of parameters related to the release classes (cf. Chapter 5)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 when running the Ichthyop code or not. By default, all blocks are enabled. But for the RELEASE and DATASET blocks, one and only one block must be enabled.
A list of parameters is associated to each block. This is added in the XML file as follows:
<parameters>
</parameters>Inside the <parameters> tag, 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 this parameter. The <default> tag provides the default value of the parameter. 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 foldersdate: 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 valuesinteger: 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 example:
<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 by default appears 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>In order to test different values of a given parameter, a serial tag can be added as follows:
<parameter type="serial">
</parameter>Different values are then 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>When simulations are run with serial parameters, all possible combinations of parameter values will be run. Output files will then contain a _sX suffix, with X the simulation number. The parameters used in a particular simulation X are provided as global NetCDF attributes in the corresponding _sX NetCDF output file.
Zone configuration files are also managed via a dedicated XML files. These files must be as follows:
<?xml version="1.0" encoding="UTF-8"?>
<zones>
</zones>Each zone is defined into a <zone> tag, which contain the following tags:
<key> is the name of the zone<enabled> specifies whether this zone must be activated by default or not.<type> specifies whether the zone should be used for release (release value, see Section 5.2) or recruitment (recruitment value)<polygon> specifies the different points used to define the zond area<bathy_mask> (optional) specifies a subset of zone area based on bathymetry (for example 0 to 200m, for using only the subset of zone area from 0 to 200 m depth)<thickness> (optional) specifies the upper and lower depths subsets of zone areas (only valid for 3D runs).<color> specifies the display color of the zone (format is [r=102,g=51,b=255]).<proportion_particles> (optional) specifies the percentage of total particles (values in \([0-1]\)) to be released in the area. This attribute is only used when type is release and if the user_defined_nparticles parameter is set to True (cf. Section 5.2)The sum of the values of proportion_particles over all the release zones should be 1!
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>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 minute when the simulation should start.
When reading a NetCDF input file, Ichthyop will determine the units in which NetCDF time is stored in this file. These units must meet the CF Metadata Conventions and therefore be provided as follows:
UNITS since YYYY-MM-DD HH:MM:SSwith 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 second 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 the CF conventions.
If it fails (i.e. the time::units attribute does not follow the CF conventions) or if no time::units attribute is provided in the input file, Ichthyop will read the time_origin parameter from the app.time option block, which must be defined following the CF conventions.
When reading two different NetCDF input files (for example one providing the ocean currents and one provinding surface winds), if none meets the CF convention, Ichthyop will apply the units defined in the time_origin parameter of Ichthyop configuration file to both, even though they may have different time units. Therefore, in this case, it is strongly recommended to include CF-like time units attributes manually to each file (cf. below).
This 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
doneThis 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, unlimited_dims='time')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
Note that it is possible to assess the time values of a NetCDF time as follows:
import xarray as xr
data = xr.open_dataset('../input/roms-benguela.nc')
data['scrum_time'].valuesarray(['1900-05-02T12:00:00.000000000', '1900-05-05T12:00:00.000000000',
'1900-05-08T12:00:00.000000000', '1900-05-11T12:00:00.000000000',
'1900-05-14T12:00:00.000000000', '1900-05-17T12:00:00.000000000',
'1900-05-20T12:00:00.000000000', '1900-05-23T12:00:00.000000000',
'1900-05-26T12:00:00.000000000', '1900-05-29T12:00:00.000000000'],
dtype='datetime64[ns]')The above works if the NetCDF file follows the CF convention, i.e. if it contains a unit and a calendar attribute.
If it does not, you will have numerical values. You need to convert it manually by providing the unit in CF form as follows.
import cftime
units = 'seconds since 1900-01-01 00:00'
calendar = 'gregorian'
data = xr.open_dataset('../input/roms-benguela.nc', decode_times=False)
cftime.num2date(data['scrum_time'].values, units, calendar)array([cftime.DatetimeGregorian(1900, 5, 2, 12, 0, 0, 0, has_year_zero=False),
cftime.DatetimeGregorian(1900, 5, 5, 12, 0, 0, 0, has_year_zero=False),
cftime.DatetimeGregorian(1900, 5, 8, 12, 0, 0, 0, has_year_zero=False),
cftime.DatetimeGregorian(1900, 5, 11, 12, 0, 0, 0, has_year_zero=False),
cftime.DatetimeGregorian(1900, 5, 14, 12, 0, 0, 0, has_year_zero=False),
cftime.DatetimeGregorian(1900, 5, 17, 12, 0, 0, 0, has_year_zero=False),
cftime.DatetimeGregorian(1900, 5, 20, 12, 0, 0, 0, has_year_zero=False),
cftime.DatetimeGregorian(1900, 5, 23, 12, 0, 0, 0, has_year_zero=False),
cftime.DatetimeGregorian(1900, 5, 26, 12, 0, 0, 0, has_year_zero=False),
cftime.DatetimeGregorian(1900, 5, 29, 12, 0, 0, 0, has_year_zero=False)],
dtype=object)In R, you should be able to see the dates as follows, providing the units as a combination of arguments to the as.POSIXct and as.difftime functions.
library(ncdf4)
# Open the NetCDF file
nc <- nc_open("../input/roms-benguela.nc")
# Read the time variable
scrum_time <- ncvar_get(nc, "scrum_time")
nc_close(nc)
# Define the origin (equivalent to 'seconds since 1900-01-01 00:00')
origin <- as.POSIXct("1900-01-01 00:00:00", tz = "UTC")
# Convert numeric seconds to datetime (equivalent to cftime.num2date)
dates <- origin + as.difftime(scrum_time, units = "secs")To check whether the file has these attributes, you can see the file metadata using ncdump -h on Linux/Mac or visualize the file using the Panoply software