Installation¶

The easiest way to use MLatom is not to install it locally but run online. If you want to install it anyway, please follow instruction below. You can watch a short video demonstrating how to install and use MLatom.

MLatom installs on Python 3.9 to 3.12 – it needs NumPy below 2.0, which has no builds for Python 3.13 or newer. We test it with Python 3.11 and recommend that version.

Before installing MLatom, we recommend creating a clean conda environment to avoid package conflicts. MLatom is a Python package and can be easily installed and upgraded using pip:

pip install --upgrade mlatom

As of MLatom 3.25.3 this installs MLatom together with all of its required Python dependencies. A few methods need extra programs (e.g., DFT-D4 for AIQM2) or optional packages, as described below.

Dependencies¶

Minimal setup

As of MLatom 3.23.4, pip install --upgrade mlatom installs everything needed to run the get started examples (AIQM2 geometry optimization) – including PyTorch and TorchANI in the versions MLatom requires and a geometry-optimization backend. The only extra step for AIQM2 is the DFT-D4 program, installed via conda below.

A few features need one more package. Install only what you use:

pip install pyscf – PySCF methods: single point, TDDFT, frequencies and thermochemistry, densities, Raman
pip install "aimnet==0.0.1" – AIMNet2 models (newer aimnet releases are a rewrite that does not work with the shipped models)
conda install -c conda-forge openbabel – format conversions (SMILES to xyz and back)
pip install ase – the ASE interface (ASE optimizers and dynamics) and MACE
conda install -c conda-forge mkl mkl-service – the KREG_API backend. kreg(..., ml_program='MLatomF') needs none of it
pip install "e3nn==0.5.0" – MDtrajNet (with e3nn 0.5.1 or newer, the published MDtrajNet-1 model produces different trajectories)
pip install rdkit / pyvibdmc / hyperopt – MLTPA / DMC / hyperparameter search

None of these is needed for the get started examples.

For dftd4 we recommend to install via conda.

conda config --add channels conda-forge
conda install dftd4
conda install dftd4-python
conda search dftd4 --channel conda-forge

After the dftd4 program is installed, you need to set the environmental variable pointing to the dftd4 executable, e.g., in bash:

export dftd4bin=[path to the executable]/dftd4

From MLatom 3.25.0 on, any dftd4 version gives the same energies for AIQM1, AIQM2, OMNI-P1 and the ANI -D4 models, because MLatom sets the D4 damping parameters itself instead of selecting them by functional name. Pick v3.5.0 if you need Hessians, i.e. frequencies and thermochemistry – see dftd4 below.

Useful optional modules

pip install sgdml openbabel-wheel xgboost scikit-learn rdkit pandas \
   ase tensorflow

The versions we test with

Each MLatom release is tested with the package versions in mlatom_constraints.txt (for MLatom 3.25.5: Python 3.11.5 on Linux, with NumPy 1.26.4, PyTorch 2.7.0, TorchANI 2.2.4, geomeTRIC 1.1, PySCF 2.10.0, ASE 3.26.0 and e3nn 0.5.0 among them); these tests leave out MACE, sGDML, PhysNet, DeePMD-kit, DM21 and MLQD. To get the same versions, give the file to pip as constraints – they fix the versions, MLatom’s included, but install nothing by themselves. The file needs Python 3.11 or 3.12 and Linux with glibc 2.28 or newer (not CentOS or RHEL 7):

conda create -n mlatom python=3.11 -y
conda activate mlatom
pip install mlatom -c mlatom_constraints.txt
pip install pyscf ase -c mlatom_constraints.txt   # and any other optional package above

mace-torch cannot be installed with the file: it needs e3nn 0.4.4, and the file has 0.5.0, which MDtrajNet needs.

Additional software packages¶

Many MLatom features are relying on other third-party software packages which are not Python modules and should be installed and setup separately as described here.

The third-party packages below are optional and can be installed separately to enable specific features. In alphabetical order:

Aitomic add-ons (required for AIQM3)
ASE (can be used for geometry optimizations and thermochemistry)
COLUMBUS (required for CASSCF)
DeePMD-kit (enables several machine learning potentials implemented there)
dftd4 (required for the D4 dispersion correction, required for AIQM1, AIQM2, ANI-2x-D4, and ANI-1x-D4)
GAP and QUIP (required for GAP-SOAP machine learning potential)
Gaussian (can be used for QM calculations, geometry optimizations, frequencies and thermochemistry, required for IRC and anharmonic frequencies)
hyperopt (can be used for hyperparameter optimization)
MACE (required for the MACE potential)
MNDO (can be used & recommended for AIQM1 and many other semi-empirical QM methods)
Newton-X (required for UV/vis spectra simulations)
Orca (required for CCSD(T)*/CBS and can be used for DFT calculations)
PhysNet (required for PhysNet potential)
sGDML (required for sGDML potential)
Sparrow (can be used & recommended for AIQM1 and many other semi-empirical QM methods)
TorchANI (installed with MLatom; required for AIQM1 and ANI potentials)
Turbomole (required for ADC(2) calculations)

