A unified framework for modeling chemically reactive systems

In the steps below we show how one can download Reaktoro, build, and install it in Linux and MacOS systems. Note that compiling Reaktoro can take some time. This is because it heavily relies on template metaprogramming for efficient vector and matrix calculations, as well as for calculation of partial derivatives of most thermodynamic properties, such as activity coefficients, phase molar volumes, standard Gibbs energies, etc. In addition, it will also compile several third-party libraries, such as CVODE for efficient solution of ordinary differential equations (ODE), and the geochemical codes PHREEQC and GEMS. Compilation of the Python wrappers can also take several minutes, as Boost.Python too relies on template metaprogramming.

Downloading the source code

Reaktoro's source code is kept in a Bitbucket repository. If you have git installed in your system, then downloading this repository is as easy as running the following command in a terminal:

git clone Reaktoro

Alternatively, you can access this link to directly download Reaktoro source code as a zipped file. If you choose this option, unzip the file before proceeding to the next step.

Installing the dependencies

Reaktoro has a few dependencies that need to be installed before it can be built. If you plan to compile only its C++ libraries, all you will need is CMake, which is used for managing and automating the whole build process, including the installation of third party libraries. The table below describes how to install CMake from the terminal in some Linux distributions:

OS Command
Ubuntu sudo apt-get install cmake
Fedora sudo yum install cmake
Arch Linux pacman -Ss cmake

Optionally, you might want to install Gnuplot if you intend to do real-time plotting of the chemical calculations.

OS Command
Ubuntu sudo apt-get install gnuplot5 gnuplot5-qt
Fedora sudo yum install gnuplot gnuplot-qt
Arch Linux pacman -Ss gnuplot

Check if a plot is successfuly output to a window terminal by issuing the command:

gnuplot -persist -e 'plot sin(x)'

If a window did not show up with an interactive plot, you might need to install a different package other than gnuplot-qt. Check your distribution, or install Gnuplot from source.

If you plan to use Reaktoro from Python, then a few more dependencies are needed to compile the Python wrappers of Reaktoro's C++ classes and methods. If you just want the C++ libraries, you can skip this and go to the next section.

Boost.Python is used to generate the Python wrappers for the C++ Reaktoro's interface. Thus, install Boost as follows:

OS Command
Ubuntu sudo apt-get install libboost-python-dev
Fedora sudo yum install boost boost-devel
Arch Linux pacman -Ss boost boost-libs py++

You will also need to install Python libraries and some Python packages such as Numpy. Because Boost.Python in most Linux systems has been compiled using Python 2.x, and not Python 3.x, we need to install Python 2.x packages:

OS Command
Ubuntu sudo apt-get install python python-dev python-numpy python-pip
Fedora sudo yum install boost boost-devel python-numpy
Arch Linux pacman -Ss python2 python2-numpy

In addition, if you also plan on building Reaktoro interpreter application, then install the following additional Python packages:

OS Command
Ubuntu sudo pip install pyinstaller tabulate
Fedora sudo pip install pyinstaller tabulate
Arch Linux pip install pyinstaller tabulate
If some of the instructions above is incomplete or inaccurate for your system's version, please get in touch.

Compiling the C++ library

Here we show how to compile only the C++ part of Reaktoro. Its Python interface is an optional component of the project, and its compilation and installation is shown in the next section.

Once CMake has been installed, go inside the directory of the downloaded Reaktoro source code. In the terminal, execute the following commands for an out-of-source build approach:

mkdir build
cd build
cmake ..

The commands above create a directory called build, where all files generated by CMake during the compilation will be saved. The command cmake .. tells CMake to configure the build process based on the main CMakeLists.txt file in the root directory of Reaktoro's source code. Finally, make compiles Reaktoro's source code.

Your system might have several threads that could be used for parallel compilation. To use three threads in a dual-core processor, use instead make -j3. To use all available threads in your processor, execute make -j.

Be careful, as the use of all available threads when compiling Reaktoro can freeze your machine! Leaving one thread idle can avoid this.

For a global installation of the compiled libraries in your system, execute:

make install

This will install Reaktoro's header files and libraries in the default installation directory of your system (e.g, /usr/local/ or /opt/local/). Note that this installation mode might require administrator rights, so that you would need to execute sudo make install instead.

For a local installation, you can specify a directory path for the installed files as:

cmake .. -DCMAKE_INSTALL_PREFIX=/home/username/local/
make install

The above call to cmake will reconfigure the build process, but it will not require recompilation if Reaktoro's libraries have already been compiled.

Compiling the Python interface

Most C++ classes and methods in Reaktoro are accessible from Python. To use its Python interface, Python wrappers to these C++ components must be compiled. These wrappers are generated using Boost.Python, so ensure your system has Boost installed. Read here for instructions.

To build the Python wrappers, the CMake option -DBUILD_PYTHON=ON must be provided to the CMake command that configures the build process:

If you have already compiled the C++ libraries, this will cause them to be recompiled. Thus, if you plan to build both C++ libraries and Python wrappers, it is advised to use the -DBUILD_PYTHON=ON option before the first call to make.

After compilation, you should find the shared library PyReaktoro inside the directory lib in the build directory. This library is also a Python module, which can be imported from Python as:

from reaktoro import *

Compiling the C++ demos

There are several demos of how to use Reaktoro in the directory demos inside the root directory of Reaktoro's source code. To build these demos, you can either execute:

make demos

or use the cmake option -DBUILD_DEMOS=ON as in:


to automatically build the demos with a call to make. Once the demos are compiled, they can be found in the directory bin of the build directory. To run them from the terminal in a Unix system, go to the bin directory and execute:


where demo-equilibrium-co2-brine is the name of a demo application in the bin directory.