From a8247b914872154b4cca87de6b147aacbb2db6cf Mon Sep 17 00:00:00 2001 From: Sebastian Weber Date: Thu, 2 Apr 2020 16:10:07 +0200 Subject: [PATCH 1/7] clarify README.md --- README.md | 101 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 75 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 64a47a944b5..c99d2a5c5ed 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,8 @@ -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. +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
@@ -6,9 +10,16 @@ The Stan Math Library is a C++, reverse-mode automatic differentiation li Licensing --------- -The Stan Math Library is licensed under the [new BSD license](https://github.com/stan-dev/math/blob/develop/LICENSE%2Emd). +The Stan Math Library is licensed under the [new BSD +license](https://github.com/stan-dev/math/blob/develop/LICENSE%2Emd). -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 lincense 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](https://github.com/stan-dev/math/wiki/Apache-2.0-License-Evaluation). +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 lincense 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](https://github.com/stan-dev/math/wiki/Apache-2.0-License-Evaluation). Required Libraries ------------------ @@ -19,7 +30,8 @@ Stan Math depends on four libraries: - SUNDIALS (version 5.1.0): [Sundials Home Page](https://computation.llnl.gov/projects/sundials/sundials-software) - Intel TBB (version 2019_U8): [Intel TBB Home Page](https://www.threadingbuildingblocks.org) -These are distributed under the `lib/` subdirectory. Only these versions of the dependent libraries have been tested with Stan Math. +These are distributed under the `lib/` subdirectory. Only these +versions of the dependent libraries have been tested with Stan Math. Documentation ------------ @@ -28,7 +40,10 @@ Documentation for Stan math is available at [mc-stan.org/math](https://mc-stan.o 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) on the Sundials library. The build system used is the make facility, which is used to manage all dependencies. +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: @@ -43,43 +58,77 @@ int main() { } ``` -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: +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: ```bash > cd /path/to/foo -> make -f path/to/stan-math/make/standalone math-libs -> make -f path/to/stan-math/make/standalone 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 are built and ready to use. The second make command ensures that all dependencies of Stan Math are available to the compiler. These are: +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`. -* Stan Math Library: path to source directory that contains `stan` as a subdirectory -* Eigen C++ Matrix Library: path to source directory that contains `Eigen` as a subdirectory -* Boost C++ Library: path to source directory that contains `boost` as a subdirectory -* SUNDIALS: path to source directory that contains `cvodes` and `idas` as a subdirectory -* Intel TBB: path to source directory that contains `tbb` as a subdirectory - -Note that the paths should *not* include the final directories `stan`, `Eigen`, or `boost` on the paths. An example of a real instantiation: +An example of a real instantiation whenever the path to Stan Math is +`~/stan-dev/math/`: ```bash -> make -f ~/stan-dev/math/make/standalone math-libs +> 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/stan` and `~/stan-dev/math/lib/eigen_3.3.3/Eigen` and `~/stan-dev/math/lib/boost_1.69.0/boost` and `~/stan-dev/math/lib/sundials_5.1.0/include` and `~/stan-dev/math/lib/tbb_2019_U8/include`. The `~/stan-dev/math/lib/tbb` directory is created by the `math-libs` makefile target automatically. The flags `-Wl,-rpath,...` instruct the linker to hard-code the path to the 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. +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/stan` and +`~/stan-dev/math/lib/eigen_3.3.3/Eigen` and +`~/stan-dev/math/lib/boost_1.72.0/boost` and +`~/stan-dev/math/lib/sundials_5.1.0/include` and +`~/stan-dev/math/lib/tbb_2019_U8/include`. The +`~/stan-dev/math/lib/tbb` directory is created by the `math-libs` +makefile target automatically. The flags `-Wl,-rpath,...` instruct the +linker to hard-code the path to the Intel TBB dynamically loaded +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. 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: +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: ```bash > make -f path/to/stan-math/make/standalone math-clean -> make -f path/to/stan-math/make/standalone math-libs +> make -j4 -f path/to/stan-math/make/standalone math-libs ``` -This ensures that the binary dependencies are created with the new compiler. +This ensures that the binary dependencies are created with the new +compiler. From 31d7de46edeff24bec2e38f86d3d9cef07722644 Mon Sep 17 00:00:00 2001 From: Stan Jenkins Date: Thu, 2 Apr 2020 14:12:17 +0000 Subject: [PATCH 2/7] [Jenkins] auto-formatting by clang-format version 5.0.0-3~16.04.1 (tags/RELEASE_500/final) --- stan/math/opencl/kernel_generator/load.hpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stan/math/opencl/kernel_generator/load.hpp b/stan/math/opencl/kernel_generator/load.hpp index 66f4fa363d6..1f90d03c382 100644 --- a/stan/math/opencl/kernel_generator/load.hpp +++ b/stan/math/opencl/kernel_generator/load.hpp @@ -49,7 +49,7 @@ class load_ * Creates a deep copy of this expression. * @return copy of \c *this */ - inline load_ deep_copy() const& { return load_(a_); } + inline load_ deep_copy() const & { return load_(a_); } inline load_ deep_copy() && { return load_(std::forward(a_)); } /** From f045abd858bf4cffc545deb8a1d5ed494a821174 Mon Sep 17 00:00:00 2001 From: Sebastian Weber Date: Thu, 2 Apr 2020 16:17:11 +0200 Subject: [PATCH 3/7] some more touches --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index c99d2a5c5ed..d01d607fc1c 100644 --- a/README.md +++ b/README.md @@ -89,23 +89,23 @@ 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/stan` and -`~/stan-dev/math/lib/eigen_3.3.3/Eigen` and -`~/stan-dev/math/lib/boost_1.72.0/boost` and +linked: `~/stan-dev/math` and `~/stan-dev/math/lib/eigen_3.3.3` and +`~/stan-dev/math/lib/boost_1.72.0` and `~/stan-dev/math/lib/sundials_5.1.0/include` and `~/stan-dev/math/lib/tbb_2019_U8/include`. The `~/stan-dev/math/lib/tbb` directory is created by the `math-libs` -makefile target automatically. The flags `-Wl,-rpath,...` instruct the -linker to hard-code the path to the Intel TBB dynamically loaded -library inside the stan-math directory into the final binary. This way -the Intel TBB is found when executing the program. +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 +directory `/path/to/math/lib/tbb` as absolute path to the system-wide `PATH` variable. Compilers From 9da9712d0ad104c786e850f0fe1251f256b8fabd Mon Sep 17 00:00:00 2001 From: Stan Jenkins Date: Thu, 2 Apr 2020 10:18:40 -0400 Subject: [PATCH 4/7] [Jenkins] auto-formatting by clang-format version 6.0.0 (tags/google/stable/2017-11-14) --- stan/math/opencl/kernel_generator/load.hpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stan/math/opencl/kernel_generator/load.hpp b/stan/math/opencl/kernel_generator/load.hpp index 1f90d03c382..66f4fa363d6 100644 --- a/stan/math/opencl/kernel_generator/load.hpp +++ b/stan/math/opencl/kernel_generator/load.hpp @@ -49,7 +49,7 @@ class load_ * Creates a deep copy of this expression. * @return copy of \c *this */ - inline load_ deep_copy() const & { return load_(a_); } + inline load_ deep_copy() const& { return load_(a_); } inline load_ deep_copy() && { return load_(std::forward(a_)); } /** From 348c2dcedc718f7eaa7d891952596d82ffd65a21 Mon Sep 17 00:00:00 2001 From: wds15 Date: Thu, 2 Apr 2020 17:33:59 +0200 Subject: [PATCH 5/7] Update README.md spelling fix --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d01d607fc1c..8cc650c26e0 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ license](https://github.com/stan-dev/math/blob/develop/LICENSE%2Emd). 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 lincense alone. The +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 From 666d97a1494e8aa4185952f273f1825dcad8064b Mon Sep 17 00:00:00 2001 From: Stan Jenkins Date: Thu, 2 Apr 2020 15:34:49 +0000 Subject: [PATCH 6/7] [Jenkins] auto-formatting by clang-format version 5.0.0-3~16.04.1 (tags/RELEASE_500/final) --- stan/math/opencl/kernel_generator/load.hpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stan/math/opencl/kernel_generator/load.hpp b/stan/math/opencl/kernel_generator/load.hpp index 66f4fa363d6..1f90d03c382 100644 --- a/stan/math/opencl/kernel_generator/load.hpp +++ b/stan/math/opencl/kernel_generator/load.hpp @@ -49,7 +49,7 @@ class load_ * Creates a deep copy of this expression. * @return copy of \c *this */ - inline load_ deep_copy() const& { return load_(a_); } + inline load_ deep_copy() const & { return load_(a_); } inline load_ deep_copy() && { return load_(std::forward(a_)); } /** From f204168ae8eb01c69ef0322ac184d3907358d79b Mon Sep 17 00:00:00 2001 From: Sebastian Weber Date: Thu, 2 Apr 2020 18:12:50 +0200 Subject: [PATCH 7/7] revert file