Installation

FastChem can be installed in three different ways: using CMake, using the setup.py script, or via the Python Package Index PyPI. The CMake approach 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 or PyPI will be integrated into your standard Python library and, thus, work as a normal Python package.

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 simply be cloned with

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

Prerequisites

FastChem is written in C++. It uses features of the C++17 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.12

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.

An installation of pyFastChem from source via 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

  • 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 uses plain C++ without any external libraries, any compiler that supports the C++17 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 be 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 compilation. 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 navigate to it:
mkdir build
cd build

For a basic installation, run CMake from within this folder:

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. On macOS, Apple’s Clang compiler does not ship with OpenMP support by default. To enable it, install libomp via Homebrew:

brew install libomp

CMake and the Python build system will automatically detect and use it.

After CMake has 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

Previous versions of FastChem relied on long double (quadruple) precision for convergence at low temperatures. Since Apple Silicon (Mx) processors have no hardware support for quadruple-precision arithmetic, this caused convergence issues on these machines. The current version of FastChem has been redesigned to work fully in double precision, resolving this limitation.

FastChem can be compiled and run on macOS, but requires some libraries and tools that are not installed by default. This especially includes CMake. In order to compile FastChem on macOS, 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. For OpenMP support, installing libomp via brew install libomp is sufficient — no alternative compiler is needed.

If the Python interface of FastChem is used, a Python 3 installation is also required. By default, macOS ships only with an outdated Python 2 version that cannot be used with FastChem. A more up-to-date version can also be installed via, for example, brew. However, one has to make sure that the python3 executable and pip3 (to install other required Python modules) actually point 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 at https://github.com/pyenv/pyenv.

Notes on Windows

While in theory FastChem could be run on Windows provided all the prerequisites are met, we have never tested its compilation and execution 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 newer versions of Windows 10. However, due to the lack of a Windows system, we are unable to test this and, therefore, cannot officially support FastChem 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 install the pyFastChem package and resolve any dependencies. Note, however, that you will still need 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 requires 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. On macOS, install libomp via brew install libomp before building to enable OpenMP support.