Examples¶

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

Please note the following important points for the ASE examples:

The external programs and packages are not developed, maintained, or endorsed by SCM.
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 software’s license terms.
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.
For questions or issues, 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.103, Linux Mint 22, June 4 2024

Note: Updated instructions for FAIR-Chem v2. Requires AMS2025.104 or later.

FAIR-Chem Github
FAIR-Chem Installation instructions
FAIR-Chem Using pretrained models with ASE

Install FAIR-Chem in a conda environment.

conda create -n fairchem2-env
conda install -c conda-forge -n fairchem2-env "python<3.13"
conda run -n fairchem2-env \
  python -m pip install \
  fairchem-core==2.2.0 "$AMSHOME"/scripting/wheels/*.whl

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

Note: You may need to request access to the model files on Huggingface.

conda run -n fairchem2-env \
   python $AMSHOME/scripting/scm/external_engines/backends/_fairchem2/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).

The FAIRChem UMA model works by specifying a task_name. This is not related to the AMS Task input keyword.

“oc20”: use this for catalysis
“omat”: use this for inorganic materials
“omol”: use this for molecules
“odac”: use this for MOFs
“omc”: use this for molecular crystals

FAIRChem example 1: adsorbate on surface

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/_fairchem2/calculator.py
    Arguments
        model_name = "uma-s-1"
        task_name = "oc20"
        device = "cpu"
    End
    Python
        Type Conda
        Conda fairchem2-env   # this environment must have been set up correctly
    End
EndEngine
eor

FAIRChem example 2: Is the singlet or triplet O2 most stable?

rm -rf fairchem_spin1.results fairchem_spin3.results

for spin in 1 3; do

AMS_JOBNAME=fairchem_spin${spin} $AMSBIN/ams -n 1 <<eor
Task GeometryOptimization
System
  Atoms
    O 0. 0. -0.6
    O 0. 0. 0.6
  End
End
Engine ASE
    File $AMSHOME/scripting/scm/external_engines/backends/_fairchem2/calculator.py
    Arguments
        model_name = "uma-s-1"
        task_name = "omol"
        device = "cpu"
        spin = $spin
    End
    Python Type=Conda Conda=fairchem2-env   # this environment must have been set up correctly
EndEngine
eor
done

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.

Install GPAW into the AMS python environment from PyPI after installing all the requirements:

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

Download and install the PAW datasets:

# 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

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

Electronic Structure

ADF

Periodic DFT

DFTB & MOPAC

Interatomic Potentials

ReaxFF

Machine Learning Potentials

Force Fields

kMC and Microkinetics

Bumblebee: OLED stacks

Fluid Thermodynamics

COSMO-RS

Workflows and Utilities

OLED workflows

ChemTraYzer2

Conformers

Reactions Discovery

AMS Driver

Properties

PES Exploration

Molecular Dynamics

Monte Carlo

Interfaces

ParAMS

PLAMS

GUI

VASP

Downloads

Windows

Mac

Linux

Documentation

Overview

Tutorials

Installation Manual

Brochures

Other Resources

Changelog

Webinars

Workshops

Knowledgebank

FAQ

Pricing and licensing

Examples¶

Overview of external methods/programs¶

AIMNet2¶

ALIGNN-FF¶

ANI (TorchANI)¶

CHGNet¶

CP2K¶

Custom¶

DeePMD-kit¶

DFTpy¶

EMT¶

FAIR-Chem¶

GPAW¶

M3GNet¶

MACE¶

MatGL¶

MatterSim¶

NequIP¶

Open Catalyst Project¶

OpenKIM¶

ORB¶

psi4¶

PySCF¶

Quantum ESPRESSO¶

sGDML¶

SO3LR¶

tblite¶

VASP¶

xTB (GFN2-xTB)¶