02. Getting Started

Getting Started

Gmacs is available for download as a series of source files. In order to use Gmacs you will need to build these source files into an executable. To build Gmacs you'll need a recent version of AD Model Builder (ADMB). We recommend downloading the latest version of ADMB from the ADMB GitHub repository and building ADMB from source. Alternatively, recent pre-compiled builds of ADMB can be downloaded from the ADMB website. Instructions for installing ADMB from pre-compiled builds can be found on the ADMB website as well.

Gmacs has been tested on the following versions of ADMB:

• 11.2
• 11.4
• 11.6

We provide detailed instructions on how to go about installing Gmacs on the most popular operating systems below.

Table of Contents

• Installing Gmacs
  • Quick Start (for Windows)
  • Quick Start (for Mac)
  • Installation on Linux
  • Developers
• Running a Model
• Simulation Mode
• Makefiles

Installing Gmacs

How you go about installing Gmacs depends on the flavour of operating system you are running on your computer. We provide step-by-step instructions for installing Gmacs on Windows, Mac and Linux computers.

Quick Start (for Windows)

1. Download gmacs-develop.zip.
2. Unzip the folder to create c:/gmacs-develop or something similar.
3. Open an ADMB Command Window.
4. Navigate to c:/gmacs-develop/src and type make.bat.
5. The Gmacs executable gmacs.exe should be built inside the src/ folder.
6. See Building a Model.

Quick Start (for Mac)

1. Download gmacs-develop.zip.
2. Unzip the folder to create /users/name/gmacs-develop or something similar.
3. Open Terminal.
4. Navigate to users/name/seacode/gmacs/src.
5. Edit the make file to reference your local machine.
6. Return to Terminal and type make to get started.
7. The Gmacs executable should be built inside the gmacs/src/build/ folder.
8. See Building a Model.

Installation on Linux

Installing ADMB on Linux is easy via GitHub. From within the directory you wish to download ADMB to, simply type the command:

git clone https://github.com/admb-project/admb

Once the ADMB source files have been downloaded from GitHub then simply navigate to the ADMB directory and build ADMB using:

cd admb
make

Gmacs can be downloaded and installed in much the same way. First clone the Gmacs GitHub repository to your local machine using git clone, then navigate to to gmacs source directory and execute the shell script make.sh to build gmacs:

git clone https://github.com/seacode/gmacs
cd gmacs/src
./make.sh

Once ADMB and gmacs have been installed we recommend adding both to your PATH so that they may be called from the terminal within any directory, this can be done using:

$PATH=...
ADMB_HOME=
sudo ln -s ~/seacode/gmacs/src/build/release/gmacs /usr/bin/gmacs

Developers

Developers and those with experience using ADMB might wish to clone the repository using Git. See the Developers page on this wiki for more information.

Running a Model

Gmacs runs as a command line (or terminal-based) program with text-based input and output: gmacs.exe can be executed from the command line, called from another program such as R, or called via a makefile. A model can be run from the command line using:

gmacs

Command line options for Gmacs include:

-i         # Information, contributors and acknowledgements
-sim seed  # Simulate data based on pin file for self-testing
-retro n   # Retrospective analysis with n terminal years
-?         # List all other ADMB command line options
-mcmc n    # Run n MCMC iterations
-mcsave n  # Save n MCMC iterations

So, for example, typing gmacs -i from the command line will print some information, contributors and acknowledgements to screen. However, before you can use Gmacs, you will need to create the model input files gmacs.dat and gmacs.ctl. We provide instructions on how to do this here. Alternatively, you might wish to try out one of our example models here first.

Simulation Mode

A simulation-estimation procedure can be performed with Gmacs, by using the gmacs -sim flag. For example, try gmacs -sim 123, where 123 is a random number seed. NOT YET IMPLEMENTED.

Makefiles

Explain use of the model and associated tools via batch files or a makefile: clean, run, get files etc.

Compiling a document

Before any of the example assessment documents can be compiled the user must install pandoc, pandoc-citeproc, pdflatex, texlive-latex-recommended, texlive-latex-extra,and texlive-fonts-recommended.