Examples¶

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

The instructions provided in this documentation are intended to guide users on how to couple external software or tools with AMS. Please note the following important points:

External Software: The external programs and packages referenced in this documentation are not developed, maintained, or endorsed by SCM.
Installation and Use: Users are responsible for the installation, configuration, and management of any external software or 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.
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.
Support: For questions or issues related to the external software, users should contact the respective developers or refer to their official documentation.

By proceeding to integrate external software with AMS, you acknowledge and accept these terms.

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
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
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: AMS2023.101, Ubuntu Linux 22.04, July 19 2023

SCM → Packages, select CUDA or CPU under ML options
Install TorchANI (will install PyTorch)
Install DGL into the AMS python environment using instructions from https://www.dgl.ai/pages/start.html. For example (depending on CUDA version):

amspython -m pip install  dgl -f https://data.dgl.ai/wheels/cu117/repo.html
amspython -m pip install  dglgo -f https://data.dgl.ai/wheels-test/repo.html

If there’s an error about the pydantic version, then do amspython -m pip uninstall pydantic followed by amspython -m pip install pydantic==1.8.0
Install ALIGNN: amspython -m pip install alignn
Place the following file in an easily accessible place, for example /home/user/alignn_ams.py:

from alignn.ff.ff import AlignnAtomwiseCalculator, default_path
import numpy as np


class MyCalculator(AlignnAtomwiseCalculator):
    def calculate(self, atoms, properties, system_changes):
        if sum(atoms.get_pbc()) == 0:
            delta = np.max(atoms.get_positions()) - np.min(atoms.get_positions())
            atoms.set_cell([delta + 10, delta + 10, delta + 10])

        return super().calculate(atoms, properties, system_changes)


def get_calculator(path: str = None):
    if path is None:
        path = default_path()

    return MyCalculator(path=path)

Specify Type File and File /path/to/alignn_ams.py in the Engine ASE block:

Listing 1 alignn_ams.run¶

#!/bin/sh

$AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

System
    Atoms
        O 0. 0. 0.
        H 1. 0. 0.
        H -0.7 0.7 0.
    End
End

Engine ASE
    Type File
    File /path/to/alignn_ams.py
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 ase
conda run -n chgnet-env \
  python -m pip install \
  chgnet "$AMSHOME/scripting/scm/amspipe" "$AMSHOME/scripting/scm/external_engines"

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 2 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

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

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

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/scm/amspipe" "$AMSHOME/scripting/scm/external_engines"

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.

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 ase
conda run -n mace-env \
  python -m pip install \
  mace-torch "$AMSHOME/scripting/scm/amspipe" "$AMSHOME/scripting/scm/external_engines"

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.

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 ase matgl
conda run -n matgl-env \
  python -m pip install \
  "$AMSHOME/scripting/scm/amspipe" "$AMSHOME/scripting/scm/external_engines"

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

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/scm/amspipe" "$AMSHOME/scripting/scm/external_engines"

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"
    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.

ORB¶

A universal potential for materials.

Tested with: AMS2024.104, Ubuntu Linux 22.04, 22 Oct 2024

SCM → Packages, select CUDA or CPU under ML options if available.
Install TorchANI (will install PyTorch)
Run the following commands in a terminal:

$AMSBIN/amspython -m pip install "cached_path>=1.6.2" "dm-tree>=0.1.8" "protobuf==3.20"
$AMSBIN/amspython -m pip install orb-models==0.4.0 --no-dependencies
FILE=`$AMSBIN/amspython -c "import orb_models; import os; print(f'{os.path.dirname(orb_models.__file__)}/forcefield/featurization_utilities.py')"`
echo "Patching $FILE"
sed '/from pynanoflann/d; s/= "pynanoflann"/= "scipy"/' "$FILE" > temp.txt
mv temp.txt "$FILE"
FILE=`$AMSBIN/amspython -c "import orb_models; import os; print(f'{os.path.dirname(orb_models.__file__)}/forcefield/graph_regressor.py')"`
echo "Patching $FILE"
sed 's/nopbc_graph =.*/nopbc_graph = torch.all(torch.all(cell == 0.0, dim=2), dim=1)/' "$FILE" > temp.txt
mv temp.txt "$FILE"

The last Python command removes the dependence on pynanoflann, for simplicity.

Create a file called orb_ams.py:

#!/usr/bin/env amspython

from orb_models.forcefield import pretrained
from orb_models.forcefield.calculator import ORBCalculator
from orb_models.forcefield.pretrained import ORB_PRETRAINED_MODELS

def get_calculator(model: str = "orb-v2", device: str = "cpu") -> ORBCalculator:
    """
    model: str
        One of the keys in ORB_PRETRAINED_MODELS.

    device: str
        "cpu" or "cuda"
    """

    if model not in ORB_PRETRAINED_MODELS:
        raise ValueError(f"Unknown model: {model}")
    calc = ORBCalculator(ORB_PRETRAINED_MODELS[model](), device=device)  # or device="cuda"

    return calc

if __name__ == "__main__":
    from ase.build import molecule
    mol = molecule("H2O")
    mol.calc = get_calculator()
    print(mol.get_potential_energy())
    print(ORB_PRETRAINED_MODELS)

Check your installation by running:

$AMSBIN/amspython /path/to/orb_ams.py

If it does not report any fatal errors, then ORB has been installed correctly.

Then run AMS and specify the path to this file in the Engine ASE block:

#!/bin/sh

$AMSBIN/ams -n 1 <<eor
Task GeometryOptimization

System
    Atoms
        O 0. 0. 0.
        H 1. 0. 0.
        H -0.7 0.7 0.
    End
End

Engine ASE
    File /path/to/orb_ams.py
    Arguments
        model = "orb-v2"   # default
        device = "cpu"  # or "cuda"
    End
EndEngine
eor

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 ase psi4 simple-dftd3 dftd3-python dftd4 dftd4-python gcp-correction
conda run -n psi4-env \
  python -m pip install \
  "$AMSHOME/scripting/scm/amspipe" "$AMSHOME/scripting/scm/external_engines"

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
conda run -n pyscf-env \
  python -m pip install --prefer-binary \
  pyscf ase "$AMSHOME/scripting/scm/amspipe" "$AMSHOME/scripting/scm/external_engines"

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.

Open Catalyst Project¶

See FAIR-Chem.

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/scm/amspipe" "$AMSHOME/scripting/scm/external_engines"

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 ase tblite tblite-python dftd4
conda run -n tblite-env \
  python -m pip install \
  "$AMSHOME/scripting/scm/amspipe" "$AMSHOME/scripting/scm/external_engines"

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

Workshops

Knowledgebank

FAQ

Pricing and licensing

Examples¶

Overview of external methods/programs¶

AIMNet2¶

ALIGNN-FF¶

ANI (TorchANI)¶

CHGNet¶

CP2K¶

DeePMD-kit¶

DFTpy¶

EMT¶

FAIR-Chem¶

GPAW¶

M3GNet¶

MACE¶

MatGL¶

MatterSim¶

NequIP¶

ORB¶

psi4¶

PySCF¶

Open Catalyst Project¶

Quantum ESPRESSO¶

sGDML¶

SO3LR¶

tblite¶

VASP¶

xTB (GFN2-xTB)¶