Installation ============ .. image:: https://img.shields.io/badge/Reaktoro%20Tutorial-Interactive!-E66581.svg?logo=data:image/png;base64,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 :target: https://mybinder.org/v2/gh/reaktoro/reaktoro-jupyter/master?filepath=tutorial%2Foverview.ipynb .. warning:: Make sure you install Reaktoro v1.2.3+ by using ``conda install reaktoro=1`` below. If you install Reaktoro v2.0, the examples from Reaktoro v1 will not work. Reaktoro v2.0 will soon become documented here, but at the moment, you really need to ensure that you are installing v1.2.3+! There are many ways for installing Reaktoro, from a simple single-line terminal command to building the entire project from sources. All current possibilities are detailed below. Installation using Conda ------------------------ Reaktoro can be easily installed using `Conda`_, a powerfull package manager used to simplify Reaktoro's installation and the management of its external software dependencies. Once you install Conda, and append the necessary channels, you'll be able to install Reaktoro by just executing the following command in your terminal: .. code:: conda install reaktoro=1 .. _Anaconda: https://www.anaconda.com/download .. _Miniconda: https://conda.io/miniconda.html Follow the Conda installation steps shown next before you execute this command! .. note:: The reason for specifying a v1.x version of ``reaktoro`` in ``conda install reaktoro=1`` is because there are at the moment candidate releases for v2.0 of Reaktoro. This version has not been documented yet, but it will soon. Installing Conda ^^^^^^^^^^^^^^^^ Conda can be installed by installing either Anaconda_ or Miniconda_. We recommend the installation of Miniconda, unless you already have Anaconda installed or you think you need 1,400+ software packages that ship with it! Miniconda is just a tiny subset of Anaconda containing only our needed ``conda`` application and its dependencies. Download the **Miniconda Installer** by clicking on the image below: .. figure:: img/logos/conda-logo.svg :figwidth: 80% :width: 80% :align: center :target: Miniconda_ Reaktoro is a proud user of Conda, a powerfull and modern package manager! You'll be given options to install `Miniconda`_ for Windows, Mac OS X, and Linux (32-bit or 64-bit) using either Python 3.7 or Python 2.7. We recommend a **64-bit installer** of Miniconda with **Python 3.7**. Adding conda-forge channels ^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Reaktoro pre-built package is hosted on `conda-forge `_. After installing Miniconda, go to a terminal and execute: .. code:: conda config --append channels conda-forge to add the conda-forge channels required to find the Reaktoro package. All should now be set to install Reaktoro using: .. code:: conda install reaktoro=1 Go to `Reporting a failed installation`_ if this does not work for you. Installation using CMake ------------------------ Reaktoro has several 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 Windows, Mac OS X, and Linux, you'll need `Conda`_. Follow the Conda installation steps in the previous section, in which a Miniconda installer is used. After installing Miniconda, go to a terminal and execute: .. code:: conda install -n base conda-devenv This installs `conda-devenv`_, a conda tool with convenient functionalities to define and initialize conda environments. 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 (if you already have git installed!): .. code:: bash git clone https://github.com/reaktoro/reaktoro.git .. |master.zip| replace:: :download:`reaktoro-master.zip` or by directly downloading |master.zip|, the latest version of Reaktoro's source code in a zip file. .. note:: 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-master``. Creating a conda environment for Reaktoro ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The next step is to create a **conda environment** that contains all the software and library dependencies needed to build Reaktoro. In the root of the reaktoro directory, execute: .. code:: bash conda devenv This command will create the conda environment called ``reaktoro``, which 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. .. note:: If you are curious about the list of dependencies needed to build Reaktoro, have a look at the file :download:`environment.devenv.yml <../../environment.devenv.yml>` in the root directory of Reaktoro's source code. This file is a *recipe* for the creation of our conda environment ``reaktoro`` containing all required dependencies. Activating the conda environment for Reaktoro ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The next step is to **activate the conda environment** ``reaktoro`` that conda-devenv_ created for us: .. code:: conda activate reaktoro .. attention:: You need to activate the ``reaktoro`` conda environment 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. Building and installing Reaktoro with CMake ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can now build and install Reaktoro by executing the following from the root of the reaktoro source directory: .. code:: cmake -P install Assuming the conda environment ``reaktoro`` is active, this command will first build Reaktoro and then install its header files, libraries, executables, Python package in your local *miniconda* directory: :Linux: ``/home/user/miniconda3/envs/reaktoro/`` :Windows: ``C:\miniconda3\envs\reaktoro\`` Alternatively, to build and install Reaktoro in a more traditional way, execute the following from the root directory of Reaktoro's source code: .. code:: mkdir build cd build cmake .. cmake --build . --target install The following is also possible with CMake v3.13 or newer: .. code:: cmake -S . -B build cmake --build build/ --target install .. tip:: Compiling the Reaktoro C++ library and the Reaktoro Python module should take a few minutes for the first time. However, if you activate the reaktoro conda environment, `ccache `_ will be used to significantly speed up future compilations automatically for you! Installing Reaktoro in a custom directory ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To install Reaktoro in a different directory, say, ``/home/user/other``, use: .. code:: cmake -DPREFIX=/home/user/other -P install or .. code:: bash cmake .. -DCMAKE_INSTALL_PREFIX=/home/user/other cmake --build . --target install You'll need, however, to set the environment variables ``PYTHONPATH``, ``LD_LIBRARY_PATH``, and ``PATH`` yourself. For example, in Linux: .. code-block:: bash export PATH=$PATH:/home/user/other/bin export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/other/lib{64} export PYTHONPATH=$PYTHONPATH:/home/user/other/lib{64}/pythonX.Y/site-packages where ``lib{64}`` is either ``lib`` or ``lib64``, and ``pythonX.Y`` where ``pythonX.Y`` depends on the python version used to compile Reaktoro's Python package (e.g., ``python3.6``, ``python3.7``). Checking for a successful installation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Check if Reaktoro was installed correctly by executing: .. code:: bash python -c 'import reaktoro; print(reaktoro.__path__[0])' This should print the path to the installed python package ``reaktoro``. For example: .. code:: bash /home/user/miniconda3/envs/reaktoro/lib/pythonX.Y/site-packages/reaktoro where ``pythonX.Y`` above depends on the python version used. .. attention:: Make sure you have the conda environment ``reaktoro`` active! Otherwise the checking above might not work without further actions (e.g., changing the ``PYTHONPATH`` environment variable). If you get instead something like: .. code:: bash Traceback (most recent call last): File "", line 1, in ModuleNotFoundError: No module named 'reaktoro' then the installation was not successful or it was installed in a custom path that is not yet given in the ``PYTHONPATH`` environment variable. Reporting a failed installation ------------------------------- .. warning:: Please double check you have installed Reaktoro v1.2.3+ and not v2.0.0rc5+. A failed installation can be a frustating emotion, but we will be happy to help you fixing your installation issue. However, please **do make sure** you followed exactly the steps given before. If you are sure that you followed every single instruction and the installation still fails, please go to: .. centered:: `Reaktoro's GitHub Issues`_ and let us know! .. _CMake: https://cmake.org/ .. _conda-devenv: https://github.com/ESSS/conda-devenv .. _Conda: https://conda.io/docs/ .. _git: https://git-scm.com/ .. _GitHub: https://github.com/reaktoro/reaktoro .. _Reaktoro's GitHub Issues: https://github.com/reaktoro/Reaktoro/issues/new