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:

Abacus, ALIGNN, AMS, Asap, BigDFT, CHGNet, DeePMD-kit, DFTD3, DFTD4, DFTK, EquiFormerV2, FLEUR, GPAW, Hotbit, M3GNet, MACE, OrbModels, SevenNet, TBLite, and XTB have their own native or external ASE interfaces.
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.
Pure python implementations included in the ASE package: EMT, EAM, Lennard-Jones, Morse, Tersoff, and HarmonicCalculator.
Calculators that wrap others, included in the ASE package:

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
EquiFormerV2	Equivariant graph-based denoising transformer universal potential
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
OrbModels	Fast, scalable, universal GNN potentials with diffusion pretraining
SevenNet	Scalable EquiVariance Enabled Neural Network interatomic potential
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
`tersoff`	Tersoff bond-order potential
`vasp`	Plane-wave PAW code
`emt`	Effective Medium Theory calculator
lj	Lennard-Jones potential
morse	Morse potential
`checkpoint`	Checkpoint calculator
`fd`	Finite-difference calculator
`loggingcalc`	Logging calculator
`socketio`	Socket-based interface to calculators
`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.