Installation

O2scl

Installation Contents

General notes

O₂scl requires Boost, GSL, libquadmath, and the HDF5 libraries (the precise procedure for installing these libraries differs from system to system, but some common cases and useful information is given below). O₂scl is designed to be used with the most recent release version of all of these libraries, but is sometimes compatible with recent older versions. The configure script attempts to add these libraries to LIBS and LDFLAGS during the installation of O₂scl. In order to compile your code with O₂scl, you will need to include, e.g. -lo2scl -lhdf5 -lgsl -lgslcblas -lquadmath -lm, and you may need to include -I flags for O₂scl headers and -L flags for O₂scl libraries. The sections below describe several different ways of installing O₂scl.

It is important to ensure that O₂scl is compiled with the same version of the HDF5 libraries that it is linked with when compiling code based on O₂scl. In order to help resolve these version conflicts, the acol utility (see The acol Command Line Utility) reports the two different HDF5 versions (see acol -v) so that it is easy to check that they are the same.

Compiling O₂scl from a release distribution

O₂scl installation is generally similar to that for GNU-style libraries. The file INSTALL has some details on this procedure. Once the dependencies are installed you should be able to run ./configure and then type make and make install. More information on the configure command can also be obtained from ./configure --help. On some systems, you may have to add additional flag to the CXXFLAGS environment variable manually before the ./configure script. The documentation is included in the O₂scl release distribution and automatically installed by make install.

Note

If you are trying to install O₂scl with a version of HDF5 earlier than 1.12 you will need to compile with -DO2SCL_HDF5_PRE_1_12.

O₂scl requires the Boost (v1.80.0 or later) and the GSL libraries (version 2.0 or later). If the configure script cannot find Boost or GSL, you may have to specify their location for the associated header files in the CXXFLAGS variable and the associated libraries in the LDFLAGS environment variable. Running ./configure --help shows some information on this. For example, in a bash shell, you could do something like:

CXX="g++" CXXFLAGS="-I/dir/to/gsl/include" LDFLAGS="-L/dir/to/gsl/libs" ./configure --prefix=="/dir/to/destination_directory

Along with GSL, a CBLAS library is also required, and ./configure will look for libcblas first, and if not found then it will look for libgslcblas. If neither is present, then you may have to manually specify a CBLAS library using the LIBS and LDFLAGS environment variables.

Compiling with the readline library is optional, but it is assumed to be present by default.

After make install, you may test the library with make check or make o2scl-test. At the end, the phrase "All O2scl tests passed" indicates that the testing was successful. You may also run make o2scl-test in the individual subdirectories of the src directory to individually test the classes and functions in that part of O₂scl. After installation, running acol -v will output several of the installation settings.

Compiling O₂scl from a release on Linux

For example, to install O₂scl on Ubuntu, begin by installing g++ and make (the g++ and make packages), GSL (the libgsl-dev package), Boost (the libboost-all-dev package), GNU readline (the libreadline-dev package), HDF5 (the libhdf5-dev package), and quadmath (the libquadmath0 package). You can then install O₂scl from one of the release distributions by using the standard GNU ./configure script and then invoking make and make install (which often requires sudo).

The HDF5 package for Ubuntu and many other Linux systems is installed in hdf5/serial/hdf5.h instead of hdf5.h, so O₂scl presumes that Linux systems are arranged that way. If HDF5 include statements should not have the hdf5/serial/ prefix, then you can use -DO2SCL_HDF5_PLAIN_HEADER, i.e.:

CXXFLAGS="-DO2SCL_PLAIN_HDF5_HEADER" ./configure

to instruct O₂scl to look for them there (for example, on bridges at the PSC). On many systems, one can use a parallel HDF5 library using -DO2SCL_HDF5_PLAIN_HEADER and a -I option to select the proper location for the parallel HDF5 header files. Finally, if your version of HDF5 is earlier than 1.12, you will need to let O₂scl know, using:

CXXFLAGS="-DO2SCL_HDF5_PRE_1_12" ./configure

Other Linux distributions are similar. For example, in OpenSUSE, you will need to use zypper to install gcc-c++, make, gsl-devel, hdf5-devel, readline-devel, libquadmath0, and boost-devel.

Note that if your boost installation is earlier than 1.70, you will need to use the -DO2SCL_OLD_BOOST flag to get all of the tests to run successfully.

Compiling O₂scl from the source code

If you want to install from source (without generating the documentation), then you must first install g++, make, automake, autoconf, and libtool packages. You also need to install all the dependencies described above (see, e.g. the section Compiling O₂scl from a release on Linux). Then you can use something along the lines of:

git clone https://github.com/awsteiner/o2scl
cd o2scl
autoreconf -i
./configure

