Description of the input parameters (Osmose 3)

This document describes all the input parameters from Osmose 3 (2013).

Format and organization of the input files

An Osmose configuration file is a text based file. The name of the file does not matter, but we recommend that you avoid any special characters and space in the name of the file as it might generate IO errors when you'll be running Osmose from the command line or calibrating the model in a UNIX environment.  The extension of the file does not  matter either.

We call the main configuration file the file that is either listed in Osmose filePath.txt (see Getting started with Osmose 3: install and run if you wonder what the filePath.txt is) or given as a command line argument. The main configuration file can contain comments, blank lines and parameters. Here is how the Osmose configuration manager proceeds when it opens the main configuration file. It scans every line of the file looking for parameters. Some lines are automatically discarded:

  • empty lines (regardless of blank or tab characters).
  • lines that start with a punctuation character, one of !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~

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

A parameter is formed by the juxtaposition of three elements: key, separator and value.

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


Osmose makes no difference between upper and lower case: simulation.ncpu, simulation.Ncpu, Simulation.nCPU, SIMULATION.NCPU designate the same key.

Keys starting with osmose.configuration.* (the star * being any sequence of characters that follow the same rules than any other key) has a special meaning to the configuration manager. It means the value of this parameter is the path of an other Osmose configuration file and the parameters in this file are to be loaded in the current configuration. That way, instead of having one big configuration file with all the parameters, it is possible to split the parameters in as many files as the user wishes. This process works recursively: one file contains one or several parameters osmose.configuration.* that point to configuration files that may contains one or several parameters osmose.configuration.*, and so on. OSMOSE handles the sub-configuration file exactly the same way as it handles the main configuration file (same convention for comments, special caracters and naming of ). As mentionned previously, the main configuration file designates the file that is listed in filePath.txt or given to Osmose as an input argument.

The separator can be any of the following characters:

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

Parameters in the same configuration file can have different separators (though it is advisable to be consistent and use the same one). The configuration manager finds out what is the separator for each parameter. The value can be any sequence of characters (even empty). The configuration manager does not try to interpret the value when it loads the configuration files, it merely stores it in a String object. A value can be served by the configuration manager as

  • a string
  • an integer
  • a float
  • a double
  • a boolean
  • an array of strings, String[]
  • an array of integers, int[]
  • an array of floats, float[]
  • an array of doubles, double[]
  • a resolved path

An array of values is a sequence of values with a separator in between: value1 separator value2 separator value3 separator value4. Accepted separators for an array of values are the same 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

and are equivalent for the configuration manager. It can be summarize as:

key separator1 value1 separator2 value2 separator2 value3 separator2 value4

with separator1 either equal or different from separator2.

Naming convention

Using consistent names throughout the configuration makes the reading and the understanding of the configuration files easy. A good name should instantly give information about the meaning and the function of a parameter. In Osmose we chosed to name the parameter following a descending hierarchical pattern. The name is divided in several tokens, separated by dots. The left token carries the broader meaning and the following tokens narrow down the definition of the parameter. Let's have a look at a few examples:



All these parameters deal with the mortality in the model. Some with fishing mortality, some other with starvation mortality. Within the starvation mortality, we need to define the mortality rate for larvae and for the other schools, etc. That is the way most parameter names have been built in Osmose.

When a parameter needs to be defined at species level, it will always show like .sp0, .sp1, .sp#

In the following sections, such parameters will be referred as

You must remember that, in this case, the # is meant for any integer ranging from zero to maximum number of species minus one.

A parameter name that ends up with .file will always designate a file name, and .path a path name, either absolute of relative.



When the parameter is a file that need be defined for every species it will look like .file.sp#

Parameters referring to plankton will look like plankton.something.plk#

Parameters referring to distribution maps will always look like

Keyword .season always means that the corresponding parameter deals with seasonal cycles.

The .enabled token means that the parameter is a switch that activate or deactivate the process that it designates.

Main parameters

This section describes the main parameters of the Osmose configuration: number of species, multi-threading, time control, restart, etc.

simulation.nspecies = 10

Number of simulated species in the configuration

simulation.nplankton = 4

Number of plankton groups in the configuration

simulation.nsimulation = 10

Number of replicated simulations with identical set of parameters

simulation.ncpu = 4