Aitomic add-ons¶

The Aitomic add-ons extend open-source MLatom with advanced Aitomistic methods. AIQM3 is distributed this way, as the aitomic-addons package on PyPI.

The package ships pre-compiled wheels for Linux (x86-64 / aarch64) with Python 3.9–3.11 only (3.11 recommended; there are no macOS or Windows wheels). Install AIQM3 together with its pinned dependencies into a fresh environment:

conda create -n aiqm3 python=3.11 -y
conda activate aiqm3
pip install -U "numpy<2" torch==2.1.2 torchani==2.2.3 mlatom aitomic-addons joblib pyscf geometric

MLatom then resolves AIQM3 automatically, with no extra imports.

For the full platform/Python compatibility checklist, the D3-dispersion setup, verification, license terms, and troubleshooting of common pip errors, see Add-ons.

COLUMBUS¶

COLUMBUS 7 is required for CASSCF calculations. It can be obtained and installed as described on the program website.

It must be made available to MLatom by setting up environmental variable COLUMBUS, e.g.:

export COLUMBUS=[path to COLUMBUS directory with runc executable]

Turbomole¶

Turbomole is required for ADC(2) calculations. It can be obtained and installed as described on the program website.

It must be made available to MLatom by setting up environmental variable TURBODIR.

Orca¶

Orca is required for CCSD(T)*/CBS calculations and can be used for DFT calculations. Here we use Orca 4.2.0. It can be obtained and installed as described on the program website.

It must be made available to MLatom by setting up environmental variable orcabin, e.g.:

export orcabin=[path to Orca executable]

DFTB+¶

Using the conda command is the recommended installation method:

conda install conda-forge::dftbplus

Alternatively, you can also install it by downloading the binary from https://www.dftbplus.org/download/stable.html or compiling from source:

git clone https://github.com/dftbplus/dftbplus.git
cd dftbplus
cmake -DCMAKE_INSTALL_PREFIX=$HOME/opt/dftb+ -B _build .
cmake --build _build -- -j
cmake --install _build
export PATH=$HOME/opt/dftb+/bin:$PATH   # MLatom calls dftb+

After installation, you need to download the DFTB+ parameter files (also called Slater–Koster files). Once downloaded, extract the files and add their path to your environment variable as (in bash):

export skfiles=/path/to/SK/files

Newton-X¶

Newton-X is required for ML-NEA calculations.

Install Newton-X (NX, preferably version==2.2 for which our implementations were tested)
use export NX=/path/to/Newton-X to define the $NX

TorchANI¶

TorchANI is required for calculations with AIQM1 and ANI family of potentials. It is installed together with MLatom (pip install mlatom), and so is PyTorch: MLatom needs TorchANI 2.2 (torchani>=2.2.3,<2.3) and PyTorch from 2.1.2 up to 2.7. We test with TorchANI 2.2.4 and PyTorch 2.7.0.

Visit https://aiqm.github.io/torchani/ for more info. The CUDA extension for AEV calculation is not supported for the NN part of AIQM1 and ANI-1ccx now.

DeePMD-kit¶

Required for DPMD and DeepPot-SE potentials.

download installer for DeePMD-kit from GitHub (tested v1.2.2)
run installer
add environmental variable $DeePMDkit that point to the where dp binary is located (bin/ in your installation directory), e.g. export DeePMDkit=[DeePMD-kit directory]/bin.

GAP and QUIP¶

Required for GAP-SOAP potentials.

compile QUIP and GAP from source

1.1 install prerequisites

sudo apt-get install gcc gfortran python3 python3-pip libblas-dev liblapack-dev # for system uses apt, do equivalent for your OS
pip install numpy ase f90wrap

1.2 get source code of QUIP and GAP

git clone --recursive https://github.com/libAtoms/QUIP.git

Get source code of GAP from http://www.libatoms.org/gap/gap_download.html (form-filling required).

Then put source code in QUIP/src/.

1.3 compile

cd QUIP
export QUIP_ARCH=linux_x86_64_gfortran_openmp # enable multi-threading, use 'export QUIP_ARCH=linux_x86_64_gfortran' if no OpenMP thus no MT capability
export QUIPPY_INSTALL_OPTS=--user # omit for a system-wide installation
make config

Enter Y for gap or edit build/linux_x86_64_gfortran/Makefile.inc with HAVE_GAP=1, then: make. Built binaries are in QUIP/build/linux_x86_64_gfortran/quip and QUIP/build/linux_x86_64_gfortran/gap_fit.

add environmental variable $quip and $gap_fit for quip and gap_fit, e.g.

export quip='[QUIP directory]/build/linux_x86_64_gfortran_openmp/quip'
export gap_fit='[QUIP directory]/build/linux_x86_64_gfortran_openmp/gap_fit'

visit https://libatoms.github.io/GAP/index.html for more information.

