Stan Math: automatic differentiation of any order in C++

A differentiation library, and what it is for

The Stan Math Library is a C++ template library for automatic differentiation of any order using forward, reverse and mixed modes, and it includes a range of built-in functions for probabilistic modelling, linear algebra and equation solving.

That is a complete description of a piece of numerical infrastructure, and the phrase that carries the weight is any order. Automatic differentiation is normally introduced as first order, the gradient you need to run gradient descent, and a library that stops there covers half the problems. Stan Math gives you the Hessian and the higher derivatives as well, which is what makes it usable for the second order methods that inference algorithms rely on.

The modes matter for a different reason. Reverse mode is the efficient one for a scalar objective with many inputs, which is the shape of a log density in a probabilistic model. Forward mode is the efficient one for a small number of inputs or for many outputs. Mixed mode is what a program that needs both wants, and having all three in one library, sharing the same types and the same expression templates, is the reason to use it rather than to write your own forward mode and link somebody else's reverse mode.

The library is the numerical foundation of the Stan ecosystem, whose site is mc-stan.org, and the repository description calls out the three built-in areas: probabilistic modelling functions, linear algebra, and equation solving, which is the ODE and algebraic solver layer that differential equation models sit on. The primary language is C++, the default branch is develop, and the licence is the BSD 3-Clause, recorded as the new BSD license with the text in the repository.

The template machinery is the whole design

Everything in Stan Math is a C++ template, and that is not an implementation detail, it is the mechanism.

A template library for automatic differentiation works by building a computation as a type rather than by running it. Each operation returns an object that carries both the value and the derivative information, and the derivative is computed when the expression is evaluated, or when a value is requested. Reverse mode in particular works by recording the operations in a tape as the forward sweep runs and replaying it in reverse to produce the adjoint, which is a technique that only fits into a template library because the tape has to be built at compile time from the expression structure.

The practical consequence for a user is that the API is arithmetic. You write the model, the library differentiates it, and there is no separate gradient function to keep in step with the function itself. That is the single largest class of bug in a hand-written differentiation setup, and it is the reason to use a library like this at all.

The second consequence is compile time, which is the cost of the approach. Template-heavy C++ compiles slowly, and the library is large enough that the build is a real part of the experience. That shows up in the repository itself, which carries a Makefile, a make/ directory, a Jenkinsfile, runTests.py and runChecks.py, because a project of this size needs its own build and test machinery rather than a single command from a package manager.

TBB is the dependency that changes the licence

The Stan Math Library depends on the Intel TBB library, which is licensed under the Apache 2.0 license, and the README says plainly that this dependency implies an additional restriction as compared with the new BSD license alone. Apache 2.0 is incompatible with GPL-2 licensed code if distributed as a unitary binary.

That is a narrow and specific statement, and it is the kind of thing that matters at the moment you choose how to ship a binary rather than at the moment you write the code. If your project is a library that others link, the restriction may not apply to you at all, because the TBB code is not merged into your artefact. If your project ships a single binary that includes the TBB code, and your own code is under a GPL-2 licence, then it does apply.

The README points at the Licensing page on the Stan wiki for the full statement. That is the right thing to do with this paragraph, because the question of how a derived binary is distributed is not one to answer from a summary, and the summary here is at least honest about pointing elsewhere.

The other dependencies are visible in the repository topics rather than in this README: Eigen for linear algebra, Boost, and SUNDIALS for equation solving. Those are the layers the built-in functions are built on, and they explain why the library carries a linear algebra and solver surface of its own rather than exposing only the differentiation machinery.

The repository is a library plus its own build and test machinery

The top-level listing is what a numerical library of this kind looks like in practice.

There is lib/ for the library itself, stan/ for the layer that the Stan language itself uses, test/ for the test suites, and benchmarks/ for the performance measurements. There is doxygen/ for the API documentation build, a makefile and a make/ directory for the build system, and hooks/ for the git hooks that the project installs.

The supporting files are the interesting part. There is a Jenkinsfile, which is the continuous integration definition, alongside runTests.py and runChecks.py, two entry points for the test and the checks. There is a .clang-format file, which is how the code style is kept consistent across a large template-heavy codebase, and a .git-blame-ignore-revs file, which is the mechanism for telling git blame to skip a bulk reformat so that the history of a line still points at the change that mattered rather than at the commit that moved the code around.

There is a licenses/ directory alongside the LICENSE.md file, which is the pattern for a project that ships third-party licence texts it needs to keep current. And there is RELEASE-NOTES.txt at the root, which is where the change history for each version lives.

The combination of a Makefile, a Jenkinsfile and a set of Python entry points says something about the project's priorities: the build has to work in several environments, and the checks are run as scripts rather than as a single binary so that they can be invoked the same way locally and in CI.

Documentation on the website, and a wiki that is explicitly retired

The documentation instruction is short and unusually firm.

All of the documentation for the library is hosted on the website, at mc-stan.org/math, and then the README asks you not to reference articles in the wiki, because they are outdated and not maintained.

That single sentence is a useful piece of advice for anyone arriving at this project from a search result, because a wiki that still ranks well in a search engine and describes an older version of a numerical library is a trap. The documentation site is the one to trust, and the release notes in the repository are the other source that is kept current.

The same pattern shows up in the release history. The versions are v5.3.0 on 2026-05-19, v5.4.0-rc1 on 2026-09-09 and v5.4.0 on 2026-09-16, so a release candidate is followed by a final within a week, and the last push was on 2026-10-19. The default branch is develop, which is the working branch for a project that ships tagged releases from it.

There is also a Zenodo badge at the top of the README, which is the archive that gives the library a permanent identifier for citation. For a numerical library that other people's papers depend on, that matters more than it would for an application, because the exact version used to produce a result has to be citable years later.

What to check before you depend on it

Three things, in the order they will affect you.

The licence. Stan Math is BSD 3-Clause, and the TBB dependency adds the restriction about GPL-2 code in a unitary binary. If you are building a library rather than a binary, this is unlikely to be your problem, and if you are building a binary under a GPL-2 licence, it is the whole problem. The licensing page on the wiki is the reference, and it is worth reading before you commit to a distribution model, not after.

The documentation. Use mc-stan.org/math and not the wiki, for the reason the README gives. A numerical library's API has many overloads and template parameters, and a stale description of them is worse than no description.

The build. This is a template-heavy C++ library with its own Makefile, its own checks and a CI pipeline, so your build time will include building it, and the project expects you to use its tooling rather than a package manager. There is no wheel, no jar and no prebuilt binary to download, and the Jenkinsfile and the make/ directory are there because the build is meant to be run the way the project runs it.

None of that makes the library a difficult choice if you are writing numerical code in C++ and want derivatives of any order with a well-understood licence and a maintained documentation site. It does mean the project expects you to follow its conventions, and the conventions start at the build.

Editorial conclusion

Adopt Stan Math if you are writing an optimiser or a sampler in C++ and need gradients, because a template library that gives you derivatives of any order in forward, reverse and mixed modes removes an entire category of implementation error. Do not adopt it without reading the licensing page, because the Intel TBB dependency is under Apache 2.0 and the README states that it is incompatible with GPL-2 licensed code when distributed as a unitary binary. Before you build on it, check the documentation site rather than the wiki, because the README explicitly asks readers not to rely on the wiki articles, since they are outdated and no longer maintained.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. stan-dev/math on GitHub