Skip to content

Commit d29995f

Browse files
SteveBronderSteveBronder
committed
update docs
1 parent 8b8871c commit d29995f

File tree

16 files changed

+1993
-1243
lines changed

16 files changed

+1993
-1243
lines changed

‎README.md

+9-156
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,15 @@ in order to facilitate the construction and utilization of algorithms
77
that utilize derivatives.
88

99

10+
Documentation, Installation, and Examples
11+
--------------
12+
13+
All of Stan math's documentation is hosted on our website below. Please do not
14+
reference articles in the wiki as they are outdated and not maintained.
15+
16+
mc-stan.org/math
17+
18+
1019
Licensing
1120
---------
1221
The Stan Math Library is licensed under the [new BSD
@@ -17,159 +26,3 @@ licensed under the Apache 2.0 license. This dependency implies an
1726
additional restriction as compared to the new BSD license alone. The
1827
Apache 2.0 license is incompatible with GPL-2 licensed code if
1928
distributed as a unitary binary. You may refer to the Licensing page on the [Stan wiki](https://github.com/stan-dev/stan/wiki/Stan-Licensing).
20-
21-
Required Libraries
22-
------------------
23-
Stan Math depends on four libraries:
24-
25-
- Boost (version 1.78.0): [Boost Home Page](https://www.boost.org)
26-
- Eigen (version 3.3.9: [Eigen Home Page](https://eigen.tuxfamily.org/index.php?title=Main_Page)
27-
- SUNDIALS (version 6.1.1): [Sundials Home Page](https://computing.llnl.gov/projects/sundials)
28-
- Intel TBB (version 2020.3): [Intel TBB Home Page](https://www.threadingbuildingblocks.org)
29-
30-
These are distributed under the `lib/` subdirectory. Only these
31-
versions of the dependent libraries have been tested with Stan Math.
32-
33-
Documentation
34-
------------
35-
36-
Documentation for Stan math is available at [mc-stan.org/math](https://mc-stan.org/math/)
37-
38-
Contributing
39-
------------
40-
41-
We love contributions from everyone in the form of good discussion, issues, and pull requests.
42-
If you are interested in contributing to Stan math please check the Contributor Guide at [mc-stan.org/math](https://mc-stan.org/math/).
43-
44-
Installation
45-
------------
46-
The Stan Math Library is a C++ library which depends on the Intel TBB
47-
library and requires for some functionality (ordinary differential
48-
equations and root solving) the Sundials library. The build system is
49-
the make facility, which is used to manage all dependencies.
50-
51-
A simple hello world program using Stan Math is as follows:
52-
53-
```cpp
54-
#include <stan/math.hpp>
55-
#include <iostream>
56-
57-
int main() {
58-
std::cout << "log normal(1 | 2, 3)="
59-
<< stan::math::normal_log(1, 2, 3)
60-
<< std::endl;
61-
}
62-
```
63-
64-
If this is in the file `/path/to/foo/foo.cpp`, then you can compile
65-
and run this with something like this, with the `/path/to` business
66-
replaced with actual paths:
67-
68-
```bash
69-
> cd /path/to/foo
70-
> make -j4 -f /path/to/stan-math/make/standalone math-libs
71-
> make -f /path/to/stan-math/make/standalone foo
72-
> ./foo
73-
log normal(1 | 2, 3)=-2.07311
74-
```
75-
76-
The first make command with the `math-libs` target ensures that all
77-
binary dependencies of Stan Math are built and ready to use. The `-j4`
78-
instructs `make` to use 4 cores concurrently which should be adapted
79-
to your needs. The second make command ensures that the Stan Math
80-
sources and all of the dependencies are available to the compiler when
81-
building `foo`.
82-
83-
An example of a real instantiation whenever the path to Stan Math is
84-
`~/stan-dev/math/`:
85-
86-
```bash
87-
> make -j4 -f ~/stan-dev/math/make/standalone math-libs
88-
> make -f ~/stan-dev/math/make/standalone foo
89-
```
90-
The `math-libs` target has to be called only once, and can be omitted
91-
for subsequent compilations.
92-
93-
The standalone makefile ensures that all the required `-I` include
94-
statements are given to the compiler and the necessary libraries are
95-
linked: `~/stan-dev/math` and `~/stan-dev/math/lib/eigen_3.3.9` and
96-
`~/stan-dev/math/lib/boost_1.78.0` and
97-
`~/stan-dev/math/lib/sundials_6.1.1/include` and
98-
`~/stan-dev/math/lib/tbb_2020.3/include`. The
99-
`~/stan-dev/math/lib/tbb` directory is created by the `math-libs`
100-
makefile target automatically and contains the dynamically loaded
101-
Intel TBB library. The flags `-Wl,-rpath,...` instruct the linker to
102-
hard-code the path to the dynamically loaded Intel TBB library inside
103-
the stan-math directory into the final binary. This way the Intel TBB
104-
is found when executing the program.
105-
106-
Note for Windows users: On Windows the `-rpath` feature as used by
107-
Stan Math to hardcode an absolute path to a dynamically loaded library
108-
does not work. On Windows the Intel TBB dynamic library `tbb.dll` is
109-
located in the `math/lib/tbb` directory. The user can choose to copy
110-
this file to the same directory of the executable or to add the
111-
directory `/path/to/math/lib/tbb` as absolute path to the system-wide
112-
`PATH` variable.
113-
114-
Intel TBB
115-
---------
116-
117-
`math` supports the new interface of Intel TBB, can be configured to use an external copy of TBB (e.g., with [`oneTBB`](https://github.com/oneapi-src/oneTBB) or the system TBB library), using the `TBB_LIB` and `TBB_INC` environment variables.
118-
119-
To build the development version of `math` with [`oneTBB`](https://github.com/oneapi-src/oneTBB):
120-
121-
- Install [`oneTBB`](https://github.com/oneapi-src/oneTBB).
122-
123-
For example, installing [`oneTBB`](https://github.com/oneapi-src/oneTBB) on Linux 64-bit (`x86_64`) to `$HOME` directory (change if needed!):
124-
```bash
125-
TBB_RELEASE="https://api.github.com/repos/oneapi-src/oneTBB/releases/latest"
126-
TBB_TAG=$(curl --silent $TBB_RELEASE | grep -Po '"tag_name": "\K.*?(?=")')
127-
TBB_VERSION=${TBB_TAG#?}
128-
129-
wget https://github.com/oneapi-src/oneTBB/releases/download/v${TBB_VERSION}/oneapi-tbb-${TBB_VERSION}-lin.tgz
130-
tar zxvf oneapi-tbb-$TBB_VERSION-lin.tgz -C $HOME
131-
132-
export TBB="$HOME/oneapi-tbb-$TBB_VERSION"
133-
```
134-
Note that you may replace `TBB_VERSION=${TBB_TAG#?}` with a custom version number if needed ( check available releases [here](https://github.com/oneapi-src/oneTBB/releases) ).
135-
136-
- 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).
137-
138-
For example, installing [`oneTBB`](https://github.com/oneapi-src/oneTBB) on Linux 64-bit (`x86_64`) to `$HOME` directory (change if needed!):
139-
```bash
140-
source $TBB/env/vars.sh intel64
141-
142-
export TBB_INC="$TBB/include"
143-
export TBB_LIB="$TBB/lib/intel64/gcc4.8"
144-
```
145-
146-
- Set `Stan` local compiler flags to use the new TBB interface:
147-
```bash
148-
mkdir -p ~/.config/stan
149-
echo TBB_INTERFACE_NEW=true>> ~/.config/stan/make.local
150-
```
151-
152-
Compilers
153-
---------
154-
155-
The above example will use the default compiler of the system as
156-
determined by `make`. On Linux this is usually `g++`, on MacOS
157-
`clang++`, and for Windows this is `g++` if the RTools for Windows are
158-
used. There's nothing special about any of these and they can be
159-
changed through the `CXX` variable of `make`. The recommended way to
160-
set this variable for the Stan Math library is by creating a
161-
`make/local` file within the Stan Math library directory. Defining
162-
`CXX=g++` in this file will ensure that the GNU C++ compiler is always
163-
used, for example. The compiler must be able to fully support C++11
164-
and partially the C++14 standard. The `g++` 4.9.3 version part of
165-
RTools for Windows currently defines the minimal C++ feature set
166-
required by the Stan Math library.
167-
168-
Note that whenever the compiler is changed, the user usually must
169-
clean and rebuild all binary dependencies with the commands:
170-
```bash
171-
> make -f path/to/stan-math/make/standalone math-clean
172-
> make -j4 -f path/to/stan-math/make/standalone math-libs
173-
```
174-
This ensures that the binary dependencies are created with the new
175-
compiler.

‎doxygen/README.md

+166
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# Stan Math Library Docs
2+
3+
The <b>Stan Math Library</b> is a BSD-3 licensed C++, reverse-mode automatic
4+
differentiation library designed to facilitate the construction and utilization of algorithms
5+
that utilize derivatives.
6+
7+
Required Libraries
8+
------------------
9+
Stan Math depends on four libraries:
10+
11+
- Boost (version 1.78.0): [Boost Home Page](https://www.boost.org)
12+
- Eigen (version 3.3.9: [Eigen Home Page](https://eigen.tuxfamily.org/index.php?title=Main_Page)
13+
- SUNDIALS (version 6.1.1): [Sundials Home Page](https://computing.llnl.gov/projects/sundials)
14+
- Intel TBB (version 2020.3): [Intel TBB Home Page](https://www.threadingbuildingblocks.org)
15+
16+
These are distributed under the `lib/` subdirectory. Only these
17+
versions of the dependent libraries have been tested with Stan Math.
18+
19+
Contributing
20+
------------
21+
22+
We love contributions from everyone in the form of good discussion, issues, and pull requests.
23+
If you are interested in contributing to Stan math please check the Contributor Guide at [mc-stan.org/math](https://mc-stan.org/math/).
24+
25+
Installation
26+
------------
27+
The Stan Math Library is a C++ library which depends on the Intel TBB
28+
library and requires the Sundials library for ordinary differential
29+
equations and root solving. The build system is
30+
the make facility, which is used to manage all dependencies.
31+
32+
A simple hello world program using Stan Math is as follows:
33+
34+
```cpp
35+
#include <stan/math.hpp>
36+
#include <iostream>
37+
38+
int main() {
39+
std::cout << "log normal(1 | 2, 3)="
40+
<< stan::math::normal_lpdf(1, 2, 3)
41+
<< std::endl;
42+
}
43+
```
44+
45+
If this is in the file `<path>/foo.cpp`, then you can compile
46+
and run this with something like this with `<path>` replaced with the path to the file:
47+
48+
```bash
49+
cd <path>/foo
50+
make -j4 -f <path>/stan-math/make/standalone math-libs
51+
make -f <path>/stan-math/make/standalone foo
52+
./foo
53+
log normal(1 | 2, 3)=-2.07311
54+
```
55+
56+
The first make command with the `math-libs` target ensures that all
57+
binary dependencies of Stan Math are built and ready to use. The `-j4`
58+
instructs `make` to use 4 cores concurrently which should be adapted
59+
to your needs. The second make command ensures that the Stan Math
60+
sources and all of the dependencies are available to the compiler when
61+
building `foo`.
62+
63+
An example of a real instantiation whenever the path to Stan Math is
64+
`~/stan-dev/math/`:
65+
66+
```bash
67+
> make -j4 -f ~/stan-dev/math/make/standalone math-libs
68+
> make -f ~/stan-dev/math/make/standalone foo
69+
```
70+
The `math-libs` target has to be called only once, and can be omitted
71+
for subsequent compilations.
72+
73+
The standalone makefile ensures that all the required `-I` include
74+
statements are given to the compiler and the necessary libraries are
75+
linked: `~/stan-dev/math` and `~/stan-dev/math/lib/eigen_3.3.9` and
76+
`~/stan-dev/math/lib/boost_1.78.0` and
77+
`~/stan-dev/math/lib/sundials_6.1.1/include` and
78+
`~/stan-dev/math/lib/tbb_2020.3/include`. The
79+
`~/stan-dev/math/lib/tbb` directory is created by the `math-libs`
80+
makefile target automatically and contains the dynamically loaded
81+
Intel TBB library. The flags `-Wl,-rpath,...` instruct the linker to
82+
hard-code the path to the dynamically loaded Intel TBB library inside
83+
the stan-math directory into the final binary. This way the Intel TBB
84+
is found when executing the program.
85+
86+
Note for Windows users: On Windows the `-rpath` feature as used by
87+
Stan Math to hardcode an absolute path to a dynamically loaded library
88+
does not work. On Windows the Intel TBB dynamic library `tbb.dll` is
89+
located in the `math/lib/tbb` directory. The user can choose to copy
90+
this file to the same directory of the executable or to add the
91+
directory `/path/to/math/lib/tbb` as absolute path to the system-wide
92+
`PATH` variable.
93+
94+
Intel TBB
95+
---------
96+
97+
`math` supports the new interface of Intel TBB, can be configured to use an external copy of TBB (e.g., with [`oneTBB`](https://github.com/oneapi-src/oneTBB) or the system TBB library), using the `TBB_LIB` and `TBB_INC` environment variables.
98+
99+
To build the development version of `math` with [`oneTBB`](https://github.com/oneapi-src/oneTBB):
100+
101+
- Install [`oneTBB`](https://github.com/oneapi-src/oneTBB).
102+
103+
For example, installing [`oneTBB`](https://github.com/oneapi-src/oneTBB) on Linux 64-bit (`x86_64`) to `$HOME` directory (change if needed!):
104+
```bash
105+
TBB_RELEASE="https://api.github.com/repos/oneapi-src/oneTBB/releases/latest"
106+
TBB_TAG=$(curl --silent $TBB_RELEASE | grep -Po '"tag_name": "\K.*?(?=")')
107+
TBB_VERSION=${TBB_TAG#?}
108+
109+
wget https://github.com/oneapi-src/oneTBB/releases/download/v${TBB_VERSION}/oneapi-tbb-${TBB_VERSION}-lin.tgz
110+
tar zxvf oneapi-tbb-$TBB_VERSION-lin.tgz -C $HOME
111+
112+
export TBB="$HOME/oneapi-tbb-$TBB_VERSION"
113+
```
114+
Note that you may replace `TBB_VERSION=${TBB_TAG#?}` with a custom version number if needed ( check available releases [here](https://github.com/oneapi-src/oneTBB/releases) ).
115+
116+
- 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).
117+
118+
For example, installing [`oneTBB`](https://github.com/oneapi-src/oneTBB) on Linux 64-bit (`x86_64`) to `$HOME` directory (change if needed!):
119+
```bash
120+
source $TBB/env/vars.sh intel64
121+
122+
export TBB_INC="$TBB/include"
123+
export TBB_LIB="$TBB/lib/intel64/gcc4.8"
124+
```
125+
126+
- Set `Stan` local compiler flags to use the new TBB interface:
127+
```bash
128+
mkdir -p ~/.config/stan
129+
echo TBB_INTERFACE_NEW=true>> ~/.config/stan/make.local
130+
```
131+
132+
Compilers
133+
---------
134+
135+
The above example will use the default compiler of the system as
136+
determined by `make`. On Linux this is usually `g++`, on MacOS
137+
`clang++`, and for Windows this is `g++` if the RTools for Windows are
138+
used. There's nothing special about any of these and they can be
139+
changed through the `CXX` variable of `make`. The recommended way to
140+
set this variable for the Stan Math library is by creating a
141+
`make/local` file within the Stan Math library directory. Defining
142+
`CXX=g++` in this file will ensure that the GNU C++ compiler is always
143+
used, for example. The compiler must be able to fully support C++11
144+
and partially the C++14 standard. The `g++` 4.9.3 version part of
145+
RTools for Windows currently defines the minimal C++ feature set
146+
required by the Stan Math library.
147+
148+
Note that whenever the compiler is changed, the user usually must
149+
clean and rebuild all binary dependencies with the commands:
150+
```bash
151+
> make -f path/to/stan-math/make/standalone math-clean
152+
> make -j4 -f path/to/stan-math/make/standalone math-libs
153+
```
154+
This ensures that the binary dependencies are created with the new
155+
compiler.
156+
157+
Licensing
158+
---------
159+
The Stan Math Library is licensed under the [new BSD
160+
license](https://github.com/stan-dev/math/blob/develop/LICENSE%2Emd).
161+
162+
The Stan Math Library depends on the Intel TBB library which is
163+
licensed under the Apache 2.0 license. This dependency implies an
164+
additional restriction as compared to the new BSD license alone. The
165+
Apache 2.0 license is incompatible with GPL-2 licensed code if
166+
distributed as a unitary binary. You may refer to the Licensing page on the [Stan wiki](https://github.com/stan-dev/stan/wiki/Stan-Licensing).

0 commit comments

Comments
 (0)