This is a repository with GMACS tpl and C++ source code only. The base code was distributed by Andre Punt on Jan. 18, 2024 following the January 2024 Crab Modeling Workshop in Anchorage, AK. This repository is a bit "cleaner" than the GMACS_Assessment_code repository because it contains only the base tpl code, a template for the personal.tpl code, the src and include sub-folders with c++ code, and a platform-independent CMake file to make the gmacs executable.
The intention of this repository is to restrict it to only the tpl and c++ code in the top-level folder, the src and include sub-folders, and a testing sub-folder. Developers should create branches off the main branch to develop and test code, then merge their changes back into the main branch after testing is successful. Please DO NOT create parallel folder structures on the main branch (as has been done in the GMACS_Assessment_code repository).
GMACS uses the AD Model Builder C++ libraries, so these must be installed prior to installing and using GMACS. GMACS also provides a script for platform-independent installation using CMake.
For Windows users, it is recommended to install RTools to provide compilers to build the ADMB libraries, a cmake executable, and unix-like shell functions for various file manipulation tasks. After installing RTools, the user should add the folder containing g++.exe to the front of their Windows PATH so that the RTools compiler/linker is found before any other version (this could be done on a per-terminal session basis). For RTools version 4.3, this would be RTools\x86_64-mingw32.static.posix\bin, where RTools is the top-level folder to which RTools was installed. In addition, add an environment variable RToolsUsr with the path to the Rtools\bin folder so that the unix-like shell commands are avaialable in the Windows Command Prompt window.
For Mac OSX users, a cmake executable script and gui can be installed from https://cmake.org/download/.
Once ADMB has been compiled, create the environment variable ADMB_HOME and set it equal to the path to the admb sub-folder of the build directory (i.e., the folder that contains bin, include, and lib). Also, copy (or rename) the libadm-contrib.xxxx.a file in the lib sub-folder to libadmb-contrib.a.
If you have not already done so, clone a copy of this repository to a folder on your local machine.
To compile the GMACS executable, open a command prompt (Windows) or terminal window (Mac OSX) and change directory to the top-level GMACS directory (i.e., the one that contains the gmacsbase.tpl, personal.tpl, and CMakeLists.txt files). Then run the following commands:
- cmake -S . -B _build -G "Unix Makefiles"
- cmake --build _build
The first command creates the _build subfolder and the Makefile appropriate for the given platform ("Unix Makefiles" appears to be an appropriate value for the -G option when compiling with RTools under either OSX or Windows). The second command builds the project by running the Makefile and (if successful) copies the gmacsbase and personal tpl files to _build, concatenates them as gmacs.tpl, calls tpl2cpp on gmacs.tpl to create the associated .cpp and .htp files, and finally compiles the source and header files to create the gmacs executble in the _build folder (gmacs on Mac OSX and gmacs.exe on Windows).
Changes to the tpl or c++ files can be recompiled using "cmake --build _build", which will only update the compilation process for files changed since the last build (i.e., not recompiling everything). To "start from scratch", you can either delete the _build folder and run the two commands above again or run "cmake --build _build --target clean" (which deletes the gmacs executable, gmacs.tpl, gmacs.cpp, gmacs.htp and all the object files under the _build folder, but not the CMake-associated files) followed by "cmake --build _build".
The testing/input_files folder contains subfolders with suitable input files to test the compiled GMACS executable. The testing/scripts folder contains R scripts which can be used to test the models in the testing/input_files subfolders. To run the tests:
- start an R session
- Create a
testing/runsfolder (if it doesn't exist already) - change the working directory to the
testing/runsfolder - source the "testing/scripts/runTests.r" file
- run the function "runTests" for the models of interest
- set the
testsinput vector to the names of the subfolders containing the models you want to test - set the top-level directory for running the tests (the default is ".", i.e. the
testing/runsfolder) - set the
compareWithPin,verbose, andcleanupflags as desired (verbosefunctionality is not yet implemented).
- set the
The function will run the models specified (copying the input files from relevant testing/inut_files subfolders). The output is a list with an element for each model tested. Each element indicates whether the test passed or, if not, where "substantial" differences (abs(new-old)>$10^{-5}$) occurred between the new par file and an old par file ("gmacs.par_old") or the pin file ("gmacs.pin") used to initialize the model.
Currently GMACS is linked to gmr, an R package to work with GMACS in R, create plots of GMACS output, compare different models and prepare SAFE documents.
This repository is a scientific product and is not official communication of the National Oceanic and Atmospheric Administration, or the United States Department of Commerce. All NOAA GitHub project code is provided on an 'as is' basis and the user assumes responsibility for its use. Any claims against the Department of Commerce or Department of Commerce bureaus stemming from the use of this GitHub project will be governed by all applicable Federal law. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by the Department of Commerce. The Department of Commerce seal and logo, or the seal and logo of a DOC bureau, shall not be used in any manner to imply endorsement of any commercial product or activity by DOC or the United States Government.
Software code created by U.S. Government employees is not subject to copyright in the United States (17 U.S.C. §105). The United States/Department of Commerce reserve all rights to seek and obtain copyright protection in countries other than the United States for Software authored in its entirety by the Department of Commerce. To this end, the Department of Commerce hereby grants to Recipient a royalty-free, nonexclusive license to use, copy, and create derivative works of the Software outside of the United States.
U.S. Department of Commerce | National Oceanographic and Atmospheric Administration | NOAA Fisheries