Examples

See the Quickstart guide for a fast example with the ASE EMT Calculator.

Please note the following important points:

  1. External Software: The external programs and packages referenced in this documentation are not developed, maintained, or endorsed by SCM.

  2. Installation and Use: Users are responsible for the installation, configuration, and management of external software and tools. By following these instructions, you will be installing third-party software on your system. SCM has no control over the content, functionality, or updates of such software. Before installation, read and agree to the external software’s license terms.

  3. Liability: SCM is not responsible for any issues arising from the installation, configuration, or use of external software, including but not limited to system instability, data loss, or security vulnerabilities. See also the SCM license terms.

  4. Support: For questions or issues related to the external software, users should contact the respective developers or refer to their official documentation. See also Troubleshooting.

This page contains tips on how to couple some ASE calculators to AMS. It is provided for information purposes only. The information may become outdated and is not guaranteed to work for you on your system.

Warning

When you manually install packages into the AMS Python environment, you may break the SCM-supported ML Potential packages, for example by installing incompatible versions of dependencies. If this happens, it is easiest to remove the AMS Python virtual environment completely and reinstall the ML Potential packages from the package manager.

We recommend that you install packages into a separate Conda environment.

Overview of external methods/programs

Method/program

AMS Engine

Type

Website

AIMNet2

ML Potential

ML Potential

Github

ALIGNN-FF

ASE

ML potential

Github

ANI (TorchANI)

ML potential

ML potential

Github

CHGNet

ASE

ML potential

Github

CP2K

ASE

DFT

cp2k.org

Custom

ASE

Custom

DeePMD-kit

ASE

ML potential

Github

DFTpy

ASE

orbital-free DFT

Gitlab

EMT

ASE

Force field

FAIR-Chem

ASE

ML Potential

Github

GPAW

ASE

DFT

website

MACE

ASE

ML Potential

Github

MatGL (M3GNet)

ASE

ML potential

Github

MatterSim

ASE

ML potential

Github

M3GNet

ML potential

ML potential

Github

NequIP

ML potential

ML potential

Github

Open Catalyst Project

ASE

ML potential

opencatalystproject.org

OpenKIM

ASE

Force fields

openkim.org

ORB

ASE

ML Potential

Github

psi4

ASE

DFT/ab initio

Website

PySCF

ASE

DFT/ab initio

Website

Quantum ESPRESSO

Quantum ESPRESSO

DFT

quantum-espresso.org

sGDML

ML potential

ML potential

Github

SO3LR

ASE

ML potential

Github

tblite

ASE

semi-empirical

Github

VASP

External

DFT

vasp.at

xTB (GFN2-xTB)

ASE

semi-empirical

Github

AIMNet2

See the ML Potential documentation.

ALIGNN-FF

Tested with: AMS2025.101, Ubuntu Linux 24.04, Jan 13 2024

Install alignn in a conda environment.

conda create -n alignn-env
conda install -c conda-forge -n alignn-env \
  dgl=2.1.0 pytorch torchvision torchaudio pytorch-cuda -c pytorch -c nvidia
