Skip to main content
`Ctrl`+`K`

# 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, EquiFormerV2, FLEUR, GPAW, Hotbit, M3GNet, MACE, OrbModels, SevenNet, 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, Tersoff, and HarmonicCalculator.

4. Calculators that wrap others, included in the ASE package:

   - `ase.calculators.checkpoint.CheckpointCalculator`

   - `ase.calculators.fd.FiniteDifferenceCalculator`

   - `ase.calculators.loggingcalc.LoggingCalculator`

   - `ase.calculators.mixing.LinearCombinationCalculator`

   - `ase.calculators.mixing.MixedCalculator`

   - `ase.calculators.mixing.SumCalculator`

   - `ase.calculators.mixing.AverageCalculator`

   - `ase.calculators.socketio.SocketIOCalculator`

   - Grimme-D3 potential

   - QM/MM calculators

     - `EIQMMM`

     - `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
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: 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.

- EAM
- Pure Python EMT calculator
- ABINIT
- Amber
- CASTEP
- CP2K
- CRYSTAL14
- Demon
- deMon-Nano
- DFTB+
- DMol3
- Elk
- Espresso
- exciting
- FHI-aims
- FLEUR
- GAMESS-US
- Gaussian
- Gromacs
- GULP
- Harmonic calculator
- Communication with calculators over sockets
- Jacapo - ASE python interface for Dacapo
- KIM
- LAMMPS Calculators
- Mopac
- NWChem
- Octopus
- ONETEP
- OpenMX
- ORCA
- PLUMED
- psi4
- Q-Chem
- SIESTA
- TURBOMOLE
- Tersoff Calculator
- VASP
- QMMM
- Checkpointing
- Finite-Difference Calculator
- Logging Calculator
- Mixing Calculators
- DFT-D3
- Other built-in calculators
- Stuff for testing things
- ACE-Molecule