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, AMS, Asap, BigDFT, DeePMD-kit, DFTD3, DFTD4, DFTK, FLEUR, GPAW, Hotbit, 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

AMS

Amsterdam Modeling Suite

Asap

Highly efficient EMT code

BigDFT

Wavelet based code for DFT

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

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

As of November 2023, there are two ways in which a calculator can be implemented:

  • a modern way – subclassing a Calculator class from ase.calculators.genericfileio.GenericFileIOCalculator (calculators implemented in such a way are ABINIT, FHI-Aims, Quantum ESPESSO, EXCITING, Octopus and Orca; there are plans to gradually rewrite the remaining calculators as well);

  • a somewhat conservative way, subclassing it from ase.calculators.calculator.FileIOCalculator.

The calculators that are implemented in the modern way can be configured using the config file. It should have a \(.ini\) format and reside in a place specified by ASE_CONFIG_PATH environmental variable. If the variable is not set, then the default path is used, which is ~/.config/ase/config.ini.

The config file should have a [parallel] section, which defines the machine-specific parallel environment, and the calculator sections, that define the machine-specific calculator parameters, like binary and pseudopotential locations. The parallel section should have a binary option, which should point to the name of the parallel runner binary file, like \(mpirun\) or \(mpiexec\). Then the Calculator class instance can be initialized with parallel=True keyword. This allows running the calculator code in parallel. The additional keywords to the parallel runner can be specified with parallel_info=<dict> keyword, which gets translated to the list of flags and their values passed to the parallel runner. Translation keys can be specified in the [parallel] section with the syntax key_kwarg_trans = command e.g if nprocs_kwarg_trans = -np is specified in the config file, then the key nprocs will be translated to -np. Then \(nprocs\) can be specified in parallel_info and will be translated to \(-np\) when the command is build.

The example of a config file is as follows:

[parallel]
binary = mpirun
nprocs_kwarg_trans = -np

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

Then the \(espresso\) calculator can be 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'},
                   parallel=True,
                   parallel_info={'nprocs': 4}
                   )
>>> si = bulk('Si')
>>> si.calc = espresso
>>> si.get_potential_energy()
-244.76638508140397

Here espresso ran in parallel with 4 processes and produced a correct result.

Calculator keywords

Example for a hypothetical ABC calculator:

ABC(restart=None, ignore_bad_restart_file=False, label=None,
atoms=None, parameters=None, command='abc > PREFIX.abc',
xc=None, kpts=[1, 1, 1], smearing=None,
charge=0.0, nbands=None, **kwargs)

Create ABC calculator

restart: str

Prefix for restart file. May contain a directory. Default is None: don’t restart.

ignore_bad_restart_file: bool

Ignore broken or missing restart file. By default, it is an error if the restart file is missing or broken.

label: str

Name used for all files. May contain a directory.

atoms: Atoms object

Optional Atoms object to which the calculator will be attached. When restarting, atoms will get its positions and unit-cell updated from file.

command: str

Command used to start calculation. This will override any value in an ASE_ABC_COMMAND environment variable.

parameters: str

Read parameters from file.

xc: str

XC-functional ('LDA', 'PBE', …).

kpts:

Brillouin zone sampling:

  • (1,1,1): Gamma-point

  • (n1,n2,n3): Monkhorst-Pack grid

  • (n1,n2,n3,'gamma'): Shifted Monkhorst-Pack grid that includes \(\Gamma\)

  • [(k11,k12,k13),(k21,k22,k23),...]: Explicit list in units of the reciprocal lattice vectors

  • kpts=3.5: \(\vec k\)-point density as in 3.5 \(\vec k\)-points per Å\(^{-1}\).

smearing: tuple

The smearing of occupation numbers. Must be a tuple:

  • ('Fermi-Dirac', width)

  • ('Gaussian', width)

  • ('Methfessel-Paxton', width, n), where \(n\) is the order (\(n=0\) is the same as 'Gaussian')

Lower-case names are also allowed. The width parameter is given in eV units.

charge: float

Charge of the system in units of \(|e|\) (charge=1 means one electron has been removed). Default is charge=0.

nbands: int

Number of bands. Each band can be occupied by two electrons.

Not all of the above arguments make sense for all of ASE’s calculators. As an example, Gromacs will not accept DFT related keywords such as xc and smearing. In addition to the keywords mentioned above, each calculator may have native keywords that are specific to only that calculator.

Keyword arguments can also be set or changed at a later stage using the set() method:

ase.calculators.set(key1=value1, key2=value2, ...)