index | modules | gitlab | page source

# 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`

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

- EAM
  - Introduction
  - Theory
  - Running the Calculator
  - Arguments
  - Additional parameters for writing potential files
  - Special features
  - Notes/Issues
  - Example:
- Pure Python EMT calculator
  - `EMT`
  - Theory
    - Energy
    - Forces
    - Stress
    - Tips
- ABINIT
  - Introduction
  - Environment variables
  - ABINIT Calculator
  - Pseudopotentials
- Amber
  - Introduction
  - Water example
- CASTEP
  - Introduction
  - Getting Started:
  - Running the Calculator
    - `Castep`
  - Arguments:
  - Additional Settings
  - Special features:
  - Notes/Issues:
  - Example:
- CP2K
  - `CP2K`
- CRYSTAL14
  - Introduction
  - Environment variables
  - CRYSTAL Calculator (a FileIOCalculator)
  - Exchange-correlation functionals
  - Setups
  - Spin-polarized calculation
  - Brillouin-zone sampling
  - Reading an external wave function
  - Code related keywords
- Demon
  - `Demon`
- deMon-Nano
  - Environment variables
  - deMon-Nano Calculator (a FileIOCalculator)
    - `DemonNano`
  - Example: Geometry Optimization with ASE
- DFTB+
  - Introduction
  - Environment variables
  - Parameters
  - Examples
    - Geometry optimization by ASE
    - Geometry optimization by DFTB+
    - NVE-MD followed by NVT-MD (both by DFTB+)
  - DFTB+ calculator class
    - `Dftb`
- DMol3
  - Environment variables
  - DMol3 Calculator
    - `DMol3`
  - Example
  - File formats
- Espresso
  - Calculator
    - Basic usage
    - Parameters
    - Parallelism
  - Input/Output
    - pw.x
    - ph.x
      - `write_espresso_ph()`
      - `read_espresso_ph()`
    - Other binaries
      - `write_fortran_namelist()`
      - `read_fortran_namelist()`
  - Namelist Class
    - `Namelist`
  - Espresso Calculator Class
    - `Espresso`
- exciting
  - Introduction
  - Muffin Tin Radius
  - Exciting Calculator Class
    - `ExcitingGroundStateCalculator`
- FHI-aims
  - Introduction
  - Running the Calculator
    - `Aims`
  - List of keywords
  - Volumetric Data Output
    - `AimsCube`
  - Example
- FLEUR
- GAMESS-US
  - Setup
  - Examples
  - Parameters
    - `GAMESSUS`
- Gaussian
  - Setup
  - Examples
  - Parameters
  - GaussianOptimizer and GaussianIRC
    - `Gaussian`
- Gromacs
  - Introduction
  - Gromacs Calculator
  - Parameters
  - Environmental variables:
  - Example: MM-only geometry optimization of a histidine molecule
- GULP
  - Instructions
  - Example
- Harmonic calculator
  - Introduction
    - `HarmonicCalculator`
    - `HarmonicForceField`
  - Theory for Anharmonic Correction via Thermodynamic Integration (TI)
  - Examples
    - Example 1: Cartesian coordinatates
    - Example 2: Internal Coordinates
    - Example 3: Free Energy Change due to Coordinate Transformation
    - Example 4: Anharmonic Corrections
- Communication with calculators over sockets
  - Introduction
  - Which codes can be used with socket I/O calculators?
  - How to use the ASE socket I/O interface
  - Run server and client manually
  - Module documentation
    - `SocketIOCalculator`
    - `SocketClient`
    - `SocketServer`
- Jacapo - ASE python interface for Dacapo
- KIM
  - Overview
  - Implementation
    - `KIM()`
  - Advanced Usage
- LAMMPS Calculators
  - LAMMPS
    - `LAMMPS`
    - Setting up an OPLS calculation
  - LAMMPSlib
    - `LAMMPSlib`
- Mopac
  - `MOPAC`
- NWChem
  - Setup
  - Examples
  - Parameters
    - `NWChem`
- Octopus
  - Introduction
  - Examples
    - Structure optimization
    - Periodic system
    - Time-dependent density functional theory
  - Additional information
    - Hints
    - Bugs and misbehaviour
- ONETEP
  - Introduction
  - Environment variables
  - Pseudopotentials
  - ONETEP Calculator
    - `Onetep`
  - Examples
