FAQ

FAQ
ADMB Frequently Asked Questions

If you have ideas for additions or modifications, please send them to Ian.Taylor@noaa.gov.
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?

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.

What does ADMB stand for?

“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.

What is 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.

What is the advantage of using ADMB?

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).

Why is AD Model builder better than using spreadsheet solvers or other statistical packages?

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.

But aren’t models with hundreds or even thousands of parameters overparameterized?

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.

Where do I get it?

From the downloads page on this website.

What operating systems are supported?

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.

What does it cost?

Nothing.

How can I learn how to use ADMB?

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.

Isn’t this sort of package too restrictive?

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.

Are there courses I can take?

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 /events/previous. 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).

Are there any books on ADMB?

Not yet.

How can I learn more about ADMB?

This website includes updates with news related to ADMB. All users should also consider joining the users@admb-project.org email list.

Who uses ADMB?

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 at /help/user-base. A list of publications that depend on ADMB is available at /documentation/bibliography.

Who created ADMB?

David Fournier created ADMB, ADMB-RE, and the AUTODIF Library in the 1980s.

Who is currently developing ADMB?

The ADMB core-team is currently about 20 people.

They are also listed in the source code
https://github.com/admb-project/admb/blob/master/src/nh99/model7.cpp

This list is displayed when a user runs ‘mymodel -info’.

Can I help improve ADMB?

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.

How is ADMB supported financially?

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.

How can I cite ADMB?

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.

Is there a GUI for ADMB?

There is a GUI that runs in R, through the PBSadmb package.

What editors work with ADMB?

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.

How does ADMB interact with other software?

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 availablehere). 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.

Installation

How do I install ADMB?

Please see the installation instructions at /documentation/installation

Which version is best for my computer?

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.

Is there a .rpm or .deb package for easy Linux installation?

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.

Does ADMB work with Borland compilers?

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.

How do I set the PATH and other environment variables?

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.

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.

Why did my installation of ADMB fail?

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.

Is the ADMB source code available?

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 GitHub

Can I build ADMB directly from the source code?

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.

How can I avoid conflicts between C++ compilers?

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.

Usage

What are all the files produced by running an ADMB executable?

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.

How do I control memory use in ADMB?

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 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

There is more detailed information on this topic within this website here, and here. And many discussions in the archives of the ADMB Users email list.

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 (available here).

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. Hereis 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.

ADMB-IDE

What is the ADMB-IDE?

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 page for more information.

Is the ADMB-IDE 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 Section 2.3 of the ADMB-IDE user manual for details.

Can I use the ADMB-IDE for compiling C++?

Definitely. To see some suggestions on configuring the ADMB-IDE to make this easier, see this discussion on the ADMB-users email list.