By default OSMOSE will try to run the replicates in multi-thread environment. If you do not want OSMOSE to use all of them, assign here the number of CPUs that OSMOSE is allowed to use. If this parameter is not defined or the value is higher than the number of CPUs on your computer, OSMOSE will run on the maximum number of CPUs available on the computer. If simulation.ncpu is smaller than 1 or null, OSMOSE will only use one CPU.

simulation.nschool = 50

This parameter controls how many new schools will be added to the population for each species at each reproduction event. simulation.nschool=15 means that, for a given species at a given time step, the spawning stock biomass will be homogeneously split among 15 new schools. If simulation.nschool is not defined, then OSMOSE assumes that simulation.nschool=10

simulation.nschool.sp# = 50

Same meaning as the parameter simulation.nschool, but at species level. This parameter has priority over simulation.nschool. If missing for one species then OSMOSE will use the parameter simulation.nschool.

simulation.nyear = 40

Number of years of the simulation

simulation.ndtPerYear = 24

Number of time steps in one year of simulation. For instance simulation.time.ndtPerYear = 24 means the year is divided in 24 time steps of identical length, 15 days each.

simulation.restart.recordfrequency.ndt = null

Record frequency (expressed in number of time steps) for the restart file. If null then OSMOSE will write only one restart file, at the end of the simulation.

simulation.restart.file = restart/

Restarts OSMOSE from (a) restart file(s). Either file exists and all the replicates (if any) will restart on this file. If the file does not exist, OSMOSE assumes that there is instead as many NetCDF restart files as replicates with the following names:,,, etc.

Species parameter

species.egg.size.sp# = 0.1

Size of eggs in centimeter

species.egg.weight.sp# = 0.0005386

Weight of eggs in gram

species.K.sp# = 1.68

species.lInf.sp# = 1.84

species.t0.sp# = -0.2

von bertalanffy growth parameters. The von Bertalanffy growth model only applies for schools older than a threshold age defined by the parameter species.vonbertalanffy.threshold.age.sp# length =lInf * (1 - exp(-K * (age - t0)))

species.vonbertalanffy.threshold.age.sp# = 1

Threshold age (year) for applying the von Bertalanffy growth model. Below that threshold,growth is assumed to be linear.

species.length2weight.allometric.power.sp# = 3.16

species.length2weight.condition.factor.sp# = 0.0074

Allometric parameters such as weight = c * length^b, where the c parameter is a 'condition.factor', and b the 'allometric.power'.

species.lifespan.sp# = 1

Lifespan of the species expressed in years. Lifespan =1 year means that the species will live one year. Lifespan = 5 years means that the species will live 5 years.