Then, you will either need to generate the documentation from doxygen using make o2scl-doc or use make blank-doc to create blank documentation. Then you can proceed using make and make install (which may require sudo depending on your configuration). For a full installation with parallelism, I typically also install libopenmpi-dev and then use ./configure --enable-openmp

Docker images for O₂scl

There are a few docker images for recent versions of O₂scl available at https://hub.docker.com/r/awsteiner/o2scl . These images are based on the docker files which are stored in the docker subdirectory, and can be found at https://github.com/awsteiner/o2scl/tree/main/docker .

Python support

O₂scl can be compiled with python support by providing the option --enable-python when the library is configured. This may also require adjusting CXXFLAGS and LDFLAGS in order to ensure the Python headers and libraries can be found. O₂scl code which uses Python also assumes that numpy was installed, so the headers for the numpy package may need to be specified. For example, using g++ on MacOS may need something of the form:

CXX="g++-13"
CXXFLAGS="-I/usr/local/lib/python3.11/site-packages/numpy/core/include
`python3-config --includes`" LDFLAGS="`python3-config --ldflags`"
./configure --enable-python

Including Python support also requires the installation of O₂sclpy (for example, using c pip) to ensure that the tests pass successfully. Thus, when including Python support it is best to install O₂scl first, install O₂sclpy second, and then test O₂scl and O₂sclpy last. See also Python Integration for more details.

Some of the docker images available at https://hub.docker.com/r/awsteiner/o2scl include an installation of O₂sclpy and O₂scl with Python support.

Optional linear algebra libraries

O₂scl is fully functional without any additional linear algebra libraries. However, many classes and functions which require linear algebra are faster with either the Eigen (http://eigen.tuxfamily.org) or Armadillo (http://arma.sourceforge.net) libraries. Support for these can be specified in the configure command with --enable-armadillo or --enable-eigen. These libraries may require additional -I or -L flags to be defined when O₂scl is installed, depending on how your particular system is configured. For example, O₂scl classes which use Armadillo use matrix decompositions so Armadillo must be compiled with LAPACK support, and you may need to specify the location of the LAPACK libraries manually.

Other optional libraries

As with the linear algebra libraries, these libraries may require additional -I or -L flags to be defined when O₂scl is installed, depending on how your particular system is configured. The configure script should automatically add -l<library name> to LDFLAGS during installation, but you will need to also add this flag to your codes which use O₂scl.

Readline support (-lreadline): The command-line interface class cli, and acol (see The acol Command Line Utility) can both take advantage of readline support. If the library is configured with --disable-readline, then the readline library is not used.

OpenMP support (typically involves the -fopenmp compiler flag): O₂scl contains a few functions which use multiple threads for faster execution. This support can be included using the -enable-openmp option to the configure script. On some systems, this will also include explicitly specifying the OpenMP libraries in the LDFLAGS environment variable. See more information in Parallel Programming with O2scl.

FFTW support (-lfftw3): O₂scl contains a few functions which require FFTW support, and this can be included if --enable-fftw is passed to the configure script.

Module support, curses support, cubature support, and pugixml support are all experimental and not currently supported.

Range-checking

Some extra range-checking for vectors and matrices is turned on by default. You can disable range-checking by defining -DO2SCL_NO_RANGE_CHECK, e.g.:

CXXFLAGS="-DO2SCL_NO_RANGE_CHECK" ./configure

More configure flags

There are several warning flags that are useful when configuring and compiling with O₂scl. See the GSL documentation for an excellent discussion, and also see the generic installation documentation in the file INSTALL in the O₂scl top-level directory. For running configure, for example, if you do not have privileges to write to /usr/local:

CPPFLAGS="-O3 -I/home/asteiner/install/include" \
LDFLAGS="-L/home/asteiner/install/lib" ./configure \
--prefix=/home/asteiner/install

In this example, specifying -I/home/asteiner/install/include and -L/home/asteiner/install/lib above ensures that the GSL libraries can be found. The --prefix=/home/asteiner/install argument to ./configure ensures that O₂scl is installed there as well.

Generation of documentation

The O₂scl documentation is included in every release tarball. It can also be generated by the user, but this is not supported. Generating the documentation requires doxygen, sphinx, breathe, alabaster, pugixml and other external applications not included in the distribution.

The most recent release documentation is available at https://awsteiner.org/code/o2scl/html/index.html and the current development version documentation is available at https://awsteiner.org/code/o2scl-dev/html/index.html . The documentation for previous releases is not on the web, but is still stored in the release .tar.gz file.

Uninstallation

While there is no explicit “uninstall” makefile target, there are only a couple places to check. Installation creates directories named o2scl in the include, doc and shared files directory (which default to /usr/local/include, /usr/local/share/doc/, and /usr/local/share) which can be removed. The acol command-line utility is installed to /usr/local/bin . Finally, all of the libraries are named with the prefix libo2scl and are created by default in /usr/local/lib.