`descent.targets.energy`

Train against relative energies and forces.

Functions

`create_dataset`(entries)	Create a dataset from a list of existing entries.
`create_dataset_from_generator`(gen_fn)	Create a dataset from a generator function, avoiding loading all entries into memory at once.
`extract_smiles`(dataset)	Return a list of unique SMILES strings in the dataset.
`predict`(dataset, force_field, topologies[, ...])	Predict the relative energies [kcal/mol] and forces [kcal/mol/Å] of a dataset.

Classes

Entry

Represents a set of reference energies and forces.

class descent.targets.energy.Entry[source]

Represents a set of reference energies and forces.

id: str | None: An optional identifier for the entry (e.g. a run name). Defaults to None.

smiles: str: The indexed SMILES description of the molecule the energies and forces were computed for.

coords: Tensor: The coordinates [Å] the energies and forces were evaluated at with shape=(n_confs, n_particles, 3).

energy: Tensor: The reference energies [kcal/mol] with shape=(n_confs,).

forces: Tensor: The reference forces [kcal/mol/Å] with shape=(n_confs, n_particles, 3).

clear() → None. Remove all items from D.

copy() → a shallow copy of D

fromkeys(value=None, /): Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /): Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from mapping/iterable E and F.: If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

box_vectors: Tensor | None: The box vectors [Å] for periodic systems with shape=(n_confs, 3, 3), or None for non-periodic systems.

descent.targets.energy.create_dataset(entries: list[Entry]) → Dataset[source]

Create a dataset from a list of existing entries.

Args:: entries: The entries to create the dataset from.
Returns:: The created dataset.

descent.targets.energy.create_dataset_from_generator(gen_fn: Callable[[], Iterator[Entry]]) → Dataset[source]

Create a dataset from a generator function, avoiding loading all entries into memory at once.

Args:

gen_fn: A callable that returns an iterator of entries. It will be called by: the HuggingFace datasets library and must be re-iterable (i.e. each call to gen_fn() should produce a fresh iterator).

Returns:

The created dataset.

descent.targets.energy.extract_smiles(dataset: Dataset) → list[str][source]

Return a list of unique SMILES strings in the dataset.

Args:: dataset: The dataset to extract the SMILES strings from.
Returns:: The list of unique SMILES strings.

descent.targets.energy.predict(dataset: Dataset, force_field: TensorForceField, topologies: dict[str, smee._models.TensorTopology], reference: Literal['mean', 'min'] = 'mean', normalize: bool = True) → tuple[Tensor, Tensor, Tensor, Tensor][source]

Predict the relative energies [kcal/mol] and forces [kcal/mol/Å] of a dataset.

Args:

dataset: The dataset to predict the energies and forces of. force_field: The force field to use to predict the energies and forces. topologies: The topologies of the molecules in the dataset. Each key should be

a fully indexed SMILES string.

reference: The reference energy to compute the relative energies with respect: to. This should be either the “mean” energy of all conformers, or the energy of the conformer with the lowest reference energy (“min”).
normalize: Whether to scale the relative energies by 1/sqrt(n_confs_i): and the forces by 1/sqrt(n_confs_i * n_atoms_per_conf_i * 3) This is useful when wanting to compute the MSE per entry.

Returns:

The predicted and reference relative energies [kcal/mol] with shape=(n_confs,), and predicted and reference forces [kcal/mol/Å] with shape=(n_confs * n_atoms_per_conf, 3).