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 |
|---|---|---|---|
ML Potential |
ML Potential |
||
ASE |
ML potential |
||
ML potential |
|||
ASE |
ML potential |
||
ASE |
DFT |
||
ASE |
Custom |
||
ASE |
ML potential |
||
ASE |
orbital-free DFT |
||
ASE |
Force field |
||
ASE |
ML Potential |
||
ASE |
DFT |
||
ASE |
ML Potential |
||
ASE |
ML potential |
||
ASE |
ML potential |
||
ML potential |
|||
ML potential |
|||
ASE |
ML potential |
||
ASE |
Force fields |
||
ASE |
ML Potential |
||
ASE |
DFT/ab initio |
||
ASE |
DFT/ab initio |
||
DFT |
|||
ML potential |
|||
ASE |
ML potential |
||
ASE |
semi-empirical |
||
DFT |
|||
ASE |
semi-empirical |
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 cp2kRun AMS with the CP2K ASE calculator
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.
#!/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-kitinto the AMS python environment. This will place thedbbinary in a location like/home/user/.scm/python/AMS2023.1.venv/binEither 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:
#!/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/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.
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.pyand place it in an easily accessible place, for example/home/user/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):
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