conda run -n alignn-env \
  python -m pip install \
  "$AMSHOME"/scripting/wheels/*.whl

Test your installation. If the below prints the energy of Si bulk, then your conda environment has been set up correctly:

conda run -n alignn-env \
  python $AMSHOME/scripting/scm/external_engines/backends/_alignn/calculator.py

Run AMS with the ASE engine. Feel free to copy the calculator.py file and modify it to your needs (note: Task and System are provided in the AMS input below).

rm -rf alignn_test.results

AMS_JOBNAME=alignn_test $AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

System
    Atoms
        Si -0.67875 -0.67875 -0.67875
        Si 0.77875 0.67875 0.67875
    End
    Lattice
        0.0 2.715 2.715
        2.715 0.0 2.715
        2.715 2.715 0.0
    End
End

Engine ASE
    File $AMSHOME/scripting/scm/external_engines/backends/_alignn/calculator.py
    Arguments
        path = None
    End
    Python
        Type Conda
        Conda alignn-env   # this environment must have been set up correctly
    End
EndEngine
eor

ANI (TorchANI)

See the ML Potential documentation.

CHGNet

Tested with: AMS2025.101, Ubuntu Linux 22.04, Nov 11 2024

Install CHGNet into a separate conda environment:

conda create -n chgnet-env
conda install -c conda-forge -n chgnet-env "python<3.13" ase
conda run -n chgnet-env \
  python -m pip install \
  chgnet "$AMSHOME"/scripting/wheels/*.whl

Test your installation. If the below prints the energy of a water molecule, then your conda environment has been set up correctly:

conda run -n chgnet-env \
   python $AMSHOME/scripting/scm/external_engines/backends/_chgnet/calculator.py

Run AMS with the ASE engine. Feel free to copy the calculator.py file and modify it to your needs (note: Task and System are provided in the AMS input below).

rm -rf chgnet_test.results

AMS_JOBNAME=chgnet_test $AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

System
    Atoms
        O 1.5 0. 0.
        C 0.0 0. 0.
        O -1.5 0. 0.
    End
End

Engine ASE
    File $AMSHOME/scripting/scm/external_engines/backends/_chgnet/calculator.py
    Arguments
        use_device = "cpu"
    End
    Python
        Type Conda
        Conda chgnet-env   # this environment must have been set up correctly
    End
EndEngine
eor

If you have a CUDA-enabled GPU, you can set use_device = "cuda" to run on the GPU instead. Or remove the option completely to use the default device.

See the CHGNet documentation and code for details.

CP2K

Tested with: AMS2023.101, Ubuntu Linux 22.04, July 5 2023

The below works for single-node calculation but fails for multinode (MPI parallelization).

  • Install CP2K. In a terminal: sudo apt install cp2k

  • Run AMS with the CP2K ASE calculator cp2k_ams.run:

Listing 1 cp2k_ams.run
#!/bin/sh

export SCM_DISABLE_MPI=1

# set OMP_NUM_THREADS to the appropriate number below

$AMSBIN/ams -n 1 <<eor

Task GeometryOptimization

System
  Atoms
              O       2.8115000409       2.5498605363       2.0000000000 
              H       2.0000000000       2.0000000000       2.0000000000 
              H       3.6254485609       2.0005857872       2.0000000000 
  End
  Lattice
         5.6254485609     0.0000000000     0.0000000000
         0.0000000000     4.5498605363     0.0000000000
         0.0000000000     0.0000000000     4.0000000000
  End
End

Engine ASE
  Type Import
  Import ase.calculators.cp2k.CP2K
  # see the ASE CP2K documentation for details about the arguments
  Arguments
     command = "OMP_NUM_THREADS=2 cp2k_shell"   # set OMP_NUM_THREADS here
     cutoff = 4000 # eV
     stress_tensor = False   # set stress_tensor here  (defaults to True)
     xc = "PBE"
     inp = """
     &FORCE_EVAL
       &DFT
         &KPOINTS
           SCHEME GAMMA
         &END KPOINTS
         &SCF
           ADDED_MOS 10
           &SMEAR
             METHOD FERMI_DIRAC
             ELECTRONIC_TEMPERATURE [K] 500.0
           &END SMEAR
         &END SCF
       &END DFT
     &END FORCE_EVAL
    """
  End
EndEngine

eor

Custom

Tested with: AMS2025.101, Ubuntu Linux 22.04, Feb 4 2025

This example shows how to set up a custom simple ASE calculator. It always returns zero forces.

Listing 2 calculator.py
#!/usr/bin/env amspython

from ase.calculators.calculator import Calculator, all_changes
import numpy as np


class ZeroCalculator(Calculator):
    implemented_properties = ["energy", "forces"]

    def calculate(self, atoms=None, properties=["energy"], system_changes=all_changes):
        super().calculate(atoms, properties, system_changes)
        self.results = dict()
        if atoms is not None:
            energy_per_atom = self.parameters.get("energy_per_atom", 0.0)
            self.results = {
                "energy": energy_per_atom * len(atoms),
                "forces": np.zeros((len(atoms), 3)),
            }


def get_calculator(energy_per_atom: float = 0.0):
    """energy_per_atom: float (eV). Always returns zero forces."""
    return ZeroCalculator(energy_per_atom=energy_per_atom)


def example():
    """Simple example for a water molecule.

    Note: this is just an example of the ASE calculator. This section
    has no effect when running through AMS.
    """
    from ase.build import molecule

    atoms = molecule("H2O")
    atoms.calc = get_calculator(energy_per_atom=1.0)

    energy = atoms.get_potential_energy()
    forces = atoms.get_forces()

    print(f"Energy of water molecule: {energy:.3f} eV")
    print(f"Forces (eV/ang): {forces}")


if __name__ == "__main__":
    example()

Run AMS with the ASE engine. Feel free to copy the calculator.py file and modify it to your needs (note: Task and System are provided in the AMS input below).

rm -rf zero_test.results

AMS_JOBNAME=zero_test $AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

System
    Atoms
        O 1.5 0. 0.
        C 0.0 0. 0.
        O -1.5 0. 0.
    End
End

Engine ASE
    File $AMSHOME/scripting/scm/external_engines/backends/_zero/calculator.py
    Arguments
        energy_per_atom = 1.0
    End
    Python
        Type amspython
    End
EndEngine
eor

DeePMD-kit

Tested with: AMS2023.104, Ubuntu Linux 22.04, 14 Nov 2023

  • Install deepmd-kit into the AMS python environment. This will place the db binary in a location like /home/user/.scm/python/AMS2023.1.venv/bin

  • Either train your own model or download one from the AIS Square

  • If you download a model you may need to convert it using db convert-from, see the DeepMD-kit documentation

Then specify Type Import and specify the path to the model (.pb) file in the Arguments:

Listing 3 deepmd-kit_ams.run
#!/bin/sh
NSCM=1 $AMSBIN/ams <<EOF
system
  Atoms
              O      -0.0008161597       0.3663784285      -0.0000000000 
              H      -0.8123162006      -0.1834821079      -0.0000000000 
              H       0.8131323603      -0.1828963206       0.0000000000 
  End
End

Task GeometryOptimization

Engine ASE
  Arguments
     
    model = '/absolute/path/to/graph.pb'

  End
  Import deepmd.calculator.DP
  Type Import
EndEngine
EOF

DFTpy

Tested with: AMS2023.101, Ubuntu Linux 22.04, August 3 2023

$AMSBIN/amspython -m pip install dftpy
$AMSBIN/amspython -m pip install pylibxc2
git clone https://gitlab.com/pavanello-research-group/local-pseudopotentials

Set the environment variable to the path to the pseudopotentials, for example

export DFTPY_DATA_PATH=`readlink -f local-pseudopotentials/BLPS/LDA/reci`

An ASE Calculator with some settings for Al is defined in dftpy_calculator.py:

#!/usr/bin/env amspython
import os
from dftpy.config import DefaultOption, OptionFormat
from dftpy.api.api4ase import DFTpyCalculator
from ase.calculators.calculator import Calculator


class MyCalculator(Calculator):
    implemented_properties = ["energy", "forces", "stress"]

    def __init__(self, config, **kwargs):
        Calculator.__init__(self, **kwargs)
        self.dftpy_calculator = DFTpyCalculator(config=config)

    def calculate(self, atoms, properties=None, system_changes=None):
        super().calculate(atoms, properties, system_changes)
        self.results = dict()
        self.results["energy"] = self.dftpy_calculator.get_potential_energy(atoms)
        self.results["forces"] = self.dftpy_calculator.get_forces(atoms)
        self.results["stress"] = self.dftpy_calculator.get_stress(atoms)


def get_calculator():
    config = DefaultOption()
    config["PATH"]["pppath"] = os.environ.get(
        "DFTPY_DATA_PATH",
        "/home/hellstrom/software/local-pseudopotentials/BLPS/LDA/reci",
    )
    config["PP"]["Al"] = "al.lda.recpot"
    config["OPT"]["method"] = "TN"
    config["KEDF"]["kedf"] = "WT"
    config["JOB"]["calctype"] = "Energy Force"
    config = OptionFormat(config)
    calc = MyCalculator(config=config)

    return calc

This file is referenced inside the Engine ASE block in the input to AMS:

#!/bin/sh
export SCM_DISABLE_MPI=1

$AMSBIN/ams <<EOF
Engine ASE
  File /home/hellstrom/dftpy_calculator.py # change this!
  Type File
EndEngine

MolecularDynamics
  InitialVelocities
    Temperature 1000
    Type Random
  End
  NSteps 20
  Thermostat
    Tau 100.0
    Temperature 1000
    Type NHC
  End
  Barostat
    Type MTK
    Pressure 1.0
    Tau 10000
  End
  TimeStep 1.0
  Trajectory
    SamplingFreq 1
  End
End

Task MolecularDynamics

system
  Atoms
             Al       0.0000000000       0.0000000000       0.0000000000 
             Al       0.0000000000       2.1200000000       2.1200000000 
             Al       2.1200000000       0.0000000000       2.1200000000 
             Al       2.1200000000       2.1200000000       0.0000000000 
             Al       0.0000000000       0.0000000000       4.2400000000 
             Al       0.0000000000       2.1200000000       6.3600000000 
             Al       2.1200000000       0.0000000000       6.3600000000 
             Al       2.1200000000       2.1200000000       4.2400000000 
             Al       0.0000000000       4.2400000000       0.0000000000 
             Al       0.0000000000       6.3600000000       2.1200000000 
             Al       2.1200000000       4.2400000000       2.1200000000 
             Al       2.1200000000       6.3600000000       0.0000000000 
             Al       0.0000000000       4.2400000000       4.2400000000 
             Al       0.0000000000       6.3600000000       6.3600000000 
             Al       2.1200000000       4.2400000000       6.3600000000 
             Al       2.1200000000       6.3600000000       4.2400000000 
             Al       4.2400000000       0.0000000000       0.0000000000 
             Al       4.2400000000       2.1200000000       2.1200000000 
             Al       6.3600000000       0.0000000000       2.1200000000 
             Al       6.3600000000       2.1200000000       0.0000000000 
             Al       4.2400000000       0.0000000000       4.2400000000 
             Al       4.2400000000       2.1200000000       6.3600000000 
             Al       6.3600000000       0.0000000000       6.3600000000 
             Al       6.3600000000       2.1200000000       4.2400000000 
             Al       4.2400000000       4.2400000000       0.0000000000 
             Al       4.2400000000       6.3600000000       2.1200000000 
             Al       6.3600000000       4.2400000000       2.1200000000 
             Al       6.3600000000       6.3600000000       0.0000000000 
             Al       4.2400000000       4.2400000000       4.2400000000 
             Al       4.2400000000       6.3600000000       6.3600000000 
             Al       6.3600000000       4.2400000000       6.3600000000 
             Al       6.3600000000       6.3600000000       4.2400000000 
  End
  Lattice
         8.4800000000     0.0000000000     0.0000000000
         0.0000000000     8.4800000000     0.0000000000
         0.0000000000     0.0000000000     8.4800000000
  End
End

EOF

EMT

See the Quickstart guide.

FAIR-Chem

Tested with: AMS2025.101, Linux Mint 22, Nov 12 2024

Install FAIR-Chem in a conda environment.

# see https://fair-chem.github.io/core/install.html#conda
wget https://raw.githubusercontent.com/FAIR-Chem/fairchem/main/packages/env.gpu.yml
conda env create -f env.gpu.yml

conda run -n fair-chem \
  python -m pip install \
  fairchem-core "$AMSHOME"/scripting/wheels/*.whl

Test your installation. This will download a model file into $HOME/fairchem_pretrained_models. If the below prints an energy at the end, then your conda environment has been set up correctly:

conda run -n fair-chem \
   python $AMSHOME/scripting/scm/external_engines/backends/_fairchem/calculator.py

Run AMS with the ASE engine. Feel free to copy the calculator.py file and modify it to your needs (note: Task and System are provided in the AMS input below).

rm -rf fairchem_test.results

AMS_JOBNAME=fairchem_test $AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

System
    Atoms
        Cu       1.27632774       1.27632774       9.80500000
        Cu       3.82898322       1.27632774       9.80500000
        Cu       6.38163870       1.27632774       9.80500000
        Cu       1.27632774       3.82898322       9.80500000
        Cu       3.82898322       3.82898322       9.80500000
        Cu       6.38163870       3.82898322       9.80500000
        Cu       1.27632774       6.38163870       9.80500000
        Cu       3.82898322       6.38163870       9.80500000
        Cu       6.38163870       6.38163870       9.80500000
        Cu       0.00000000       0.00000000      11.61000000
        Cu       2.55265548       0.00000000      11.61000000
        Cu       5.10531096       0.00000000      11.61000000
        Cu       0.00000000       2.55265548      11.61000000
        Cu       2.55265548       2.55265548      11.61000000
        Cu       5.10531096       2.55265548      11.61000000
        Cu       0.00000000       5.10531096      11.61000000
        Cu       2.55265548       5.10531096      11.61000000
        Cu       5.10531096       5.10531096      11.61000000
        O        1.27632774       0.00000000      14.61000000
        C        1.27632774       0.00000000      13.45966000
    End
    Lattice
        7.66 0.0 0.0
        0.0 7.66 0.0
        0.0 0.0 20.0
    End
End

Engine ASE
    File $AMSHOME/scripting/scm/external_engines/backends/_fairchem/calculator.py
    Arguments
        model_name = "EquiformerV2-31M-S2EF-OC20-All+MD"
        # checkpoint_path = "/path/to/eqV2_31M_omat_mp_salex.pt"  # for checkpoint paths
        cpu = True
    End
    Performance DFTB
    Python
        Type Conda
        Conda fair-chem   # this environment must have been set up correctly
    End
EndEngine
eor

See the fairchem documentation and code for details.

GPAW

Tested with: AMS2023.102, Ubuntu Linux 22.04, August 1 2023

GPAW is a planewave density functional theory code.

export C_INCLUDE_PATH=$AMSBIN/python3.8/include/python3.8/
amspython -m pip install gpaw

# VENV_BIN is something like /home/user/.scm/python/AMS2023.1.venv/bin
VENV_BIN=$(dirname $(amspython -c "import sys; print(sys.executable)"))
# set TARGET_DIR appropriately
TARGET_DIR=/home/user/gpaw
# Download and install the PAW dataset
amspython $VENV_BIN/gpaw install-data $TARGET_DIR

Follow the instructions from the install-data command.

  • Download GPAW_calculator.py and place it in an easily accessible place, for example /home/user/GPAW_calculator.py.

Listing 4 GPAW_calculator.py
import numpy
import ase
import gpaw


class ASEGPAWCalculator(ase.calculators.calculator.Calculator):
    def __init__(
        self,
        pbc=[True, True, True],
        cancel_total_force=False,
        charge=0,
        name="atoms",
        **gpaw_kwargs,
    ):
        self.name = name
        self.counter = 1
        self.pbc = pbc
        self.cancel = cancel_total_force
        self._kwargs = gpaw_kwargs
        ase.calculators.calculator.Calculator.__init__(self)
        self._setup_gpaw(charge)

    def calculate(self, atoms=None, properties=None, system_changes=None):
        atoms.center()
        atoms.set_pbc(self.pbc)
        super().calculate(atoms, properties, system_changes)

        self.gpaw.calculate(atoms, properties, system_changes)
        self.results = self.gpaw.results
        # remove total force on the molecule
        if self.cancel:
            molecule_force = self.results["forces"].sum(axis=0)
            per_atom_force = molecule_force / self.results["forces"].shape[0]
            self.results["forces"] -= per_atom_force

    def _setup_gpaw(self, charge):
        self.charge = charge
        txt = self.name
        if self.counter > 1:
            txt = txt + f"_{self.counter}"
        txt = txt + ".txt"
        self.gpaw = gpaw.GPAW(txt=txt, **self._kwargs)
        self.counter += 1

    @property
    def implemented_properties(self):
        return self.gpaw.implemented_properties


# AMS looks for "get_calculator"
get_calculator = ASEGPAWCalculator

  • Run AMS with the ASE engine and specify File /path/to/GPAW_calculator.py (the path must be absolute, not relative):

Listing 5 GPAW_ams.run
AMS_JOBNAME=gpaw $AMSBIN/ams -n 1 <<EOF
properties
  gradients yes
End

system
  Atoms
   H      4.630000    5.000000    5.000000
   H      5.370000    5.000000    5.000000
  End
  Lattice
    10.0 0.0 0.0
    0.0 10.0 0.0
    0.0 0.0 10.0
  End
End

task GeometryOptimization

GeometryOptimization
  Method Quasi-Newton
  Convergence
    Gradients 0.00019446905
  End
End

Engine ASE
  File /path/to/GPAW_calculator.py
EndEngine

EOF

GPAW always requires a lattice defined in the AMS system since they are part of the basis set definition for planewaves. For non-periodic systems you can turn off periodic boundary conditions in GPAW by specifying the following block in the ASE Engine:

Arguments
    pbc = [False, False, False]
End

M3GNet

See the ML Potential documentation. This uses the Tensorflow-based implementation of M3GNet.

MACE

Tested with: AMS2025.101, Linux Mint 22, Nov 12 2024

Install mace in a conda environment.

conda create -n mace-env
conda install -c conda-forge -n mace-env "python<3.13" ase
conda run -n mace-env \
  python -m pip install \
  mace-torch "$AMSHOME"/scripting/wheels/*.whl

Test your installation. If the below prints the energy of a water molecule, then your conda environment has been set up correctly:

conda run -n mace-env \
   python $AMSHOME/scripting/scm/external_engines/backends/_mace/calculator.py

Run AMS with the ASE engine. Feel free to copy the calculator.py file and modify it to your needs (note: Task and System are provided in the AMS input below).

rm -rf mace_test.results

AMS_JOBNAME=mace_test $AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

System
    Atoms
        O 1.5 0. 0.
        C 0.0 0. 0.
        O -1.5 0. 0.
    End
End

Engine ASE
    File $AMSHOME/scripting/scm/external_engines/backends/_mace/calculator.py
    Arguments
        model_paths = None
        device = "cpu"
    End
    Python
        Type Conda
        Conda mace-env   # this environment must have been set up correctly
    End
EndEngine
eor

If you have a CUDA-enabled GPU, you can set device = "cuda" to run on the GPU instead. Or remove the option completely to use the default device.

See the mace documentation and code for details.

If you have a CUDA-enabled GPU, you can set device = "cuda" to run on the GPU instead. Or remove the option completely to use the default device.

CuEquivariance with MACE is also supported. Simply install CuEquivariance in the conda environment:

conda run -n mace-env \
  python -m pip install \
  cuequivariance-torch cuequivariance-ops-torch-cu12

Or use cuequivariance-ops-torch-cu11 for CUDA 11. Next add enable_cueq = True to the Arguments block. We observed a speedup of 10-20% and a reduction in memory usage of 50% for a 25x25x25 angstrom water box.

See the mace documentation and code for details.

MatGL

Note

To use the AMS-bundled version of M3GNet, see M3GNet.

MatGL reimplements M3GNet in PyTorch. To use this implementation (and separate parametrization), you need to run at least Python 3.9.

This can be done by using a separate Python environment for the ASE calculator.

Tested with: AMS2025.101, Ubuntu Linux 22.04, November 14 2024

conda create -n matgl-env
conda install -c conda-forge -n matgl-env "python<3.13" ase matgl
conda run -n matgl-env \
  python -m pip install \
  "$AMSHOME"/scripting/wheels/*.whl

Test your installation. If the below prints the energy of a water molecule, then your conda environment has been set up correctly:

conda run -n matgl-env \
   python $AMSHOME/scripting/scm/external_engines/backends/_matgl/calculator.py

Run AMS with the ASE engine. Feel free to copy the calculator.py file and modify it to your needs (note: Task and System are provided in the AMS input below).

rm -rf matgl_test.results

AMS_JOBNAME=matgl_test $AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

System
    Atoms
        O 1.5 0. 0.
        C 0.0 0. 0.
        O -1.5 0. 0.
    End
End

Engine ASE
    File $AMSHOME/scripting/scm/external_engines/backends/_matgl/calculator.py
    Arguments
        model = "M3GNet-MP-2021.2.8-PES"
    End
    Python
        Type Conda
        Conda matgl-env   # this environment must have been set up correctly
    End
EndEngine
eor

See the matgl documentation and code for details.

MatterSim

Tested with: AMS2025.101, Ubuntu Linux 24.04, Dec 4 2024 and Apple M2, Jan 29 2025

Install mattersim in a conda environment.

conda create -n mattersim-env python=3.9
conda run -n mattersim-env \
  python -m pip install \
  mattersim "$AMSHOME"/scripting/wheels/*.whl

Test your installation. If the below prints the energy of Si bulk, then your conda environment has been set up correctly:

conda run -n mattersim-env \
  python $AMSHOME/scripting/scm/external_engines/backends/_mattersim/calculator.py

Run AMS with the ASE engine. Feel free to copy the calculator.py file and modify it to your needs (note: Task and System are provided in the AMS input below).

rm -rf mattersim_test.results

AMS_JOBNAME=mattersim_test $AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

System
    Atoms
        Si -0.67875 -0.67875 -0.67875
        Si 0.77875 0.67875 0.67875
    End
    Lattice
        0.0 2.715 2.715
        2.715 0.0 2.715
        2.715 2.715 0.0
    End
End

Engine ASE
    File $AMSHOME/scripting/scm/external_engines/backends/_mattersim/calculator.py
    Arguments
        device = "cpu"
        load_path = "MatterSim-v1.0.0-5M.pth"
    End
    Python
        Type Conda
        Conda mattersim-env   # this environment must have been set up correctly
    End
EndEngine
eor

If you have a CUDA-enabled GPU, you can set device = "cuda" to run on the GPU instead. Or remove the option completely to use the default device.

See the Mattersim documentation and code for details.

NequIP

See the ML Potential documentation.

Open Catalyst Project

See FAIR-Chem.

OpenKIM

Tested with: AMS2025.101, Linux Mint 22, April 15 2025

See also: https://openkim.org/browse/models/alphabetical

Install OpenKIM into a separate conda environment:

You need to also download the model that you want to use. Here, we use a MEAM potential for Cu/Ti/N, see

conda create -n kim-env
conda install -c conda-forge -n kim-env "python<3.13" ase kim-api kimpy
conda run -n kim-env kim-api-collections-management install user MEAM_LAMMPS_MirazDhariwalMeng_2020_CuNTi__MO_122936827583_002
conda run -n kim-env python -m pip install "$AMSHOME"/scripting/wheels/*.whl

Test your installation. If the below prints the energy of Cu bulk, then your conda environment and OpenKIM model have been set up correctly:

conda run -n kim-env \
   python $AMSHOME/scripting/scm/external_engines/backends/_kim/calculator.py

Run AMS with the ASE engine.

rm -rf kim_test.results

AMS_JOBNAME=kim_test $AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

Properties
    ElasticTensor Yes
End

GeometryOptimization
    OptimizeLattice Yes
    Convergence
        Quality Good
    End
End

System
    Atoms
        Ti 0.0 0.0 0.0
        N 2.12 2.12 2.12
    End
    Lattice
        0.0 2.12 2.12
        2.12 0.0 2.12
        2.12 2.12 0.0
    End
End

Engine ASE
    Type Import
    Import ase.calculators.kim.KIM
    Arguments
        model_name = "MEAM_LAMMPS_MirazDhariwalMeng_2020_CuNTi__MO_122936827583_002"
    End
    Python
        Type Conda
        Conda kim-env
    End
EndEngine
eor

See the OpenKIM documentation for details.

ORB

A universal potential for materials.

Tested with: AMS2024.104, Ubuntu Linux 22.04, Jan 7 2025 and and Apple M2, Jan 29 2025

Install orb-models into a separate conda environment:

conda create -n orb-env
conda install -c conda-forge -n orb-env "python<3.13" ase
conda run -n orb-env \
  python -m pip install \
  orb-models "$AMSHOME"/scripting/wheels/*.whl
conda run -n orb-env \
  python -m pip install "pynanoflann@git+https://github.com/dwastberg/pynanoflann#egg=af434039ae14bedcbb838a7808924d6689274168"

Test your installation. If the below prints the energy of a water molecule, then your conda environment has been set up correctly:

conda run -n orb-env \
   python $AMSHOME/scripting/scm/external_engines/backends/_orb/calculator.py

Run AMS with the ASE engine. Feel free to copy the calculator.py file and modify it to your needs (note: Task and System are provided in the AMS input below).

rm -rf orb_test.results

AMS_JOBNAME=orb_test $AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

System
    Atoms
        O 1.5 0. 0.
        C 0.0 0. 0.
        O -1.5 0. 0.
    End
End

Engine ASE
    File $AMSHOME/scripting/scm/external_engines/backends/_orb/calculator.py
    Arguments
        device = "cpu"
    End
    Python
        Type Conda
        Conda orb-env   # this environment must have been set up correctly
    End
EndEngine
eor

If you have a CUDA-enabled GPU, you can set device = "cuda" to run on the GPU instead. Or remove the option completely to use the default device.

See the orb documentation and code for details.

psi4

Tested with AMS2025.101, Ubuntu Linux 22.04, September 25 2024

Install psi4 into a separate conda environment:

conda create -n psi4-env
conda install -c conda-forge -n psi4-env "python<3.13" ase psi4 simple-dftd3 dftd3-python dftd4 dftd4-python gcp-correction
conda run -n psi4-env \
  python -m pip install \
  "$AMSHOME"/scripting/wheels/*.whl

Test your installation. If the below prints the energy of a water molecule, then your conda environment has been set up correctly:

conda run -n psi4-env \
   python $AMSHOME/scripting/scm/external_engines/backends/_psi4/calculator.py

Run AMS with the ASE engine. Feel free to copy the calculator.py file and modify it to your needs (note: Task and System are provided in the AMS input below).

rm -rf psi4_test.results

AMS_JOBNAME=psi4_test $AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

System
    Atoms
        O 1.5 0. 0.
        C 0.0 0. 0.
        O -1.5 0. 0.
    End
End

Engine ASE
  Type File
  File $AMSHOME/scripting/scm/external_engines/backends/_psi4/calculator.py
  Arguments
    method = 'b3lyp'
    basis = '6-31G*'
    num_threads = 'max'  # or set to a number
  End
  Performance DFT
  Python
      Type Conda
      Conda psi4-env   # this environment must have been set up correctly
  End
EndEngine
eor

See the psi4 documentation and code for details.

PySCF

Tested with: AMS2025.101, Ubuntu Linux 22.04, November 14 2024

Install PySCF into a separate conda environment:

conda create -n pyscf-env
conda install -c conda-forge -n pyscf-env "python<3.13"
conda run -n pyscf-env \
  python -m pip install --prefer-binary \
  pyscf ase "$AMSHOME"/scripting/wheels/*.whl

Test your installation. If the below prints the energy of a water molecule, then your conda environment has been set up correctly:

conda run -n pyscf-env \
   python $AMSHOME/scripting/scm/external_engines/backends/_pyscf/calculator.py

Run AMS with the ASE engine. Feel free to copy the calculator.py file and modify it to your needs (note: Task and System are provided in the AMS input below).

rm -rf pyscf_test.results

AMS_JOBNAME=pyscf_test $AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

System
    Atoms
        O 1.5 0. 0.
        C 0.0 0. 0.
        O -1.5 0. 0.
    End
End

Engine ASE
  Type File
  File $AMSHOME/scripting/scm/external_engines/backends/_pyscf/calculator.py
  Arguments
    xc = 'pbe'
    basis = '631g*'
  End
  Performance DFT
  Python
    Type Conda
    Conda pyscf-env   # this environment must have been set up correctly
  End
EndEngine
eor

See the pyscf documentation and code for details.

Quantum ESPRESSO

See the Quantum ESPRESSO documentation.

sGDML

See the ML Potential documentation.

SO3LR

Tested with: AMS2025.101, Ubuntu Linux 24.04, Dec 4 2024

Install so3lr in a conda environment.

conda create -n so3lr-env
conda install -c conda-forge -n so3lr-env "python<3.13" ase
conda run -n so3lr-env \
  python -m pip install \
  git+https://github.com/general-molecular-simulations/so3lr \
  "$AMSHOME"/scripting/wheels/*.whl

Test your installation. If the below prints the energy of a water molecule, then your conda environment has been set up correctly:

conda run -n so3lr-env \
  python $AMSHOME/scripting/scm/external_engines/backends/_so3lr/calculator.py

Run AMS with the ASE engine. Feel free to copy the calculator.py file and modify it to your needs (note: Task and System are provided in the AMS input below).

rm -rf so3lr_test.results

AMS_JOBNAME=so3lr_test $AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

System
    Atoms
        O 1.5 0. 0.
        C 0.0 0. 0.
        O -1.5 0. 0.
    End
    Lattice
        25.0 0.0 0.0
        0.0 25.0 0.0
        0.0 0.0 25.0
    End
End

Engine ASE
    File $AMSHOME/scripting/scm/external_engines/backends/_so3lr/calculator.py
    Arguments
        calculate_stress = False
        lr_cutoff = 12.0
    End
    Python
        Type Conda
        Conda so3lr-env   # this environment must have been set up correctly
    End
EndEngine
eor

If you have a CUDA-enabled GPU, you can set device = "cuda" to run on the GPU instead. Or remove the option completely to use the default device.

See the so3lr documentation and code for details.

tblite

Tested with: AMS2025.101, Linux Mint 22, Nov 12 2024

Install tblite in a conda environment.

conda create -n tblite-env
conda install -c conda-forge -n tblite-env "python<3.13" ase tblite tblite-python dftd4
conda run -n tblite-env \
  python -m pip install \
  "$AMSHOME"/scripting/wheels/*.whl

Test your installation. If the below prints the energy of a water molecule, then your conda environment has been set up correctly:

conda run -n tblite-env \
   python "$AMSHOME/scripting/scm/external_engines/backends/_tblite/calculator.py"

Run AMS with the ASE engine. Feel free to copy the calculator.py file and modify it to your needs (note: Task and System are provided in the AMS input below).

rm -rf tblite_test.results

# tip: copy-paste this input into AMSinput to use the GUI
AMS_JOBNAME=tblite_test $AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

System
    Atoms
        O 1.5 0. 0.
        C 0.0 0. 0.
        O -1.5 0. 0.
    End
End

Engine ASE
    Type Import
    Import tblite.ase.TBLite
    Arguments
        method = "GFN2-xTB"
    End
    Python
        Type Conda
        Conda tblite-env   # this environment must have been set up correctly
    End
EndEngine
eor

See the tblite documentation and code for details.

VASP

See the VASP via AMS documentation.

xTB (GFN2-xTB)

See tblite