4 Stock Files

The stock files contain all the information that Gadget requires for each stock in the model. To define the stock files in the Gadget model, the following lines are required in the “main” Gadget file:

[stock]
stockfiles             <names of the stock files>

The “main” file needs to list the files that define the stocks to be used in the model. Each stock requires a separate stock file. The information for the stocks are very detailed, and so these stock files are quite large and can be complicated to look at. The basic format for this file is:

stockname              <name of the stock>
livesonareas           <areas that the stock lives on>
minage                 <minimum age for the stock>
maxage                 <maximum age for the stock>
minlength              <minimum length for the stock>
maxlength              <maximum length for the stock>
dl                     <step size for the length groups>
refweightfile          <see Reference Weight>
growthandeatlengths    <see Growth and Eat Lengths>
doesgrow               <see Growth>
naturalmortality       <see Natural Mortality>
iseaten                <see Stock Prey>
doeseat                <see Stock Predator>
initialconditions      <see Initial Conditions>
doesmigrate            <see Migration>
doesmature             <see Maturation>
doesmove               <see Movement>
doesrenew              <see Renewal>
doesspawn              <see Spawning>
doesstray              <see Straying>

The first seven lines of this file give the basic details of the stock, and are fairly self explanatory. It should be noted that the oldest age group and the longest length group are interpreted in Gadget as plus groups for the stock. The remaining lines give more detail about the stock, and are covered in the sub sections below.

4.1 Reference Weight

The reference weight section lists the weight of the stock for various length groups. This is the reference weight that can be used in the initial conditions to set up the stock, and can also be used by the growth functions when calculating the increase in length of the stock due to the growth. In the stock file, the format for the reference weight is given by:

refweightfile          <name of the reference weight file>

The format of the reference weight file is simply a two column list of the length and the corresponding weight for the stock. This file is ordered so that the smallest length group is given first, up to the longest length group which is given last. The format for this file is shown below:

<length>  <weight>

When this data is read into Gadget it is aggregated so that the weight is calculated for each length group defined in the stock file.

4.2 Growth and Eat Lengths

The calculations for the growth and consumption parts of the Gadget model can be done on a coarser scale than that defined in the stock file. The growth and eat lengths section of the stock file gives the name of a length aggregation file that defines this length grouping. In the stock file, the format for the growth and eat lengths is:

growthandeatlengths    <name of the length aggregation file>

4.3 Growth

The growth section of the stock file determines if, and how, the stock will grow in the Gadget model. The format for the first part of the growth section is given below:

doesgrow               <0 or 1> ; 0 for no growth, 1 for growth

If there is no growth, then the following sections don’t apply, and the next section of the input file is the natural mortality, given in section 4.5 below. If the stock does grow, there are various different functions that determine the mean growth of the stock, so there are a number of different formats that the growth data can take. Once the mean growth has been calculated, the growth then needs to be statistically distributed to give the overall growth of the stock. Thus, after the growth function data has been read in, there is then data for the growth implementation. The full format for the growth of the stock is therefore given by:

doesgrow               1
growthfunction         <growth function>
<format for the growth function data>
<format for the growth implementation>

The $<$growth function$>$ defines what growth function is to be used to calculate the growth of the stock. Currently, there are 7 growth functions defined, so valid function names are:

multspec - use the MULTSPEC growth function
weightvb - use the WeightVB growth function
weightjones - use the WeightJones growth function
weightvbexpanded - use the WeightVBExpanded growth function
lengthvb - use the LengthVB growth function
lengthpower - use the LengthPower growth function
lengthvbsimple - use the LengthVBSimple growth function

4.3.1 MULTSPEC Growth Function

This growth function is a simplified “MULTSPEC” growth equation, with the increase in length for each length group of the stock given by equation (4.1), and the corresponding increase in weight of the stock given by equation (4.2) below:

\[\begin{equation} \tag{4.1} \Delta L_{i} = \Delta t p_{0} {L_{i}}^{p_{1}} \psi (p_{2} T + p_{3}) \end{equation}\]

\[\begin{equation} \tag{4.2} \Delta W_{i} = \Delta t p_{4} {W_{i}}^{p_{5}} (\psi - p_{6}) (p_{7} T + p_{8})\end{equation}\]

