Installation

Metatensor is available for multiple programming languages, and how to install and use it will depend on the programming language you are using.

Metatensor is split into multiple Python packages, each providing a subset of the functionality in a modular way. Most users will want to install all the packages, but installing individual packages is also supported.

The simplest way to install metatensor is to use pip, and run the following commands:

# Make sure you are using the latest version of pip
pip install --upgrade pip

pip install metatensor

This will install the metatensor package, as well as metatensor-core, metatensor-operations and metatensor-learn. We provide pre-built version of metatensor-core for Linux (x64), Windows (x64) and macOS (x64 and ARM64). The other packages are pure Python package that should install on any operating system.

You can install any of these sub-packages one by one with

pip install metatensor-core
pip install metatensor-operations
pip install metatensor-learn

TorchScript integration: If you also want to use the TorchScript bindings to metatensor, use this instead (see this page for more information).

pip install metatensor[torch]

The main classes of metatensor are available from C and C++, and can be installed as a C-compatible shared library, with a C++ header wrapping the C library with a modern C++ API. The installation also comes with the required files for CMake integration, allowing you to use metatensor in your own CMake project with find_package(metatensor).

To build and install the code, you’ll need to find the latest release of metatensor-core on GitHub releases, and download the corresponding metatensor-core-cxx file in the release assets.

You will also need to install a Rust compiler and cargo either with rustup or the package manager of your operating system. Then, you can run the following commands:

cmake -E tar xf metatensor-core-cxx-*.tar.gz
cd metatensor-core-cxx-*
mkdir build && cd build

# configure cmake here if needed
cmake ..

# build and install the code
cmake --build . --target install

The build and installation can be configures with a few CMake options, using -D<OPTION>=<VALUE> on the cmake command line, or one of the cmake GUI (cmake-gui or ccmake). Here are the main configuration options:

Option

Description

Default

CMAKE_BUILD_TYPE

Type of build: debug or release

release

CMAKE_INSTALL_PREFIX

Prefix in which the library will be installed

/usr/local

CMAKE_INSTALL_INCLUDEDIR

Path relative to CMAKE_INSTALL_PREFIX where the headers will be installed

include

CMAKE_INSTALL_LIBDIR

Path relative to CMAKE_INSTALL_PREFIX where the shared library will be installed

lib

BUILD_SHARED_LIBS

Default to installing and using a shared library instead of a static one

ON

METATENSOR_INSTALL_BOTH_STATIC_SHARED

Install both the shared and static version of the library. If OFF only the library selected by BUILD_SHARED_LIBS will be built.

ON

To use metatensor from Rust, you can add following to your project Cargo.toml

[dependencies]
metatensor = "0.1"

We have one feature that can be enabled with cargo: static, which forces the code to use the static build of metatensor-core instead of a shared build. It is disabled by default. Enabling it will mean that your code might not be able to share data with other metatensor-enabled programs if they are using a different version of metatensor. For example if you are working on a Python extension with PyO3, you should not use the static feature and instead have the code load the same shared library as the metatensor Python package.

The TorchScript bindings to metatensor are accessible in Python in the metatensor-torch package. You can install this at the same time you install the rest of metatensor with

# Make sure you are using the latest version of pip
pip install --upgrade pip

pip install metatensor[torch]

or as a standalone package with

pip install metatensor-torch

We provide pre-compiled wheels on PyPI that are compatible with all the supported torch versions at the time of metatensor-torch release. Currently PyTorch version 1.12 and above is supported.

If you want to use the code with an unsupported PyTorch version, or a new release of PyTorch which did not exist yet when we released metatensor-torch; you’ll need to compile the code on your local machine with

pip install metatensor-torch --no-binary=metatensor-torch

This local compilation will require a couple of additional dependencies:

  • a modern C++ compiler, able to handle C++17, such as:

    • gcc version 7 or above;

    • clang version 5 or above;

    • Microsoft Visual C++ (MSVC) compiler, version 19 (2015) or above.

  • if you want to use the CUDA version of PyTorch, you’ll also need the CUDA toolkit, including the NVIDIA compiler.

By default, PyTorch is installed with CUDA support on Linux, even if you do not have a CUDA-compatible GPU, and will search for a CUDA toolkit when building extension (such as metatensor-torch). If you don’t want to install the CUDA toolkit in this case, you can use the CPU-only version of PyTorch with

pip install --extra-index-url https://download.pytorch.org/whl/cpu metatensor-torch --no-binary=metatensor-torch

A similar index URL can be used to install the ROCm (AMD GPU) version of PyTorch, please refer to the corresponding documentation.

See also

Some potential build failures and corresponding workarounds are listed at the end of the TorchScript C++ installation instructions.

The TorchScript bindings to metatensor are also available as a C++ library, which can be integrated in non-Python software (such as simulation engines) to use custom metatensor models directly in the software without relying on a Python interpreter. The code is installed as a shared library which register itself with torch when loaded, the corresponding header files and a CMake integration allowing you to use metatensor-torch in your code code with find_package(metatensor_torch).

