3 Model Files

Gadget requires a number of data files to define a Gadget model. The number of data files required depends on the complexity of the Gadget model, and there is no limit on the number, or name, of these data files. The main input file gives links to all the other data files required, and must be specified with the “-main \(<\)filename\(>\)” command line option, or be called “main”.

3.1 Main File

The main Gadget input file is usually called “main”, unless it is specified with the “-main \(<\)filename\(>\)” command line option. This file only contains links to other files which will make up the Gadget model. The format for this file is:

<typeoffile>        <filename>

where \(<\)typeoffile\(>\) is a keyword to tell Gadget what sort of information the file will contain, and the name of the file is given by \(<\)filename\(>\), relative to the directory in which the main file resides. Where zero or more files of a certain type could be used, the main file is divided into sections that are separated by a keyword in [square brackets]. The format for the main file is shown below:

timefile            <name of the time file>
areafile            <name of the area file>
printfiles          <names of the print files>
[stock]
stockfiles          <names of the stock files>
[tagging]
tagfiles            <names of the tag files>
[otherfood]
otherfoodfiles      <names of the otherfood files>
[fleet]
fleetfiles          <names of the fleet files>
[likelihood]
likelihoodfiles     <names of the likelihood files>

The printfile element of the main file is optional, and can be commented out if no model output is required. It should be noted that the keyword “printfiles” must be present, so to comment out the printfile section, a semi colon should be placed before the name of the printfile, as shown in the line below:

printfiles ; <filename> commented out so no printing will take place

3.2 Time File

This specifies the start and end times for the model run, and the number of timesteps per year. Note that the model can run into the future, and that datasets covering only part of the overall run can be used. Gadget splits each year up into a number of time steps, but these time steps need not all be the same length.

The format for this file is a list of the first year and timestep, and the last year and timestep, and how each year is to be divided into timesteps. This is done by specifying first the number of timesteps in a year, and then the length of each timestep (in months), and Gadget will check that the number of timesteps in a year sums up to 12. This is shown below:

firstyear       <first year>
firststep       <first step>
lastyear        <last year>
laststep        <last step>
notimesteps     <how the year is split up>

Examples for how the year can be split up include:

  1. 4 equal timesteps, splitting the year into quarters

    notimesteps     4 3 3 3 3

  2. 12 equal timesteps, splitting the year into months

    notimesteps     12 1 1 1 1 1 1 1 1 1 1 1 1

  3. 6 unequal timesteps, splitting the year into the following periods, \(<\)January - February\(>\), \(<\)March\(>\), \(<\)April - June\(>\), \(<\)July - September\(>\), \(<\)October\(>\) and \(<\)November - December\(>\)

    notimesteps     6 2 1 3 3 1 2

3.3 Area File

This file specifies which areas the model will be run on, and gives a time dependent temperature for each area. Note that although the temperature data must be provided it need not actually be used, depending on the growth and feeding options chosen for the stock file.

The format for this file is a list of the areas that are to be used (by specifying a numeric identifier for each area), followed by the size of each area (in square kilometres) and then a listing of the temperature for each timestep and area combination. An example of this format is given below:

areas   <vector of area identifiers>
size    <vector of sizes>
temperature
<year>  <step>  <area>  <temperature>

3.4 Other Input Data Files

There are four other types of input that are important since they are used in other data files to denote a grouping of data. These are Aggregation files, which are files used to gather data into convenient groups, TimeVariable files, which are files used to denote variables that can vary over time, StockVariable files, which are files used to denote vairables that can vary with population, and ActionAtTime, which is used to define the timesteps that an action takes place within a data file.

3.4.1 Aggregation Files

Aggregation files are important since they are used to group the data in convenient groups. They consist of a text label (used to identify the group in the data) followed by a list of the data that the label represents. This data will then be read in from an associated data file. There are aggregation files to group areas, ages, lengths or preys together. Aggregation files can contain comments and blank lines, to make the format easier to view in a text editor.

3.4.1.1 Area Aggregation

Area aggregation files contain one or more identifying labels and then a list of one or more areas that the label refers to. The format for this is:

<label>      <areas>

An example of this is:

north        1  2  6
south        3  4  5  7

This example shows that for the associated data file, the label “north” will be interpreted as applying to areas 1, 2 and 6 and the label “south” will be interpreted as applying to areas 3, 4, 5 and 7.

3.4.1.2 Age Aggregation

Age aggregation files contain one or more identifying labels and then a list of one or more ages that the label refers to. The format for this is:

<label>      <ages>

An example of this is:

young        1  2  3  4
old          5  6  7

This example shows that for the associated data file, the label “young” will be interpreted as applying to ages 1 - 4 and the label “old” will be interpreted as applying to ages 5 to 7.

3.4.1.3 Length Aggregation

Length aggregation files contain one or more identifying labels and then the minimum and maximum length that the label refers to. The format for this is:

<label>      <minimum>  <maximum>

