1.2. Entities, state variables, and scales

1.2.1. Entities

In the current section, the different types of entities of the Osmose model are described.

The Configuration entity describes the parameters and entities that will be shared among the different simulations.
The Simulation entity describes a given simulation. Simulations differ from each other if stochasticity is enabled.
The Cell entity describes the individual cells of the Osmose computation 2D grid (longitude, latitude, cell index, etc.)
The Species entity represents the species whose life-cycle is fully represented. This entity contain fixed parameters, which are not modified during the simulation.
The BackgroundSpecies entity represents the species whose life-cycle is not represented. These species can feed on and be eaten by Species, and can be fished. This entity contain fixed parameters, which are not modified during the simulation.
The ResourceSpecies entity represents the low-trophic level species. These species cannot predatate Species or BackgroundSpecies but can be eaten by them. This entity contain fixed parameters, which are not modified during the simulation.
The School entity describes a group of Species individuals, whose life cycle is fully considered and which all share the same characteristics (age, weight, species, location, etc, trophic level).
The BackgroundSchool entity describes a group of BackgroundSpecies individuals, whose biomass is provided as input and whose life-cycle is not simulated and which all share the same characteristics (age, weight, species, location, etc, trophic level).
The Resource entity describes a swarm of ResourceSpecies, whose biomass is provided as input.

1.2.2. State variables

1.2.2.1. Simulation

The Simulation entity contains the following state variables:

Table 1.1 `Simulation` state variables
Variable	Description	Type
i_step_simu	Times step of the simulation	int, \(\in [0, N_{year} \times N_{step\_year}]\)
rank	Index of the simulation	int, \(\in[0, N_{simulation}]\)
schoolSet	List of the `School` inside the simulation	`SchoolSet`
backSchoolSet	List of the `BackgroundSchool` inside the simulation	`BackgroundSchoolSet`

1.2.2.2. Cell

The Cell entity contains the following state variables:

Table 1.2 `Cell` state variables
Variable	Description	Type	Units
i	i-index of the current cell on the 2D grid	int, \(\in [0, N_x - 1]\)
j	j-index of the current cell on the 2D grid	int, \(\in [0, N_y - 1]\)
land	true if the cell is on land	boolean
lat	latitude	float	Degrees North
lon	longitude	float	Degrees East
surf	surface	float, > 0	\(m^2\)

1.2.2.3. Species

The Species entities contain the following state variables:

Table 1.3 `Species` state variables
Variable	Description	Type	Units
name	name of the species	string
index	index of the species	int, \(\in[0, N_{species} - 1]\)
fileIndex	index of the species in the configuration file	int, \(>0\)
lifespan	species life span	int, \(>0\)	time-steps
c	allometric factor	float
bPower	allometric power	float
sizeMaturity	Size at maturity	float	cm
ageMaturity	Age at maturity	float	year
eggSize	Size of eggs	float	cm
eggWeight	Weight of eggs	float	g
firstFeedingAgeDt	First feeding age	int	time-step
larvaeToAdultsAgeDt	Age at which the school is considered as adult	int	time-step
TL_EGG	egg trophic level	float, \(= 3.0\)

The BackgroundSpecies entities contain the following state variables:

Table 1.4 `BackgroundSpecies` state variables
Variable	Description	Type	Units
name	Species name	string
index	Species index.	int, \(\in [N_{species}, N_{species} + N_{bkgspecies}] - 1\)
fileindex	index of the species in the	int, \(>0\)
age	Age array	[float]	years
ageDt	Age array	[int]	time-step
c	allometric factor	float
bPower	allometric power	float float
classProportion	Proportion of biomass attributed to each size-class	float[]	%
length	Length array	float[]	cm
nClass	Number of size-classes	int, \(>1\)
trophicLevel	Array of trophic level	float[]
timeSeries	Time series of proportion of biomass attributed to each size-class

Table 1.5 `ResourceSpecies` state variables
Variable	Description	Units
accessMax	Maximum value for resource accessibility	0.99
accessibilityCoeff	Fraction of the resource biomass available to the fish	[0, 1]
fileindex	Species index in the configuration file
index	Resource species index
name	Resource species name
sizeMax	Maximum size of the plankton size	Cm
sizeMin	Maximum size of the plankton size	Cm
trophicLevel	Trophic level

1.2.2.4. School

The School entity contains the following state variables:

