ase_calculator#

ASE Calculator interface for GFN-FF.

Unit conventions#

ASE uses Angstrom and eV throughout. The conversions applied here are:

positions   : Angstrom  →  Bohr       (divide by ase.units.Bohr)
lattice     : Angstrom  →  Bohr       (divide by ase.units.Bohr)
energy      : Hartree   →  eV         (multiply by ase.units.Hartree)
forces      : -(Eh/Bohr) → eV/Ang    (multiply by ase.units.Hartree / ase.units.Bohr)
stress      : Eh/Bohr³  → eV/Ang³    (sigma / volume * Hartree / Bohr**3)
              returned in Voigt order [xx, yy, zz, yz, xz, xy]

For non-periodic systems sigma is zero, so stress is reported as a zero six-vector. For periodic systems the stress is sigma / cell_volume.

class gfnff.ase_calculator.GFNFF(charge=0, solvent='', printlevel=0, fragments=None, ref_charges=None, accuracy=None, version=None, parametrisation=None, bond_matrix=None, **kwargs)[source]#

Bases: Calculator

ASE calculator for the GFN-FF force field.

Parameters:

  • charge (int, optional) – Total molecular charge. May also be provided via atoms.info["charge"], which takes precedence.

  • solvent (str, optional) – Implicit solvent name (e.g. "h2o", "acetone"). Empty string (default) runs in vacuum.

  • printlevel (int, optional) – Fortran output verbosity (0 = silent).

  • fragments (array_like of int, optional) – Per-atom fragment index, shape (nat,). When given, GFN-FF forms no bonds between atoms of differing fragments (host-defined fragmentation instead of automatic detection). May also be provided via atoms.info["fragments"], which takes precedence.

  • ref_charges (array_like of float, optional) – Per-atom reference charges, shape (nat,), summed per fragment to set the per-fragment EEQ charge constraint. No charge model is invoked. May also be provided via atoms.info["ref_charges"] (takes precedence).

  • version (Version or int or str, optional) – Parametrisation version, e.g. "mcgfnff2023". None uses the library default. mcgfnff2023 requires a periodic system.

  • parametrisation (str, optional) – Path to a parameter file. A .toml path is applied as an overlay on the internal set for version, so it need only name the keys it changes.

  • bond_matrix (array_like of int, optional) – Molecular graph, shape (nat, nat) of integer bond orders. Replaces GFN-FF’s distance-based bond perception, so the connectivity need not be supported by the coordinates. Combined with version="harmonic2020" this turns an unstructured cloud of atoms plus a graph into a 3D structure. May also be provided via atoms.info["bond_matrix"], which takes precedence.

Notes

atoms.get_charges() returns the EEQ partial charges from the current geometry. They are a by-product of the energy evaluation, so asking for them triggers a calculation exactly as energy or forces would.

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.

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

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.

default_parameters: dict[str, Any] = {'accuracy': None, 'charge': 0, 'parametrisation': None, 'printlevel': 0, 'solvent': '', 'version': None}#

Default parameters

discard_results_on_any_change = True#

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

get_hessian(atoms=None, step=None)[source]#

Cartesian nuclear Hessian in eV / Angstrom**2.

Deliberately not one of implemented_properties: ASE would then compute it on every calculate call, and an MD step does not need a Hessian. Ask for it explicitly instead.

Parameters:

  • atoms – Structure to evaluate. Defaults to the one already attached.

  • step – Finite-difference step in Angstrom for the terms not yet available in closed form. None lets the library choose.

Returns:

hessian – Second derivatives in eV / Angstrom**2. Degree of freedom (c, a) is at index 3 * a + c. The matrix is symmetric.

Return type:

ndarray, shape ``(3 * nat, 3 * nat)``

Raises:

NotImplementedError – For periodic systems: the analytic terms have no periodic implementation, and finite-differencing them would silently ignore the images.

get_vibrations(atoms=None, step=None)[source]#

Hessian wrapped as an ASE VibrationsData.

Gives frequencies, normal modes and thermochemistry through ASE’s own machinery, without the finite-difference sweep ase.vibrations would otherwise run over 6N displaced singlepoints.

implemented_properties: list[str] = ['energy', 'forces', 'stress', 'charges']#

Properties calculator can handle (energy, forces, …)

reset()[source]#

Clear all information from old calculation.