The age of the schools is such that 0 <= age < lifespan. For example, if lifespan = 1 year, age will vary from zero included to 1 excluded ([0, 1[). If lifespan = 5 years, age will vary from zero included to 5 excluded ([0, 5[)

species.maturity.size.sp# = 1.05

Size at maturity, in centimeter = euphausiids

Name of the species. Do not use space or any special character.

species.relativefecundity.sp# = 42254

Number of eggs per gram of mature female

species.sexratio.sp# = 0.5

Ration of female in the population, ranging from zero to one.

Movement parameters

movement.distribution.method.sp# = maps

Type of spatial distribution. Either 'random' or 'maps'.

If 'random' OSMOSE will look for the parameter 'movement.distribution.ncell.sp#'

If 'maps' OSMOSE will use the maps parameters. See below how to define a map.

movement.distribution.ncell.sp# = 200

Number of adjacent cells where the species is allowed to move around. OSMOSE will select randomly n adjacent cells on the grid at the beginning of the simulation and it will assume it is the area of distribution of this species for the rest of the simulation. Within this randomly created area, the school will move around following a random walk. See the parameter 'movement.randomwalk.range.sp#' for explanation about the random walk process.

movement.randomwalk.range.sp# = 1

Range of the random walk expressed in number of cells. If range = zero, the school remains in the current cell. If range = 1, the school can either stay in the current cell or move in any of the 8 immediately adjacent cells (as long as the destination cell is not land). If range=2, the school can either stay in the current cell or move in any of the 24 immediately adjacent cells (as long as the destination cell is not land). Etc.

Map definition

Here are all the parameters required to define a map of distribution in Osmose: = maps/mymap.csv = euphausiids = 0 = 1 = 0 = 40 = 0;1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16;17;18;19;20;21;22;23

One map is associated to a unique species for given age span, year span and season. The full spatial distribution of a species can be represented using as many maps as necessary to cover different age spans and/or year spans and/or seasons. Let's now have a look at each parameter in detail. = maps/mymap.csv

File path to the CSV file that defines the geographical extent of the map. The CSV file has the same number of lines and columns as the OSMOSE grid. Land is always indicated with -99. The distribution area can be defined using either a presence/absence map (1 for presence, 0 for absence) or a map of probability of presence (containing values ranging from 0 to 1, the sum of the probabilities should never exceed 1).

The same CSV file can be used to define different maps.

If the file path is set to null it means that the schools concerned by this map are out of the simulated domain (e.g., migrating species). See the parameter mortality.out.rate.sp for mortality rate of species momentarily out of the simulated area. When a school comes back to the simulated area, it will be randomly located on a new map (the one corresponding to the species and age class of the school at the current time step of the simulation). = euphausiids

Name of the species associated to the map. The name must be similar to the parameter = 0 = 1

Age span of the schools associated to the map such as age.min <= age < age.max = 0 = 40

Year span of the schools associated to the map such as year.min <= current year of the simulation < year.max

If these two parameters are not provided, OSMOSE assumes year.min = 0 and year.max = simulation.nyear = 0;1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16;17;18;19;20;21;22;23

Vectors of the time step over one year associated to the map. For example, here, [0, 23] means that this map is used all year long.

Several maps of distribution for one species

In the above example there is one single map defined for euphausiids as the map applies for euphausiids from age 0 up to age 1 from year 0 to 40 and at every time step over a year. It means that the spatial distribution of this species does not vary with age, year or season. Nonetheless several maps can be defined for representing the spatial distribution of a species. For example:

#Map 0
movement.map0.species = euphausiids
movement.map0.file = maps/mymap_euphau1.csv
movement.map0.age.min = 0
movement.map0.age.max = 0.2
movement.map0.year.min = 0
movement.map0.year.max = 40
movement.map0.season = 0;1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16;17;18;19;20;21;22;23

#Map 1
movement.map1.species = euphausiids
movement.map1.file = maps/mymap_euphau2.csv
movement.map1.age.min = 0.2
movement.map1.age.max = 1
movement.map1.year.min = 0
movement.map1.year.max = 40
movement.map1.season = 0;1;2;3;4;5;6;7;8;9

#Map 2
movement.map2.species = euphausiids
movement.map2.file = maps/mymap_euphau3.csv
movement.map2.age.min = 0.2
movement.map2.age.max = 1
movement.map2.year.min = 0
movement.map2.year.max = 40
movement.map2.season = 10;11;12;13;14;15;16;17;18;19;20;21;22;23

By increasing the number of maps, the description of the spatial distribution can be as detailed and refined as you want, as long as you have such information. It will allow for instance to create some maps for eggs (an egg in Osmose is a new school of age zero that is created during the reproduction process), some maps for the juveniles and some maps for the adults, as many as necessary to describe ontogenetic migrations.

From one time step to an other, the movement manager checks whether a given school remains in the same map or should "jump" to an other map (e.g. eggs map to juvenile map or adults in summer to adults in winter). In the latter case - change of map, the schools are relocated randomly in the new map. In the former case - same map, the movement manager mimics foraging movement with a random-walk that moves schools to immediately adjacent cells within their distribution area. See the parameter movement.randomwalk.range.sp# for details.


predation.accessibility.file = predation-accessibility.csv

Definition of the accessibility matrix, in a CSV file, for every species and stages (if stages are defined, see the parameters 'predation.accessibility.stage.threshold.sp' and 'predation.accessibility.stage.structure'). This matrix must not be used to define diet preferences but rather to take into account for a difference of positions in the water column (meaning some schools might evolve around the same geographical area but never meet because they do not occur at the same depth).

Example of a CSV predation accessibility file:

Prey / Predator;euphausiids;cephalopods < 0.22 year;cephalopods > 0.22 year
cephalopods < 0.22 year;0.0;0.0;0.0
cephalopods > 0.22 year;0.0;0.0;0.8

Spreadsheet view:

Each line of the matrix corresponds to a prey (including plankton groups), and each column to a predator. The file must be understood as follow: euphausiids (line 1) are accessible to all the predators (columns) by 80%; cephalopods < 0.22 (line 2) are not accessible to any predator; and cephalopods > 0.22 (line 3) are not accessible to euphausiids and cephalopods <= 0.22 but are accessible by 80% to cephalopods > 0.22

The order of the rows and columns must follow the indexing of the species and stages (e.g., species0; species1; species2 stage0; species2 stage1; species3).

predation.accessibility.stage.structure = age

Metrics to define the predation/prey size ratio stages, either age or size.

predation.accessibility.stage.threshold.sp# = 2.3

Thresholds between accessibility stages, expressed either in years if 'predation.accessibility.stage.structure=age' or in centimeters if 'predation.accessibility.stage.structure;size'. One threshold value, here 2.3 year, means that two accessibility stages are defined for this species: younger than 2.3 years and older than 2.3 years. Two threshold values mean that three stages are defined. If value is set to null, then stages are not defined.

predation.predPrey.stage.threshold.sp# = 3;11.6

Definition of stages for predation/prey size ratios. It controls how many predator/prey size ratios will be defined for each species. If the value of this parameter is set to null, then no stage is defined for predator/prey size ratios.


Metrics to define the predation/prey size ratio stages, either age or size.

predation.predPrey.sizeRatio.max.sp# = 5;5;5

Maximum predator prey size ratio for the different stages of each species. In the example above, this species has 3 predPrey stages (2 size thresholds defined for corresponding parameter predation.predPrey.stage.threshold.sp#). Therefore, OSMOSE expects to be given 3 predator/prey size ratios. Maximum predator/prey size ratio = 5 means that the largest prey for a fish of this species will be 5 times smaller the fish.

predation.predPrey.sizeRatio.min.sp# = 500;5000;3000

Minimum predator/prey size ratio for the different stages of each species. Minimum predator/prey size ratio = 500;5000;3000 means that the smallest prey for a fish of this species at stage 0 will be 500 times smaller than the fish ; the smallest prey for a fish of this species at stage 1 will be 5000 times smaller than the fish ; and the smallest prey for a fish of this species at stage 2 will be 3000 times smaller than the fish.

predation.ingestion.rate.max.sp# = 10.07

Maximum ingestion rate for each species, expressed in grams of food per gram of fish and per year. It means that, at a given time step, a school will be able to predate at maximum (biomass of the school * max ingestion rate / number of time step in one year).

predation.efficiency.critical.sp# = 0.57

Critical predation efficiency. Predation success for a school is defined as the ratio of is the biomass preyed over the maximum biomass that can potentially be preyed (and the maximum biomass that can be preyed is defined as biomass of the school * max ingestion rate / number of time step in one year). This critical predation efficiency parameter defines the threshold of the predation success. If predation success is smaller than the critical predation efficiency, the starvation process will be applied to the school and the fish will not grow. Conversely if the predation success is bigger than the critical predation efficiency, the starvation process will not occur for the school and the fish will grow.

Fishing = 3

F, the annual mortality rate due to fishing. Ndead_fishing(t) = N(t) * (1 - exp(-F/n_steps_year)) = 1 = null

Age (in year) or size (in centimetre) of recruitment into the fisheries. OSMOSE will first look for a recruitment age parameter. If this parameter is not found or the value of this parameter is set to 'null', OSMOSE will look for a recruitment size. If neither a recruitment age nor a recruitment size is found, a recruitment age of zero year is assumed and the user will be notified by a warning message. = fishing/fishing-seasonality-anchovy.csv

File path of the fishing seasonality file. This controls how the fishing mortality is applied over the year.

Here is an example of the CSV file:


One line per time step. The first column defines time, expressed in year. The second column defines the fraction of the F mortality rate to apply at a given time step. The sum of the season factors over a year should sum to one.

OSMOSE is also able to read an interannual CSV file with as many season factors as the number of time steps of the simulation.

Natural mortality

mortality.natural.rate.sp# = 0.2

Annual natural mortality rate D. This natural mortality rate includes all type of mortalities that are not explicitly represented in OSMOSE, such as mortality due to other predators (seals, seabirds). Ndead_natural(t) = N(t) * (1 – exp(-D / n_dt_year))

mortality.natural.larva.rate.sp# = 0.1

Larva mortality rate, expressed in [dt-1]. This term represents sources of mortality for age class 0 (age class zero in OSMOSE lasts for one time step) such as the non-fecundation of eggs, a starvation more pronounced than at older ages (rel to CC), or predation by species that are not explicitly considered in OSMOSE. Ndead0(t) = N(t) * (1 – exp(-M))

Migration mortality

mortality.out.rate.sp# = 0.8

Annual mortality rate for species that move out of the simulated area, Mout. When a school moves out, none of the usual processes apply (predation, growth, fishing, natural mortality, growth, starvation). The Mout mortality rate comprises all sources of mortality outside the simulated area. It applies as long as the school is located out of the simulated area (see the parameter 'movement.map0.file' for detailled explanations on how to set up migration periods for a given school). The Mout parameters is such that, at a given time step, Ndead_out(t) = N(t) * (1 - exp(-Mout/n_dt_per_year))


At the end of each time step, the numbers of eggs spawned by a species is calculated as follow:

nEgg = sexRatio * alpha * season * (SSB * 1e6)

with sexRatio defined by the parameter 'species.sexratio.sp#' alpha defined by the parameter 'species.relativefecundity.sp#', season defined by the parameter 'reproduction.season.file' and SSB the Spawning Stock Biomass. SSB is calculated as the sum of the biomass of the schools that reached sexual maturity (defined by the parameter 'species.maturity.size.sp#'). As SSB is expressed in tons and alpha in grams of mature female, SSB is multiplied by 1e6.

reproduction.season.file = reproduction-seasonality.csv

Seasonality of the annual influx of biomass for every species. It controls how the annual flux of biomass is inputted in the system over the year.

Here is an example of the csv file:

Time (year);euphausiids;cephalopods;sardine;anchovy;sprat;horsemackerel;mackerel;bluewhiting;hake;tuna

One line per time step. The first column defines time, expressed in year. The subsequent columns define the seasonality of reproduction for each species. For example, the second column is the fraction of eggs to be spawned by species 1 at each time step. OSMOSE will also be able to read an interannual CSV file with as many season factors as the number of time steps of the simulation. The sum of the season factors over a year should sum to one (even though OSMOSE will not check, which somehow allows you to mimic interannual variability when CSV file is interannual).

Input flux of biomass

Some species might no do the full life cycle within the simulated domain (reproduce outside the domain for example). For such species, one way to take them into account is to include of flux of schools with user-defined age and length at specific time of the year.

flux.incoming.season.file = incoming-flux-seasonality.csv

Seasonality of the annual influx of biomass for every species. It controls how the annual flux of biomass is inputted in the system over the year.

Here is an example of the csv file:

Time (year);euphausiids;cephalopods;sardine;anchovy;sprat;horsemackerel;mackerel;bluewhiting;hake;tuna

One line per time step. The first column defines time ,expressed in year. The subsequent columns define the seasonality of the annual influx of biomass for each species. In the example above, there is an influx of biomass defined for species 9 only. The sum of the season factors over a year should sum to one.

OSMOSE will also be able to read an interannual CSV file with as many season factors as the number of time steps of the simulation.

flux.incoming.annual.biomass.sp# = 4000

Annual influx of biomass for this species expressed in ton. The influx of biomass at a each time step will be calculated as: annual.biomass * season factor (as defined above in the parameter 'flux.incoming.season.file' ). If this parameter is not defined for a species, OSMOSE will assume that the incoming flux is zero.

flux.incoming.age.sp# = 3

Age of the incoming fish, in years

flux.incoming.size.sp# = 80

Size of the incoming fish, in centimetre


The grid defines the geographical extent of the simulated domain and the spatial discretization. The grid is defined by a NetCDF file that provides for every cell a the grid: the latitude, the longitude and whether it is land or ocean (the mask). OSMOSE does not set any convention regarding the latitude and the longitude. Just make sure it is consistent with the convention of the LTL dataset. The grid does not have to be regular.

grid.netcdf.file =

The path of the NetCDF grid file = lat
grid.var.lon = lon
grid.var.mask = mask

The name of the variables latitude, longitude and mask in the NetCDF grid file. = fr.ird.osmose.grid.NcGrid

The Java class that should be used to build the OSMOSE grid. Do not change this parameter unless you know exactly what you are doing.

Historically OSMOSE allows to define a regular grid, given a few parameters. Even though it is preferable to use the NetCDF grid definition, here is how a regular grid can be defined:

grid.ncolumn = 56
grid.nline = 62 = -37.5
grid.lowright.lon = 24.4 = -28.2
grid.upleft.lon = 16
grid.mask.file = grid-mask.csv = fr.ird.osmose.grid.OriginalGrid

The mask file is a CSV with ncolumn and nline. Land takes the value -99,  and ocean cell are defined by a 0. Here is an example of a CSV mask file for a 4x4 grid:


OSMOSE also allows to define grid based on ECO3M or BFM grid. These are specific cases though for handling the LTL dataset more easily and will not be detailled here. Please refer to section "LTL dataset directly from biogeochemical model".

Low trophic level

Low trophic level (LTL hereafter) organisms such as phytoplankton and zooplancton are not explicitly modelled in Osmose but are essential to take into account are they constitute the base of the trophic chain. They are considered as an input of the model, spatially explicit and varying with time.

First one must define the LTL groups that are included in the configuration. In a second time, Osmose needs to know how the LTL data will be delivered.

Plankton groups

plankton.accessibility2fish.plk# = 0.0855

The fraction of the plankton biomass that are accessible to the fish, ranging from zero to one. This parameter accounts for many biological processes that are not explicitly represented in Osmose and basically says that only a small fraction of the plankton in the water column is effectively available to the fish for preying upon. Plankton accessibility is generally completely unknown and, just like larval mortality, it should be estimated in the calibration process.

plankton.conversion2tons.plk# = 0.72

Factor for converting biomass from plankton unit (as provided in the LTL input file) to wet weight in tonne/km2. (e.g. mmolN/m2 to tonne/km2) = Dinoflagellates

Name of the plankton group

plankton.size.max.plk# = 0.002
plankton.size.min.plk# = 0.0002

The minimum and maximum size of the organisms in the plankton group, in centimetre

plankton.TL.plk# = 1

The trophic level of the plankton group

LTL dataset

OSMOSE expects the LTL dataset to be spatially explicit and varying with time. The plankton biomass must be provided as time series (with same time step than OSMOSE configuration) on the OSMOSE grid, in a NetCDF file. = fr.ird.osmose.ltl.LTLFastForcing

The parameter indicates which Java class in Osmose should handle the reading of the LTL dataset. LTLFastForcing is the default plugin. Do not change it, unless you know exactly what you are doing.

ltl.netcdf.file =

Path of the NetCDF file that stores the plankton biomass for every LTL group. Here is an example of the NetCDF header for the OSMOSE default configuration:

netcdf osm_ltlbiomass_integrated {
    ltl = 4 ;
    nx = 56 ;
    ny = 62 ;
    time = UNLIMITED ; // (24 currently)
    float time(time) ;
        time:units = "days since 1-1-1 0:0:0" ;
        time:calendar = "360_day" ;
        time:description = "time ellapsed, in days, since the beginning of the simulation" ;
    float ltl_biomass(time, ltl, ny, nx) ;
        ltl_biomass:units = "tons per cell" ;
        ltl_biomass:description = "plankton biomass in osmose cell, in tons integrated on water column, per group and per cell" ;
        ltl_biomass:_FillValue = -99.f ;
    float ltl_biomass_pred(time, ltl, ny, nx) ;
        ltl_biomass_pred:units = "tons per cell" ;
        ltl_biomass_pred:description = "plankton biomass after predation process in osmose cell, in tons integrated on water column, per group and per cell" ;
        ltl_biomass_pred:_FillValue = -99.f ;
    float latitude(ny, nx) ;
        latitude:units = "degree" ;
        latitude:description = "latitude of the center of the cell" ;
    float longitude(ny, nx) ;
        longitude:units = "degree" ;
        longitude:description = "longitude of the center of the cell" ;

// global attributes:
        :dimension_ltl = "0=Dinoflagellates 1=Diatoms 2=Ciliates 3=Copepods " ;

How to generate such a NetCDF file is beyond the scope of this document. Specific documentations about generating/inputting LTL data to OSMOSE will be provided soon.

ltl.nstep = 24

Number of time steps in the LTL dataset file. The parameter must be a multiple of the number of time step per year. OSMOSE will loop over the LTL data through time.

LTL dataset directly from biogeochemical model

LTL dataset usually comes from the output of biogeochemical models, such as NPZD, PISCES, ECO3M, BFM, etc. OSMOSE provides a few plugins to read directly the LTL data from the output of biogeochemical models. These plugins have been added on the go and might reveal some flaws under scrutiny. It is recommended to provide the LTL data in the pre-defined OSMOSE format instead (as explained above). They do exist though and we mention them briefly.

  • ROMS-PISCES = fr.ird.osmose.ltl.LTLFastForcingRomsPisces
ltl.netcdf.file.t# =ltl/
ltl.netcdf.var.plankton.plk# = SPHYTO
ltl.netcdf.grid.file =
ltl.netcdf.var.bathy = h
ltl.netcdf.var.csr = Cs_r
ltl.netcdf.var.hc = hc = lat_rho
ltl.netcdf.var.lon = lon_rho
ltl.integration.depth = -100

This plugin expects as many NetCDF files as time step per year. The integration depth, metre, is the depth of the water column to be taken into account for integrating the plankton biomass. ROMS grid and OSMOSE grid can be different, though all of OSMOSE grid must be included within the ROMS grid.

  • ECO3M = fr.ird.osmose.ltl.LTLFastForcingECO3M
ltl.netcdf.file.t# = ltl/
ltl.netcdf.var.plankton.plk# = NANON
ltl.netcdf.var.zlevel = levels_ZHL
ltl.integration.depth = -100

This plugin expects as many NetCDF files as time step per year. Same definition of the integration depth as for ROMS-PISCES plugin. For this plugin, it is assumed that the OSMOSE grid does match the ECO3M grid or is at least in line with it (for example one OSMOSE cell is the aggregation of 3x3 ECO3M cells). It implies a case-specific definition of the OSMOSE grid.

ECO3M grid definition: = fr.ird.osmose.grid.ECO3MGrid
grid.netcdf.file =
grid.stride = 4 = Latitude
grid.var.lon = Longitude
grid.var.mask = Mask

The parameter grid.strid controls the level of aggregation of ECO3M cells for generating one OSMOSE cell. In this case an OSMOSE cell will be a cluster of 4x4 ECO3M cells.

  • BFM



output.start.year = 20

Year at which outputs start to be written.

output.recordfrequency.ndt = 24

Record frequency is expressed in number of time steps. In the example above, the indicators will be either averaged or cumulated (depending on the nature of the indicator) over 24 time steps before being written. A record frequency of 1 means that indicators will be written in output files at every time step of the simulation.

output.dir.path = output

Path of the output directory, either relative or absolute.

output.file.prefix = gol

Prefix of the output files

output.cutoff.enabled = false

Enable/disable the cutoff. Cutoff indicates to OSMOSE whether or not it should consider the schools younger than the cutoff age (see parameter 'output.cutoff.age.sp#') when calculating indicators.

output.cutoff.age.sp# = 0.5

Cutoff age, expressed in year. If the parameter 'output.cutoff.enabled' is enabled, then OSMOSE will ignore all schools younger that 0.5 year old when calculating the indicators.

Follows a list of all the OSMOSE outputs. A complete description of OSMOSE output files is provided here (coming soon).

  • Biomass and abundance outputs
output.abundance.enabled = true
output.biomass.enabled = true
  • Diet outputs = true = true = size = null

Parameter accepts values size or age and allows to detail the diet matrix for several stages. takes either threshold lengths (centimetre) or ages (year).  A null value means that no threshold should be considered and the output will show only one column or row for the species. The user can define as many threshold values as needed (e.g. = 1; 2; 3; 4; 5) be remember that it will increase the size of the CSV output file just as much.

  • Mortality outputs
output.mortality.enabled = true
  • Size-based outputs
output.size.catch.enabled = true
output.size.enabled = true
output.size.perSpecies.enabled = true
output.size.spectrum.enabled = true
output.size.spectrum.perSpecies.B.enabled = true
output.size.spectrum.perSpecies.N.enabled = true
output.size.spectrum.size.max = 205
output.size.spectrum.size.min = 0
output.size.spectrum.size.range = 10

Parameters spectrum.size.min/max/range are expressed in centimetre and allows a custom discretisation of the size spectrum. The user can set a much of a small range as needed, but it will increase the size of the CSV file.

  • Spatial outputs
output.spatial.enabled = true
output.spatial.ltl.enabled = true
  • Trophic level outputs
output.TL.catch.enabled = true
output.TL.enabled = true
output.TL.perAge.enabled = true
output.TL.perSize.enabled = true
output.TL.spectrum.enabled = true
  • Fishing outputs
output.yield.abundance.enabled = true
output.yield.biomass.enabled = true

Related documents