- OpenMX
  - Introduction
  - Environment variables
  - Keyword Arguments of OpenMX objects
    - `OpenMX`
  - Calculator parameters
  - Density of States
  - Methods of OpenMX objects
- ORCA
  - Setup and usage
  - Class Definition
    - `ORCA`
- PLUMED
  - Introduction
  - Installation
  - Set-up
    - Units
  - Plumed Calculator Class
    - `Plumed`
- psi4
  - `Psi4`
  - Setup
  - Examples
  - Parallelization
  - Parameters
- Q-Chem
  - Setup
  - Examples
    - `QChem`
- SIESTA
  - Introduction
  - Environment variables
  - SIESTA Calculator
  - Extra FDF parameters
  - Example
  - Defining Custom Species
  - Pseudopotentials
  - Restarting from an old Calculation
  - Choosing the coordinate format
  - Siesta Calculator Class
    - `Siesta`
  - Excited states calculations
  - Raman Calculations with SIESTA and PyNAO
  - Further Examples
  - Siesta lrtddft Class
    - `SiestaLRTDDFT`
  - Siesta RamanCalculatorInterface Calculator Class
    - `RamanCalculatorInterface`
- TURBOMOLE
  - Setting up the environment
  - Using the calculator
    - Python interface
    - Command-line interface
  - Reading output
    - Properties
    - Metadata
    - Restart mode
      - Caveat about using the restart mode
    - Policies for files in the working directory
  - Parameters
  - Examples
    - Single-point energy calculation
    - Nudged elastic band calculation
    - Single-point gradient calculation of Au13-
    - Geometry optimization using TurbomoleOptimizer (recommended)
    - Geometry optimization and normal mode analysis for H2O
    - QMMM simulation
  - Deprecated, non-implemented and unsupported features
    - Deprecated but still accepted parameters
    - Not implemented parameters
    - Unsupported methods and features
- VASP
  - Introduction
  - Environment variables
    - VASP execution
    - Pseudopotentials
  - VASP Calculator
    - `Vasp`
  - Exchange-correlation functionals
  - Setups
  - Spin-polarized calculation
  - Brillouin-zone sampling
    - Single-parameter schemes
    - Three-parameter scheme
    - Explicitly listing the k-points
    - Band structure paths
  - LD(S)A+U
  - Restart old calculation
  - Storing the calculator state
    - `Vasp.asdict()`
    - `Vasp.fromdict()`
    - `Vasp.write_json()`
    - `Vasp.read_json()`
  - Vibrational Analysis
    - `Vasp.get_vibrations()`
    - `Vasp.read_vib_freq()`
  - Examples
    - Band structure with VASP
    - Density of States
- QMMM
  - Explicit Interaction QMMM
    - `EIQMMM`
    - `LJInteractions`
    - `LJInteractionsGeneral`
    - `Embedding`
  - Simple, subtractive QMMM calculations
    - `SimpleQMMM`
  - Force-based QM/MM
    - `ForceQMMM`
- Checkpointing
  - Manual checkpointing
    - `Checkpoint`
      - `Checkpoint.load()`
      - `Checkpoint.flush()`
      - `Checkpoint.save()`
  - Automatic checkpointing with the checkpoint calculator
    - `CheckpointCalculator`
      - `CheckpointCalculator.implemented_properties`
      - `CheckpointCalculator.default_parameters`
      - `CheckpointCalculator.calculate()`
- Finite-Difference Calculator
  - `FiniteDifferenceCalculator`
  - `calculate_numerical_forces()`
  - `calculate_numerical_stress()`
- Logging Calculator
  - `LoggingCalculator`
- Mixing Calculators
  - `LinearCombinationCalculator`
  - `MixedCalculator`
  - `SumCalculator`
  - `AverageCalculator`
- DFT-D3
  - Introduction
  - Examples
  - Additional information
    - Caveats
- Other built-in calculators
  - TIP3P
    - `TIP3P`
  - TIP4P
    - `TIP4P`
  - Lennard-Jones
    - `LennardJones`
  - Morse
    - `MorsePotential`
- Stuff for testing things
  - `FreeElectrons`
    - `FreeElectrons.calculate()`
    - `FreeElectrons.default_parameters`
    - `FreeElectrons.get_eigenvalues()`
    - `FreeElectrons.get_fermi_level()`
    - `FreeElectrons.get_ibz_k_points()`
    - `FreeElectrons.get_number_of_spins()`
    - `FreeElectrons.implemented_properties`
- ACE-Molecule
  - Setup
  - Parameters