Installation

FastChem can be installed in three different ways: either using CMake, by calling a Python setup function setup.py or by using the Python Package Index PyPI. The former will install the C++ stand-alone executable and optionally the Python module, while the latter two will only provide the pyFastChem Python module. The Python module created by CMake will only be available locally in the python directory, while the one produced by setup.py will be integrated in your standard Python library and, thus, work as a normal Python package. Additionally, we also support a Python installation via PyPI, the Python Package Index.

Obtaining the code

FastChem is hosted on the NewStrangeWorlds GitHub page: https://github.com/newstrangeworlds/fastchem. If git is available on a computer, the repository can be simply cloned with

git clone https://github.com/newstrangeworlds/fastchem

Prerequisites

FastChem is written in C++. It uses features of the C++11 standard and, therefore, requires a compiler that implements this standard. We also provide an optional Python interface, allowing FastChem to be called directly from within a Python script. The interface is based on the Python package PyBind11.

Prerequisites for installation via CMake

The complete list of prerequisites for a basic CMake installation is:

• a C++ compiler (e.g. g++ or Clang on MacOS)

• CMake, at least version 3.10

The C++ compiler will be detected by the CMake script when it generates the makefiles. For some of its optional components FastChem will need:

• an OpenMP library (to run FastChem in parallel)

• a Python 3.x interpreter (for the Python interface)

Prerequisites for Python installation via setup.py or PyPI

The PyPI repository of pyFastChem includes binary wheels for many platforms, such as Linux, MacOS, and Windows and supports several different versions of Python. If no binary wheel for your system is available, pip will need to compile the package from source.

For an installation of pyFastChem from source with the setup.py script or PyPI requires

• a Python 3.x interpreter

• a C++ compiler (e.g. g++ or Clang on MacOS)

• an OpenMP library (optional, required to run FastChem in parallel)

• pip (when using PyPI)

as well as the following Python modules:

• PyBind11

• setuptools

• distutils

• glob

• tempfile

Supported C++ compilers

The compilation of FastChem has been tested on a variety of different compilers and platforms. In particular, it was verified that FastChem can be compiled with:

• GCC 7.5 or newer

• Clang 12.0 (including Apple’s Clang 12.0)

Since FastChem just uses plain C++ without any external library, any compiler that supports the C++11 standard should be able to compile the code successfully.

PyBind11 Library

For its Python interface, FastChem requires the PyBind11 library that translates the Python calls into C++. While PyBind11 can in theory be installed via pip, conda, or brew (on MacOS), CMake is not always able to properly locate the installed library.

For the installation via CMake, we therefore chose to include PyBind11 as a submodule in the FastChem repository. CMake will take header files and Python scripts provided by the submodule to create the PyFastChem module. No separate compilation or installation of PyBind11 is required. During the setup stage, CMake will download the PyBind11 library automatically. This code will be placed into a separate _deps folder.

If you choose to install pyFastChem via the setup.py function, then the PyBind11 library has to already present in your local Python installation.

Configuration and compilation with CMake

Before FastChem can be compiled, CMake is required to configure the compilation files, locate libraries, and write the makefiles that will perform the actual compilations. If required libraries are missing, CMake will report a corresponding error message. In this case, the missing libraries or compilers need to be installed before the configuration can be completed.

To run the CMake configuration, first create the build folder inside the FastChem source code folder and switch to the folder:

mkdir build
cd build

For a basic installation, within the folder run CMake:

cmake ..

If the Python interface should be installed as well, run

cmake -DUSE_PYTHON=ON ..

CMake will also try to locate an OpenMP library to allow FastChem to be run in parallel. If it cannot detect the library, only the single-core version of FastChem will be compiled. If FastChem is to be run on MacOS, using OpenMP might be difficult since Apple’s Clang compiler does not directly support OpenMP, even if the corresponding library has been installed. It might be possible, though, to install an alternative compiler, for example g++, that supports the use of OpenMP.

After CMake successfully configured the compilation files, FastChem can be compiled by running:

make

Upon successful compilation, the executable fastchem should be present in the main FastChem folder. If the optional Python interface is used, FastChem will be automatically compiled twice because the Python version requires different compiler options.

Notes on MacOS

Newer Apple computers contain an ARM-based processor (a.k.a. Apple Silicon, Mx), which is not compatible with the x86 architecture used by many other Linux and Windows machines. This ARM processor has no hardware support for quadruple-precision numbers that are used in FastChem. Consequently, FastChem will run only with double-precision on these computers, which will cause convergence issues at lower temperatures. Since this is a hardware limitation of the Apple Silicon chip, there is no way to change this behavior within FastChem.

FastChem can be compiled and run on MacOS, but requires some libraries and apps that are not installed by default. This especially includes CMake. In order to compile FastChem on MacOS, the the prerequisites listed above need to be installed. This can be easily achieved by, for example, using brew.

In a standard installation of MacOS, no compiler is available. The Apple version of the Clang compiler can be installed through Xcode and the command line tools by running

xcode-select --install

in the terminal.

Alternatives (e.g. g++) to the default Clang shipped with MacOS can also be installed via brew. However, CMake is not always able to detect these compilers and will still use Clang. This also applies to the optional OpenMP library that allows FastChem to be run in parallel. The Clang compiler does not directly support the library, even if it has been installed via brew.

If the Python interface of FastChem is used, a corresponding Python 3 installation is also required. By default, MacOS ships only with an outdated Python 2 version that cannot be used for FastChem. A more up-to-date version can also be installed by, for example, brew. However, one has to make sure that the python3 executable and things like pip3 (to install other required Python modules) actually link to that version. An alternative way to install and manage different versions of Python without interference from MacOS’ internal Python version is pyenv, which can be found under https://github.com/pyenv/pyenv.

Notes on Windows

While in theory FastChem could be run on Windows if meeting all the prerequisites, we have never tested the compilation and execution of FastChem on such a system. In principle, this should be possible under a virtual Linux environment, such as cygwin, or with the Windows Subsystem for Linux (WSL) shipped with the newer versions of Windows 10. However, due to the lack of a Windows system, we are unable to test this and, therefore, officially at least we cannot support FastChem running on Windows.

Installation of pyFastChem with Python

When setting up pyFastChem with PyPI, it is installed via pip:

pip install pyfastchem

Depending on the Python installation, pip might need to be replaced by pip3 in case pip is linked to Python 2.x.

This command will download and compile the pyFastChem package and resolve potential dependencies. It is important to note, though, that one still has to download the chemistry input data and other Python scripts from the FastChem repository in order to use the package properly.

The PyPI repository of pyFastChem includes binary wheels for most platforms, such as Linux, MacOS, and Windows and supports several different versions of Python. If no binary wheel for your system is available, pip will try to compile the package from source. This will require a working compiler and the necessary Python development headers.

As an alternative, pyFastChem can also be directly installed from source via the setup.py script located in the root directory of FastChem. The setup is started by

python setup.py install

assuming that python points to your Python 3.x executable. Otherwise, replace python with python3. As discussed above, using setup.py will only create the Python module of FastChem, not the stand-alone executable.

In both cases, the pyFastChem module itself will be installed in your local Python package library path and, thus, be available throughout your system like any other normal Python package. The module’s location and additional module information can be obtained via

pip show pyfastchem

The setup script will also try to detect the presence of compiler support for OpenMP to run FastChem calculations in parallel. This is currently likely to fail in case of MacOS since Apple’s Clang compiler officially does not support this library. We might adapt the setup.py script in the future to allow for alternative compilers under MacOS.