To build and install the code, you’ll need to find the latest release of metatensor-torch on GitHub releases, and download the corresponding metatensor-torch-cxx file in the release assets. Then, you can run the following commands:

cmake -E tar xf metatensor-torch-cxx-*.tar.gz
cd metatensor-torch-cxx-*
mkdir build && cd build

# configure cmake here if needed
cmake ..

# build and install the code
cmake --build . --target install

You will have to to manually install some of the dependencies of metatensor-torch yourself to compile this code, and any of the dependencies is not in a standard location, specify the installation directory when configuring cmake with CMAKE_PREFIX_PATH. The following dependencies might have to be installed beforehand:

  • the C++ interface of metatensor.

  • the C++ part of PyTorch, which you can install on it’s own. We are compatible with libtorch version 1.12 or above. You can also use the same library as the Python version of torch by adding the output of the command below to CMAKE_PREFIX_PATH:

    python -c "import torch; print(torch.utils.cmake_prefix_path)"

Option

Description

Default

CMAKE_BUILD_TYPE

Type of build: debug or release

release

CMAKE_INSTALL_PREFIX

Prefix in which the library will be installed

/usr/local

CMAKE_PREFIX_PATH

;-separated list of path where CMake will search for dependencies. This list should include the path to metatensor and torch

Workaround for some build errors

The CMake configuration used by libtorch sometimes fails to setup the build environment. You’ll find here a list of some known build failures and how to workaround them.

  • Unknown CUDA Architecture Name 9.0a in CUDA_SELECT_NVCC_ARCH_FLAGS

    This can happen when building with a CUDA-enabled version of torch and a recent version of cmake. This issue is tracked at https://github.com/pytorch/pytorch/issues/113948. To work around it, you can export TORCH_CUDA_ARCH_LIST="8.0 8.6 8.9 9.0" in your environment before building the code.

  • Imported target "torch" includes non-existent path
  [...]/MKL_INCLUDE_DIR-NOTFOUND"
in its INTERFACE_INCLUDE_DIRECTORIES.

    This can happen when building for x86_64 Linux when MKL is not available on the current machine. Since MKL is a completely optional dependency, you can silence the error by running cmake with the -DMKL_INCLUDE_DIR=/usr/include option.

Installing a development version

Metatensor is developed on GitHub. If you want to install a development version of the code, you will need git to fetch the latest version of the code. You will also need a Rust compiler on top of any language specific compiler. You can install Rust using rustup or the package manager of your operating system.

You can install a development version of all the metatensor sub-packages with:

# Make sure you are using the latest version of pip
pip install --upgrade pip

git clone https://github.com/metatensor/metatensor
cd metatensor
pip install .

# alternatively, the same thing in a single command
pip install git+https://github.com/metatensor/metatensor

You can also install a single sub-package at the time with

git clone https://github.com/metatensor/metatensor
cd metatensor
pip install ./python/metatensor_core
pip install ./python/metatensor_operations
pip install ./python/metatensor_learn
pip install ./python/metatensor_torch

# alternatively, the same thing in a single command
pip install git+https://github.com/metatensor/metatensor#subdirectory=python/metatensor_core
pip install git+https://github.com/metatensor/metatensor#subdirectory=python/metatensor_operations
pip install git+https://github.com/metatensor/metatensor#subdirectory=python/metatensor_learn
pip install git+https://github.com/metatensor/metatensor#subdirectory=python/metatensor_torch

You can install the development version of metatensor with the following (the same cmake configuration options are available):

git clone https://github.com/metatensor/metatensor
cd metatensor/metatensor-core

mkdir build && cd build

# configure cmake here if needed
cmake ..

# build and install the code
cmake --build . --target install

Add the following to your project Cargo.toml

[dependencies]
metatensor = {git = "https://github.com/metatensor/metatensor.git"}

You can install a development version of the TorchScript bindings to metatensor with:

# Make sure you are using the latest version of pip
pip install --upgrade pip

git clone https://github.com/metatensor/metatensor
cd metatensor
pip install .[torch]

# alternatively, the same thing in a single command
pip install "metatensor[torch] @ git+https://github.com/metatensor/metatensor"

If you want to install and update only the metatensor-torch package, you can do the following:

git clone https://github.com/metatensor/metatensor
cd metatensor
pip install ./python/metatensor_torch

# alternatively, the same thing in a single command
pip install git+https://github.com/metatensor/metatensor#subdirectory=python/metatensor_torch

You can install the development version of metatensor with the following (the same cmake configuration options are available):

git clone https://github.com/metatensor/metatensor
cd metatensor/metatensor-torch
mkdir build && cd build

# configure cmake here if needed
cmake ..

# build and install the code
cmake --build . --target install