Skip to main content
`Ctrl`+`K`

# Adding new calculators

Adding an ASE interface to your favorite force-calculator is very simple. Take a look at the `Calculator` and `FileIOCalculator` classes below (the code is here: ase/calculators/calculator.py). You should inherit from the `FileIOCalculator` and implement the `read()`, `read_results()` and `write_input()` methods. The methods `set()`, `check_state()` and `set_label()` may also need to be implemented.

See also

- The code for our Abinit interface: ase/calculators/abinit.py

- Calculator interface proposal

- `ase.calculators`

## Description of base-classes

### The Calculator base-class

class ase.calculators.calculator.Calculator(restart=None, ignore_bad_restart_file=<object object>, label=None, atoms=None, directory='.', **kwargs)

  Base-class for all ASE calculators.

  A calculator must raise PropertyNotImplementedError if asked for a property that it can’t calculate. So, if calculation of the stress tensor has not been implemented, get_stress(atoms) should raise PropertyNotImplementedError. This can be achieved simply by not including the string ‘stress’ in the list implemented_properties which is a class member. These are the names of the standard properties: ‘energy’, ‘forces’, ‘stress’, ‘dipole’, ‘charges’, ‘magmom’ and ‘magmoms’.

  Basic calculator implementation.

  restart: str

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

  ignore_bad_restart_file: bool

    Deprecated, please do not use. Passing more than one positional argument to Calculator() is deprecated and will stop working in the future. Ignore broken or missing restart file. By default, it is an error if the restart file is missing or broken.

  directory: str or PurePath

    Working directory in which to read and write files and perform calculations.

  label: str

    Name used for all files. Not supported by all calculators. May contain a directory, but please use the directory parameter for that instead.

  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.

  default_parameters: Dict[str, Any] = {}

    Default parameters

  ignored_changes: Set[str] = {}

    Properties of Atoms which we ignore for the purposes of cache

  discard_results_on_any_change = False

    Whether we purge the results following any change in the set() method.

  set_label(label)

    Set label and convert label to directory and prefix.

    Examples:

    - label=’abc’: (directory=’.’, prefix=’abc’)

    - label=’dir1/abc’: (directory=’dir1’, prefix=’abc’)

    - label=None: (directory=’.’, prefix=None)

  todict(skip_default=True)

    Obtain a dictionary of parameter information

  reset()

    Clear all information from old calculation.

  read(label)

    Read atoms, parameters and calculated properties from output file.

    Read result from self.label file. Raise ReadError if the file is not there. If the file is corrupted or contains an error message from the calculation, a ReadError should also be raised. In case of succes, these attributes must set:

    atoms: Atoms object

      The state of the atoms from last calculation.

    parameters: Parameters object

      The parameter dictionary.

    results: dict

      Calculated properties like energy and forces.

    The FileIOCalculator.read() method will typically read atoms and parameters and get the results dict by calling the read_results() method.

  set(**kwargs)

    Set parameters like set(key1=value1, key2=value2, …).

    A dictionary containing the parameters that have been changed is returned.

    Subclasses must implement a set() method that will look at the chaneged parameters and decide if a call to reset() is needed. If the changed parameters are harmless, like a change in verbosity, then there is no need to call reset().

    The special keyword ‘parameters’ can be used to read parameters from a file.

  check_state(atoms, tol=1e-15)

    Check for any system changes since last calculation.

  calculate(atoms=None, properties=['energy'], system_changes=['positions', 'numbers', 'cell', 'pbc', 'initial_charges', 'initial_magmoms'])

    Do the calculation.

    properties: list of str

      List of what needs to be calculated. Can be any combination of ‘energy’, ‘forces’, ‘stress’, ‘dipole’, ‘charges’, ‘magmom’ and ‘magmoms’.

    system_changes: list of str

      List of what has changed since last calculation. Can be any combination of these six: ‘positions’, ‘numbers’, ‘cell’, ‘pbc’, ‘initial_charges’ and ‘initial_magmoms’.

    Subclasses need to implement this, but can ignore properties and system_changes if they want. Calculated properties should be inserted into results dictionary like shown in this dummy example:

        self.results = {'energy': 0.0,
                        'forces': np.zeros((len(atoms), 3)),
                        'stress': np.zeros(6),
                        'dipole': np.zeros(3),
                        'charges': np.zeros(len(atoms)),
                        'magmom': 0.0,
                        'magmoms': np.zeros(len(atoms))}

    The subclass implementation should first call this implementation to set the atoms attribute and create any missing directories.

  calculate_numerical_forces(atoms, d=0.001)

    Calculate numerical forces using finite difference.

    All atoms will be displaced by +d and -d in all directions.

    Deprecated since version 3.24.0.

  calculate_numerical_stress(atoms, d=1e-06, voigt=True)

    Calculate numerical stress using finite difference.

    Deprecated since version 3.24.0.

  band_structure()

    Create band-structure object for plotting.

### The FileIOCalculator class

class ase.calculators.calculator.FileIOCalculator(restart=None, ignore_bad_restart_file=<object object>, label=None, atoms=None, command=None, profile=None, **kwargs)

  Base class for calculators that write/read input/output files.

  File-IO calculator.

  command: str

    Command used to start calculation.

  classmethod ruleset(*args, **kwargs)

    Helper for subclasses to define FileIORules.

  calculate(atoms=None, properties=['energy'], system_changes=['positions', 'numbers', 'cell', 'pbc', 'initial_charges', 'initial_magmoms'])

    Do the calculation.

    properties: list of str

      List of what needs to be calculated. Can be any combination of ‘energy’, ‘forces’, ‘stress’, ‘dipole’, ‘charges’, ‘magmom’ and ‘magmoms’.

    system_changes: list of str

      List of what has changed since last calculation. Can be any combination of these six: ‘positions’, ‘numbers’, ‘cell’, ‘pbc’, ‘initial_charges’ and ‘initial_magmoms’.

    Subclasses need to implement this, but can ignore properties and system_changes if they want. Calculated properties should be inserted into results dictionary like shown in this dummy example:

        self.results = {'energy': 0.0,
                        'forces': np.zeros((len(atoms), 3)),
                        'stress': np.zeros(6),
                        'dipole': np.zeros(3),
                        'charges': np.zeros(len(atoms)),
                        'magmom': 0.0,
                        'magmoms': np.zeros(len(atoms))}

    The subclass implementation should first call this implementation to set the atoms attribute and create any missing directories.

  write_input(atoms, properties=None, system_changes=None)

    Write input file(s).

    Call this method first in subclasses so that directories are created automatically.

  read_results()

    Read energy, forces, … from output file(s).