PhysNet¶

Required for PhysNet models.

clone form PhysNet’s GitHub page

git clone https://github.com/MMunibas/PhysNet.git

install TensorFlow:

pip install tensorflow

if you use TensorFlow v2, you need to execute the command below in PhysNet’s directory to make the scripts compatible with TFv2.

for i in `find . -name '*.py'`; do sed -i -e 's/import tensorflow as tf/import tensorflow.compat.v1 as tf\ntf.disable_v2_behavior()/g' $i; done

add environmental variable $PhysNet to the directory, e.g.

export PhysNet=[PhysNet directory]/

sGDML¶

Required for GDML and sGDML potentials.

install sGDML

pip install sgdml==0.4.4

add the path of sGDML binary to environmental variable $sGDML, e.g.

export sGDML=[path to the executable]/sgdml

Visit http://quantum-machine.org/gdml/doc/ for more information.

Note

sGDML is not among the packages we test each MLatom release with.

MACE¶

Required for MACE potentials.

pip install --upgrade mace-torch

Warning

MLatom versions >3.13 works with MACE-Torch 0.3.8. If you encounter any problem, you can install these versions via pip install mace-torch==0.3.8.

MLatom versions ≤3.13 works with version 0.3.2 of MACE according to our tests. If, for some reason, you need to downgrade MACE, it is not that straightforward because you would need to find the related commit on github. The old installation instructions which will not work but you can try to adjust:

clone MACE git from GitHub

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

install MACE with pip

pip install ./mace

MNDO¶

MNDO program is required to provide the ODM2* part of AIQM1. Alternatively, a (development) version of SCINE Sparrow can be used (at the moment it has no analytical derivatives for ODM2* part and hence only single-point simulations are recommended; see a paper on Sparrow; note that the development version of Sparrow also implements single-point AIQM1 calculations).

The free binary and open-source code of the MNDO program is available from the official distributors of the MNDO code as described at https://mndo.kofo.mpg.de.

After the MNDO program is installed, you need to set the environmental variable pointing to the MNDO executable (typically mndo99), e.g., in bash:

export mndobin=[path to the executable]/mndo99

Sparrow¶

The SCINE Sparrow program can be used to provide many of the semi-empirical methods. See its website for the installation instructions.

Note that the a (development) version can also be used instead of the MNDO program to provide the ODM2* part of AIQM1, but the biggest limitation is that it has no analytical gradients at the moment. See a paper on Sparrow for details. Note that the development version of Sparrow also implements single-point AIQM1 calculations. Our recommendation is just to use this development version of Sparrow for AIQM1 single-point calculations on the Aitomistic Hub if needed. It is difficult to install this version.

dftd4¶

dftd4 program is required to provide the D4 part of AIQM1.

The dftd4 program can be obtained as both executable and open-source code. We recommend using dftd4 v3.5.0 (dftd4 v2.5.0 for the MLatom versions earlier than 3.0.1), which can calculate Hessian needed for thermochemical calculations. To install the dftd4 program from source code, please see the README.md file on dftd4 GitHub page for more details.

Note

Which dftd4 version, and why it used to matter. dftd4 4.0.0 renamed the wb97x parameter set to wb97x-2008 and gave the name wb97x to a different functional (ωB97X-D4). AIQM1, AIQM2, OMNI-P1 and the ANI -D4 variants were built against the 2008 one, so on dftd4 ≥ 4.0.0 MLatom before 3.25.0 silently used another functional’s damping – shifting AIQM2 by several kcal/mol and roughly doubling the depth of dispersion-bound minima.

From MLatom 3.25.0 the damping parameters are given to dftd4 explicitly rather than selected by name, so results no longer depend on which dftd4 is installed, and the two versions agree to every digit. If you are on an older MLatom with dftd4 ≥ 4.0.0 (any environment built with conda install dftd4 since November 2025), upgrading MLatom will change your D4 energies – to the intended ones.

The remaining reason to prefer v3.5.0 is Hessian support for thermochemistry, as above, not the parameters.

After the dftd4 program is installed, you need to set the environmental variable pointing to the dftd4 executable, e.g., in bash:

export dftd4bin=[path to the executable]/dftd4

Gaussian¶

Required for geometry optimizations, freq, TS search, IRC, thermochemistry, and ML-NEA. For some of these tasks, alternatively, ASE can be used, see below.

Our implementation work with both Gaussian 09 and Gaussian 16. It is a commercial program, which can be obtained and installed separately.

To use Gaussian interface, make sure that your environmental variable $GAUSS_EXEDIR points to the right place.

ASE¶

Required for geometry optimizations, freq, and thermochemistry. Alternatively, Gaussian can be used, see above.

The ASE (Atomic Simulation Environment) are Python modules, which can be installed as described on ASE website, i.e.:

pip install ase

hyperopt¶

To enable hyperopt, please run pip install hyperopt to install the hyperopt package.

Conda environment¶

Quick Miniconda Installation