-
Notifications
You must be signed in to change notification settings - Fork 20
Getting started
Let me start by saying what this guide is not. It is not a definitive manual for Gadget. For comprehensive information on the options available for Gadget consult the book 'BORMICON: A Boreal Migration and Consumption Model' or the updated manual for Gadget. For details of the haddock example consult the guide that is distributed with the data files, or examine the data files using a standard text editor. A good place to start looking for information is by consulting the Gadget web site at www.hafro.is/gadget or by emailing gadgethelp@hafro.is.
What this document is intended to provide is an introduction to the getting started with the Gadget program. It will cover the basics of running Gadget. It will also give an overview of the structure of the data and model files for Gadget and the output produced, with special emphasis on the haddock example. There is also a brief introduction to the optimisation routines used within Gadget. It will also provide a brief discussion of factors to consider when creating your own models.
This document was written for Gadget version 2.0.00, and is hopefully correct for that release, and updated slightly for version 2.0.03. It may or may not be accurate for later releases. Note that the model format changed significantly between Gadget versions 1.0.x and 2.0.x.
This document assumes a basic knowledge of UNIX familiarity. Specifically it assumes that you can use some text editor, change and create directories, and copy and list files. This should be a sufficient knowledge base to be able to run and modify Gadget models. In order to download Gadget familiarity with ftp would be useful, however help is given for this in an appendix. If your UNIX familiarity is limited it may be worth your while getting someone else to download and compile the program for you, however you will definitely need to be able to read and edit text files under UNIX in order to get far with using Gadget.
Gadget is a flexible and powerful tool for creating ecosystem models. The program was developed for modelling marine ecosystems in a fisheries management and biology context, however there is nothing in the program that restricts it to fish, and models have been developed to examine marine mammal populations. Indeed there is nothing to demand that the populations being considered are marine, or even aquatic, in nature.
Gadget allows you to include a number of features into your model: One or more species, each of which may be split into multiple stocks; multiple areas with migration between areas; predation between and within species; maturation; reproduction and recruitment; multiple commercial and survey fleets taking catches from the populations. Variations on a theme
As well as Gadget there are several similar programs in existence. BORMICON (BOReal MIgration and CONsumption model) is the old name for Gadget. If you find a version calling itself BORMICON then it is an obsolete version. You should probably update to a more recent version (see Getting Started, below). Note that when Gadget runs there will be a short message on the screen letting you know which version number you are running. Fleksibest is a variant of Gadget developed at the Marine Research Institute in Bergen, Norway. Gadget is capable of running Fleksibest models, so it is probably best to use that. Finally there are two different implementations of Gadget available. One runs on a single computer, and is the version described here. The distributions include a second version of Gadget capable of running on multiple computers in parallel using PVM (Parallel Virtual Machine). This obviously reduces the run time of complex models, but requires the PVM program to be installed and running. This is an advanced topic, and will not be covered here.
Gadget does two separate, but related things. Firstly it takes a model specification and performs a simulation using that set up. The model specification dictates the form of the equations to be used to describe growth, recruitment, fleet selectivity and so on, and the exact parameters to be used in these equations. Gadget will calculate model population and catches through time for your given set up. Note that to do this it does not use real-world data (except possibly overall catch tonnage). The program then compares various aspects of the modelled catches with real-world data from actual catches, and produces numeric likelihood scores measuring how well the model matched each data set. The program also computes a single overall likelihood score. This is a single number representing the 'goodness of fit' between the simulation and the data.
It is worth repeating this point. Gadget runs a complete simulation without reference to any data. It then compares the modelled and real catches, and produces a score evaluating the fit between the two.
If Gadget is called upon to optimise a model solution (see Running Gadget) it simply iterates this process, trying different parameter values for each iteration. The 'best fit' will be produced by the parameter set which produces a model with the lowest overall likelihood score. There are several different optimisation methods utilised (see Optimisation for details).
Gadget is a UNIX program. It has been tested for Solaris and Linux, and should run 'as is' on these systems. It should also run on other versions of UNIX, but may require some modifications to the makefile in order to do so. It may also work on various Unix emulators (such as Cygwin), but this cannot be guaranteed. Gadget is distributed via anonymous ftp on the site ftp.hafro.is. Log in as 'anonymous' and give your email address as a password. CD to the directory for the version you require (whatever the most recent version is), and download the latest version. More detailed help on ftp is presented in an appendix.
Gadget is distributed as a series of source code files, not as executable programs. This minimises the download times, and allows for multiple computer types to be supported in a single distribution. It also means that you will need to compile the program once you have downloaded the source code. Change directory to the source (source code) directory. Within this directory are all the source code (.cc) and header (.h) files needed to compile the program. There is also a file called 'Makefile', this contains information for the compiler about what files are present and how to convert them to a useable program. The Makefile contains different information for different machines, and you will need to edit the Makefile in order to select the machine you are using. First make a backup copy of the Makefile. Then open the Makefile in the editor of your choice. At the top of the file are a number of different options, for Solaris and Linux under a variety of different options. One of these is active, the rest are commented out (with # symbols at the start of each line). Identify which set-up is right for you. This is likely to be either Solaris of Linux with g++ and no pvm. Remove any comment signs on the lines relating to your computer (not including any lines of English text, which really are comments). Ensure that all other options are commented out, and save and quit.
You now have the Makefile ready for your computer, and you should just be able to type 'make' and the program will be compiled for you. This process will take some time, and result in a file called 'gadget' being created. This is the actual program file which you will need to copy to a more useful location (see next section).
If the compilation does not work then either contact us (at gadgethelp@hafro.is) or consult your local computer technical support staff.
Gadget can either be run by copying the program to the same directory as the model data and running it from there, or by specifying the locations of the data and output files and placing the program elsewhere. I recommend the former, at least initially - it is easier to set up, and avoids confusions about exactly which data a particular run may have used.
Copy the executable (program) called 'gadget' into the data directory for the haddock example. Type
gadget -s -i refinputfile -o lik.out
and hit Return. Gadget should run, taking parameter values from the file 'refinputfile' and produce summary output in the file 'lik.out'. Options
There are a number of different options you can specify when running Gadget. You need to tell the computer if it is doing a single run (-s) or an optimising run (-l), where it should get parameter values from (-i), where it should put the output file (-o or -co), and possibly any other options it might need to read (-opt). A number of possible commands to invoke Gadget are given below, with their meanings.
gadget -s -i refinputfile -o lik.out
performs a single run using parameter values stored in 'refinputfile'. This file lists the parameter values in the order they appear in the model specification files. Parameter and likelihood values are output in a file called 'lik.out'.
gadget -s -i refinputfile -co lik.out
performs a single run using parameter values stored in 'refinputfile'. This has values listed by 'name' and value, with a comment describing each variable (the semicolon is Gadget's comment sign). Likelihood score and parameter values are output in 'lik.out'. The '-co' option puts the output into column format similar to the refinputfile.
gadget -l -i refinputfile -o lik.out
performs an optimising (likelihood) run. This starts with the parameters in 'refinputfile', and attempts to find better values using the default Hooke & Jeeves method. The results of the optimisation run are placed into 'lik.out', one line per point examined.
gadget -l -i refinputfile -opt optinfofile -o lik.out
as above, but with optimisation details taken from a file called 'optinfofile'. The 'optinfofile' distributed with the haddock example specifies that a combination of Simulated Annealing and Hooke & Jeeves optimisation be used to find the best parameters. This is the recommended command for an optimising run.
Note that selecting output of the details of the modelled fish population is controlled from the 'printfile', not from the command line. See 'Outputs' for more details. The '-o' switch described above controls output of information about the optimisation, not about the actual fish populations.
Gadget is a program for running models. It is not, in itself, a model. The model to be examined must be specified in a series of files which the program can then read and use to construct and process a simulation of the described ecosystem. This section looks at the overall structure of the files used to describe the model. More details are provided in the documents listed in the introduction, but by far the best way to understand the detail of what the files do is to read them.
Gadget requires two different types of input - model description and data. The format for specifying this information has recently changed. From Gadget 2.0.x and above the format outlined below will be used. The model description and data are separated into different files. The model description files also contain information on the location of the data files so that Gadget can find them.
Eventually the data files will be generated automatically from the database. At the time of writing (December 2002) these scripts are in development and are almost completed. Of course, these scripts can only be of assistance if you have data in the database in the first place [update: these scripts are now complete and can generate the majority of the data files that are needed to run a Gadget model automatically].
Most filenames are decided by the user, however there is one file which should not be renamed - this is the 'main' file. This lists other files which will control different parts of the model.
Note that the file format for Gadget has been changed from version 1 to version 2. The format now separates model description from data, making the overall model files easier to read and generate. Generating the files may be done by hand, or by using scripts which extract data from the datawarehouse in the correct format for use by Gadget. The data input and model output are now in a standardized column format. This makes it easy to generate the data, and to develop scripts to manipulate the output. Main
The only file in a Gadget model that shouldn't be renamed, the main file serves to tell Gadget which other files to read. Not all files are directly referred to here, the main file lists the model description files. These in turn list the relevant data files that Gadget will need to consult.
The standard format of a line is to read something like 'timefile time'. The first word (timefile in this case) is a key word for the program - this is what Gadget looks for. The second is the name of the file. Thus Gadget now knows that to find the timefile data it has to look for a file called 'time'. Some of these are preceded by a keyword in [square brackets]. This is telling Gadget what type of file is about to follow. All the mainfile contains is a number of these lines, specifying which files the model needs to read. Note that some entries (e.g. the [otherfood] in the haddock example) may be left blank if they are not required for a particular model.
timefile time
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 (e.g. In the haddock example the survey mean length data covers 1989 to 1999, although the model itself runs between 1978 and 2006). At this point we are only specifying the model run, and not saying anything about the data files.
areafile area
This file specifies which areas the model will be run on, and gives a time dependent temperature for each area. The haddock example is a single area model, so only one column is needed. Note that although this data must be provided it need not actually be used. In the haddock example the temperature is used in the growth equation. However it is multiplied by zero, thus giving temperature independent growth. But because it is included by default it is easy to switch to temperature dependence if your model requires it.
printing ; printfile
This governs which output files will be created by Gadget (see Outputs below for more details on this). Note that in this example there is a comment sign (the semicolon) between the 'printing' key word, and the 'printfile' file. This prevents the program reading the word 'printfile', and thus suppressing printing of stock output files. To enable printing simply remove the semicolon. The example included with the haddock example prints out 4 different files, all in a subdirectory called 'out' (if you wish to use a subdirectory to organise your files in this manner then it must exist before the program is run). Details of these and other output types can be found in the manual. Note that printing only occurs on a single (-s) run of Gadget, not on an optimising (-l) run.
[stock] stockfiles had
This is the most important file, it governs the growth of the stock (haddock in this case). This file specifies basic components of the stock, the size and age range, where it lives, how it grows and if we are modelling migration, maturation, spawning or recruitment for this stock. For more details of the functions used consult the user manual.
Note that the fixed parameters for the growth equation have changed in recent examples. Growth is modelled as Von Bertalanffy weight growth, and this is converted to length growth with a length weight relationship controlled by parameters p6 and p7. There is also the possibility for a component to model the lack of length growth in undernourished fish. This component is controlled by parameters p3, p4, and p5. These have now been set to switch the component off, thus reducing the growth to Von Bertalanffy.
[tagging]
This is a new feature that is currently at an experimental stage, so its probably best to ignore this for the time being. Tagging experiments can be used to follow the migration of the stock, which is additional information to help Gadget model the migration in a mutli-area model.
[otherfood]
This is left blank in this example - i.e. there is no 'otherfood'. In a multi-species model food (i.e. energy availability) is a limiting factor on fish growth. Some of this is modelled directly with predators and prey being in the model. However it is unlikely that all components of the ecosystem will be explicitly modelled, and thus an estimate of the amount of food available from other, non-modelled, sources may be needed.
[fleet] fleetfiles fleet
This specifies which file will contain the data to set up the fishing fleets which will be incorporated into the model. In this case examining the file 'fleet' indicates that there will be two fleets, called 'survey' and 'comm' (i.e. the commercial fleet), with data about the annual catch in 'fleet.data'. A third 'fleet' called 'future' is specified. This is for runs into the future where fishing must be modelled without relying on data about catches. Note that 'survey' and 'comm' are of type 'totalfleet' (i.e. a real fleet) while 'future' is of type 'linearfleet'. Note also that 'future' will catch nothing before the second quarter of 1999, after the last data in the model. It is easy to add extra fleets here if you wish to divide the fishing effort into discrete fleets.
[likelihood] likelihoodfiles likelihood
This specifies the likelihood functions to be used in comparing the model run to the data. The file is broken into blocks by use of the '[component]' keyword. Each separate component then lists the name by which the component will be know, the weight by which the score from that component will be multiplied by when computing the weighted total likelihood score, the type of likelihood component, and the file storing the data. Some components may require additional information, examine the 'likelihood' file to see what other information may be required. Anything listed as an 'aggfile' is an aggregation file. These contain information about the level of aggregation that will be used when comparing the model results to the data (e.g. to look at ages individually or to list them separately). Each line within an aggregation file starts with a label. This is followed by either a list of discrete classes (e.g. age or area) or a length range which will be grouped together into that label. Note also that each dataset covers different years - this is perfectly acceptable, the haddock example has years where there is little data (1979-1985), years with a lot of data (1989-1999) and years with no data at all (2000-2006). The actual data is stored in a series of files detailed in the likelihood file. Examine these files in more detail to get a flavour for what is possible. As mentioned before it is intended that these files be generated automatically from the datawarehouse. Consult the manual for more information on possible likelihood files, or examine the examples distributed with Gadget.
Back to the contents Output
There are two kinds of output file created by Gadget - details of the model parameters and optimisation process, and details of the simulated populations and catches.
Model parameters and optimisation history are given in the file specified after the '-o' flag. In the haddock example a version of this is supplied and called 'lik.out'. This file contains a list of the parameters supplied to the model in the input file, then their values. Following this are the values of each likelihood component, and finally the overall likelihood score. It is this last number which measures the 'fit' of the model to the data, and which the optimisers work on. If a single run was performed then a single line of output is produced, describing the model parameters used, and the resulting likelihood scores. If an optimisation run was indicated (with the -l switch) then multiple lines are produced - one for each iteration of the optimiser. In this case it is possible to follow through the progress of the optimiser as it tries different parameter combinations and accepts or rejects them. The final line of data is the 'best' solution the optimiser could find (unless it failed to converge in which case it is simply the point at which it ran out of iterations). If all you are interested in is what the final solution is, then you can rapidly scroll to the end of the file using the cat command (cat filename).
The second set of output files detail the simulated population and catches. These are controlled by the printfile, which in turn is specified by the 'main' file. Edit the 'main' file and ensure that there is a line reading 'printfile printfile', with no semicolon between the two words. Exactly what output files are produced and where they are stored is determined by the 'printfile', but the default is to place four different files in a subdirectory called 'out'. Note that this directory must exist before you run Gadget, so if you have copied the files to a new directory you will also need to create an 'out' directory (mkdir out). The most useful of the files is had.std - this produces summary information for each time step within the model. For each year, area, timestep and age it lists (in order) the number of fish in the population, their mean lengths and weights, the standard deviation of their lengths, and the number and biomass caught (consumed) by the fleet. Note that the fleet (combined commercial and survey fleets) are treated as predators, thus the 'number consumed' heading.
Optimisation is a major topic, and this section does not attempt to give details of the procedures involved. Rather it outlines the pros and cons of the various methods so that you can choose which is most appropriate for you. In general the combined Simulated Annealing and Hooke & Jeeves is probably the most useful.
All the optimisation techniques here attempt to minimise the likelihood function. That is, they look for the best set of parameters to run the model with in order to get the best fit according to the likelihood functions you have specified.
To understand what the optimisation is doing, visualise a landscape. There will be high and low points, steep slopes, shallow slopes and so on. An optimiser is attempting to find the highest or, in this case, lowest point on that landscape. The 'height' is analogous to the overall likelihood score, and the optimiser is attempting to find the point with the lowest likelihood score. However instead of just two horizontal dimensions (north-south and east-west) Gadget will produce a surface with one dimension for each parameter to be optimised. This can easily result in several hundred dimensions, in the haddock example there are 37. Hooke & Jeeves
This is a simple and fast method, but somewhat unreliable. It is often described as a 'hill climbing' technique. From the initial starting point the program takes a step in various 'directions', and conducts a new model run. If the new likelihood score is better than the old one then the program uses the new point as it's best guess. If it is worse then Gadget retains the old point. The search proceeds in series of these steps, each step slightly smaller than the previous one. When the program finds a point which it cannot improve on with a small step in any direction then it accepts this point as being the 'solution', and exits. It can be seen that this renders the scheme vulnerable to producing local solutions, accepting a local dip as being the solution even if a better solution exists elsewhere. In order to combat this tendency it is strongly recommended that you re-run the optimisation, using the final point of one run as the start of the next. This will effectively re-set the searching step size to large steps, and give the program a chance of escaping from local solutions. Finding the same result twice in a row does not guarantee it is the best possible solution, but finding different results certainly indicates that the larger result is not the solution you are seeking.
Hooke & Jeeves is the default optimisation method. Simply run the program specifying an optimising (likelihood) run, and Hooke & Jeeves optimisation will be used. Simulated Annealing
This is not the place for a full description of Simulated Annealing or the details of using it. Put simply, where Hooke & Jeeves performs a 'local' stepwise search, Simulated Annealing searches much more widely over the surface in order to find the best point. By doing this it is less likely than Hooke & Jeeves to be fooled by a local optima, and more likely to home in on the true optimum. However the price to paid for doing this is that it takes considerably more computer time to reach a solution. Simulated Annealing and Hooke & Jeeves
This method attempts to combine the wide search of Simulated Annealing and the rapid convergence of Hooke & Jeeves. It relies on the observation that the likelihood function for many Gadget models consists of a large 'valley' in which the best solution lies, surrounded by much more 'rugged' terrain. A small amount of Simulated Annealing at the start of the run serves to move the search into this valley, at which point Hooke & Jeeves takes over an homes in on a solution within that valley. Hopefully the Simulated Annealing will move to the correct side of any 'mountains' and avoid Hooke & Jeeves becoming trapped into unrealistic local optima.
The parameters controlling the optimisation can be altered, however this is not recommended until you are comfortable using Gadget.
A different approach to optimising Gadget is taken by the separate 'paramin' program. This is a multi-processor program that attacks the trade off between run-time and optimising power by using multiple networked computers to run a powerful series of optimising functions. Paramin can run using either Unix or Linux machines, and needs the OPEN-MPI to be installed. It will not be covered further here, since it is well beyond a starting topic. If you are interested in setting up and running paramin, please look it up in the Gadget user guide which comes with Gadget or contact gadgethelp@hafro.is for more information.
OK, so you've experimented with the haddock example, and you want to construct your own model. This is getting beyond the realms of a quick and easy guide, but a few pointers will be provided here to help you get started.
Model building is an exercise in parsimony. The aim is to produce a simulation capable of adequately reproducing the key features of the system being considered, while at the same time avoiding introducing un-necessary and excessive complexity into the model. Obviously there are a number of subjective terms in the preceding sentence: 'adequately', 'key', 'un-necessary' and 'excessive' will all vary considerably depending on the situation. There is not any single 'correct' answer as to what balance should be drawn between these conflicting goals, it will depend upon the system, the requirements of the model and the person designing the model. However it is important to bear this tension in mind while designing your model.
The golden rule of any model-building exercise is to start simple.
I'll repeat that: start simple, get the simple version working before adding complexity. Get a skeletal model up and working before you start adding complicated features to it. And when you do add extra stocks, areas or data files, then add them a few at a time. Things will go wrong, and it's easier to locate problems if you take it in small steps. It also makes it easier to identify the benefits provided as you increase the flexibility of the model.
Remember that in Gadget data and model are separate, and it is possible to run a model with no data whatsoever. More usefully you'll probably want to include a small amount of data in your initial model. Commercial catch tonnage should be included from the start (if available) as it makes a large contribution to the population dynamics. It would also be a good idea to have one data file you can use for the likelihood functions, perhaps the mean length in a survey. This will give your new model an anchor point it can optimise to.
Once you've got the model running with this minimal data set you can add in further data - more information about the survey catch, data from one or more commercial fleets, survey index data, whatever is available. Add these to the model individually or in small groups to ensure that each version works before proceeding to the next.
You should add in all your data before increasing the number of model parameters. Remember that in order to arrive at sensible parameter values the optimiser needs to compare model output to real world data. Therefore if you add flexibility to the model without also providing multiple data files the optimisers will be unable to find sensible solutions.
Gadget uses a large number of variables, all of which have to be assigned values. Some of these can be estimated, but even there an initial estimate has to be supplied. Furthermore Gadget cannot estimate all of the variables simultaneously. Start by fixing most parameters at values which are close to known data. For example the recruitment numbers and length may be reasonably well known, and can begin as fixed numbers. Once your model is running you can estimate some parameters to fine tune them and then leave them fixed for future runs. Use the sensitivity analysis perl script (see 'Sensitivity analysis') provided with the source code to identify which variables may be treated in this manner. Important variables, which have a significant impact on the model should be estimated each time. Those which have only minor impacts if changed may be fixed for future runs.
In order to build a viable model you need to be able to examine the behaviour of that model. A model needs to be biologically plausible, and internally consistent. It also needs to produce a reasonable match to the data, and to do this using a minimum amount of complexity. Obviously these factors are somewhat subjective, how good a match is required, and how much complexity is acceptable is a matter of judgment according to the situation, but there are procedures which can be followed in order to assist in making these judgments.
The first and easiest of these is the likelihood score; both the summary score and the individual components. Once you have a simple model running on all your data sets you can begin to introduce model flexibility in the form of more variables to be estimated, or by allowing some parameters to be estimated separately for each year (see 'Annual modelling'). When you add in this extra flexibility keep a record of the likelihood score and components for each combination. This will give you a quick guide to see how much of an improved fit the extra complexity produced. The point of diminishing returns is often reached; it is simply not worth adding in everything into the model.
This approach will not tell you which variables you should add, or even how many to add. But it will let you base your decision on solid information, and allow you to better resist the temptation to over-parameterise your model. Annual modelling
This is a slightly advanced topic. Rather than estimating a single parameter for all years it is possible to estimate separate parameters for each year, or to group years into blocks and estimate a different value of a parameter for each block. This is particularly useful if you reason to suspect that key parameters may vary significantly between some years (e.g. growth, fleet selectivity). This can be done anywhere a parameter appears in the model files to be estimated. Simply replace the name of the variable with the name of a file which contains a list of the different yearly variables to be estimated. Extra flexibility is always nice, but you do not want the model to become over-parameterised. It is therefore important to add this flexibility only where required, and only in those areas which will provide the greatest benefit. In designing your model it is important to use prior (biological or fisheries) knowledge to identify areas in which this extra variability may be required. Initially construct your model without the extra variation. Then modify the model with the extra flexibility in a single part of the model, and examine how much better the new model fits to the data. Sensitivity analysis
A standard technique for evaluating model results is a sensitivity analysis. This measures how much the results would have changed if the starting parameters had been slightly different. It identifies how stable the solution is in general, and highlights which variables have the greatest effect on the model result.
Initially you select a starting point. This is typically your 'best' optimised solution. You then systematically vary each parameter in turn around this point, holding all the others constant. For each of the resulting parameter values you conduct a single, non-optimising run, and examine the results. Since there are typically a large number of runs it is generally only feasible to examine a small number of key outputs. In the case of the Gadget model the overall likelihood score provides an ideal tool for doing this.
Included with the later releases of Gadget are two perl scripts, sens.pl and plot.pl. These will automatically conduct a sensitivity analysis for you, varying each parameter by a user specified result, plotting the results and producing postscript output files ready to send to a printer. Note that you will need to have 'perl' installed to run the scripts, and 'gnuplot' to produce the plots. Both of these should be included in any Unix or Linux release.
Gadget is a computer model. It is not intelligent in any way, and the optimisers are merely attempting to minimize a single one-dimensional measure of fit between the model output and the data. It is possible that the results thus produced may not be at all sensible. In particular the likelihood functions are designed to examine small differences between two sets of numbers, and may behave strangely where the model and the data are vastly different. It is thus important that you examine the output from the options set in the 'printfile' to ensure that the stock produced is 'reasonable'.
A second caveat concerns this guide. As already stated it is not a complete manual. A manual does exist, and should be consulted for detailed descriptions of the model. In particular the details of the options where a 'function' is required are listed.
This introduction has only shown the basics of single-species, single-area models. The point of Gadget is to conduct multi-species, multi-area models. Several single-species models can be developed independently and then combined with additional data on the interactions (e.g. stomach content data). Details on the relevant likelihood components can be found in the manual, but I would advise creating viable single-species models before proceeding to link them.
Better optimisation procedures can be obtained by using the paramin program. This improvement is particularly important in complex multi-species models, where optimisation becomes more difficult. The ability to use multiple computers will also allow larger and more complex models to be run in reasonable timescales.
You may find that you wish to do something that Gadget does not allow for. A good principle is to try and fit this into the Gadget framework if possible. If it is really not possible then you may need to alter the code to allow for your requirements. If you come up with something useful then let us know so that we can incorporate it into the distributed model.
A last point. The gadgethelp@hafro.is email has been included because we really do want to hear from you. If you have problems with Gadget then we will try and help, and we do want hear about your experiences and problems so that we can improve the program.
The Gadget program and haddock example are stored as zipped tar files on an anonymous ftp site at ftp.hafro.is. This means that anyone can download and use the software. If you already know how to use ftp and tar then the files can be found in the directory /pub/reiknid/dst2/gadget. If you don't then this appendix should provide a quick guide to getting the files onto your computer.
You will need a machine running some version of UNIX, and to have a terminal open. Connecting
To connect to the ftp site simply type 'ftp ftp.hafro.is'. You will then be prompted to log on to the site. At the 'Name:' prompt type 'anonymous', and give your complete email address as the password (e.g. gadgethelp@hafro.is). Once you have connected, type 'binary' to ensure that the ftp client treats the files as binary files, and not ASCII text files, which can cause problems for some clients. Downloading
To get to the Gadget files type 'cd /pub/reiknid/dst2/gadget'. Then type 'dir' to get a listing of all the files in the directory. Select the highest version number (2.0.03 at the time of writing this document, but use the most up to date version available) and type 'get gadget2.0.03.tar.gz', replacing the number with the version you wish to download. Depending on the speed of your connection it could take a while to complete the download. Be patient. Disconnecting
When you have finished downloading the file simply type 'bye' and the ftp program will disconnect you and exit. Unzipping and untarring
You should now have the file on your computer, but they are stored in a zipped tar archive. This not only makes them smaller, allowing for quicker downloads, but also allows whole directories worth of files to be downloaded in one go. You can use this one file to create all the directories and files you require. First unzip the file by typing 'gunzip gadget2.0.03.tar.gz'; this leaves you with the TARed archive file, containing all the components of Gadget. To extract the files from the archive type 'tar -xf gadget2.0.03.tar', again replacing the numbers if necessary. This will uncompress the files and place them in their correct directories. At the end you should be left with a directory called 'gadget2.0.03', with all the files in various sub directories. Congratulations; you are now ready to compile and run Gadget.
If you have any difficulties consult your local computer help support (all of this procedure is standard practice, and not specific to Gadget, so they should be able to help). If this doesn't work then email gadgethelp@hafro.is.
Finally, remember that Gadget is an evolving tool. New versions will be posted on the ftp site. It would be worth your while to keep up to date and ensure that you download the most recent version. This not only allows you to use the best version available, but also ensured that help and support will be available, which may not be the case for obsolete versions.