Changes from Osmose 3 to Osmose 3 Update 1

Osmose 3 update 1, as the name indicates, is an update of Osmose 3 and, as such, does not lead to major changes in the parameters. This document highlights the most important changes from Osmose 3 to Osmose 3 update 1 in terms of features, and lists all the changes of parameters, additions and deprecations.

This release updates and clarifies the mortality algorithms, hereafter called ITERATIVE and STOCHASTIC algorithms (see section below). Both stochastic and iterative algorithms now guarantee Finput=Foutput (so no need to back calculate fishing mortality from output as we used to do before). Fishing mortality and natural mortality accept any type of time variability (constant, seasonal, interannual, interannual + seasonal). The release introduces the option of parameterizing fishing by input catches (this could be useful if you would like to simulate fishing quotas for example). Effort for unifying the output format has been made (not finished though). This new release of Osmose also comes will clear guidelines for the calibration procedure (separate document).

You can retrieve Osmose 3 Update 1 and the default configuration either from the download section or from the subversion server (contact us and ask for the login if you whish to use SVN):

Update configuration file

The update of an old configuration to Osmose 3 Update 1 must be done by steps, from one version to the next one.

Osmose 2 to Osmose 3

From Osmose 2, 2012 or Osmose 2, 2009, you need to update manually your configuration files to be compatible with Osmose 2, 2013. They are no major changes though.
From Osmose 2, 2013 to Osmose 3, there is a utility that will convert automatically your configuration file to the new Osmose 3 format. Open Osmose 3 Update 1 with Netbeans and expand package fr.ird.osmose.util. Open class There is two variables to set up:

  • inputFile that provides the path to the Osmose 2, 2013 INPUT.txt
  • outputPath that provides the path of the directory for the converted Osmose 3 configuration.

Right click on from the “Projects” panel and click on “Run File”. The conversion starts and should last one or two seconds.

This converter has been written as a convenience for the developer to upgrade quickly several configurations and was not intended at first to be shared. Even though it should work without any problem for the end user, be aware that it is not a fancy tool and you must double check the new configuration files and look for any inconsistency.

Osmose 3 to Osmose 3 update 1

From Osmose 3 to Osmose 3 update 1, there is unfortunately not yet any automatised updater (on its way though, it will be included in Osmose 3 update 2). Nonetheless a basic Osmose 3 configuration should run out of the box with Osmose 3 update 1 and any missing parameters will be reported in the logs. The main visible changes concern the names of the output parameters but Osmose will mention it in the logs. Moreover this document details all the new available features and changes.

Mortality algorithm

Most of the work on this update concerns the mortality algorithm. Detailed documentation on the new mortality algorithm will be published soon. In the meantime, here is a brief history of the work on the mortality algorithm for the last 12 months.


The initial problem we wanted to address is that in Osmose 2, Finput mismatched Foutput, which is very annoying when one is supposed to do batches of scenarii with different Finput. Simulation results could still be reported in function of Foutput, but the problem was the absence of control in the fishing driver in input. We came up with two different solutions to the problem: an iterative approach and a purely stochastic approach. At first we observed that:

  1. The iterative algorithm works consistently with relatively low values of F but does not behave satisfactorily with higher values of F. Looking at it closely we understood that it is because we handle side by side mortality via a rate (fishing mortality rate F) and mortality via biomass removal (predation) so that from a certain threshold value, F is outcompeted by predation pressure.
  2. Stochastic case was not working well at all, high variability in the simulations and calibration failures.

Here are the solutions we implemented to address the problems mentioned above:

  • For iterative algorithm: added fishing by catches so that both predation and fishing deal with biomasses, which solved the problem. But it disqualified the algorithm when implementing scenarii of Finput.
  • For stochastic algorithm: added a subdt for ensuring that the random order of the mortality sources within a cell does not bias the mortality outcome. And this was the beginning of series of problems that we've been dealing with in 2014.

As said previously, the idea behind the sub time step is to get rid of the variability due to the random order of the mortality sources. The main problem we faced was that it created trends in the state variables depending on the number of sub time steps. This means the processes at sub time step level were not consistent any more, with the processes expressed at time step level. So we had to update several parts of the code, namely predation, eggs release and LTL forcing, to make sure that the meaning of the processes at sub time step level remains consistent as expressed at time step level.