When more than one length group label is defined, then the labels should be ordered so that the smallest length group is first in the file. The data is checked, so that the maximum length associated with label \(<\)i\(>\) is the same as the minimum length for label \(<\)i+1\(>\). An example of this is:

small        5   25
medium       25  55
large        55  80

This example shows that for the associated data file, the label “small” will be interpreted as applying to lengths 5-25cm, the label “medium” will be interpreted as applying to the lengths 25-55cm and the label “large” will be interpreted as applying to lengths 55-80cm.

3.4.1.4 Prey Aggregation

Prey aggregation files contain one or more identifying labels, and then the names of the preys, the minimum and maximum lengths for the preys and the digestion coefficients for the consumption of the preys. The format for this is:

<label>
<prey names>
lengths                  <minimum>  <maximum>
digestioncoefficients    d0  d1  d2

The digestion coefficients define a multiplier used when calculating the consumption of the prey. This multiplier is length dependant, and is calculated according to the digestion equation given below:

\[\begin{equation} \tag{3.1} D = d_{0} + d_{1}l^{d_{2}}\end{equation}\]

An example of a prey aggregation file is:

; for the first prey
smallcapelin
immature.capelin
lengths                  5  10
digestioncoefficients    1  0  0
;
; for the second prey
mediumcapelin
immature.capelin mature.capelin
lengths                  10 15
digestioncoefficients    1  0  0
;
; for the third prey
largecapelin
mature.capelin
lengths                  15 20
digestioncoefficients    1  0  0

This example shows that for the associated data file, the label “smallcapelin” will be interpreted as applying to immature capelin (a stock called immature.capelin) of lengths 5-10cm, the label “mediumcapelin” will be interpreted as applying to immature and mature capelin (stocks immature.capelin and mature.capelin) of lengths 10-15cm, and the label “largecapelin” will be interpreted as applying to mature capelin (a stock called mature.capelin) of lengths 15-20cm.

3.4.2 TimeVariable Files

TimeVariable files are used in place of a single variable in the input files, to define variables in the Gadget model that can vary over time. They are used by specifying the name of the TimeVariable file in place of the value or parameter in the input file. TimeVariable files can contain comments and blank lines, to make the format easier to view in a text editor.

TimeVariable files consist of a one word description of the data, followed by an optional multipler value and then the keyword “timedata”, and then a list of the timesteps when the value of TimeVariable changes, along with the new value for the TimeVariable. The values can either be numerical values or a parameter to be optimised. The first timestep in the TimeVariable file must correspond to the first timestep in the model. The basic format for this file is shown below:

<description>          ; one word description of the data
multipler              <optional multipler> ; default value 1
timedata
<year>  <step>  <value>

An example of a TimeVariable file is:

annualgrowth
timedata
; year  step  value
1995    1     #grow1995
1996    1     #grow1996
1997    1     #grow1997
1998    1     #grow1998
1999    1     #grow1999
2000    1     #grow2000

This example shows that the value of parameter “grow1995” is to be used for growth in 1995, “grow1996” is to be used in 1996 and so on through to “grow2000” which is to be used from 2000 through to the end of the simulation. Note that this example assumes that the first timestep of the simulation is the first timestep in 1995.

3.4.3 StockVariable Files

StockVariable files are used in place of a single variable in the input files, in a similar manner to the TimeVariable files, to define variables in the Gadget model that can vary due to stock populations changes. They are used by specifying the name of the StockVariable file in place of the value or parameter in the input file. StockVariable files can contain comments and blank lines, to make the format easier to view in a text editor.

StockVariable files consist of a one word description of the data, followed by an optional multipler value and then the keyword “stockdata”, and then a list of the stocks to use when caluclating the value of the StockVariable:

<description>          ; one word description of the data
multipler              <optional multipler> ; default value 1
stockdata
biomass                <0 or 1> ; default value 1
<vector of stock names>

The optional flag \(<\)biomass\(>\) is used to specify whether the biomass or the number of the stock population is used when calcualting the value of the StockVariable. If this is set to 0, then the StockVariable value will be based on the available number of the stock(s). If this line is not specified, then a biomass value of 1 is assumed and the StockVariable value will be based on the available population numbers for the stock(s).

An example of a StockVariable file is:

capelinconsumption
multipler     (* #param1 #param2)
stockdata
immature.capelin mature.capelin

This example shows that the value of the StockVariable is to be calculated as the value of “param1” times the value of “param2” times the total biomass of the stocks “immature.capelin” plus “mature.capelin”.

3.4.4 ActionAtTime

ActionAtTime is a simple list of timesteps within a data file that define when a specified action (for example printing) will take place. The format for this is:

<year>  <step>

where year and step are either a valid timestep or the keyword “all”. These can be grouped together to specify a more complex time period.

Examples of valid ActionAtTime entries in the data files include:

  1. the action taking place on the first timestep of 2002

    2002    1

  2. the action taking place on all timesteps of 2000

    2000    all

  3. the action taking place on the second timestep of each year

    all     2

  4. the action taking place on all timesteps of each year

    all     all

  5. the action taking place on the first and second timesteps of each year

    all     1
all     2