Calculators

For ASE, a calculator is a black box that can take atomic numbers and atomic positions from an Atoms object and calculate the energy and forces and sometimes also stresses.

In order to calculate forces and energies, you need to attach a calculator object to your atoms object:

>>> atoms = read('molecule.xyz')
>>> e = atoms.get_potential_energy()  
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/jjmo/ase/atoms/ase.py", line 399, in get_potential_energy
    raise RuntimeError('Atoms object has no calculator.')
RuntimeError: Atoms object has no calculator.
>>> from ase.calculators.abinit import Abinit
>>> calc = Abinit(...)
>>> atoms.calc = calc
>>> e = atoms.get_potential_energy()
>>> print(e)
-42.0

Here we attached an instance of the ase.calculators.abinit class and then we asked for the energy.

Supported calculators

The calculators can be divided in four groups:

  1. Abacus, ALIGNN, AMS, Asap, BigDFT, CHGNet, DeePMD-kit, DFTD3, DFTD4, DFTK, FLEUR, GPAW, Hotbit, M3GNet, MACE, TBLite, and XTB have their own native or external ASE interfaces.

  2. ABINIT, AMBER, CP2K, CASTEP, deMon2k, DFTB+, ELK, EXCITING, FHI-aims, GAUSSIAN, Gromacs, LAMMPS, MOPAC, NWChem, Octopus, ONETEP, PLUMED, psi4, Q-Chem, Quantum ESPRESSO, SIESTA, TURBOMOLE and VASP, have Python wrappers in the ASE package, but the actual FORTRAN/C/C++ codes are not part of ASE.

  3. Pure python implementations included in the ASE package: EMT, EAM, Lennard-Jones, Morse and HarmonicCalculator.

  4. Calculators that wrap others, included in the ASE package: ase.calculators.checkpoint.CheckpointCalculator, the ase.calculators.loggingcalc.LoggingCalculator, the ase.calculators.mixing.LinearCombinationCalculator, the ase.calculators.mixing.MixedCalculator, the ase.calculators.mixing.SumCalculator, the ase.calculators.mixing.AverageCalculator, the ase.calculators.socketio.SocketIOCalculator, the Grimme-D3 potential, and the qmmm calculators EIQMMM, and SimpleQMMM.

name

description

Abacus

DFT supporting both pw and lcao basis

ALIGNN

Atomistic Line Graph Neural Network force field

AMS

Amsterdam Modeling Suite

Asap

Highly efficient EMT code

BigDFT

Wavelet based code for DFT

CHGNet

Universal neural network potential for charge-informed atomistics

DeePMD-kit

A deep learning package for many-body potential energy representation

DFTD3

London-dispersion correction

DFTD4

Charge-dependent London-dispersion correction

DFTK

Plane-wave code for DFT and related models

FLEUR

Full Potential LAPW code

GPAW

Real-space/plane-wave/LCAO PAW code

Hotbit

DFT based tight binding

M3GNet

Materials 3-body Graph Network universal potential

MACE

Many-body potential using higher-order equivariant message passing

TBLite

Light-weight tight-binding framework

XTB

Semiemprical extended tight-binding program package

abinit

Plane-wave pseudopotential code

amber

Classical molecular dynamics code

castep

Plane-wave pseudopotential code

cp2k

DFT and classical potentials

demon

Gaussian based DFT code

demonnano

DFT based tight binding code

dftb

DFT based tight binding

dmol

Atomic orbital DFT code

eam

Embedded Atom Method

elk

Full Potential LAPW code

espresso

Plane-wave pseudopotential code

exciting

Full Potential LAPW code

aims

Numeric atomic orbital, full potential code

gamess_us

Gaussian based electronic structure code

gaussian

Gaussian based electronic structure code

gromacs

Classical molecular dynamics code

gulp

Interatomic potential code

harmonic

Hessian based harmonic force-field code

kim

Classical MD with standardized models

lammps

Classical molecular dynamics code

mixing

Combination of multiple calculators

mopac

Semiempirical molecular orbital code

nwchem

Gaussian based electronic structure code

octopus

Real-space pseudopotential code

onetep

Linear-scaling pseudopotential code

openmx

LCAO pseudopotential code

orca

Gaussian based electronic structure code

plumed

Enhanced sampling method library

psi4

Gaussian based electronic structure code

qchem

Gaussian based electronic structure code

siesta

LCAO pseudopotential code

turbomole

Fast atom orbital code

vasp

Plane-wave PAW code

emt

Effective Medium Theory calculator

lj

Lennard-Jones potential

morse

Morse potential

checkpoint

Checkpoint calculator

socketio

Socket-based interface to calculators

loggingcalc

Logging calculator

dftd3

DFT-D3 dispersion correction calculator

EIQMMM

Explicit Interaction QM/MM

SimpleQMMM

Subtractive (ONIOM style) QM/MM

Note

A Fortran implemetation of the Grimme-D3 potential, that can be used as an add-on to any ASE calculator, can be found here: https://gitlab.com/ehermes/ased3/tree/master.

The calculators included in ASE are used like this:

>>> from ase.calculators.abc import ABC
>>> calc = ABC(...)

where abc is the module name and ABC is the class name.

Calculator configuration

Calculators that depend on external codes or files are generally configurable. ASE loads the configuration from a configfile located at ~/.config/ase/config.ini. The default path can be overriden by setting the environment variable ASE_CONFIG_PATH to another path or paths separated by colon.

To see the full configuration on a given machine, run ase info --calculators.

An example of a config file is as follows:

[abinit]
command = mpiexec /usr/bin/abinit
pp_paths = /usr/share/abinit/pseudopotentials

[espresso]
command = mpiexec pw.x
pseudo_path = /home/ase/upf_pseudos

Calculators build a full command by appending command-line arguments to the configured command. Therefore, the command should normally consist of any parallel arguments followed by the binary, but should not include further flags unless desired for a specific reason. The command is also used to build a full command for e.g. socket I/O calculators.

The Espresso calculator can then invoked in the following way:

>>> from ase.build import bulk
>>> from ase.calculators.espresso import Espresso
>>> espresso = Espresso(
                   input_data = {
                        'system': {
                           'ecutwfc': 60,
                        }},
                   pseudopotentials = {'Si': 'si_lda_v1.uspp.F.UPF'},
                   )
>>> si = bulk('Si')
>>> si.calc = espresso
>>> si.get_potential_energy()
-244.76638508140397

It can be useful for software libraries to override the local configuration. To do so, the code should supply the configurable information by instantiating a “profile”, e.g., Abinit(profile=AbinitProfile(command=command)). The profile encloses the configurable information specific to a particular code, so this may differ depending on which code. It can also be useful for software libraries that manage their own configuration to set the ASE_CONFIG_PATH to an empty string.