gfnff#

Python bindings for the GFN-FF force-field library.

Public API#

GFNFFCalculator: Low-level interface (Bohr / Hartree units).
GFNFF: ASE Calculator subclass (Angstrom / eV units). Available when ASE is installed; raises ImportError otherwise.
Version: Parametrisation versions accepted by the version argument of both.

class gfnff.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.

class gfnff.GFNFFCalculator(numbers, positions_bohr, *, charge: int = 0, printlevel: int = 0, solvent: str = '', lattice=None, npbc: int = 0, fragments=None, ref_charges=None, accuracy: float | None = None, version=None, parametrisation: str | None = None, bond_matrix=None)[source]#

Bases: object

Wraps the GFN-FF C API for a single molecular or periodic system.

Parameters:

numbers – Atomic numbers, shape (nat,).
positions_bohr – Cartesian coordinates in Bohr, shape (nat, 3), C-contiguous.
charge – Total molecular charge (integer).
printlevel – Verbosity of Fortran output (0 = silent, 1 = errors only, 2 = informational, 3 = verbose).
solvent – Implicit solvent name (e.g. "h2o", "acetone"). Empty string or None disables solvation.
lattice – Lattice vectors in Bohr, shape (3, 3), C-contiguous. Each row is one lattice vector (same convention as the C API). None for non-periodic systems.
npbc – Number of periodic dimensions (0–3). Ignored when lattice is None.
accuracy – Cutoff/precision factor. Larger is looser and faster; above 1.0 the EEQ system is solved in single precision. None uses the library default (0.1, or 2.0 above 10000 atoms). Must be given here rather than changed later, because it also sets the thresholds used to build the topology.

version:: Parametrisation version: a Version member, its integer value, or its name (e.g. "mcgfnff2023"). None uses the library default. mcgfnff2023 is rejected for non-periodic systems.
parametrisation:: Path to a parameter file. None uses the internal set for version. A .toml path is applied as an overlay on that set, so the file need only name the keys it changes; any other path is read as the legacy flat format. TOML support requires a build with toml-f.
fragments:: Optional per-atom fragment index, shape (nat,) (int). When given, GFN-FF forms no bonds between atoms of differing fragments, enforcing a host-defined fragmentation instead of the automatic detection.
ref_charges:: Optional per-atom reference charges, shape (nat,) (float). Summed over each fragment to set the per-fragment EEQ charge constraint. No charge model is invoked; the caller supplies the array directly.
bond_matrix:: Optional molecular graph, shape (nat, nat) of integer bond orders. A nonzero element declares a bond. When given it replaces GFN-FF’s distance-based bond perception entirely, so the connectivity need not be supported by the coordinates – which is the point: it lets a structure be built from a graph plus an arbitrary starting geometry. Must be symmetric with a zero diagonal, non-negative, at most 41 bonds per atom, and non-periodic. Only the zero/nonzero pattern is used today; the orders are validated and stored but have no consumer, since GFN-FF derives its own pi bond orders.

charges()[source]#

Atomic partial charges from the last singlepoint.

The EEQ charges are a by-product of the energy evaluation rather than a separate model, so they belong to the geometry most recently passed to singlepoint() (or hessian(), which runs one).

Returns:: charges – Partial charges in units of the elementary charge. They sum to the total charge given at initialization.
Return type:: ndarray, shape ``(nat,)``
Raises:: RuntimeError – If no singlepoint has been run on this calculator yet, or if the selected version has no charges at all (harmonic2020 returns before the EEQ solve).

deallocate()[source]#: Explicitly free Fortran-side memory.

hessian(numbers, positions_bohr, step=None)[source]#

Compute the Cartesian nuclear Hessian for the given geometry.

Only available for non-periodic systems: the analytic terms have no periodic implementation yet, and finite-differencing them would silently ignore the periodic images.

Parameters:

numbers – Atomic numbers, shape (nat,).
positions_bohr – Coordinates in Bohr, shape (nat, 3).
step – Finite-difference step in Bohr for the terms not yet available in closed form. None lets the library choose.

Returns:

hessian (ndarray, shape ``(3 * nat, 3 * nat)``) – Second derivatives in Eh / Bohr**2. Degree of freedom (c, a) is at index 3 * a + c. The matrix is symmetric.
energy (float) – Total energy in Hartree.
gradient (ndarray, shape ``(nat, 3)``) – Analytic gradient in Eh / Bohr.

Raises:

NotImplementedError – If the calculator was initialized for a periodic system.
RuntimeError – If the library reports any other failure.

print_results(iunit: int = 6)[source]#

Print the GFN-FF energy decomposition to a Fortran unit.

Parameters:: iunit – Fortran I/O unit number. Use 6 for standard output.

singlepoint(numbers, positions_bohr, lattice=None)[source]#

Compute energy, gradient and stress tensor for the given geometry.

Parameters:

numbers – Atomic numbers, shape (nat,).
positions_bohr – Coordinates in Bohr, shape (nat, 3).
lattice – Lattice vectors in Bohr, shape (3, 3). Must be provided for periodic systems (same npbc as at initialization).

Returns:

energy (float) – Total energy in Hartree.
gradient (ndarray, shape ``(nat, 3)``) – Energy gradient in Eh / Bohr.
sigma (ndarray, shape ``(3, 3)``) – Stress tensor in Hartree. Zero for non-periodic systems.

version#: kept for introspection; the library has no getter for either

class gfnff.Version(*values)#

Bases: IntEnum

GFN-FF parametrisation versions.

default leaves the choice to the library (currently angewChem2020_2). mcgfnff2023 is for molecular crystals and is rejected for non-periodic systems. harmonic2020 replaces the bond potential with a harmonic one. conformer2020 reproduces angewChem2020_2 wherever the bonds are near their equilibrium lengths, but its bonds cannot dissociate.

angewChem2020 = 1#

angewChem2020_1 = 2#

angewChem2020_2 = 3#

conformer2020 = 5#

default = 0#

harmonic2020 = -1#

mcgfnff2023 = 4#

Modules

`ase_calculator`	ASE Calculator interface for GFN-FF.
`calculator`	Low-level Python wrapper around the GFN-FF C API.
`cli`	Command-line interface for GFN-FF singlepoint and geometry optimisation.