Repository navigation
Initialisation Method overview
OSMOSE 4.4 includes several routes to define the initial state of focal species at the beginning of a simulation. These routes differ in the way the initial population is described, in the amount of information they require from the user, and in the degree to which the initial state is provided directly or reconstructed from other inputs.
At the broadest level, the initialisation module supports two main types of workflow. In one case, the initial state is provided directly as a school-by-school description. In the other, the initial state is reconstructed first at population level and only later translated into schools. In addition, OSMOSE retains an older seeding-based route in which the model is allowed to generate the initial population dynamically over an initial period.
These methods coexist in OSMOSE 4.4 because they reflect different historical stages in the development of the model and different practical needs. Some methods are more explicit and direct, while others are more practical when the user has standard biological parameterisation and a limited set of observational inputs but no full restart-like initial state.
For clarity, this document distinguishes between the following conceptual methods:
- Reconstructed population-level initialisation
- Direct school-level initialisation
- Egg seeding initialisation
In addition, the current codebase includes a conversion route that derives a population-level initialisation block from restart outputs. This route is best understood as a bridge between school-level and population-level workflows rather than as a fully separate conceptual method.
A useful way to understand the initialisation module is to distinguish between the information ultimately consumed by the OSMOSE core simulator (Java) and the procedures used to generate that information.
The OSMOSE core simulator engine requires an explicit initial state from which it can create the schools present at the beginning of the simulation. Depending on the method, this direct initial state takes one of two forms. Either it is supplied as a school-level file, in which each school is already described explicitly, or it is supplied as a population-level parameter block, in which biomass and population structure are specified at class level and schools are created from those aggregate descriptors.
Around these direct initialisation inputs, OSMOSE 4.4 includes auxiliary procedures whose role is to construct the final inputs used at runtime. These procedures do not themselves constitute the initial state. Rather, they are preparation steps. The clearest example is reconstructed population-level initialisation, in which the user provides observational inputs and regular species parameters, and an auxiliary estimation procedure converts that information into the population.initialization.* parameters later used by the OSMOSE core simulator.
This distinction is important because many configuration parameters that appear in the initialisation workflow are not read directly by the core simulator when the starting schools are created. Some belong only to the preparatory stage. In practice, confusion often arises when users conflate the data used to reconstruct an initial condition with the initial condition itself. The present document therefore treats the generation procedure and the final initialisation inputs as separate elements of the workflow.
In the reconstructed population-level initialisation, the user does not provide the initial schools directly. Instead, the user provides a set of observational inputs and species parameters from which OSMOSE reconstructs a plausible initial population structure for each focal species. This reconstruction is performed at population level, typically through classes defined over age and size, and is then converted into the population.initialization.* parameters. These parameters describe total biomass, biomass allocation among classes, class boundaries, ages, trophic levels, and the number of schools per class. The core simulator then uses this parameter block to create the actual schools at the start of the simulation.
This method is the most suitable default workflow in OSMOSE 4.4 for many practical applications, because it avoids the need for a hand-built restart-like file while remaining more explicit and controllable than seeding.
In direct school-level initialisation, the user provides an explicit school-by-school description of the initial state through a restart-like netCDF file referenced by population.initialization.file. This file contains one record per school and includes, at minimum, the species identity, spatial position, abundance, age, length, weight, and trophic level of each school.
Conceptually, this is the most direct form of initialisation, because the initial schools are already fully specified. It is particularly suitable for restart workflows, coupling applications, or cases in which the user already has a detailed school-level state available from a previous simulation or from an externally generated file.
Egg seeding initialisation is an older route in which the model begins with ghost spawners whose biomass is specified by species and which release eggs during a preliminary seeding phase. The objective is not to define the final initial state explicitly, but rather to allow OSMOSE to generate a population dynamically over an initial period. The duration of the seeding phase and the seeding biomass by species are provided by configuration parameters.
This method can still be useful in particular situations, but it is not the preferred general workflow for OSMOSE 4.4 because the resulting initial state is obtained only indirectly and may require a longer stabilisation period. Notably, this method is incompatible with an interannual simulation.
The codebase also contains procedures that read restart outputs and convert them into a population.initialization.* block. These procedures occupy an intermediate position between direct school-level and reconstructed population-level initialisation. They do not reconstruct the initial state from observational data in the same way as the population-level method, but they do aggregate an explicit school-level state into the parameterised format used by population-level initialisation.
This route is useful when a user wishes to derive a compact population-level initialisation block from an equilibrated or otherwise prepared restart state, for example to simplify subsequent configurations or to transfer an initial state between workflows.