vibesketch.chem.relax

Relax a species’ 3D structure with FIRE on an RDKit force field, constraints held.

A conformer from embedding or a file is pulled to a nearby minimum of MMFF94 (T. A. Halgren, J. Comput. Chem. 17, 490-519 (1996)) or UFF (A. K. Rappé, C. J. Casewit, K. S. Colwell, W. A. Goddard III and W. M. Skiff, J. Am. Chem. Soc. 114, 10024-10035 (1992)), RDKit supplying the energy and gradient and vibesketch.chem.fire the minimiser. A job’s constraints hold during the relaxation and are exact, not restraints:

  • A fixed atom (a position constraint) feels no force, through FIRE’s mask.

  • A distance, angle or dihedral is held by projection. Before the run and after every move, the coordinates are put back on the constraint surface with Newton steps of least norm along the constraint gradients, the SHAKE idea (J.-P. Ryckaert, G. Ciccotti and H. J. C. Berendsen, J. Comput. Phys. 23, 327-341 (1977)); the force the minimiser sees has its components along those gradients removed, so it only drives motion that keeps the constraints. The dihedral’s gradient follows A. Blondel and M. Karplus, J. Comput. Chem. 17, 1132-1141 (1996).

The force field is the caller’s choice and is not swapped silently: a species it has no parameters for is refused with the reason. The drawn stereochemistry is checked on the result as embedding checks it, and a relaxation that changed it is refused. Everything is deterministic.

Units: angstrom, kcal/mol and kcal/mol/angstrom, degrees in constraints.

Module Attributes

FORCE_FIELDS

The force fields, in the order they are tried when the caller names none.

DEFAULT_FMAX

the largest force component, in kcal/mol/angstrom.

DEFAULT_MAX_STEPS

Integration steps before giving up.

Functions

relax_3d(species, *[, constraints, ...])

Relax species' first conformer, holding constraints.

Classes

ConstraintCheck(kind, atoms, target, value)

A constraint and its value at the end, in angstrom or degrees.

Relaxed(conformer, force_field, ...[, ...])

A relaxed 3D structure and what the relaxation did.

Exceptions

RelaxFailed

The species could not be relaxed as asked.
vibesketch.chem.relax.FORCE_FIELDS: tuple[Literal['mmff94', 'uff'], ...] = ('mmff94', 'uff')

The force fields, in the order they are tried when the caller names none.

class vibesketch.chem.relax.ConstraintCheck(kind, atoms, target, value)[source]

Bases: object

A constraint and its value at the end, in angstrom or degrees.

Parameters:
kind: str
atoms: list[int]
target: float
value: float
property deviation: float[source]

How far the value is from the target, in angstrom or degrees.

to_dict()[source]
Return type:

dict[str, Any]

exception vibesketch.chem.relax.RelaxFailed[source]

Bases: ValueError

The species could not be relaxed as asked.

class vibesketch.chem.relax.Relaxed(conformer, force_field, energy_before, energy, fmax, steps, converged, constraints=<factory>, warnings=<factory>)[source]

Bases: object

A relaxed 3D structure and what the relaxation did.

Parameters:
conformer: Conformer

The new structure, method fire+mmff94 or fire+uff.

force_field: Literal['mmff94', 'uff']
energy_before: float

The force field’s energy at the start, in kcal/mol.

energy: float

The force field’s energy at the end, in kcal/mol.

fmax: float

The largest remaining force component that can still move an atom.

steps: int
converged: bool
constraints: list[ConstraintCheck]
warnings: list[str]
to_dict()[source]
Return type:

dict[str, Any]

vibesketch.chem.relax.relax_3d(species, *, constraints=None, force_field='mmff94', fmax=0.05, max_steps=5000)[source]

Relax species’ first conformer, holding constraints.

force_field is mmff94 or uff; a species it has no parameters for is refused. The run stops once no force component that can still move an atom exceeds fmax (kcal/mol/angstrom) or after max_steps steps, and the result says which. Raises RelaxFailed with the reason when the species has no structure, the conformer does not match it, a constraint names an atom it lacks or cannot be satisfied, the force field lacks parameters, or the drawn stereochemistry was lost.

Parameters:
Return type:

Relaxed