where: $<\Delta t>$ is the length of the timestep, as a fraction of year $<$ T $>$ is the temperature $<\psi>$ is the feeding level (see section 4.7.1

There are 4 parameters in the length equation, and 5 in the weight equation, giving a total of 9 parameters to be declared to define this growth function. This is given in the main stock file by declaring a single vector with 9 components, consisting of the 4 length parameters followed by the 5 weight parameters. This is shown below:

growthparameters       <growth parameters vector>

4.3.2 WeightVB Growth Function

This growth function is a form of the Von Bertalanffy growth equation, extended to introduce the concept of starvation to the growth function. The increase in the weight for each length group the stock is given by equation (4.3), and the corresponding increase in the length of the stock is given by equation (4.6) below:

\[\begin{equation} \tag{4.3} \Delta W_{i} = \Delta t q_{0} e^{q_{1} T} \left( \left( \frac{W_{i}}{q_{2}} \right)^{q_{4}} - \left( \frac{W_{i}}{q_{3}} \right)^{q_{5}} \right)\end{equation}\]

\[\begin{equation} \tag{4.4} r = \frac{W - \left( p_{0} + p_{8} \left( p_{1} + p_{2}p_{8} \right) \right) W_{ref}}{W}\end{equation}\]

\[\begin{equation} \tag{4.5} f(x) = \begin{cases} 0 & \textrm{if $p_{3} + p_{4}x \leq 0$} \\ p_{5} & \textrm{if $p_{3} + p_{4}x \geq p_{5}$} \\ p_{3} + p_{4}x & \textrm{otherwise} \end{cases}\end{equation}\]

\[\begin{equation} \tag{4.6} \Delta L_{i} = \frac{\Delta W_{i}} {p_{6} p_{7} l^{p_{7} - 1}} f(r)\end{equation}\]

where: $<\Delta t>$ is the length of the timestep, as a fraction of year $<$ T $>$ is the temperature $<W_{ref}>$ is the reference weight

Comparing the weight to the reference weight (by using equations(4.4) and (4.5) introduces the concept of starvation to the Gadget model. When the weight of the population is less than a function of the reference weight, there is no length increase (ensuring that the growth only has an effect on the weight).

There are 6 parameters for the equation for increase of the weight, and a further 9 parameters for the increase in length. These are declared in 2 vectors, as shown below:

wgrowthparameters      <weight parameters vector>
lgrowthparameters      <length parameters vector>

4.3.3 WeightJones Growth Function

This growth function is a form of the Jones growth equation, extended to introduce the concept of starvation to the growth function. The increase in the weight for each length group the stock is given by equation (4.7), and the corresponding increase in the length of the stock is given by equation (4.10) below:

\[\begin{equation} \tag{4.7} \Delta W_{i} = \Delta t \left( \frac{C}{q_{0} W_{i}^{q_{1}}} - q_{2} W_{i}^{q_{3}} e^{(q_{4} T + q_{5})} \right)\end{equation}\]

\[\begin{equation} \tag{4.8} r = \frac{W - \left( p_{0} + \psi \left( p_{1} + p_{2}\psi \right) \right) W_{ref}}{W}\end{equation}\]

\[\begin{equation} \tag{4.9} f(x) = \begin{cases} 0 & \textrm{if $p_{3} + p_{4}x \leq 0$} \\ p_{5} & \textrm{if $p_{3} + p_{4}x \geq p_{5}$} \\ p_{3} + p_{4}x & \textrm{otherwise} \end{cases}\end{equation}\]

\[\begin{equation} \tag{4.10} \Delta L_{i} = \frac{\Delta W_{i}} {p_{6} p_{7} l^{p_{7} - 1}} f(r)\end{equation}\]

where: $<\Delta t>$ is the length of the timestep, as a fraction of year $<$ C $>$ is the consumption, calcluated by $M \psi$ (see 4.7.2, equation (4.22) & (4.23) respectively) $<$ T $>$ is the temperature $<\psi>$ is the feeding level (see 4.7.2, equation (4.23)) $<W_{ref}>$ is the reference weight

There are 6 parameters for the equation for increase of the weight, and a further 8 parameters for the increase in length. These are declared in 2 vectors, as shown below:

wgrowthparameters      <weight parameters vector>
lgrowthparameters      <length parameters vector>

4.3.4 WeightVBExpanded Growth Function

This growth function is an expanded form of the Von Bertalanffy growth equation, with additional information to allow for differing growth depending on the year, timestep and area. The increase in the weight of the stock is given by equation (4.11) below, and the corresponding increase in the length of the stock is identical to that for WeightVB growth function (see section 4.3.2) given by equation (4.6):

\[\begin{equation} \tag{4.11} \Delta W_{i} = \Delta t Y_{y} S_{s} A_{a} q_{0} e^{q_{1}T} \left( \left( \frac{W_{i}}{q_{2}} \right)^{q_{4}} - \left( \frac{W_{i}}{q_{3}} \right)^{q_{5}} \right) \end{equation}\]

where: $<\Delta t>$ is the length of the timestep, as a fraction of year $<$ T $>$ is the temperature $<Y_{y}>$ is a multiplier for year y $<S_{s}>$ is a multiplier for step s $<A_{a}>$ is a multiplier for area a

There are 6 parameters for the equation for increase of the weight, and a further 9 parameters for the increase in length and these are declared in 2 vectors. Additionally there are vectors for the year, step and area multipliers, as is shown below:

wgrowthparameters      <weight parameters vector>
lgrowthparameters      <length parameters vector>
yeareffect             <year effect vector>
stepeffect             <step effect vector>
areaeffect             <area effect vector>

Note that the $<$year effect$>$ vector requires one entry for each year, the $<$step effect$>$ vector requires one entry for each step and the $<$area effect$>$ vector requires one entry for each area.

4.3.5 LengthVB Growth Function

This growth function is a simplified form of the Von Bertalanffy growth equation. The increase in the length for each length group the stock is given by equation (4.12), with the corresponding increase in the weight of the stock read in from a data file:

\[\begin{equation} \tag{4.12} \Delta L_{i} = \left( L_{\infty} - L_{i} \right) \left( 1 - e^{-\kappa \Delta t} \right)\end{equation}\]

where: $<\Delta t>$ is the length of the timestep, as a fraction of year

There are a total of 2 parameters for the equation for increase in length. These are declared in a single vector, as shown below:

growthparameters       <linf> <kappa>
weightgrowthfile       <weight data file>

It is important to note that if the value of $L_{\infty}$ is less than the mean length of a length group, then the length increase calculated by equation (4.12) would be negative for that length group, which will result in Gadget printing a warning message. To avoid this, the user should ensure that the value of $L_{\infty}$ is always greater than the mean length of the largest length group.

The weight data file consists of a list of the year, timestep, area and length group label, followed by the mean increase in weight for that timestep/area/length combination. The length group label used must match those specified in the growthandeatlengths length aggregation file. The format of this file is shown below:

<year>  <step>  <area>  <length group>  <number>

4.3.6 LengthPower Growth Function

This growth function uses a simple power-based growth equation to calculate the increase in length. The increase in the length for each length group the stock is given by equation (4.13), with the corresponding increase in the weight of the stock read in from a data file:

\[\begin{equation} \tag{4.13} \Delta L_{i} = L_{i}^{q_{0}} e^{q_{1} \Delta t}\end{equation}\]

where: $<\Delta t>$ is the length of the timestep, as a fraction of year

There are a total of 2 parameters for the equation for increase in length. These are declared in a single vector, as shown below:

growthparameters       <growth parameters vector>
weightgrowthfile       <weight data file>

<year>  <step>  <area>  <length group>  <number>

4.3.7 LengthVBSimple Growth Function

This growth function is a simplified form of the Von Bertalanffy growth equation. The increase in the length for each length group the stock is given by equation (4.14), and the corresponding increase in the weight of the stock is given by equation (4.15) below:

\[\begin{equation} \tag{4.14} \Delta L_{i} = \left( L_{\infty} - L_{i} \right) \left( 1 - e^{-\kappa \Delta t} \right)\end{equation}\]

\[\begin{equation} \tag{4.15} \Delta W_{i} = \alpha \left( \left( L_{i} + \Delta L_{i} \right) ^{\beta} - {L_{i}}^{\beta} \right)\end{equation}\]

where: $<\Delta t>$ is the length of the timestep, as a fraction of year

There are a total of 4 parameters for the equation for increase in length and weight. These are declared in a single vector, as shown below:

growthparameters       <linf> <kappa> <alpha> <beta>

It is important to note that if the value of $L_{\infty}$ is less than the mean length of a length group, then the length increase calculated by equation (4.14) would be negative for that length group, which will result in Gadget printing a warning message. To avoid this, the user should ensure that the value of $L_{\infty}$ is always greater than the mean length of the largest length group.

4.4 Growth Implementation

The growth functions described above calculate the mean growth for the stock within the model. This must then be translated into a statistical distribution of actual growths around that mean. Currently there is only one statistical distribution implemented with Gadget, the beta-binomial, which is described below.

Note that regardless of the results of the implementation function there is a minimum width to the possible distribution implemented in Gadget - where growth is allocated between two adjacent length categories. This is a result of the discretisation within Gadget. To avoid this the user should select a length category size small enough for some fish to grow by at least 3 or 4 categories in one time step.

4.4.1 Beta-Binomial

This method uses a statistical distribution to govern the implementation of fish growth. The statistical distribution chosen is the beta-binomial, an extension of the binomial distribution with the flexibility to produce non-symmetrical distributions, which is defined for integers, x = 0, …, n as:

\[\begin{equation} \tag{4.16} {n \choose x} p^x (1 - p)^{n - x} = \frac{\Gamma(n + 1)}{\Gamma(x + 1)\Gamma(n - x + 1)} p^x (1 - p)^{n - x}\end{equation}\]

For more flexibility, this can be re-arranged by calculating the parameter $<$p$>$ from a second beta-binomial distribution, leading to equation (4.17) shown below, which is defined for 0 $\le$ p $\le$ 1:

\[\begin{equation} \tag{4.17} f(p) = \frac{\Gamma(\alpha + \beta)}{\Gamma(\alpha) \Gamma(\beta)}p^{\alpha - 1}(1 - p)^{\beta - 1}\end{equation}\] \[\begin{equation} \tag{4.18} \alpha = \frac{\beta \Delta L}{n - \Delta L}\end{equation}\]

The distribution is governed by three parameters; the mean length growth computed by the growth function scaled by dividing by the width of the length groups ($<\Delta$L $>$), a fixed limit on the number of length groups ($<$ n $>$), and a value for beta. This distribution was chosen because it provides a high degree of flexibility resulting from changing a single estimated parameter, beta. To define the distribution data using a beta-binomial distribution the following data is required in the main stock file:

beta                   <beta>
maxlengthgroupgrowth   <max length group growth>

The parameter $<$beta$>$ is the parameter that Gadget can estimate in the optimisation routines, in order to tune the distribution to best fit the data. High values of beta produce a narrow distribution, whilst lower values produce a more dispersed distribution with a larger right-hand tail. Note that very low values of beta (which lead to $\alpha$ < 1 in equation (4.18)) can lead to unexpected results and should be avoided.

The $<$max length group growth$>$ value is the maximum number of length categories a fish is permitted to grow in a single timestep within the model. This should be set to be several length groups larger than any fish can be reasonably expected to grow in a time step, in order to provide the beta-binomial distribution with sufficient flexibility to produce a distribution around the mean.

4.5 Natural Mortality

The natural mortality is a measure of how much of the stock will be removed from the model due to additional natural causes that are not modelled as part of other processes (for example predation). In Gadget, this is simply modelled as the proportion of the stock that is removed due to these additional causes (the residual mortality) from each age group, on each timestep, as shown in equation (4.19) below:

\[\begin{equation} \tag{4.19} N_{a} = e^{-m_{a} \Delta t}\end{equation}\]

where: $<\Delta t>$ is the length of the timestep, as a fraction of year.

The natural mortality parameters $<m_{a}>$ are specified in the stock file as a vector, with one parameter per age group, as shown below:

naturalmortality       <natural mortality vector>

4.6 Stock Prey

The stock prey section of the stock file determines if, and how, the stock will be treated as a prey in the Gadget model. The format for the first part of the prey section of the main stock file is given below:

iseaten                <0 or 1> ; 0 for not eaten, 1 for eaten

Note that the fleets are treated as a predator by Gadget, so for the stock to be caught by the fleets, the stock needs to be declared as a prey. If the stock is not eaten, then the following section doesn’t apply, and the next section of the input file is the stock predator, given in section 4.7 below. If the stock is eaten, then for Gadget to treat it as a prey the length groups for that prey, and the energy content of the prey, must be defined. The length groups need not be to the same scale as for the stock as a whole. This is done by listing a length aggregation file that is to be used, as well as the energy content (in kilojoules per kilogram), as shown for the full example below:

iseaten                1
preylengths            <length aggregation file>
energycontent          <energy value>

4.7 Stock Predator

The stock predator section of the stock file determines if, and how, the stock will be treated as a predator in the Gadget model. The format for the first part of the predator section is given below:

doeseat                <0 or 1> ; 0 for not a predator, 1 for predator

If the stock is not a predator, then the following sections don’t apply, and the next section of the input file is the initial conditions, given in section 4.8 below. If the stock is a predator, then it is necessary to specify information about the predation. This is done by defining a suitability function, and then some prey preference, consumption and feeding parameters. The full format for this is shown below:

doeseat                1
suitability            <see Suitability>
preference             <prey preference values>
maxconsumption         <maximum consumption vector>
halffeedingvalue       <half feeding value>

The $<$suitability$>$ defines the prey that the predator will consume, and is discussed in the Suitability section below (see section 4.7.3. The $<$prey preference$>$ values, $<$maximum consumption$>$ vector and $<$half feeding$>$ value parameters define how the stock consumes any prey that is eaten, and are described in the following section.

4.7.1 Consumption

The consumption determines how much of a given prey is consumed by the predator. This will result in the population of the prey being reduced, and can also affect the growth of the predator, depending on the growth function selected. The consumption of a prey is dependant on the length of both the predator and the prey, and the amount of the prey available, as a proportion of the total amount of food available. The consumption of prey $p$ is given by equation (4.20) below:

\[\begin{equation} \tag{4.20} C_{p}(l, L) = \frac{N_{L} M_{L} \psi_{L} F_{p}(l, L)}{E_p \displaystyle \sum_{\it preys} \sum_{\it prey\_lengths} F_{p}(l, L)}\end{equation}\]

\[\begin{equation} \tag{4.21} F_{p}(l, L) =\Big( S_{p}(l, L) E_{p} N_{l} W_{l} \Big) ^{d_{p}}\end{equation}\]

\[\begin{equation} \tag{4.22} M_{L} = m_{0} \Delta t e^{(m_{1}T - m_{2}T^3)} L^{m_{3}}\end{equation}\]

\[\begin{equation} \tag{4.23} \psi_{L} = \frac{\displaystyle \sum_{\it preys} \sum_{\it prey\_lengths} F_{p}(l, L)}{H \Delta t + \displaystyle \sum_{\it preys} \sum_{\it prey\_lengths} F_{p}(l, L)}\end{equation}\]

where:

$<$ L $>$ is the length of the predator
$<$ l $>$ is the length of the prey
$<$ H $>$ is the half feeding value
$<$ d $>$ is the preference of the predator for the prey (see section 4.7.2)
$<$ E $>$ is the energy content of the prey (see section 4.6)
$<$ N $>$ is the number of prey in the length cell
$<$ W $>$ is the mean weight of the prey in the length cell
$<$ S $>$ is the suitability function (see section 4.7.3)
$<\Delta t>$ is the length of the timestep
$<$ T $>$ is the temperature of the area that the feeding takes place on

Equation (4.20) produces the total biomass that the predator stock wants to consume of a given prey. When summing preys summation is over all preys that the predator consumes, including non-modelled prey given as “otherfood” in section 6. The value of $<$ C $>$ can have an affect on the growth of the predator when the growth function has been set to “WeightJones” (see section 4.3.3).

Equation (4.21) produces the total energy content that a single predator wants to consume of a given prey,

4.7.2 Prey preference

The prey preference parameter is specified by listing the names of the prey and the associated preference value, as shown in the example below:

...
preference
<name of prey 1>       <preference for prey 1>
<name of prey 2>       <preference for prey 2>
maxconsumption         <maximum consumption vector>
...

In equation (4.21), the parameter $<$ d $>$ gives the preference of the predator for the prey, controlling the form of the functional response that is used to model the predation. Setting this parameter to 1 will ensure that a Type II functional response is used (note that this is always used when modelling the predation by the fleets, see section 7. Any other value will mean that a Type III functional response is used.

In equation (4.22), the parameter $<$ M $>$ gives the maximum possible consumption for the predator on the current timestep. This is a function of temperature and the length of the predator, using the 4 parameters specified by the $<$maximum consumption$>$ vector in the input file. Note that the maximum consumption should be specified in kilojoules per month.

In equation (4.23), the parameter $<\psi>$ gives the “feeding level” which denotes the fraction of the available food that the predator is consuming. This is governed by the total amount of prey available and the $<$half feeding$>$ value which is specified in the input file. The $<$half feeding$>$ value is the biomass of prey required to allow the predator to consume prey at half the maximum consumption level. The value of $<\psi>$ can have an affect on the growth of the predator (ie. when there isn’t sufficient food available) when the growth function has been set to “MULTSPEC” or “WeightJones”.

4.7.3 Suitability

The suitability determines how the predators act on the preys. This selectivity relationship between the predator and the prey is based on the lengths of the predator and prey, and are defined by declaring a suitability function and the parameters for that function. The suitability values can be thought of as the proportion of the prey length group that the predator length group can consume, and as such the suitability values should be between 0 and 1.

To define a suitability relationship based on a suitability function, the stock file (for the predator) needs to contain the following data:

suitability
<preyname>    function <functionname> <parameters> ; for each prey

The $<$functionname$>$ defines which suitability function is to be used to calculate the suitability for the predator acting on the prey. Currently there are 7 suitability functions defined, and the valid suitability function names are:

constant - use the Constant suitabilty function
straightline - use the StraightLine suitabilty function
exponential - use the Exponential suitabilty function
newexponentiall50 - use the ExponentialL50 suitabilty function
richards - use the Richards suitabilty function
andersen - use the Andersen suitabilty function
andersenfleet - use the Andersen suitabilty function, modified for fleets
gamma - use the Gamma suitabilty function

For the following suitability functions, the convention used is to represent the length group of the prey by l, and the length group of the predator by L.

4.7.4 Constant Suitability Function

This is a constant suitability function, where there is no dependence on either the length of the predator or the length of the prey as given by the following equation:

\[\begin{equation} \tag{4.24} S(l, L) = \alpha\end{equation}\]

Hence, to specify a constant suitability function, the file format required is:

<preyname>    function constant <alpha>

4.7.5 StraightLine Suitability Function

This is a suitability function that has no dependence on the length of the predator, and a linear dependence on the length of the prey as given by the following equation:

\[\begin{equation} \tag{4.25} S(l, L) = \alpha l + \beta\end{equation}\]

Hence, to specify a straight line suitability function, the file format required is:

<preyname>    function straightline <alpha> <beta>

4.7.6 Exponential Suitability Function

This is a suitability function that has a logarithmic dependence on both the length of the predator and the length of the prey as given by the following equation:

\[\begin{equation} \tag{4.26} S(l, L) = {\frac{\delta}{1 + e^{(- \alpha - \beta l - \gamma L)}}}\end{equation}\]

Hence, to specify this suitability function, the file format required is:

<preyname>    function exponential <alpha> <beta> <gamma> <delta>

4.7.7 ExponentialL50 Suitability Function

This is a suitability function that has no dependence on the length of the predator, and a logarithmic dependence on the length of the prey as given by the following equation:

\[\begin{equation} \tag{4.27} S(l, L) = { \frac{1}{1 + e^{ -\alpha (l - l_{50})}}}\end{equation}\]

Note that the prey length dependence is actually dependant on the difference between the length of the prey and $l_{50}$, which is the length of the prey with a 50% probability of predation. Hence, to specify this suitability function, the file format required is:

<preyname>    function newexponentiall50 <alpha> <l50>

4.7.8 Richards Suitability Function

This is a suitability function that is an extension to the Exponential suitiability function, and has a logarithmic dependence on both the length of the predator and the length of the prey as given by the following equation:

\[\begin{equation} \tag{4.28} S(l, L) = \left({\frac{p_3}{1 + e^{(- p_0 - p_1 l - p_2 L)}}}\right) ^ {\frac{1}{p_4}}\end{equation}\]

Hence, to specify this suitability function, the file format required is:

<preyname>    function richards <vector of 5 parameters>

4.7.9 Andersen Suitability Function

This is a more general suitability function that is dependant on the ratio of the predator length to the prey length as given by the following equation:

\[\begin{equation} \tag{4.29} S(l, L) = \begin{cases} p_0 + p_2e^{-\frac{(\ln\frac{L}{l} - p_1)^2}{p_4}} & \textrm{if $\ln\frac{L}{l} \leq p_1$} \\ p_0 + p_2e^{-\frac{(\ln\frac{L}{l} - p_1)^2}{p_3}} & \textrm{if $\ln\frac{L}{l} > p_1$} \end{cases}\end{equation}\]

Note that the log of the ratio of the predator/prey lengths is bounded, to ensure that the suitability function is always well defined. To specify this suitability function, the file format required is:

<preyname>    function andersen <vector of 5 parameters>

4.7.10 Andersen Fleet Suitability Function

This is a modified version of the Andersen suitability function that is dependant on the ratio of a parameter to the prey length as given by the following equation:

\[\begin{equation} \tag{4.30} S(l, L) = \begin{cases} p_0 + p_2e^{-\frac{(\ln\frac{p_5}{l} - p_1)^2}{p_4}} & \textrm{if $\ln\frac{p_5}{l} \leq p_1$} \\ p_0 + p_2e^{-\frac{(\ln\frac{p_5}{l} - p_1)^2}{p_3}} & \textrm{if $\ln\frac{p_5}{l} > p_1$} \end{cases}\end{equation}\]

Note that the log of the ratio of the fleet parameter/prey length is bounded, to ensure that the suitability function is always well defined. Compared to the standard Andersen suitability function, the additional parameter is used to replace the predator length and is often used as a proxy for the mesh size used by the fleets. To specify this suitability function, the file format required is:

<preyname>    function andersenfleet <vector of 6 parameters>

4.7.11 Gamma Suitability Function

This is a suitability function that is only dependant on the prey length as given by the following equation:

\[\begin{equation} \tag{4.31} S(l, L) = \left(\frac{l}{(\alpha - 1) \beta\gamma}\right) ^ {(\alpha - 1)}e ^ {(\alpha - 1 - \frac{l}{\beta\gamma})}\end{equation}\]

Hence, to specify this suitability function, the file format required is:

<preyname>    function gamma <alpha> <beta> <gamma>

This is a suitability function that is more suitable for use when considering the predation by a fleet (see section 7.6), where the parameter $<\gamma>$ would represent the size of the mesh used by the fleet (specified in centimetres).

4.8 Initial Conditions

The initial conditions section of stock file specifies the stock population at the start of the simulation (ie. at the beginning of the first timestep specified in the “time” file). This includes setting up the population size, the length distribution and the mean weight for each length group. This is done by specifying the minimum and maximum age and length for the stock on this timestep, and either specifying parameters to allow Gadget to create a stock distribution based on a Normal distribution, or the numbers that make up the stock distribution required.

The format for the initial conditions section of the stock file is given below:

initialconditions
minage                 <minimum age for the initial stock>
maxage                 <maximum age for the initial stock>
minlength              <minimum length for the initial stock>
maxlength              <maximum length for the initial stock>
dl                     <step size for the initial length groups>
sdev                   <standard deviation multiplier>
<initial stock distribution data>

The optional $<$sdev$>$ value is used to scale the standard deviation of the length of the initial stock. The standard deviation used in calculating the length distribution will be multiplied by this value. If it is not specified, then it is assumed to have a value of 1 (ie, no scaling will take place). The optional $<$dl$>$ value is used to set the length group divisions for the initial stock population. If this is not specified, then it is assumed that the initial population will have the same value for $<$dl$>$ as for the stock, as specified in the main stock file.

There are three formats for the initial stock distribution data, as given below:

Normal Condition - use a Normal function to generate the length distribution, with a relative condition factor to assign a mean weight to the initial population Normal Parametric - use a Normal function to generate the length distribution, with a parametric weight-length relationship to calculate a mean weight for the initial population Numerical - specify the numbers, and the corresponding mean weights, for the initial population

4.8.1 Normal Condition Distribution

To specify an initial stock with the lengths given by a Normal distribution, and using a relative condition factor to generate the weights, the main stock file needs to specify the name of a datafile containing the information about the Normal distribution, as shown below:

normalcondfile         <name of the initial stock data file>

The initial stock file contains all the information that Gadget requires to construct an initial population of the stock. Gadget will construct a population of 10,000 fish for each age group, with the length groups for these age groups having a Normal distribution about a specified mean length with a specified standard deviation. The mean weight for this initial population is calculated by multiplying the reference weight (specified in the main stock file) by a relative conditioning factor (which is typically set to 1).

To get from a population with 10,000 fish in each age group (for each area) to the initial population used in the model, each age group is multiplied by an age weighting factor and an area weighting factor.

Hence, the format for the initial stock file is given below:

<age>  <area>  <age factor>  <area factor>  <mean>  <stddev>  <relcond>

4.8.2 Normal Parametric Distribution

To specify an initial stock with the lengths given by a Normal distribution, and using a weight-length relationship to generate the weights, the main stock file needs to specify the name of a datafile containing the information about the Normal distribution, as shown below:

normalparamfile        <name of the initial stock data file>

The initial stock file contains all the information that Gadget requires to construct an initial population of the stock. Gadget will construct a population of 10,000 fish for each age group, with the length groups for these age groups having a Normal distribution about a specified mean length with a specified standard deviation. The mean weight for this initial population is then calculated from the standard weight-length relationship, as given in equation (4.32) below:

\[\begin{equation} \tag{4.32} W = \alpha L^{\beta}\end{equation}\]

Hence, the format for the initial stock file is given below:

<age>  <area>  <age factor>  <area factor>  <mean>  <stddev>  <alpha>  <beta>

4.8.3 Numerical Distribution

An alternative approach is to define the initial stock population by specifying an age-length table, along with the mean weight, for the initial stock. This approach requires the main stock file to specify a data file to give the age-length table, as shown below:

numberfile             <name of the initial stock data file>

The initial stock file contains the age-length table for the initial population. This file specifies the population, and mean weight, of the stock for each area, age group and length group combination, as shown below:

<area>  <age>  <length>  <number>  <weight>

Note that the $<$length$>$ value refers to the minimum length of the age-length cell that the initial population will be put into.

4.9 Migration

The migration section of the stock file determines if, and how, the stock will migrate in the Gadget model. The migration of a stock within a Gadget model is calculated based on migration matrices. The format for the first part of the migration section is given below:

doesmigrate            <0 or 1> ; 0 for no migration, 1 for migration

If the stock does not migrate, then the following section doesn’t apply, and the next section of the input file is the maturation, given in section 4.10 below. If the stock does migrate, then further information about the migration is required. There are currently 2 formats for the migration data, as given in the list below:

Migration Matrices - specify the migration matrices to be used Migration Ratios - specify the ratio of the stock that moves between areas, and let Gadget calculate the required matrices based on these ratios

4.9.1 Migration Matrices

To specify the migration of the stock by defining the migration matrices directly, the main stock file needs to specify the name of a datafile containing information about when the migration will take place, and the name of a datafile containing information about the migration matrices, as shown below:

doesmigrate            1
yearstepfile           <name of the migration timestep data file>
definematrices         <name of the migration matrix data file>

The migration timestep file contains a simple list of the timesteps that the migration will take place on, along with the name of the migration matrix that is to be used on each timestep, as shown below:

<year>  <step>  <migration matrix>

The migration matrix file contains the migration matrices to be used to move the stock between the various areas within the Gadget model. Each matrix is listed, starting with the keyword [migrationmatrix], followed by the name of the migration matrix, and then the matrix to be used, as shown below:

[migrationmatrix]
name   <migration matrix>
<migration matrix data>

The $<$migration matrix$>$ data should be a square $n$ x $n$ matrix, for the $n$ areas that the stock is defined on, with the proportion moving from each area given in the columns, and the proportion moving to each area given in the rows. Since migration shouldn’t change the total number of fish in the model, each column in the matrix should sum to one.

An example of a migration matrix data for a stock that is defined on two areas is given below:

[migrationmatrix]
name    example
0.6     0.3
0.4     0.7

For the migration of the stock in the example shown above, 60% of the stock that are on area 1 at the start of the migration will move to area 1 (ie. they will stay there) and the remaining 40% will move to area 2. For the stock that start the timestep on area 2, 30% will move to area 1 and the remaining 70% will stay on area 2.

4.9.2 Migration Ratios

An alternative approach is to specify the migration of the stock by defining the ratio of the stock that will migrate between given areas, and let Gadget calculate the resulting migration matrices to use within the model. To use this format for the migration data, the main stock file needs to specify the name of a datafile containing information about when the migration will take place, and the name of a datafile containing information about the migration ratios, as shown below:

doesmigrate            1
yearstepfile           <name of the migration timestep data file>
defineratios           <name of the migration ratio data file>

The migration timestep file contains a list of the timesteps that the migration will take place on, along with the name of the migration matrix that is to be used on each timestep, in the same format as for the Migration Matrices, as shown above.

The migration ratio file contains the ratios to be used by Gadget to construct the migration matrices to move the stock between the various areas within the Gadget model. Each matrix is listed, starting with the keyword [migrationmatrix], followed by the name of the migration matrix, and then a list of the ratios to be used to construct the matrix, as shown below:

[migrationmatrix]
name    <migration matrix>
<from>  <to>    <ratio>

The migration ratio data is a list of the ratio of the stock that moves from the $<$from$>$ area to the $<$to$>$ area. Gadget will attempt to construct the migration matrix based on these ratios. Where the data is incomplete, Gadget will assume that there is no migration between areas (ie. fish will stay on the area that they are on at the start of the timestep). If Gadget cannot construct a (unique) migration matrix, then the model will stop the current simulation and display an error message.

An example of a migration ratio data for a stock that is defined on two areas is given below:

[migrationmatrix]
name    example
1       2       0.4
2       1       0.3

For the migration of the stock in the example shown above, 40% of the stock that are on area 1 at the start of the migration will move to area 2, and the remaining 60% will stay on area 1. For the stock that start the timestep on area 2, 30% will move to area 1 and the remaining 70% will stay on area 2.

4.10 Maturation

The maturation section of the stock file determines if, and how, the stock will mature in the Gadget model. The format for the first part of the maturation section is given below:

doesmature             <0 or 1> ; 0 for no maturation, 1 for maturation

If the stock does not mature, then the following sections don’t apply, and the next section of the input file is the movement, given in section 4.11 below. If the stock does mature, then there are various different functions that describe how the stock can mature. The type of maturity function is denoted by a name, as shown below, and then the data required for that maturity function is given in a datafile. Thus the format for the maturity data, in the main stock file, is given below:

doesmature             1
maturityfunction       <maturity function>
maturityfile           <name of the maturity data file>

The $<$maturity function$>$ defines the function that is to be used to calculate how the stock will mature. Currently there are 4 maturity functions defined, and the valid maturity function names are:

newconstant - use the Constant maturation function
newconstantweight -use the ConstantWeight maturation function
fixedlength - use the FixedLength maturation function
continuous - use the Continuous maturation function

The format for the data in the maturity data file is dependent on the maturity function that is to be used. All the maturity functions require the name of the mature stocks that the immature stock will mature into, and the ratio of the maturing part of the immature stock that is to mature into each mature stock. This allows for part of an immature stock to mature into more than one mature stock, so for example, an immature stock could mature into either a male mature stock or a female mature stock.

The maturity functions calculate the proportion of the fish in each age-length group that will become mature, and then move these fish from the age-length group for the current stock into the corresponding age-length group for the mature stock. Note that there is a check to ensure that the corresponding age-length group exists for the mature stock, and if it doesn’t then the fish don’t become mature and will stay in the immature stock.

4.10.1 Constant Maturity Function

This maturity function calculates the proportion of an age-length group of an immature stock that becomes mature according to the maturity equation (4.33) given below:

\[\begin{equation} \tag{4.33} P(l, a) = \frac{1}{ 1 + e^{-\alpha(l - l_{50}) -\beta(a - a_{50})}}\end{equation}\]

The maturity term is a function of $l_{50}$ and $a_{50}$, which are the length and age where 50% of the stock are mature. For this maturation function, it is assumed that maturation is an annual event, taking place on the same timesteps in each year. The file format for this maturity function is the similar to that for the Continuous maturity function, and is shown below:

maturestocksandratios       <stockname i>  <ratio i> ; for each stock i
coefficients                <alpha>  <l50>  <beta>  <a50>
maturitysteps               <vector of timesteps>

The $<$maturitysteps$>$ vector is a vector of timesteps that the maturation process will take place on.

4.10.2 ConstantWeight Maturity Function

This maturity function is an extension to the Constant maturity function, with the maturity proportion being calculated according to the maturity equation (4.34) given below:

\[\begin{equation} \tag{4.34} P(l, a) = \frac{1}{ 1 + e^{-\alpha(l - l_{50}) -\beta(a - a_{50}) -\gamma(k - k_{50})}}\end{equation}\]

The maturity function has been extended to include the relative condition of the stock (calculated by dividing the current weight by the reference weight) and $k_{50}$ which is the relative condition where 50% of the stock is mature. The file format for this maturity function is the similar to that for the Constant maturity function, and is shown below:

maturestocksandratios       <stockname i>  <ratio i> ; for each stock i
coefficients                <alpha>  <l50>  <beta>  <a50>  <gamma>  <k50>
maturitysteps               <vector of timesteps>

4.10.3 FixedLength Maturity Function

This maturity function takes a different approach, and bases the proportion of the immature stock that matures on the length of the immature stock, as the length varies through the year. This is approach assumes that the maturation process is the same for each year. The proportion of the immature stock that matures is given by the equation (4.35) below:

\[\begin{equation} \tag{4.35} P(l, a) = \begin{cases} 1 & \textrm{if there is an $i$ such that $s_i$ is the current step and $l > l_i$} \\ 0 & \textrm{otherwise} \end{cases}\end{equation}\]

For each timestep in the year, the stock is assumed to mature when the length of the fish reaches a certain value. This length can change for each timestep. This information is given in a file with the format specified below:

maturestocksandratios       <stockname i>  <ratio i> ; for each stock i
maturitysteps               <vector of timesteps>
maturitylengths             <vector of lengths>

Note that the $<$maturitysteps$>$ and the $<$maturitylengths$>$ vectors need to be the same size.

4.10.4 Continuous Maturity Function

This maturity function calculates the proportion of an age-length group of an immature stock that becomes mature according to the maturity equations(4.36) and (4.37) given below:

\[\begin{equation} \tag{4.36} P(l, a) = {\frac{1}{1 - M}}{\frac{dM}{dt}}\end{equation}\]

\[\begin{equation} \tag{4.37} M(l_{t},a_{t}) = \frac{1}{1 + e^{-\alpha(l_{t} - l_{50}) - \beta(a_{t} - a_{50})}}\end{equation}\]

The maturity term is a function of $l_{50}$ and $a_{50}$, which are the length and age where 50% of the stock are mature. This is a continuous process, with the maturity proportion being calculated on every timestep. The file format for this maturity function is given below:

maturestocksandratios       <stockname i>  <ratio i> ; for each stock i
coefficients                <alpha>  <l50>  <beta>  <a50>

4.11 Movement (“Transition”)

The movement section of the stock file determines if, and how, the stock will move (into a different stock) in the Gadget model. This allows for a Gadget model to be set up with different stock files for stock that is the same species, but with differing properties (for instance age or maturity status) and for the entries to move between these stocks when required. For the current version of Gadget, the only movement between stocks that is valid is for the stock in the oldest age group of one stock to move into a different stock. The format for the first part of the movement section is given below:

doesmove               <0 or 1> ; 0 for no movement, 1 for movement

If the stock does not move, then the following section doesn’t apply, and the next section of the input file is the renewal, given in section 4.12 below. If the stock does move, then the information required to define the movement is the timestep for the movement to occur (since the movement is assumed to be an annual event) and the names of the stocks to move the oldest age group into, along with the ratio of the oldest age group that will move into that particular stock. Thus the full format for the movement of the stock is given below:

doesmove                    1
transitionstocksandratios   <stockname i>  <ratio i> ; for each stock i
transitionstep              <timestep for the stock to move>

The movement function simples move the fish from the oldest age-length groups for the current stock into the corresponding age-length group for the stock that the fish will move into (in a similar manner to that used for the maturation, given in section 4.10). Note that there is a check to ensure that the corresponding age-length group exists, and if it doesn’t then the fish don’t move and will stay in the oldest age group for current stock, which is modelled as a plus group.

4.12 Renewal (“Recruitment”)

The renewal section of the stock file determines if, and how, the stock will be renewed in the Gadget model. The format for the first part of the renewal section is given below:

doesrenew              <0 or 1> ; 0 for no renewal, 1 for renewal

If the stock does not renew, then the following sections don’t apply, and the next section of the input file is the spawning, given in section 4.13 below. If the stock does renew, then further information is required about the renewal data. This is given in a separate file, so the format for the renewal data, in the main stock file, is given below:

doesrenew              1
minlength              <minimum length for the recruits>
maxlength              <maximum length for the recruits>
dl                     <step size for the recruits>
<renewal distribution data>

The $<$dl$>$ value is optional, and can be used to specify a different step size for the recruits than for the stock that the recruits will be added to. If this value is not specified here then the recruits will be given the same step length as for the stock they will be added to.

In a similar manner to the format for the initial population (see section 4.8) there are three formats for the renewal distribution data, as given below:

Normal Condition - use a Normal function to generate the length distribution, with a relative condition factor to assign a mean weight to the new recruits Normal Parametric - use a Normal function to generate the length distribution, with a parametric weight-length relationship to calculate a mean weight for the new recruits Numerical - specify the numbers, and the corresponding mean weights, for the new recruits

4.12.1 Normal Condition Distribution

To specify renewal data with the lengths given by a Normal distribution, and using a relative condition factor to generate the weights, the main stock file needs to specify the name of a datafile containing the information about the Normal distribution, as shown below:

normalcondfile         <name of the renewal data file>

The renewal file contains all the information that Gadget requires to construct the renewal data for the stock. For each timestep and area, this file lists the the age of the recruits (which would typically match the minimum age of the stock that the recruits are to be added to), the number of recruits (in units of 10,000 fish), parameters used to define the Normal distribution for length groups of the recruits, and the relative condition factor, used along with the reference weight to assign a mean weight for the recruits.

Hence, the format for the renewal file is given below:

<year>  <step>  <area>  <age>  <number>  <mean>  <stddev>  <relcond>

4.12.2 Normal Parametric Distribution

To specify renewal data with the lengths given by a Normal distribution, and using a weight-length relationship to generate the weights, the main stock file needs to specify the name of a datafile containing the information about the Normal distribution, as shown below:

normalparamfile        <name of the renewal data file>

The renewal file contains all the information that Gadget requires to construct the renewal data for the stock. For each timestep and area, this file lists the the age of the recruits (which would typically match the minimum age of the stock that the recruits are to be added to), the number of recruits (in units of 10,000 fish), parameters used to define the Normal distribution for length groups of the recruits, and parameters to define the weight-length relationship for these recruits.

Hence, the format for the renewal file is given below:

<year>  <step>  <area>  <age>  <number>  <mean>  <stddev>  <alpha>  <beta>

4.12.3 Numerical Distribution

An alternative approach is to define the renewal data by specifying an age-length table, along with the mean weight, for each timestep that will have new fish added to the stock. This approach requires the main stock file to specify a data file to give the age-length table, as shown below:

numberfile             <name of the renewal data file>

The renewal file contains data for an age-length table for each timestep that will have new fish added to the stock. This file specifies the number, and mean weight, of the new fish for each timestep, area, age group and length group combination, as shown below:

<year>  <step>  <area>  <age>  <length>  <number>  <weight>

Note that the $<$length$>$ value refers to the minimum length of the age-length cell that the new fish will be put into.

4.13 Spawning

The spawning section of the stock file determines if, and how, the stock will spawn in the Gadget model. This covers the mortality and weight loss from the stock due to the spawning process, and optionally the creation of a new spawned stock. The format for the first part of the spawning section is given below:

doesspawn              <0 or 1> ; 0 for no spawning, 1 for spawning

If the stock does not spawn, then the following sections don’t apply, and the next section of the input file is the straying information, given in section 4.15 below. If the stock does spawn, then further information is required about the spawning data. This is given in a separate file, so the format for the spawning data, in the main stock file, is given below:

doesspawn              1
spawnfile              <name of the spawning data file>

The spawning data file defines what happens to the stock as it spawns. The spawning is length-dependent, and the affect that spawning has on each length group of the mature stock is given by the spawning equations(4.38) and (4.39) below:

\[\begin{equation} \tag{4.38} N = N {\left(1 + P {(e^{-m} - 1)}\right)}\end{equation}\]

\[\begin{equation} \tag{4.39} W = W \frac{\left(1 + P {((2 - w)e^{-m} - 1)}\right)}{\left(1 + P {(2e^{-m} - 1)}\right)}\end{equation}\]

where: $<$ N $>$ is the population of the age-length group $<$ W $>$ is the mean weight of the population of the age-length group $<$ P $>$ is the proportion of the length group that will spawn $<m>$ is the spawning mortality for that length group $<w>$ is the spawning weight loss for that length group

In equation (4.38), the population of the age-length cell of the mature stock is reduced due to the spawning mortality of the fish that spawn. In equation (4.39), the mean weight of the population in the age-length cell is adjusted to take the reduction in weight of the fish that spawn, and the change in population, into account.

Spawning is considered to be an annual event, that takes place on the same timestep and the same area in each year that the spawning occurs. To model the spawning process as it affects the parent (without the creation of a child stock), it is necessary to specify the timestep and area that the spawning will take place on, and the length selection functions to determine proportion of each length group that will spawn, and the spawning mortality and weight loss of those that spawn. This is done in the spawning data file, as shown below:

spawnsteps             <vector of timesteps>
spawnareas             <vector of areas>
firstspawnyear         <first year that the spawning occurs>
lastspawnyear          <last year that the spawning occurs>
onlyparent
proportionfunction     <see Length Selection>
mortalityfunction      <see Length Selection>
weightlossfunction     <see Length Selection>

The optional <firstspawnyear> and <lastspawnyear> values define the first and last years on which the spawning process will take place. This means that it is possible to define recruits (see section 4.12 above) for some years in the model and use a spawning process in other years in the model. If these are not specified in the input file, then it assumed that the spawning process will take place on all years in the simulation, and these will default to the first year and last year in the simulation.

Alternatively, it is possible to consider the spawning process as part of a through life-cycle model, and so the spawning process can create recruits to be added to one or more stocks (in a similar manner to the renewal data, given in section 4.12 above). The total number of recruits given by the spawning process is added to the youngest age group of the spawned stock at the start of the following timestep. The lengths of the spawned stock are distributed with a Normal distribution about a specified mean length $<$mean$>$ with a standard deviation $<$stddev$>$. The mean weight of the fish in these age length cells is given from equation (4.32), with $\alpha$ and $\beta$ specified in the spawning data file. Hence, if the spawning process is to calculate a number of recruits to the model, the format for the spawning data file is shown below:

spawnsteps             <vector of timesteps>
spawnareas             <vector of areas>
firstspawnyear         <first year that the spawning occurs>
lastspawnyear          <last year that the spawning occurs>
spawnstocksandratios   <stockname i> <ratio i> ; for each stock i
proportionfunction     <see Length Selection>
mortalityfunction      <see Length Selection>
weightlossfunction     <see Length Selection>
recruitment            <functionname>  <parameters>
stockparameters        <mean>  <stddev>  <alpha>  <beta>

The recruitment $<$functionname$>$ defines which recruitment function to use to calculate the number of recruits to be added to the spawned stock. Currently there are 4 recruitment functions defined, and the valid recruitment function names are:

fecundity - use the Fecundity recruitment function
simplessb - use the SimpleSSB recruitment function
ricker - use the Ricker recruitment function
bevertonholt - use the BevertonHolt recruitment function

4.13.1 Fecundity Recruitment Function

This recruitment function calculates the number of recruits to be added to the spawned stock as a function of the length, age, number and weight of the spawning stock, given by the following equation:

\[\begin{equation} \tag{4.40} R = p_{0} \sum_{\it ages}\sum_{\it lengths} l ^{p_{1}} a ^{p_{2}} N_{al} ^{p_{3}} W_{al} ^{p_{4}}\end{equation}\]