calculator#

Low-level Python wrapper around the GFN-FF C API.

All quantities use the native C API units:

  • positions / lattice : Bohr

  • energy : Hartree

  • gradient : Eh / Bohr

class gfnff.calculator.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:
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.calculator.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#