math: A C++ repository from gregorp90

The Stan Math Library is a C++, reverse-mode automatic differentiation library designed to be usable, extensive and extensible, efficient, scalable, stable, portable, and redistributable in order to facilitate the construction and utilization of algorithms that utilize derivatives.

\htmlonly

\endhtmlonly

Licensing

The Stan Math Library is licensed under the new BSD license.

The Stan Math Library depends on the Intel TBB library which is licensed under the Apache 2.0 license. This dependency implies an additional restriction as compared to the new BSD license alone. The Apache 2.0 license is incompatible with GPL-2 licensed code if distributed as a unitary binary. You may refer to the Apache 2.0 evaluation page on the Stan Math wiki.

Required Libraries

Stan Math depends on four libraries:

Boost (version 1.75.0): Boost Home Page
Eigen (version 3.3.9: Eigen Home Page
SUNDIALS (version 5.7.0): Sundials Home Page
Intel TBB (version 2020.3): Intel TBB Home Page

These are distributed under the lib/ subdirectory. Only these versions of the dependent libraries have been tested with Stan Math.

Documentation

Documentation for Stan math is available at mc-stan.org/math

Installation

The Stan Math Library is a C++ library which depends on the Intel TBB library and requires for some functionality (ordinary differential equations and root solving) the Sundials library. The build system is the make facility, which is used to manage all dependencies.

A simple hello world program using Stan Math is as follows:

#include <stan/math.hpp>
#include <iostream>

int main() {
  std::cout << "log normal(1 | 2, 3)="
            << stan::math::normal_log(1, 2, 3)
            << std::endl;
}

If this is in the file /path/to/foo/foo.cpp, then you can compile and run this with something like this, with the /path/to business replaced with actual paths:

> cd /path/to/foo
> make -j4 -f /path/to/stan-math/make/standalone math-libs
> make -f /path/to/stan-math/make/standalone foo
> ./foo
log normal(1 | 2, 3)=-2.07311

The first make command with the math-libs target ensures that all binary dependencies of Stan Math are built and ready to use. The -j4 instructs make to use 4 cores concurrently which should be adapted to your needs. The second make command ensures that the Stan Math sources and all of the dependencies are available to the compiler when building foo.

An example of a real instantiation whenever the path to Stan Math is ~/stan-dev/math/:

> make -j4 -f ~/stan-dev/math/make/standalone math-libs
> make -f ~/stan-dev/math/make/standalone foo

The math-libs target has to be called only once, and can be omitted for subsequent compilations.

The standalone makefile ensures that all the required -I include statements are given to the compiler and the necessary libraries are linked: ~/stan-dev/math and ~/stan-dev/math/lib/eigen_3.3.9 and ~/stan-dev/math/lib/boost_1.75.0 and ~/stan-dev/math/lib/sundials_5.7.0/include and ~/stan-dev/math/lib/tbb_2020.3/include. The ~/stan-dev/math/lib/tbb directory is created by the math-libs makefile target automatically and contains the dynamically loaded Intel TBB library. The flags -Wl,-rpath,... instruct the linker to hard-code the path to the dynamically loaded Intel TBB library inside the stan-math directory into the final binary. This way the Intel TBB is found when executing the program.

Note for Windows users: On Windows the -rpath feature as used by Stan Math to hardcode an absolute path to a dynamically loaded library does not work. On Windows the Intel TBB dynamic library tbb.dll is located in the math/lib/tbb directory. The user can choose to copy this file to the same directory of the executable or to add the directory /path/to/math/lib/tbb as absolute path to the system-wide PATH variable.

Intel TBB

math supports the new interface of Intel TBB, can be configured to use an external copy of TBB (e.g., with oneTBB or the system TBB library), using the TBB_LIB and TBB_INC environment variables.

To build the development version of math with oneTBB:

Install oneTBB.

For example, installing oneTBB on Linux 64-bit (x86_64) to $HOME directory (change if needed!):

TBB_RELEASE="https://api.github.com/repos/oneapi-src/oneTBB/releases/latest"
TBB_TAG=$(curl --silent $TBB_RELEASE | grep -Po '"tag_name": "\K.*?(?=")')
TBB_VERSION=${TBB_TAG#?}

wget https://github.com/oneapi-src/oneTBB/releases/download/v${TBB_VERSION}/oneapi-tbb-${TBB_VERSION}-lin.tgz
tar zxvf oneapi-tbb-$TBB_VERSION-lin.tgz -C $HOME

export TBB="$HOME/oneapi-tbb-$TBB_VERSION"

Note that you may replace TBB_VERSION=${TBB_TAG#?} with a custom version number if needed ( check available releases here ).

Set the TBB environment variables (specifically: TBB for the installation prefix, TBB_INC for the directory that includes the header files, and TBB_LIB for the libraries directory).

For example, installing oneTBB on Linux 64-bit (x86_64) to $HOME directory (change if needed!):

source $TBB/env/vars.sh intel64

export TBB_INC="$TBB/include"
export TBB_LIB="$TBB/lib/intel64/gcc4.8"

Set Stan local compiler flags to use the new TBB interface:

mkdir -p ~/.config/stan
echo TBB_INTERFACE_NEW=true>> ~/.config/stan/make.local

Compilers

The above example will use the default compiler of the system as determined by make. On Linux this is usually g++, on MacOS clang++, and for Windows this is g++ if the RTools for Windows are used. There's nothing special about any of these and they can be changed through the CXX variable of make. The recommended way to set this variable for the Stan Math library is by creating a make/local file within the Stan Math library directory. Defining CXX=g++ in this file will ensure that the GNU C++ compiler is always used, for example. The compiler must be able to fully support C++11 and partially the C++14 standard. The g++ 4.9.3 version part of RTools for Windows currently defines the minimal C++ feature set required by the Stan Math library.

Note that whenever the compiler is changed, the user usually must clean and rebuild all binary dependencies with the commands:

> make -f path/to/stan-math/make/standalone math-clean
> make -j4 -f path/to/stan-math/make/standalone math-libs