ESPObjective

class openff.recharge.optimize.ESPObjective[source]

Bases: Objective

A utility class which contains helper functions for computing the contributions to a least squares objective function which captures the deviation of the ESP computed using molecular partial charges and the ESP computed by a QM calculation.

Methods

__init__()

compute_objective_terms(esp_records[, ...])

Pre-calculates the terms that contribute to the total objective function.
__init__()
classmethod compute_objective_terms(esp_records: List[MoleculeESPRecord], charge_collection: Optional[Union[QCChargeSettings, LibraryChargeCollection]] = None, charge_parameter_keys: Optional[List[Tuple[str, Tuple[int, ...]]]] = None, bcc_collection: Optional[BCCCollection] = None, bcc_parameter_keys: Optional[List[str]] = None, vsite_collection: Optional[VirtualSiteCollection] = None, vsite_charge_parameter_keys: Optional[List[Tuple[str, str, str, int]]] = None, vsite_coordinate_parameter_keys: Optional[List[Tuple[str, str, str, Literal['distance', 'in_plane_angle', 'out_of_plane_angle']]]] = None) → Generator[ObjectiveTerm, None, None]

Pre-calculates the terms that contribute to the total objective function.

This function assumes that the array (/tensor) of values to train will have shape (n_charge_parameter_keys + n_bcc_parameter_keys + vsite_charge_parameter_keys, 1) with the values in the array corresponding to the values pointed to by the keys starting with library charge values (if any), followed by BCCs (if any) and finally any v-site charge increments (if any). See the vectorize method of the collections for an easy way to generate such an array.

Notes

It is critical that the order of the values of the array match the order of the keys provided here otherwise the wrong parameters will be applied to the wrong atoms.

Parameters

  • esp_records – The calculated records that contain the reference ESP and electric field data to train against.

  • charge_collection – Optionally either i) a collection settings that define how to compute a set of base charges (e.g. AM1) or ii) a collection of library charges to be applied. This base charges may be perturbed by any supplied bcc_collection or vsite_collection. If no value is provided, all base charges will be set to zero.

  • charge_parameter_keys – A list of tuples of the form (smiles, (idx_0, ...)) that define those parameters in the charge_collection that should be trained.

    Here idx_i is an index into the value field of the parameter uniquely identified by the smiles key.

    This argument can only be used when the charge_collection is a library charge collection.

    The order of these keys must match the order of the charges in the vector of charges being trained. See for e.g. LibraryChargeCollection.vectorize.

  • bcc_collection – A collection of bond charge correction parameters that should perturb the base set of charges for each molecule in the esp_records list.

  • bcc_parameter_keys – A list of SMIRKS patterns that define those parameters in the bcc_collection that should be trained.

    The order of these keys must match the order of the charges in the vector of charges being trained. See for e.g. BCCCollection.vectorize.

  • vsite_collection – A collection of virtual site parameters that should create virtual sites for each molecule in the esp_records list and perturb the base charges on each atom.

  • vsite_charge_parameter_keys – A list of tuples of the form (smirks, type, name, idx) that define those charge increment parameters in the vsite_collection that should be trained.

    Here idx is an index into the charge_increments field of the parameter uniquely identified by the other terms of the key.

    The order of these keys must match the order of the charges in the vector of charges being trained. See for e.g. VirtualSiteCollection.vectorize_charge_increments.

  • vsite_coordinate_parameter_keys – A list of tuples of the form (smirks, type, name, attr)) that define those local frame coordinate parameters in the vsite_collection that should be trained.

    Here attr should be one of {'distance', 'in_plane_angle', 'out_of_plane_angle'}.

    The order of these keys must match the order of the charges in the vector of charges being trained. See for e.g. VirtualSiteCollection.vectorize_coordinates.

Returns

  • The precalculated terms which may be used to compute the full

  • contribution to the objective function.