Installation

Depending on what you plan to do with xtb-python there are two recommended ways to install.

If you plan to use this project in your workflows, proceed with the Installation with Conda. If you plan to develop on this project, proceed with Building from Source.

For the basic functionalities the xtb-python project requires following packages:

cffi
numpy

Additionally the project provides a calculator implementation for ASE (see Atomic Simulation Environment) which becomes available if the ase package is installed. For integration with the QCArchive infrastructure (see QCSchema Integration) the qcelemental package is required.

Of course, the package depends on the extended tight binding program package as well, directly or indirectly. Depending on how xtb-python was packaged it requires an installation of xtb or it will be able to provide its own. For more details on the xtb API dependency see Building from Source.

Installation with Conda

For details on how to setup conda look up the conda documentation.

Installing xtb-python from the conda-forge channel can be achieved by adding conda-forge to your channels with:

conda config --add channels conda-forge

Once the conda-forge channel has been enabled, xtb-python can be installed with:

conda install xtb-python

It is possible to list all of the versions of xtb-python available on your platform with:

conda search xtb-python --channel conda-forge

To install the additional dependencies for ASE and QCArchive integration use

conda install qcelemental ase

Building from Source

To install xtb-python from source clone the repository from GitHub with

git clone https://github.com/grimme-lab/xtb-python
cd xtb-python
git submodule update --init

This will ensure that you have access to the xtb-python and the parent xtb repository, with the latter to be found in subprojects/xtb.

Building the Extension Module

To work with xtb-python it is necessary to build the extension to the xtb API first, this is accomplised by using meson and the C foreign function interface (CFFI). Following modules should be available to build this project:

cffi
numpy
meson  # build only

To install the meson build system first check your package manager for an up-to-date meson version, usually this will also install ninja as dependency. Alternatively, you can install the latest version of meson and ninja with pip (or pip3 depending on your system):

pip install cffi numpy meson ninja

If you prefer conda as a package manage you can install meson and ninja from the conda-forge channel. Make sure to select the conda-forge channel for searching packages.

conda config --add channels conda-forge
conda install cffi numpy meson ninja

Now, setup the project by building the CFFI extension module from the xtb API with:

meson setup build --prefix=$PWD --default-library=shared
ninja -C build install

This step will create the CFFI extension _libxtb and place it in the xtb directory.

Meson cannot find xtb dependency

If meson cannot find your xtb installation check if you have pkg-config installed and that xtb can be found using

pkg-config xtb --print-errors

In case this fails ensure that the xtb.pc file is in a directory in the PKG_CONFIG_PATH and retry. For the official release tarball you possible have to edit the first line of xtb.pc to point to the location where you installed xtb:

--- a/lib/pkgconfig/xtb.pc
+++ b/lib/pkgconfig/xtb.pc
@@ -1,4 +1,4 @@
-prefix=/
+prefix=/absolute/path/to/xtb
 libdir=${prefix}/lib
 includedir=${prefix}/include/xtb

Note

Installs from conda-forge should work out-of-box.

Dealing with Several Versions of Python

If you have several versions of Python installed you can point meson with the -Dpy=<version> option to the correct one. Depending on your setup you have to export your compilers (CC and FC) first and set the -Dla_backend=<name> and -Dopenmp=<bool> option accordingly.

Installing in Development Mode

After creating the _libxtb extension, the Python module can be installed as usual with

pip install -e .

Now you are set to start using xtb-python. You can test your setup by opening a new Python interpreter and try to import the interface module

>>> import xtb.interface

If you also want to use extensions install with

pip install -e '.[ase,qcschema]'

Now you can test your installation with

pytest --pyargs xtb

Helpful Tools

We aim for a high quality code base and encourage substainable development models.

Please, install a linter like flake8 or pylint to catch errors before they become bugs. Also, typehints are mandatory in this project, you should typecheck locally with mypy. A consistent coding style is enforced by using black, every source file should be reformatted using black, the only exceptions are tests.

Building without Upstream Dependency

For convenience we also offer a mode to work without an upstream xtb dependency, this can be quite handy if you also want to work on the xtb API itself or want to create a failsafe package that cannot break due to ABI or API incompatibilities.

Note

It is highly recommend to make yourself familiar with building xtb first.

For this approach we follow the same scheme as with the normal extension build. You will need the following packages installed

cffi
numpy
meson  # build only

Additionally you will need a development version of Python, for the Python headers, a Fortran and a C compiler (GCC 7 or newer or Intel 17 or newer) and a linear algebra backend (providing LAPACK and BLAS API).

We closely follow the approach from before, but we change the configuration of the extension build to

meson setup build --prefix=$PWD --default-library=static
ninja -C build install

Depending on how you acquired the project mesons wrap-tool will first need to download the xtb source code. Instead of dynamically depending on xtb the complete project will be build and included as a whole into the CFFI extension module, making your xtb-python effectively independent of xtb.

You can pass the -Dopenmp=<bool> and -Dla_backend=<netlib|openblas|mkl> in the configuration step to configure the xtb build. To change the compiler used export them in the environment variables CC and FC.

Tip

For more information on the build with meson, follow the guide in the xtb repository here.

From here you can proceed with Installing in Development Mode.