Installation using CMake#

Reaktoro has several external software and library dependencies that need to be pre-installed for its successful compilation and installation using CMake. To greatly simplify the building process of Reaktoro for Linux, Windows, and macOS, you’ll need Conda.

Please follow the Conda installation steps before proceeding with the instructions below.

Attention

If you do not want to rely on Conda for facilitating the process of building Reaktoro from source, you’ll need to manually install all dependencies listed in the file environment.devenv.yml.

Installing conda-devenv#

Reaktoro relies on conda-devenv, a tool that conveniently allows us to manage different software dependencies across Linux, Windows, and macOS operating systems using a single conda dependency file environment.devenv.yml instead of multiple environment.yml files, one for each system.

After installing conda, go to a terminal and execute:

conda install -n base conda-devenv

to install conda-devenv in the base conda environment.

Downloading Reaktoro from GitHub#

We need now to download the source code of Reaktoro, which is hosted on GitHub. This can be done by either executing the following git command from the terminal (ensure you already have git installed!):

git clone https://github.com/reaktoro/reaktoro.git

or by directly downloading reaktoro-main.zip, the latest version of Reaktoro’s source code in a zip file.

Caution

If you use the direct download option above, please unzip the downloaded file in a directory of your choice. We assume the unzipped folder is named reaktoro for the next installation steps, and not reaktoro-main! If you are deloping Reaktoro, make sure you use git clone instead.

Installing Reaktoro’s software dependencies#

Before building Reaktoro, we need to install all software dependencies needed during the build process. We do not want, however, all these dependencies polluting our system and possibly causing conflicts and/or corrupting existing software.

This is achieved by installing all Reaktoro’s dependencies in a dedicated conda environment.

In the root of the reaktoro directory, execute:

conda devenv

This command will install all dependencies listed in environment.devenv.yml in a conda environment named reaktoro. This step can take a few minutes to complete for the first time.

Attention

You only need to execute conda devenv again when the list of external dependencies changes or some configuration in the conda environment reaktoro is altered.

Building and installing Reaktoro with CMake#

Before using cmake to configure, build, and install Reaktoro, you need to activate the conda environment reaktoro that the conda devenv command from the previous section created for us:

conda activate reaktoro

Attention

You need to activate the conda environment reaktoro whenever you use Reaktoro from C++ or Python! This is because conda will adjust some environment variables in your system (e.g., PYTHONPATH, LD_LIBRARY_PATH, PATH) so that Reaktoro’s libraries, executables, and Python packages can be found. Activating the reaktoro conda environment is the simplest way to get these environment variables set correctly.

You can now configure the build of Reaktoro (using default options) by executing (assuming you are at the root of the reaktoro directory!):

cmake -S . -B build

Speed up linking time in Linux and macOS

The created conda environment reaktoro on Linux and macOS should contain the LLVM linker lld which has been shown to be significantly faster than the GNU linker ld when linking Reaktoro’s C++ library, tests, examples and Python module.

To enable it, execute the following cmake configure command instead of the previous one:

cmake -S . -B build -DCMAKE_CXX_FLAGS="-fuse-ld=lld"

which specifies that Reaktoro will be built in the directory build. The actual build operation happens when you execute the command:

cmake --build build --parallel

cmake --build build --config Release --parallel

Danger

In Linux and macOS, there is a risk of your system freezing with the command above because it will use all its computing cores and demand a lot of memory. If your system is not powerful enough and/or does not have plenty of memory, you should limit the number of parallel jobs. For example,

cmake --build build --parallel 3

will use only three parallel jobs.

Note for Windows users

In Windows, if you are using Microsoft Visual Studio, you’ll need to ensure a Release build because some library dependencies in Reaktoro do not interact well with Reaktoro built in Debug mode (e.g., yaml-cpp).

This is not an issue for Linux and macOS systems.

Running Reaktoro’s tests#

Reaktoro contains hundreds of tests and thousands of assertions to ensure that everything has been implemented correctly. There are tests implemented in both C++ and Python languages.

To execute all C++ and Python tests, run:

cmake --build build --target tests

cmake --build build --config Release --target tests

You can also run the C++ and Python tests individually:

cmake --build build --target tests-cpp
cmake --build build --target tests-py

cmake --build build --config Release --target tests-cpp
cmake --build build --config Release --target tests-py

Note for Windows users

If you encounter strange issues in Windows when running the tests, and some C++ tests fail, there is a chance this is a result of an accidental Debug build in Windows instead of Release when using Microsoft Visual Studio. See previous section.

Building and running Reaktoro’s C++ examples#

Reaktoro contains many examples in C++ demonstrating its usage for various applications. These examples live in the directory examples/cpp within the root directory of Reaktoro.

To build them, execute:

cmake --build build --target examples

Note for Windows users

If you are using Microsoft Visual Studio, the command above may not work and you’ll need to build the examples by opening the Visual Studio project generated by CMake in the build directory.

You can now run individual C++ examples by executing them:

build/examples/cpp/ex-equilibrium-fixed-ph

Running Reaktoro’s Python examples#

Reaktoro also contains many examples written in Python that can be found in the directory examples/python within the root directory of Reaktoro’s source code.

Before we can execute them from the terminal, we need to set the PYTHONPATH environment variable so that the reaktoro Python package can be found. From the root directory, execute:

source build/envs

build\envs4release.bat

This command should output a message indicating the new value of changed environment variables, such as PYTHONPATH and PATH (in Windows) or LD_LIBRARY_PATH (in Linux and macOS).

We are now able to execute individual Reaktoro examples written in Python as follows (ensure you are in the root directory of Reaktoro’s source code!):

python examples/python/ex-beginner-equilibrium-phreeqc.py

python examples\python\ex-beginner-equilibrium-phreeqc.py

Installing Reaktoro after it has been built#

You may want to install Reaktoro in a directory of your choice after building it with cmake. You can do so by first specifying where to install:

cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/home/username/wherever

cmake -S . -B build -DCMAKE_INSTALL_PREFIX=C:\Users\Username\Wherever

and then executing the install target:

cmake --build build --target install

cmake --build build --config Release --target install

This step will install Reaktoro’s C++ header files, libraries, executables, and the Python package reaktoro in the specified installation path.

Please help me installing Reaktoro!#

If you have problems with the instructions above and after investigating the problem even more, you couldn’t find a solution (for example, it might just be a common cmake problem for which there is already a solution on the internet), please contact us.