DESCENT 0.6.1.dev10+ga8229506d documentation

descent

descent.targets.dimers

Train against dimer energies.

Functions

compute_dimer_energy(topology_a, topology_b, ...)	Compute the energy of a dimer in a series of conformers.
create_dataset(dimers)	Create a dataset from a list of existing dimers.
create_dataset_from_generator(gen_fn)	Create a dataset from a generator function, avoiding loading all dimers into memory at once.
create_from_des(data_dir, energy_fn)	Create a dataset from a DESXXX dimer set.
default_closure(trainable, topologies, dataset)	Return a default closure function for training against dimer energies.
extract_smiles(dataset)	Return a list of unique SMILES strings in the dataset.
predict(dataset, force_field, topologies)	Predict the energies of each dimer in the dataset.
report(dataset, force_fields, topologies, ...)	Generate a report comparing the predicted and reference energies of each dimer.

Classes

Dimer

Represents a single experimental data point.

class descent.targets.dimers.Dimer

Represents a single experimental data point.

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

descent.targets.dimers.create_dataset(dimers: list[Dimer]) → Dataset

Create a dataset from a list of existing dimers.

Args:

dimers: The dimers to create the dataset from.

Returns:

The created dataset.

descent.targets.dimers.create_dataset_from_generator(gen_fn: Callable[[], Iterator[Dimer]]) → Dataset

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

Args:

gen_fn: A callable that returns an iterator of dimers. 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.dimers.create_from_des(data_dir: Path, energy_fn: Callable[[pandas.DataFrame, tuple[str, ...], Tensor], Tensor]) → Dataset

Create a dataset from a DESXXX dimer set.

Args:

data_dir: The path to the DESXXX directory. energy_fn: A function which computes the reference energy of a dimer. This

should take as input a pandas DataFrame containing the metadata for a given group, a tuple of geometry IDs, and a tensor of coordinates with shape=(n_dimers, n_atoms, 3). It should return a tensor of energies with shape=(n_dimers,) and units of [kcal/mol].

Returns:

The created dataset.

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

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.dimers.compute_dimer_energy(topology_a: TensorTopology, topology_b: TensorTopology, force_field: TensorForceField, coords: Tensor) → Tensor

Compute the energy of a dimer in a series of conformers.

Args:

topology_a: The topology of the first monomer. topology_b: The topology of the second monomer. force_field: The force field to use. coords: The coordinates of the dimer with shape=(n_dimers, n_atoms, 3).

Returns:

The energy [kcal/mol] of the dimer in each conformer.

descent.targets.dimers.predict(dataset: Dataset, force_field: TensorForceField, topologies: dict[str, smee._models.TensorTopology]) → tuple[Tensor, Tensor]

Predict the energies of each dimer in the dataset.

Args:

dataset: The dataset to predict the energies of. force_field: The force field to use. topologies: The topologies of each monomer. Each key should be a fully

mapped SMILES string.

Returns:

The reference and predicted energies [kcal/mol] of each dimer, each with shape=(n_dimers * n_conf_per_dimer,).

descent.targets.dimers.default_closure(trainable: Trainable, topologies: dict[str, smee._models.TensorTopology], dataset: Dataset)

Return a default closure function for training against dimer energies.

Args:

trainable: The wrapper around trainable parameters. topologies: The topologies of the molecules present in the dataset, with keys

of mapped SMILES patterns.

dataset: The dataset to train against.

Returns:

The default closure function.

descent.targets.dimers.report(dataset: Dataset, force_fields: dict[str, smee._models.TensorForceField], topologies: dict[str, dict[str, smee._models.TensorTopology]], output_path: Path)

Generate a report comparing the predicted and reference energies of each dimer.

Args:

dataset: The dataset to generate the report for. force_fields: The force fields to use to predict the energies. topologies: The topologies of each monomer for the given force field. Each key

should be a fully mapped SMILES string. The name of the force field must also be present in force_fields

output_path: The path to write the report to.