If you have ideas for additions or modifications, please send them to
ADMB developers with editing privileges are welcome to make changes, but should read the Note on Editing the FAQ before doing so.
- 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?
- 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?
- 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?
- 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?
- What are all the files produced by running an ADMB executable?
- How do I control memory use in ADMB?
- What is the Hessian?
- Why does it sometimes say "Hessian does not appear to be positive definite"?
- Are there tips on debugging code that doesn't seem to be working right?
- How do I compile old Borland TPL’s in MinGW?
- What is necessary to run MCMC?
- How is MCMC implemented in ADMB?
- Can I do interpolation?
- Can ADMB do parallel processing?
- Can ADMB produce DLLs (dynamic-link libraries)?
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 (see http://otter-rsch.com/tresults.htm 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.
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 http://admb-project.org/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).
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:
This list is displayed when a user runs 'mymodel -info'.
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 (ADMB-IDE) 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 at http://admb-project.org/documentation/installation
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.
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
'admb' is not recognized as an internal or external command, operable program or batch file.
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 firstname.lastname@example.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 http://admb-project.org/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
- Parameter Estimate file (.par),
- Standard Deviation file (.std),
- Correlation Matrix file (.cor), and
- User-Defined Output file (.rep).
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
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 50000000The 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
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.
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).
An example of the debugging process applied by Dave Fournier (for a model with the error "Function minimizer not making progress") is described here.
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.
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
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.
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.
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.
An Integrated Developement Environment which augments a text editor with a variety of tools for compiling, running, and debugging ADMB models. See the ADMB-IDE manual for details, including screenshots.
Yes, although there is no installer, so the user has to do a little setup. See Section 1.3 of the ADMB-IDE user manual for details.
Definitely. To see some suggestions on configuring the ADMB-IDE to make this easier, see this discussion on the ADMB-users email list.