Installation¶

You can install featomic in different ways depending on which language you plan to use it from.

Installing the Python module¶

Pre-compiled wheels¶

The easiest way to install featomic is to use pip.

pip install --upgrade pip
pip install featomic

Building from source¶

If you want to build the code from source, you’ll need a Rust compiler, which you can install using rustup or your OS package manager; and git.

# 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

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
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_FETCH_METATENSOR	Automatically fetch, build and install metatensor (a dependency of featomic)	OFF
FEATOMIC_USE_STATIC_METATENSOR	Link against the static version of metatensor. You should only use this if you know your code will never be loaded with together with another library using metatensor, for example if you are building a fully static executable.	OFF

Using the Rust library¶

Add the following to your project Cargo.toml

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

Installing the TorchScript bindings¶

For usage from Python¶

You can install the code with pip:

pip install --upgrade pip
pip install featomic[torch]

You can also build the code from source

pip install --upgrade pip

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

# 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/metatensor/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_FETCH_METATENSOR_TORCH=ON
the TorchScript interface of metatomic. We can download and build an appropriate version of it automatically by setting the cmake option -DFEATOMIC_FETCH_METATOMIC_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_FETCH_METATENSOR_TORCH	Should CMake automatically download and install metatensor-torch?	OFF
FEATOMIC_FETCH_METATOMIC_TORCH	Should CMake automatically download and install metatomic-torch?	OFF