Installation Guide

The installation of MatterTune consists of three stages:

  1. Configure environment dependencies for one specific backbone model

  2. Install the MatterTune package

  3. Set up additional dependencies for external datasets and data sources

Warning

MatterTune must be installed on environments with python>=3.10

Warning

Since there are dependency conflicts between different backbone models, we strongly recommend creating separate virtual environments for each backbone model you plan to use.

Backbone Installation

Below are the installation instructions for our currently supported backbone models using conda and pip.

MatterSim

We strongly recommand to install MatterSim from source code

git clone git@github.com:microsoft/mattersim.git
cd mattersim

Find the line 41 of the pyproject.toml in MatterSim, which is "pydantic==2.9.2",. Change it to "pydantic>=2.9.2", and python=3.9 in environment.yaml to python=3.10. After finishing this modification, install MatterSim by running:

mamba env create -f environment.yaml
mamba activate mattersim
uv pip install -e .
python setup.py build_ext --inplace

MACE

MACE can be directly installed with pip:

pip install --upgrade pip
pip install mace-torch

or it can be installed from source code:

git clone https://github.com/ACEsuit/mace.git
pip install ./mace

JMP

Please follow the installation instructions in the jmp-backbone repository.

ORB

Please follow the installation instructions in the orb-models repository.

EquiformerV2

conda create -n eqv2-tune python=3.10
conda activate eqv2-tune
pip install "git+https://github.com/FAIR-Chem/fairchem.git@omat24#subdirectory=packages/fairchem-core" --no-deps
pip install ase "e3nn>=0.5" hydra-core lmdb numba "numpy>=1.26,<2.0" orjson "pymatgen>=2023.10.3" submitit tensorboard "torch==2.5.0" wandb torch_geometric h5py netcdf4 opt-einsum spglib

MatterTune Package Installation

Important

MatterTune should be installed after setting up the backbone model dependencies.

Clone the repository and install MatterTune by:

pip install -e .

External Dataset Installation

Matbench

Clone the repo and install by:

git clone https://github.com/hackingmaterials/matbench
cd matbench
pip install -e . -r requirements-dev.txt

Materials Project

Install mp-api:

pip install mp-api

Note

There are currently dependency conflicts between mp-api and matbench packages. You may not be able to use both simultaneously in a single virtual environment.

Materials Project Trajectories

To access MPTraj data from our Hugging Face dataset:

pip install datasets