Table 1.6 `School` state variables
Variable	Description	Type	Units
abundance	Number of fish in the school at the beginning of the time-step	float
biomass	Biomass of the school at the beginning of the school	float	Tons
instantaneousAbundance	Instanteanous number of fish in the school	float
instantaneousBiomass	Instanteanous biomass of the school at the beginning of the school	float	Tons
discardedBiomass	Biomass of the school that has been discarded by each fishing gear	float[]	Tons
fishedBiomass	Biomass of the school that has been landed by each fishing gear	float[]	Tons
nDead	Number of dead fish in the current time nstep for each mortality cause (predation, fishing, natural mortality, starvation)	float
predSuccessRate	Predation success rate	float	%
preyedBiomass	Biomass of prey ingested by the school at current time step	float	Tons
preys	List of preys eaten by the school	HashMap<Integer	Prey>
uuid	Unique identifier of the individual	UUID
lat	Latitude of the individual	float	Degrees north
lon	Longitude of the individual	float	Degrees east
x	i-index of the individual in the 2D grid	int
y	j-index of the individual in the 2D grid	int
ageDt	Age of the school	int	Time-step
eggRetained	Buffer variable that will temporarily retain some eggs inside a time step	float
length	Length of the individuals in the school	float	cm
lengthi	Length of the individuals in the school at the beginning of the time-step	float	cm
out	True if the school is out of the computation domain	boolean
starvationRate	Starvation rate of the school	float
trophicLevel	Trophic level of the school	float
weight	Weight of the school	float	tons
species	School species	`Species`
abundanceHasChanged	True if abundance has changed in the current time-step	boolean
accessibility	Array of accessibility of the school to its preys	float[]
ageDeath	Age at which a school individuals die times the abundance	float[]	\(N\times years\)

Table 1.7 `BackgroundSchool` state variables
Variable	Description	Units
abundance	Number of fish in the school at the beginning of the time-step
biomass	Biomass of the school at the beginning of the school	Tons
discardedBiomass	Biomass of the school that has been discarded by each fishing gear	Tons
fishedBiomass	Biomass of the school that has been landed by each fishing gear	Tons
nDead	Number of dead fish in the current time nstep for each mortality cause (predation, fishing, natural mortality, starvation)
predSuccessRate	Predation success rate	%
preyedBiomass	Biomass of prey ingested by the school at current time step	Tons
preys	List of preys eaten by the school
uuid	Unique identifier of the individual
lat	Latitude of the individual
lon	Longitude of the individual
x	i-index of the individual in the 2D grid
y	j-index of the individual in the 2D grid
classIndex	Class index to which belongs the school
bkgSpecies	School background species

1.2.3. Scales

The basic units of OSMOSE are fish schools, which are composed of individuals that belong to the same species, and that have the same age, size (length, weight), food requirements and, at a given time step, the same geographical coordinates. From the school states (hereafter called individual states), biomass and abundance can be tracked at the population or community levels along with the size, age, and spatial dimensions.

Other variables can be reported such as the trophic level, the diets, the different sources of mortality, the catches from fishing operations. Because each school simulated in OSMOSE is represented from the egg stage to the terminal age, which necessitates high calculation and memory capacities, and because comprehensive information on entire life cycles needs to be parameterized, the selection of focus species is made parsimoniously, and usually between 10 and 20 high-trophic level species or functional groups are explicitly considered in OSMOSE applications.

The model operates on a weekly to monthly time step, and runs up to 100 years or more depending on applications and simulations.

For eggs (age 0), weight and sizes are provided as parameters. For the others, conversion from size to weight (and conversely) is obtained by using allometric relationships:

\[ \begin{align}\begin{aligned}W = c \times L^b\\L = \left(\frac{W}{c}\right)^{\frac{1}{3}}\end{aligned}\end{align} \]

where the \(c\) parameter is a condition factor, and \(b\) the allometric power.

Biomass to abundance conversion for a school is made by using the mean weight of the school:

\[ \begin{align}\begin{aligned}B = N \times W\\N = \frac{B}{W}\end{aligned}\end{align} \]

Table 1.8 Allometric parameters
species.length2weight.condition.factor.sp#	Allometric factor (\(c\))
species.length2weight.allometric.power.sp#	Allometric power (\(b\))
species.egg.size.sp#	Egg size (cm)
species.egg.weight.sp#	Egg weight (g)