| 1 : |
agomez |
1 |
#ifndef gadget_h
|
| 2 : |
|
|
#define gadget_h
|
| 3 : |
|
|
|
| 4 : |
|
|
/**
|
| 5 : |
|
|
\mainpage Draft Gadget Documentation
|
| 6 : |
|
|
|
| 7 : |
|
|
Gadget is the <b>G</b>lobally applicable <b>A</b>rea <b>D</b>isaggregated <b>G</b>eneral <b>E</b>cosystem <b>T</b>oolbox. 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. Gadget has been used to investigate the population dynamics of many stocks and stock complexes in Icelandic waters, the Barents Sea, the North Sea and the Irish and Celtic Seas.
|
| 8 : |
|
|
|
| 9 : |
|
|
Gadget can run complicated statistical ecosystem models, which take many features of the ecosystem into account. Gadget works by running an internal model based on many parameters, and then comparing the data from the output of this model to ''real'' data to get a goodness-of-fit likelihood score. The parameters can then be adjusted, and the model re-run, until an optimum is found, which corresponds to the model with the lowest likelihood score.
|
| 10 : |
|
|
|
| 11 : |
|
|
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.
|
| 12 : |
|
|
|
| 13 : |
|
|
For more information about Gadget, including links to download the software, please see the webpage that has been set up at http://www.hafro.is/gadget or email us at gadgethelp@hafro.is
|
| 14 : |
|
|
|
| 15 : |
|
|
This document is the developers manual for Gadget, and describes the classes, functions and variables from a programmers point of view. Also included in this document is the \link standards Gadget Coding Standards \endlink which gives brief details of the layout of the C++ source files that developers should follow.
|
| 16 : |
|
|
*/
|
| 17 : |
|
|
|
| 18 : |
|
|
/* A list of the standard header files that are needed for Gadget */
|
| 19 : |
|
|
/* Older compilers need these to be declared in the old format */
|
| 20 : |
|
|
#include <cassert>
|
| 21 : |
|
|
#include <cctype>
|
| 22 : |
|
|
#include <cstdio>
|
| 23 : |
|
|
#include <cstdlib>
|
| 24 : |
|
|
#include <cstring>
|
| 25 : |
|
|
#include <iostream>
|
| 26 : |
|
|
#include <fstream>
|
| 27 : |
|
|
#include <sstream>
|
| 28 : |
|
|
#include <iomanip>
|
| 29 : |
|
|
#include <cmath>
|
| 30 : |
|
|
#include <ctime>
|
| 31 : |
|
|
#include <vector>
|
| 32 : |
|
|
#include <signal.h>
|
| 33 : |
|
|
#include <unistd.h>
|
| 34 : |
|
|
#include <sys/utsname.h>
|
| 35 : |
|
|
#include <sys/param.h>
|
| 36 : |
|
|
|
| 37 : |
|
|
/* This is a nasty hack to use the functions in the std namespace */
|
| 38 : |
|
|
/* it would be much better to explicitly state the std namespace */
|
| 39 : |
|
|
/* when using the functions - eg std::strcmp() not just strcmp() */
|
| 40 : |
|
|
/* Older compilers will reject this so it needs to be removed */
|
| 41 : |
|
|
using namespace std;
|
| 42 : |
|
|
|
| 43 : |
|
|
/* Some compilers define the values for EXIT_SUCCESS and EXIT_FAILURE */
|
| 44 : |
|
|
/* but to be sure that they are defined, they are also included here. */
|
| 45 : |
|
|
#ifndef EXIT_SUCCESS
|
| 46 : |
|
|
#define EXIT_SUCCESS 0
|
| 47 : |
|
|
#endif
|
| 48 : |
|
|
#ifndef EXIT_FAILURE
|
| 49 : |
|
|
#define EXIT_FAILURE 1
|
| 50 : |
|
|
#endif
|
| 51 : |
|
|
|
| 52 : |
|
|
/* Also defined are some of the constants used by Gadget */
|
| 53 : |
|
|
const int MaxStrLength = 129; /* 128 + 1 */
|
| 54 : |
|
|
const int LongString = 4097; /* 4Kb + 1 */
|
| 55 : |
|
|
const double verybig = 1e+10;
|
| 56 : |
|
|
const double rathersmall = 1e-10;
|
| 57 : |
|
|
/* machine accuracy for doubles is apparently 2.2204460492503131e-16 */
|
| 58 : |
|
|
//const double verysmall = 4.4408921e-16; /* twice machine accuracy */
|
| 59 : |
|
|
const double verysmall = 1e-20;
|
| 60 : |
|
|
const char chrComment = ';';
|
| 61 : |
|
|
const char sep = ' ';
|
| 62 : |
|
|
|
| 63 : |
|
|
#ifndef TAB
|
| 64 : |
|
|
#define TAB '\t'
|
| 65 : |
|
|
#endif
|
| 66 : |
|
|
|
| 67 : |
|
|
/* Also defined are some of the printer constants used by Gadget */
|
| 68 : |
|
|
const int lowprecision = 1;
|
| 69 : |
|
|
const int smallprecision = 4;
|
| 70 : |
|
|
const int printprecision = 6;
|
| 71 : |
|
|
const int largeprecision = 8;
|
| 72 : |
|
|
const int fullprecision = 15;
|
| 73 : |
|
|
const int lowwidth = 4;
|
| 74 : |
|
|
const int smallwidth = 8;
|
| 75 : |
|
|
const int printwidth = 10;
|
| 76 : |
|
|
const int largewidth = 12;
|
| 77 : |
|
|
const int fullwidth = 18;
|
| 78 : |
|
|
|
| 79 : |
|
|
/* Update the following line each time upgrades are implemented */
|
| 80 : |
|
|
#define GADGETVERSION "2.2.00-BETA"
|
| 81 : |
|
|
|
| 82 : |
|
|
#endif
|
| 83 : |
|
|
|
| 84 : |
|
|
/**
|
| 85 : |
|
|
\page standards Gadget Coding Standards
|
| 86 : |
|
|
|
| 87 : |
|
|
This section contains brief details of the Gadget coding standards, based on the proposals made at the 2000 DST2 meeting in Nantes, and documented in annex L7 of the DST2 progress report for that year.
|
| 88 : |
|
|
|
| 89 : |
|
|
\section name Naming Conventions
|
| 90 : |
|
|
|
| 91 : |
|
|
Class names should always begin with a capital letter, and class names consisting of multiple words should be written with each word capitalised.
|
| 92 : |
|
|
|
| 93 : |
|
|
Class members, variables and functions should always start with a lower case letter. Additional words in the name should be separated by capitalising each word. The use of underscores to separate words is discouraged.
|
| 94 : |
|
|
|
| 95 : |
|
|
Examples:
|
| 96 : |
|
|
\verbatim
|
| 97 : |
|
|
#class# TimeClass {
|
| 98 : |
|
|
// ...
|
| 99 : |
|
|
}
|
| 100 : |
|
|
|
| 101 : |
|
|
TimeClass* currentTime;
|
| 102 : |
|
|
|
| 103 : |
|
|
#void# incrementTime(TimeClass currentTime) {
|
| 104 : |
|
|
// ...
|
| 105 : |
|
|
}
|
| 106 : |
|
|
\endverbatim
|
| 107 : |
|
|
|
| 108 : |
|
|
\section space Spacing, Indentation and Brackets
|
| 109 : |
|
|
|
| 110 : |
|
|
Only spaces should be used for indentation, two spaces for each level of indentation. A block opening curly bracket should be at the end of the line that defines the block. The matching end bracket is placed on a line of its own, at the same level of indentation as the line that starts the block. If an \c if block is followed by an \c else clause, the next block should be started on the same line as the closing curly bracket of the previous block.
|
| 111 : |
|
|
|
| 112 : |
|
|
An opening round bracket following a keyword (\c if, \c while, \c for, etc.) should be separated from the keyword with a space. There should also be a space separating the closing round bracket and the opening curly bracket, if the curly brackets are required. In function calls, the opening bracket for the function arguments should not be separated from the function name.
|
| 113 : |
|
|
|
| 114 : |
|
|
All mathematical and logical operators (=, \<, +, etc.) should be separated from the variables they are operating on by a space before and after the operator. Similarly when variables are separated by a comma or a semi-colon, there should be a space after the separator.
|
| 115 : |
|
|
|
| 116 : |
|
|
Examples:
|
| 117 : |
|
|
\verbatim
|
| 118 : |
|
|
#for# (i = 0; i < n; i++) {
|
| 119 : |
|
|
// ...
|
| 120 : |
|
|
}
|
| 121 : |
|
|
|
| 122 : |
|
|
#if# (isDone()) {
|
| 123 : |
|
|
// ...
|
| 124 : |
|
|
} #else# #if# (something()) {
|
| 125 : |
|
|
// ...
|
| 126 : |
|
|
} #else# {
|
| 127 : |
|
|
// ...
|
| 128 : |
|
|
}
|
| 129 : |
|
|
|
| 130 : |
|
|
doSomething(a, b, c);
|
| 131 : |
|
|
\endverbatim
|
| 132 : |
|
|
|
| 133 : |
|
|
\section forloop Local Variables in For Loops
|
| 134 : |
|
|
|
| 135 : |
|
|
Due to the limitations of some compilers, variables defined and initialised in the opening of a \c for loop will not always have a local scope for that loop. These variables should, therefore, be defined outside the scope of the loop.
|
| 136 : |
|
|
|
| 137 : |
|
|
Example:
|
| 138 : |
|
|
\verbatim
|
| 139 : |
|
|
#int# i;
|
| 140 : |
|
|
#for# (i = 0; i < n; i++) {
|
| 141 : |
|
|
// ...
|
| 142 : |
|
|
}
|
| 143 : |
|
|
\endverbatim
|
| 144 : |
|
|
|
| 145 : |
|
|
\section doc Method Documentation
|
| 146 : |
|
|
|
| 147 : |
|
|
This documentation has been generated from the source files by Doxygen (see http://www.doxygen.org for more information). To ensure that Doxygen can document all the classes, functions and variables in Gadget, these have been described with ''doxygen style'' comments that have been placed in the header files for each class. As a minimum, these comments include the \c \\brief command to give a brief description of the object, the \c \\param command to give a description of the parameters (if any) and the \c \\return command to give a description of the return value (if any). More complicated objects will require more detailed descriptions.
|
| 148 : |
|
|
|
| 149 : |
|
|
Any non-trivial method should also have a short description in the code, in addition to any documentation in the header file.
|
| 150 : |
|
|
|
| 151 : |
|
|
Example:
|
| 152 : |
|
|
\verbatim
|
| 153 : |
|
|
#**
|
| 154 : |
|
|
* \brief This will return the total number of timesteps that have taken place in the
|
| 155 : |
|
|
simulation from the start of the model simulation until a specified year and step
|
| 156 : |
|
|
* \param year is the specified year
|
| 157 : |
|
|
* \param step is the specified step
|
| 158 : |
|
|
* \return number of timesteps taken
|
| 159 : |
|
|
*#
|
| 160 : |
|
|
#int# TimeClass::calcSteps(#int# year, #int# step);
|
| 161 : |
|
|
\endverbatim
|
| 162 : |
|
|
|
| 163 : |
|
|
\section cvs Version Control
|
| 164 : |
|
|
|
| 165 : |
|
|
To maintain version control of the source files, a CVS repository has been set up on the Marine Research Institute server in Reykjavik. Any user with secure shell access to the MRI server can access this repository, and a web interface to this repository is also available to allow users to browse the source code online (see http://www.hafro.is/viewcvs/viewcvs.cgi/gadget/). Any ''official'' version of the Gadget software will be tagged and released from the source code that is in the CVS repository. The CVS repository should also contain any user documents and files external to the main source code that are distributed with the source code (for example, shell scripts to help analyse the output from a Gadget simulation).
|
| 166 : |
|
|
|
| 167 : |
|
|
\section compat Code Compatibility
|
| 168 : |
|
|
|
| 169 : |
|
|
Gadget is a program that has been developed on a Unix computing platform, and is regularly compiled and run on machines running versions of Linux, Solaris and Cygwin (a Unix emulator for Microsoft Windows machines, see http://www.cygwin.com for more information). By regularly compiling and running Gadget on a variety of computing platforms, it is hoped that the source code is compatible with as many computing platforms as possible. The list of computing platforms, and C++ compilers, that Gadget is regularly tested on is:
|
| 170 : |
|
|
|
| 171 : |
|
|
\li Linux (Fedora 9), compiled using \c g++ version 4.3.0
|
| 172 : |
|
|
\li Linux (Ubuntu 8.04), compiled using \c g++ version 4.2.3
|
| 173 : |
|
|
\li Linux (Fedora 8), compiled using \c g++ version 4.1.2
|
| 174 : |
|
|
\li Cygwin (1.5.25-14), compiled using \c g++ version 3.4.4-3
|
| 175 : |
|
|
|
| 176 : |
|
|
*/
|
Parent Directory
Revision Log