Repository navigation
Initialisation Other methods
This section documents the other initialisation routes currently implemented in OSMOSE 4.4. Although reconstructed population-level initialisation is the preferred default workflow for most practical applications, the model still supports other methods that remain useful in particular contexts. These methods reflect earlier stages in the development of OSMOSE and continue to serve specific technical purposes.
The three routes covered here are egg seeding initialisation, direct school-level initialisation, and restart-derived generation of population-level initialisation inputs. The first is an indirect, reproduction-based route in which the initial population emerges dynamically from seeded reproduction. The second is the most explicit route, in which the initial schools are provided directly through a restart-like file. The third is a utility workflow that converts an explicit school-level state into the population-level parameter block used by reconstructed population-level initialisation.
Egg seeding initialisation is a legacy, reproduction-based route in which the initial population is not specified explicitly, either at school level or at population level. Instead, the mechanism is implemented within the reproduction process of the OSMOSE core simulator (Java), where it can generate eggs artificially from a user-defined seeding quantity when a species produces no eggs from its actual mature schools and the simulation is still within the configured seeding period.
Functionally, this mechanism can serve two related purposes. First, it can act as an indirect initialisation method when the model starts without mature individuals, in which case seeded reproduction generates the first cohorts until a self-sustaining reproducing population becomes established. Second, it can be used more generally as a safeguard against collapse, for example by assigning a very small seeding value that allows a species to recover even after severe depletion. In both cases, the resulting population is not given directly by the user but emerges dynamically from reproduction and subsequent life-history processes.
Egg seeding therefore remains useful as an initialisation route in OSMOSE 4.4, even though it is implemented as part of the reproduction process and can also be used outside strict initialisation in a broader anti-collapse role.
The egg seeding route is controlled by a seeding duration and by species-specific seeding quantities.
The first parameter controls the duration of the seeding phase:
population.seeding.year.max
This parameter gives the maximum duration of seeding in years. Internally, it is converted to the corresponding number of model time steps.
For each species, the user may then supply a seeding biomass and, where relevant, a seeding abundance:
population.seeding.biomass.sp0
population.seeding.biomass.sp1
...
population.seeding.biomass.spX
population.seeding.abundance.sp0
population.seeding.abundance.sp1
...
population.seeding.abundance.spX
Which of these two quantities is used depends on the species reproduction mode. In the current implementation, oviparous species use biomass-based seeding, whereas viviparous species use abundance-based seeding. Users should therefore ensure that the seeding quantities are consistent with the reproductive mode specified for each species.
If population.seeding.year.max is not provided, and reconstructed population-level initialisation is not enabled, OSMOSE sets the seeding duration by default to the lifespan of the longest-lived species and emits a warning. This behaviour reflects the historical role of seeding as the implicit fallback route in older workflows.
At each time step, the reproduction process computes egg production from the mature schools currently present in the system. This computation depends on the spawning season, sex ratio, fecundity, and the quantity of spawners available for the species. If mature schools produce eggs normally, those eggs are used and the seeding mechanism is not activated.
Seeding is triggered only when two conditions are met simultaneously:
- the total number of eggs produced by mature schools for the species is zero;
- the simulation time is still before the end of the configured seeding period.
When this happens, OSMOSE computes an artificial egg production from the configured seeding biomass or seeding abundance, using the same broad reproductive ingredients as ordinary spawning: sex ratio, fecundity, seasonal spawning fraction, and seeding quantity. The mechanism therefore does not create a mature population explicitly. Instead, it introduces an artificial spawning biomass that produces missing natural egg production during the seeding phase.
The eggs produced through seeding are then converted into schools at age class zero, just as in the regular reproduction process. The population that later appears in the simulation therefore emerges from these age-0 schools and their subsequent development, rather than being inserted directly as a complete mature population.
From a practical perspective, egg seeding can be interpreted in two complementary ways.
When species begin without mature individuals, or when the initial state would otherwise fail to produce eggs, seeding acts as an indirect initialisation mechanism, by creating the first age-0 cohorts until mature individuals appear and ordinary reproduction can take over. This explains why seeding has historically been treated as one of the initialisation methods of OSMOSE, even though its implementation is embedded in the reproduction process rather than in a standalone initial-condition configuration.
When mature populations exist but the user wishes to avoid irreversible collapse, seeding can instead be used as a safeguard. In that case, the seeding quantity may be set to a very low value so that, even if the simulated population crashes to the point where no eggs are produced by mature schools, a minimal reproductive source remains available and recovery becomes possible.
These two uses are closely related, because both rely on the same mechanism: artificial egg production triggered when natural spawning fails.
The main strength of egg seeding is that it provides a simple and robust way to maintain a minimal reproductive source in the system. This can be useful both for starting the simulation from the absence of mature individuals and for preventing permanent collapse in cases where a small residual reproductive capacity is intended to remain.
Its main limitation is that it offers only indirect control over the resulting initial state. The user specifies a seeding biomass quantity and a duration, but not the final age structure, size structure, trophic-level distribution, or school composition that will emerge from the process. The resulting population therefore depends on the interaction between seeded reproduction and the subsequent model dynamics.
For this reason, egg seeding is generally less explicit and less transparent than reconstructed population-level initialisation or direct school-level initialisation. It should be regarded as a legacy but still useful route, particularly when a phenomenological recovery mechanism is desirable or when the simulation must establish a reproducing population from an initial absence of mature individuals.
A typical biomass-based configuration looks like:
population.seeding.year.max = 50
population.seeding.biomass.sp0 = 6420
population.seeding.biomass.sp1 = 8068
population.seeding.biomass.sp2 = 6916
population.seeding.biomass.sp3 = 9940
population.seeding.biomass.sp4 = 3000
population.seeding.biomass.sp5 = 37868
population.seeding.biomass.sp6 = 3316
population.seeding.biomass.sp7 = 28544
population.seeding.biomass.sp8 = 10720
population.seeding.biomass.sp9 = 186040
In this example, seeding is available for fifty years, and each species is assigned a seeding biomass used to generate eggs if the species has no egg production from mature schools during that period. In practice, the same logic applies to abundance-based seeding for viviparous species, except that the configured quantity is then expressed in abundance rather than biomass.
Direct school-level initialisation is the most explicit way to initialise OSMOSE. In this route, the user provides the initial state directly as a school-by-school description through a restart-like netCDF file. The OSMOSE core simulator (Java) then reads this file and uses it as the starting state of the simulation.
Conceptually, this route differs fundamentally from reconstructed population-level initialisation. In population-level initialisation, the user provides a class-based aggregate description from which schools are later created. In school-level initialisation, the schools already exist in the input. The file therefore constitutes the initial condition itself rather than an intermediate representation.
Direct school-level initialisation is controlled through a single parameter:
population.initialization.file
This parameter points to a netCDF file containing the full school-level initial state. For example:
population.initialization.file = input/initial_conditions/humboldt-n_1992.nc
The file path is relative to the configuration in the usual OSMOSE way.
The expected file structure is the same general type as an OSMOSE restart file. The file contains one record per school, with dimension nschool, and includes at least the following variables:
-
species: species index of the school; -
x,y: spatial grid indices of the school; -
abundance: number of individuals in the school; -
age: age of the school, in years; -
length: body length, in centimetres; -
weight: body weight, in grams; -
trophiclevel: trophic level of the school.
In addition, the file typically contains global attributes such as the simulation step and a mapping between species indices and species names. A representative example is:
dimensions:
nschool = 20287
variables:
int species[nschool]
float x[nschool]
float y[nschool]
double abundance[nschool]
float age[nschool]
float length[nschool]
float weight[nschool]
float trophiclevel[nschool]
global attributes:
step = -1
species = 0=anchovy 1=hake 2=sardine 3=jurel ...
The value step = -1 indicates that the file is intended to be used as an initial-condition file rather than as an ordinary restart attached to a later simulation step. More variables are expected in the direct school-level initialisation if the bioenergetic or genetic modules are active.
The key feature of this route is that spatial position is supplied explicitly through x and y, and that all school attributes are already defined in the file. There is therefore no need for the OSMOSE core simulator to reconstruct the size structure, age structure, or biomass allocation across classes. The state is already fully expressed in the school-based representation used internally by the model.
This makes direct school-level initialisation particularly suitable when the user wants complete control over the initial condition, when a previous OSMOSE run is being reused as a starting point, or when initial conditions are supplied by an external process such as a coupling workflow.
The main strength of direct school-level initialisation is its explicitness. It is the most direct and transparent route because the initial state is already available in the same type of representation used internally by the OSMOSE core simulator. This also makes it the natural choice for restart workflows.
Its main limitation is practical. Preparing a valid school-level initial-condition file can be technically demanding, especially when the file is not simply copied from a previous OSMOSE run. The user must supply every school explicitly, including abundance, size, age, trophic level, and position. For many applications, especially when only survey and fishery information are available, this is much less convenient than reconstructed population-level initialisation.
In short, direct school-level initialisation is the most explicit method, but not necessarily the most practical one for ordinary parameterisation workflows.
In addition to the two conceptual routes described above, the OSMOSE 4.4 codebase includes utility procedures that read restart outputs and convert them into a population.initialization.* block. This is not a distinct conceptual family of initialisation in the same sense as seeding, school-level initialisation, or reconstructed population-level initialisation. Rather, it is a conversion route between representations.
The basic idea is simple. A school-level state already exists, typically from a previous run or a set of restart files. Instead of reusing it directly as a school-level initial condition, the user may wish to aggregate it into the class-based species-level format used by population-level initialisation. The restart-derived procedure performs exactly that translation.
This route is useful for at least two purposes. First, it allows users to derive a compact, reusable population.initialization.* block from an equilibrated or otherwise prepared school-level state. Second, it clarifies the relationship between school-level and population-level representations by showing how a school-based state can be aggregated into the parameters required by the population-level route.
In this sense, the restart-derived conversion route is a bridge between two initialisation representations rather than an entirely separate method.
The restart-derived conversion reads one or more restart files, extracts the school-level variables, and aggregates them by species and age. From these aggregated values, it derives:
- total initial biomass by species;
- relative biomass among classes;
- representative size information;
- representative ages;
- trophic levels;
- numbers of schools per class.
The resulting block can then be written as population.initialization.* parameters, which may later be reused as a population-level initial condition.
A related utility route also exists for copying restart files into an initial-condition folder while resetting the global step attribute, which effectively prepares them for direct school-level initialisation. Together, these procedures support movement between restart outputs and both conceptual initialisation families documented in this text.
The most natural use case for restart-derived conversion is when the user already has a school-level state judged to be suitable, for example after an equilibrium or preparatory run, but wants to preserve it in a more compact population-level form. This can be useful for simplifying future configurations or for sharing an initial state without distributing a large school-by-school file.
The main caveat is that aggregation inevitably loses information. Once a school-level state is converted into a population-level parameter block, the exact school identities and spatial positions are no longer preserved in the same way. The converted block therefore captures the broad demographic structure of the initial state, but not its full school-level detail.
For this reason, restart-derived conversion should be seen as a practical utility, not as a perfect one-to-one substitute for direct school-level initialisation.
Taken together, the three routes described in this section define the main alternatives to reconstructed population-level initialisation.
Egg seeding initialisation is the most indirect route. It does not describe the initial state explicitly, but lets it emerge dynamically from seeded reproduction over a limited period or persist as a safeguard when ordinary spawning fails. Its value lies both in backward compatibility and in specific use cases where a bootstrap or anti-collapse mechanism is desirable.
Direct school-level initialisation is the most explicit route. It provides the OSMOSE core simulator with a complete school-level state and is therefore the natural option for restart workflows and coupling contexts. Its main drawback is the amount of detail required from the user.
Restart-derived generation of population-level inputs is not really an alternative conceptual family, but rather a bridge. It is useful when a school-level state already exists and the user wishes to derive from it a compact class-based parameter block for later use.
Against this background, reconstructed population-level initialisation remains the preferred general-purpose workflow in OSMOSE 4.4. It offers the most practical balance between explicitness and usability. The methods described in the present section should therefore be understood primarily as complementary routes: useful, sometimes essential, but generally secondary to the default population-level workflow documented in Section 4.