Installation¶

You can install featomic in different ways depending on which language you plan to use it from. In all cases you will need a Rust compiler, which you can install using rustup or your OS package manager.

Installing the Python module¶

For building and using the Python package, clone the repository using git and install featomic using pip.

From source:

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

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

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

Featomic is also provided as prebuilt wheel which avoids the intermediate step of building the package with a Rust compiler from the source code.

pip install --upgrade pip
pip install --extra-index-url https://luthaf.fr/nightly-wheels/ featomic

Installing the C/C++ library¶

This installs a C-compatible shared library that can also be called from C++, as well as CMake files that can be used with find_package(featomic).

git clone https://github.com/metatensor/featomic
cd featomic/featomic-c-api
mkdir build
cd build
cmake <CMAKE_OPTIONS_HERE> ..
make 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`
INCLUDE_INSTALL_DIR	Path relative to `CMAKE_INSTALL_PREFIX` where the headers will be installed	`include`
LIB_INSTALL_DIR	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
FEATOMIC_INSTALL_BOTH_STATIC_SHARED	Install both the shared and static version of the library	ON
FEATOMIC_ENABLE_CHEMFILES	Enable the usage of chemfiles for reading systems from files	ON
FEATOMIC_FETCH_METATENSOR	Automatically fetch, build and install metatensor (a dependency of featomic)	OFF

Using the Rust library¶

Add the following to your project Cargo.toml

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

Featomic has one optional dependency (chemfiles), which is enabled by default. If you want to disable it, you can use:

[dependencies]
featomic = {git = "https://github.com/metatensor/featomic", default-features = false}

Installing the TorchScript bindings¶

For usage from Python¶

Building from source:

git clone https://github.com/metatensor/featomic
cd featomic/python/featomic-torch
pip install .

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

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

For usage from C++¶

git clone https://github.com/lab-cosmo/featomic
cd featomic/featomic-torch
mkdir build && cd build
cmake ..
# configure cmake if needed
cmake --build . --target install

Compiling the TorchScript bindings requires you to manually install some of the dependencies:

the C++ part of PyTorch, which you can install on it’s own. You can also use the installation that comes with a Python installation by adding the output of the command below to CMAKE_PREFIX_PATH:
```
python -c "import torch; print(torch.utils.cmake_prefix_path)"
```
the C++ interface of featomic, which itself requires the C++ interface of metatensor;
the TorchScript interface of metatensor. We can download and build an appropriate version of it automatically by setting the cmake option -DFEATOMIC_TORCH_FETCH_METATENSOR_TORCH=ON

If any of these dependencies is not in a standard location, you should specify the installation directory when configuring cmake with CMAKE_PREFIX_PATH. Other useful configuration options are:

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.
FEATOMIC_TORCH_FETCH_METATENSOR_TORCH	Should CMake automatically download and install metatensor-torch?	OFF