FAQ

by Ian Taylor — last modified Feb 02, 2012 04:15 PM

Contributors: arnima

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
Installation
Usage
ADMB-IDE

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

Are there any books on ADMB?

Not yet.

Can I help improve ADMB?

Yes [somebody fill in more info here].

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 (link to info).

Who created ADMB?

David Fournier created ADMB, ADMB-RE, and the AUTODIF Library in the 1980s. More information on the history of ADMB is available here.

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 publications that depend on ADMB is posted here.

How is ADMB supported financially?

The ADMB Project is supported by the National Center for Ecological Analysis and Synthesis, the Pelagic Fisheries Research Program, the ADMB Foundation, and a grant from NOAA Fisheries to the Joint Institute of Marine and Atmospheric Research.

How can I cite ADMB?

In the text of a paper: AD Model Builder (ADMB Project 2009) is used to implement the model. In the references: ADMB Project. 2009 AD Model Builder: automatic differentiation model builder. Developed by David Fournier and freely available from admb-project.org.

Update: A journal publication describing ADMB has just been published and is freely available through open access at http://www.tandfonline.com/doi/abs/10.1080/10556788.2011.597854. This will be the recommended citation for ADMB for any publications using ADMB.

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

Installation

Which version is best for my computer?

Obviously this depends on the type of computer you have. For Windows users, there is a choice of three compiler options. Among the three, the MinGW 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 MinGW 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.

Do I need an administrator account to install ADMB?

No, you do not. However, in some cases the environmental variables that point to the ADMB files may not have been set correctly when installing as a non-administator. 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 Environmental Variables, are in the email archives, here and here.

The key is to make sure that the PATH environmental 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 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).

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.

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 either in bytes or in chucks of about 36 bytes depending on the context (a quirk that will hopefully go away in the next release of ADMB). 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.

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?

ADMB is currently being developed to run certain standard models in parallel, such as models with separable random effects. Additional expansions will hopefully follow.

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

Document Actions

Send this

Sections

Personal tools

FAQ

Document Actions