ADMB Frequently Asked Questions (FAQs)
If you have ideas for additions or modifications, please send them to
Ian.Taylor@noaa.gov. ADMB is a free and open source software suite for non-linear statistical
modeling. It was created by David Fournier and now being developed by the
ADMB Project, a creation of the non-profit ADMB Foundation. An extension of
the language, ADMB-RE is available for modeling random effects. "AD Model Builder", where the "AD" refers to the automatic
differentiation capabilities that come from the AUTODIF Library, a C++
language extension also created by David Fournier, which implements reverse
mode automatic differentiation. Automatic differentiation (AD) is a method to evaluate the derivative of
a function. Unlike, symbolic differentiation, AD can work on extremely
complex problems. And AD methods are more precise than the approximations
that come from numerical differentiation. These calculations are done behind
the scenes, so the user needs only to provide the code to calculate an
objective function to be minimized. One minor challenge of using AD methods
is that care needs to be taken that the objective function to be minimized
is differentiable with respect to the parameters. To meet this challenge,
ADMB provides some the smoothed alternatives to functions like absolute
value that can be used to keep things differentiable. For more details,
see Automatic
Differentiation on Wikipedia. The main advantages are speed, accuracy, stability, and the ability
to build large models. ADMB has been estimated to perform faster at solving
complex optimization problems than the numerical programming languages
GAUSS, MATLAB, S-PLUS, and R. In one example, ADMB solved a minimization
problem with 100 parameters in 3 seconds, while the "nlminb" function in R
took 93 minutes to achieve the same solution for code of both models). The major problem in nonlinear statistical modeling is fitting the model to
data. This involves nonlinear optimization. For the kinds of problems
generally encountered in statistical modeling the best nonlinear
optimization routines employ the derivatives of the function being
maximized. Spreadsheet solvers and other statistical modeling packages use
finite difference approximations for the derivatives of the function to be
maximized in their solvers. This approach has two major limitations. The
inaccuracy of the derivative approximations leads to instability in the
solver. The result is that the solver becomes unreliable for ill-conditioned
problems (naturally most real problems of interest are ill-conditioned).
Also with finite difference approximations it takes at least n function
evaluations to obtain the finite difference approximation for a function
with n independent variables. As a result it is generally impossible
to fit models with more than 20 or so parameters reliably with this
approach. The automatic differentiation used by ADMB makes it possible to
fit models with hundreds or even thousands of parameters in an efficient and
reliable manner. In addition AD Model Builder produces a compiled executable
which generally executes faster than the interpreters used by spreadsheets
and other statistical packages. Well of course a model should only have as many parameters as it needs
- no more but no less. One use of many parameters in statistical
models is in the Bayesian equivalent of structural time-series models. In
this approach parameters which would be assumed to be constant in the
classical frequentist approach are allowed to vary slowly over time if there
is evidence in the data being analyzed which supports such change. The
advantage of the Bayesian approach over the structural time series approach
is that the methods are exact even in the nonlinear case and it is simple to
replace the usual assumption of normality with robust distributions. From the downloads page
on this website. ADMB is available for Windows, Mac OS X, Linux, and OpenSolaris. 64-bit
versions for Windows are not yet complete, but all other systems have both
32-bit and 64-bit versions available. Nothing. The syntax of ADMB is based on C++, so any knowledge of C++ or similar
languages will be useful. However it is not necessary to know any of the
advanced object-oriented aspects of C++ programming such as classes,
derived classes, function overloading etc. to use ADMB. A key requirement
of ADMB compared to C++ is that parameters have to be declared in a special way
that notifies the program that these are the quantities with respect to
which the derivative of the objective function will be calculated. The ADMB downloads include a collection of example files and more
examples are available on
the examples page of this
website. The documentation has numerous snippets of code that can be adapted
to your needs. If you use BUGS, there is an article about converting WinBUGS to ADMB in
the June 2010 edition of
the ADMB Foundation Newletter. ADMB employs an open architecture. It is possible to insert any
legal C++ code into many parts of the template to customize the performance
of your model. Also if desired you can always work directly with the C++
source code which ADMB produces from your TPL file. Yes, courses have been offered by various people with experience in ADMB.
A list of previously offered courses and contact information for potential
instructors is
at courses.
The University of Washington has also offered a course "Numerical Computing
for the Natural Resources" taught by Andre Punt, which is focused on ADMB.
Other Universities may offer courses as well (let us know so they can be
added to this FAQ). Not yet. This website includes updates with news related to ADMB. All users should
also consider joining
the users@admb-project.org email
list
(link to info). A growing group of people in a variety of fields. The largest group of
users are working in fisheries science, both because David Fournier, the
creator of ADMB has worked in this field, and because fisheries models often
have hundreds of parameters and would be intractable without ADMB. A list of worldwide institutions using ADMB is available here. A list of
publications that depend on ADMB is
posted here. David Fournier created ADMB, ADMB-RE, and the AUTODIF Library in the
1980s. More information on the history of ADMB is
available here. The ADMB core-team is currently about 20 people. They are listed in two places: Yes. Please consider attending one of the ADMB developers workshops and joining the users@admb-project.org. You can also e-mail the developers core team: developers@admb-project.org. The ADMB Project is currently supported by the ADMB Foundation, and a grant from NOAA Fisheries to the Joint Institute of Marine and Atmospheric Research. In the past it has received support from the National Center for Ecological
Analysis and Synthesis, and the Pelagic Fisheries Research Program. Fournier, D.A., H.J. Skaug, J. Ancheta, J. Ianelli, A. Magnusson,
M.N. Maunder, A. Nielsen, and J. Sibert. 2012. AD Model Builder:
using automatic differentiation for statistical inference of highly
parameterized complex nonlinear models. Optim. Methods Softw. 27:233-249. The paper is freely available through open access at
http://www.tandfonline.com/doi/abs/10.1080/10556788.2011.597854. There is a GUI that runs in R, through the PBSadmb package. An integrated development environment (AD Studio) is available on
the downloads page. It is
based on Emacs but configured to be easy to learn. Many other editors have
been used by ADMB programs.
See editing tools
page for comments on configuring various editors for ADMB
programming. The most common interaction between ADMB and other languages is through
the text files input to and output from ADMB programs. Many users of ADMB
use R to summarize or plot results of their ADMB models (a list of R
packages associated with ADMB output is
available here).
There is a package glmmADMB for R that utilizes ADMB and some users have
compiled ADMB models as DLLs to help it interact with other software. Please see the installation instructions. Obviously this depends on the type of computer you have. For Windows
users, there are multiple compiler options. Among the three, the
installer for GCC compiler is the only one for which the compiler is
included with the ADMB installer (because it is open source and can be
distributed in this way). For this reason, the Windows GCC installer
is the recommended choice. Some
benchmarks have been completed to compare compilers, and more will
likely be added in the future. Not yet. Folks are attempting to put a Debian package together (see discussions
here and
here). And hopefully this will be available in the near future. As of March 2012, the use of Borland compilers is no longer supported by the ADMB Project. Although Borland was a common compiler for ADMB in the past, the number of ADMB users working with Borland had declined and the effort that had been spent on maintaining compatibility was directed elsewhere. TPL files that worked under Borland should in general work with other compilers. Also see notes below under "How do I compile old Borland TPL’s in MinGW?" for more information. In some cases the environment variables that point
to the ADMB files may not have been set correctly, e.g. when installing as a
non-administrator. In Windows this is indicated by an error message like Discussion of this point, with instructions for setting
Environment Variables, are in the email archives,
here,
here, and here. The key is to make sure that the PATH environment variable includes the
directory where the ADMB files are located. In DOS, if you type "echo %PATH%",
you should see the folder with ADMB files. If you don't, follow the links above
for suggestions on how to set those variables. Installation of ADMB is getting easier and easier, but problems may still
crop up. If you don't have an ADMB user nearby to consult, write
to users@admb-project.org,
providing details of your computer, what version of ADMB you downloaded, and
a description of the problem. Yes. You can download all source files for the latest release of ADMB from
downloads.
Or you can check out the latest development version of the source code using
the information
here. To learn about keeping synchronized with the development code, you may
want to read about Subversion (SVN). Yes. There are instructions in the README file included with the source code.
It has been
suggested (at least for those familiar with the compiling process) that
"if you experience a strange crash recompile and get a coffee before you waste time
thinking about it." Obviously the determination of what constitutes "strange"
may be somewhat subjective. The precompiled "Windows and GCC" version of ADMB comes with the C++ compiler
included. This has the potential to conflict with the compilers included with
other programs, such as Rtools.
Some ideas for avoiding such conflicts are discussed in an email
here. Most files contain results of the model in either ASCII or binary format.
Some are temporary files created in the process of running the model and can
be ignored. The most commonly used output files are A good source of more information on all the files
is Chapter
6 of the draft ADMB Getting Started Guide. ADMB has inputs to allocate memory for different types of calculations. These are controlled
either via lines in the TPL file such as
ADMB developers with editing privileges are welcome
to make changes, but should read the
Note on Editing the FAQ before doing so.</p>
General Information
Installation
Usage
AD Studio
General Information
What is ADMB?
What does ADMB stand for?
What is automatic differentiation?
What is the advantage of using ADMB?
Why is AD Model builder better than using spreadsheet solvers or other statistical packages?
But aren't models with hundreds or even thousands of parameters overparameterized?
Where do I get it?
What operating systems are supported?
What does it cost?
How can I learn how to use ADMB?
Isn't this sort of package too restrictive?
Are there courses I can take?
Are there any books on ADMB?
How can I learn more about ADMB?
Who uses ADMB?
Who created ADMB?
Who is currently developing ADMB?
core-team
model7.cpp
This list is displayed when a user runs 'mymodel -info'.Can I help improve ADMB?
How is ADMB supported financially?
How can I cite ADMB?
Is there a GUI for ADMB?
What editors work with ADMB?
How does ADMB interact with other software?
Installation
How do I install ADMB?
Which version is best for my computer?
Is there a .rpm or .deb package for easy Linux installation?
Does ADMB work with Borland compilers?
How do I set the PATH and other environment variables?
'admb' is not recognized as an internal or external command,
operable program or batch file.
Why did my installation of ADMB fail?
Is the ADMB source code available?
Can I build ADMB directly from the source code?
How can I avoid conflicts between C++ compilers?
Usage
What are all the files produced by running an ADMB executable?
How do I control memory use in ADMB?
arrmblsize = 200000; // use instead of gradient_structure::set_ARRAY_MEMBLOCK_SIZE
gradient_structure::set_GRADSTACK_BUFFER_SIZE(100000000);
gradient_structure::set_CMPDIF_BUFFER_SIZE(50000000);
Or via command line inputs such as
mymodel.exe -ams 200000 -gbs 100000000 -cbs 50000000
The numbers are in bytes except for the GRADSTACK_BUFFER_SIZE, which is in chuncks of about 36 bytes depending on the context
(a quirk that can be avoided by using the new set_GRADSTACK_BUFFER_BYTES instead). See Section 1.28
"The TOP OF MAIN section" and Chapter 12 "Command line options" in the
ADMB User Manual for more
information.
There are a few things to watch out for:
- Don't try to input any values greater than 2^31 - 1 = 2147483647
- Don't use scientific notation when using command line options
- Watch out for large temporary files associated with insufficient memory use
What is the Hessian?
It is a matrix of second-order partial derivatives of the objective function defined in your model, which in ADMB is calculated at the parameter values which have minimized this function. This represents the curvature of the likelihood surface and is used to calculate estimates of uncertainty for all the estimated model parameters and chosen derived quantities.
Why does it sometimes say "Hessian does not appear to be positive definite"?
This generally happens if a minimum has not been found. The are various possible causes. Probably the most common is that the model has been written incorrectly so the objective function is not differentiable with respect to all the parameters. Another common cause is parameters hitting bounds. Non-positive-definite Hessians can also occur if the data are too perfect (see discussion here).
Are there tips on debugging code that doesn't seem to be working right?
An example of the debugging process applied by Dave Fournier (for a model with the error "Function minimizer not making progress") is described here.
How do I compile old Borland TPL’s in MinGW?
Now that Borland is no longer supported by ADMB, users will need to ensure that their programs work with other compilers. In many cases there will be no issues. However, header files (include statements I put in the GLOBALS_SECTION) may be compiler specific. Here's a suggestion from Mark Fowler based on his experience making the switch:
First step. Simply remove the ‘.h’ extensions of the Borland includes. MinGW has many equivalents for Borland includes that differ only in the extension (e.g. iostream, fstream, iomanip, string).
Second step. Identify remaining ‘source’ includes (just those in your TPL, not those of the includes themselves) that still balk the MinGW compiler. Disable all those that still produce an error. Now the compiler will only choke on absent commands that derive from disabled includes. Some of my TPLs simply compiled at this step, as I had been carrying over spurious includes across programs, so there were no commands in the TPL associated with them. For those that still trip the compiler do a web search on “[header_file] Borland MinGW” to find the right include to substitute, or a go-around. Most of these seemed to derive from user groups focused on web programming.
What is necessary to run MCMC?
MCMC is easy to implement in ADMB using the -mcmc N -mcsave N2 commands when running a model to run a chain of length N and save the output every N2 steps. To get output of parameter values that have been saved, you need to either read the binary .psv file (i.e. using the readBin function in R--see example code), or include in the code some commands to write to a file which are conditioned on the statement if(mceval_phase()) and then run the model again using the -mceval command. Finally, it is necessary to have at least one derived quantity designated as an sdreport variable in your model. For more on MCMC, see chapter 2 of the ADMB User Manual
How is MCMC implemented in ADMB?
AD Model Builder uses the hessian to produce an (almost) multivariate normal distribution for the Metropolis-Hastings algorithm. It is not exactly multivariate normal because the random vectors produced are modified to satisfy any bounds on the parameters. See the user manual for various modifications to the MCMC that are available, such as to deal with highly correlated parameters. Hybrid Monte Carlo sampling can also be used through the -hybrid command, but thorough benchmarks have not been conducted for this method.
Can I do interpolation?
Cubic splines are available in ADMB, but haven't yet been documented. Some example code is on this website here and in this email. Here is another useful source of information.
Can ADMB do parallel processing?
Parallel processing capabilities are currently in development. To see a description of current capabilities, see "Open MPI Presentation" and " Parallelization in ADMB" in the folder commmunity/admb-developers-workshop-march-13-16-2012.
Can ADMB produce DLLs (dynamic-link libraries)?
Note: this information is from an email by Arni Magnusson sent to the ADMB-Users email list.
At this time (January 2011) the DLL compilation is broken on most platforms - but probably not all.
Many years ago, Dave Fournier implemented fully working DLL compilation on all ADMB platforms (e.g. ADMB 5.0 in 2000). My understanding is that Dave did not continue to maintain this feature, because it took a lot of effort and it looked like few or no users were compiling ADMB DLLs.
When I wrote the adcomp/adlink/admb scripts in 2009, I decided to provide the -d option, knowing that the feature was at least half-broken. The idea is to highlight a feature that can probably be resurrected - and of course to provide DLL compilation on the few platforms where it still works.
The development team has only allocated limited efforts to examine the issue of DLL compilation, but encourages interested users to do so. Several discussions can be found here.
AD Studio
--------What is AD Studio?
An Integrated Development Environment which augments a text editor with a variety of tools for compiling, running, and debugging ADMB models. See the AD Studio manual for details, including screenshots.
Is AD Studio available for Mac or Linux as well as Windows?
Yes, although there is no installer, so the user has to do a little setup. See the AD Studio manual for details.
Can I use AD Studio for compiling C++?
Definitely. To see some suggestions on configuring AD Studio to make this easier, see this discussion on the ADMB-users email list.