Here comes the list of the modifications we made in the code in order to achieve consistency of the stochastic algorithm:

  • starvation: at the end of time step t, we can calculate the starvation mortality rate based on what a school has been eating during time step t. At time step t + 1, the starvation mortality is applied based on the starvation mortality rate estimated at the end of time step t. For sub time step level, we apply starvation mortality rate / subdt
  • the predation success rate is calculated as the average predation success rate over the sub time steps. We did so after noticing that calculating the predation success rate at the end of the time step (ie eaten B[end of dt]/maxBiomassToPrey[beginning of dt]) would systematically underestimate the predation success (as the maximum biomass to prey upon at sub time step level is calculated from the instantaneous biomass of the predator, we always have maxBiomassToPrey(sub time step) < maxBiomassToPrey(dt) / n_subdt)
  • the meaning of the plankton accessibility coefficient (estimated by EA) has been clarified. It removes from the system a fraction of the LTL biomass beforehand. accessible_LTL_biomass = accessibility_coefficient * LTL_biomass is what is available at current time step dt for the predators.
  • the meaning of the larval mortality (estimated by EA) has been clarified. Similarly to the plankton accessibility coefficient, the larval mortality will remove some eggs from the system beforehand. It stands for eggs and larvae mortality before even being available to predation. In concrete terms, the larval mortality is applied before entering the stochastic algorithm. This is meant to represent the high loss of eggs from the system modelled (non fecundation, sinking, exportation from system due to drifting).
  • eggs are released evenly over the sub time steps (instead of releasing all the eggs at the beginning of the time step, which led to a dramatic increase of the egg mortality due to predation). Every sub time step, the biomass (and the abundance) of the school of eggs is incremented by (spawned_biomass - egg_loss) / n_subdt, egg_loss accounting for the larval mortality.
  • a LTL group is handled as any other preys. The accessible_LTL_biomass is updated on the fly as it is preyed upon by predators.

New parameters

mortality.algorithm = stochastic
mortality.subdt = 10

Low trophic level

plankton.multiplier.plk0 = 1

Added a parameter 'plankton.multiplier.plk#' for multiplying plankton biomass, in order to run different scenarios of plankton forcing in relation to a reference state (plankton.multiplier.plk0 = 1 by default for the reference state). For instance plankton.multiplier.plk0 = 2 means that Osmose will multiply by two the biomass of the plankton group zero of the LTL dataset.


File format and naming convention

Modifications of the Osmose outputs aim to provide data in a systematic way, always abiding to the same format, so that it can be easily interpreted and analysed by post-processing tools (such as Osmose2R for instance). The name of the Osmose parameters for enabling the outputs tend to follow the pattern:


The byAge/bySize/byTL means that the outut data will be split by age, size or trophic level classes. The perSpecies means that the information is divided into one file per species.

Osmose outputs are provided in CSV files and can have the following formats:

  • Time serie for all species.

For instance:

  • Time series by age, size or trophic level classes, for all species.

For instance:

  • Time series of trophic interaction by age or size class, per species (one file per species)
  • Time series of trophic interaction, for all species

For instance
  • Mortality files

For instance:


Trophic interactions and mortality rates cannot be satisfactorily written in a CSV file as they are time series of 2D arrays (or more if we include age or size classes). A NetCDF file would suit better the purpose but would make the use of post-processing routines compulsory, which can be a hindrance for the end-user. We have not reached yet a satisfactory answer to the problem and output formats will keep evolving in future releases.

CSV separator

output.csv.separator = COMA (or SEMICOLON, EQUALS, TAB, COLON)

Added parameter 'output.csv.separator' that controls the CSV separator in the CSV output files. Coma by default.


output.restart.enabled = true

Added parameter 'output.restart.enabled' to be able to deactivate completely the writing of the NetCDF restart file. True by default.

output.restart.spinup = 0

Sets the number of years before starting to write the restart file (assuming that the record frequency of the restart file is one year for instance). Zero by default.

output.restart.recordFrequency.ndt = 24

Renamed parameter 'simulation.restart.recordFrequency.ndt'. Only use this parameter if you would like Osmose to save more restart files rather than just one at the end of the simulation.


Added new outputs and that gives information about the predation, either from the prey or predator perspective, per age/size class.

Size-based or age-based distributed parameters


Updated list of size/age based outputs.


Included fishing mortality by catches. All the parameters that do exist for “rate” have the equivalent for “catches”. Example : parameter '' and its equivalent for catches '' = catches (or rate)

Added parameter '' either 'catches' or 'rate'. Rate by default.

Possible ways of parametrizing fishing in Osmose (rates and catches):

  • Fishing mortality by dt, by age class
  • Fishing mortality by dt, by size class
  • Annual rates with seasonality file per species
  • Constant annual rates by species with seasonality file per species
  • Constant annual rate by species

Spatial F not taken into account yet.

Natural mortality

In a similar way to fishing, the parametrization of the natural mortality has been extended to take into account time variability at different levels.

Larval mortality

  • Larval mortality by dt
  • Constant larval mortality


Natural mortality

  • Natural mortality rate by dt and by age or size class
  • Natural mortality rate by dt
  • Annual natural mortality rate

Marine Protected Area

The user can defined as many MPA as he wishes.

mpa.file.mpa0 = maps/mpa0.csv
mpa.start.year.mpa0 = 10
mpa.end.year.mpa0 = 15

An MPA is defined by a map of 0 and 1 and by a time span. Parameters  'mpa.file.mpa#'  'mpa.start.year.mpa#' and 'mpa.end.year.mpa#'

The MPA are handled within the Fishing process. Every time there is a new MPA to be activated or deactivated, Osmose updates the correction factor that will be applied to the fishing mortality rates in order to take into account the uniform redistribution of the fishing effort outside the MPAs.

Reproduction and incoming flux

Updated and so that the seasonality files can be provided by species. Parameters 'reproduction.season.file' and 'flux.incoming.season.file' are still valid (and they have priority) but user can also choose to specify instead parameters such as: