ESPObjectiveTerm

class openff.recharge.optimize.ESPObjectiveTerm(atom_charge_design_matrix: Optional[Union[ndarray, torch.Tensor]], vsite_charge_assignment_matrix: Optional[Union[ndarray, torch.Tensor]], vsite_fixed_charges: Optional[Union[ndarray, torch.Tensor]], vsite_coord_assignment_matrix: Optional[Union[ndarray, torch.Tensor]], vsite_fixed_coords: Optional[Union[ndarray, torch.Tensor]], vsite_local_coordinate_frame: Optional[Union[ndarray, torch.Tensor]], grid_coordinates: Optional[Union[ndarray, torch.Tensor]], reference_values: Union[ndarray, torch.Tensor])[source]

Bases: ObjectiveTerm

A class that stores precalculated values used to compute the difference between a reference set of electrostatic potentials and a set computed using a set of fixed partial charges.

See the predict and loss functions for more details.

Methods

__init__(atom_charge_design_matrix, ...)

Parameters

  • atom_charge_design_matrix -- A matrix with shape=(n_grid_points, n_bcc_charges + n_vsite_charges) that

combine(*terms)

Combines multiple objective term objects into a single object that can be evaluated more efficiently by stacking the cached terms in a way that allows vectorized operations.

loss(charge_parameters, ...)

Evaluate the L2 loss function (i.e (target_values - predict(q, c)) ** 2) using the current values of the parameters being trained.

predict(charge_parameters, ...)

Predict the value of the electrostatic property of interest using the current values of the parameter.

to_backend(backend)

Converts the tensors associated with this term to a particular backend.
__init__(atom_charge_design_matrix: Optional[Union[ndarray, torch.Tensor]], vsite_charge_assignment_matrix: Optional[Union[ndarray, torch.Tensor]], vsite_fixed_charges: Optional[Union[ndarray, torch.Tensor]], vsite_coord_assignment_matrix: Optional[Union[ndarray, torch.Tensor]], vsite_fixed_coords: Optional[Union[ndarray, torch.Tensor]], vsite_local_coordinate_frame: Optional[Union[ndarray, torch.Tensor]], grid_coordinates: Optional[Union[ndarray, torch.Tensor]], reference_values: Union[ndarray, torch.Tensor])
Parameters

  • atom_charge_design_matrix – A matrix with shape=(n_grid_points, n_bcc_charges + n_vsite_charges) that yields the atom contributions to electrostatic property of interest when left multiplying by a vector of partial charges parameters [e] with shape=(n_bcc_charges + n_vsite_charges, 1).

    It is usually constructed by X=RT where R is either an inverse distance [1 / Bohr] or vector field [1 / Bohr^2] matrix and T is an assignment matrix that computes the partial charge on each atom as the sum of one or more charges from the charge vector.

  • vsite_charge_assignment_matrix – A matrix with shape=(n_vsites, n_vsite_charges) that that computes the partial charge on each virtual site as the sum of one or more charges from the a vector of virtual site charge parameters [e], i.e

    vsite_charges = vsite_charge_assignment_matrix @ v_site_charge_parameters

  • vsite_fixed_charges – A vector with shape=(n_vsites, 1) of the partial charges assigned to each virtual site that will remain fixed during an optimization.

  • vsite_coord_assignment_matrix – A matrix with shape=(n_vsites, 3) of indices into a flat vector of virtual site local frame coordinate parameters that will be trained, such that

    ``vsite_local_coords == vsite_coord_params[vsite_coord_assignment_matrix]

    • vsite_fixed_coords``

    An entry of -1 indicates a value of 0.0 should be used.

  • vsite_fixed_coords – A vector with shape=(n_vsites, 3) of virtual site local frame coordinates virtual site that will remain fixed during an optimization, such that

    ``vsite_local_coords == vsite_coord_params[vsite_coord_assignment_matrix]

    • vsite_fixed_coords``

  • vsite_local_coordinate_frame – A tenser with shape=(4, n_vsites, 3) and units of [A] that stores the local frames of all virtual sites whereby local_frames[0] is an array of the origins of each frame, local_frames[1] the x-directions, local_frames[2] the y-directions, and local_frames[2] the z-directions.

  • grid_coordinates – A matrix with shape=(n_grid_points, 3) and units of [A] of the grid coordinates that the electrostatic property will be evaluated on.

  • reference_values – A vector with shape=(n_grid_points, n_dim) of the reference values of the electrostatic property of interest evaluated on a grid of points.

classmethod combine(*terms: _TERM_T) → _TERM_T

Combines multiple objective term objects into a single object that can be evaluated more efficiently by stacking the cached terms in a way that allows vectorized operations.

Notes

  • This feature is very experimental and should only be used if you know what you are doing.

Parameters

terms – The terms to combine.

Return type

The combined term.

loss(charge_parameters: Union[ndarray, torch.Tensor], vsite_coordinate_parameters: Optional[Union[ndarray, torch.Tensor]]) → Union[ndarray, torch.Tensor]

Evaluate the L2 loss function (i.e (target_values - predict(q, c)) ** 2) using the current values of the parameters being trained.

Parameters

  • charge_parameters – A vector with shape=(n_bcc_charges + n_vsite_charges, 1) and units of [e] that contains the current values of both the BCC and virtual site charge increment parameters being trained.

    The ordering of the parameters should match the order used to generate the atom_charge_design_matrix.

  • vsite_coordinate_parameters – A flat vector with shape=(n_bcc_charges + n_vsite_charges, 1) that contains the current values of both the virtual site coordinate parameters being trained.

    All distances should be in units of [A] and all angles in units of degrees.

    The ordering of the parameters should match the order used to generate the vsite_coord_assignment_matrix.

Return type

The L2 loss function.

predict(charge_parameters: Union[ndarray, torch.Tensor], vsite_coordinate_parameters: Optional[Union[ndarray, torch.Tensor]])

Predict the value of the electrostatic property of interest using the current values of the parameter.

Parameters

  • charge_parameters – A vector with shape=(n_bcc_charges + n_vsite_charges, 1) and units of [e] that contains the current values of both the BCC and virtual site charge increment parameters being trained.

    The ordering of the parameters should match the order used to generate the atom_charge_design_matrix.

  • vsite_coordinate_parameters – A flat vector with shape=(n_bcc_charges + n_vsite_charges, 1) that contains the current values of both the virtual site coordinate parameters being trained.

    All distances should be in units of [A] and all angles in units of degrees.

    The ordering of the parameters should match the order used to generate the vsite_coord_assignment_matrix.

Returns

  • The predicted value of the electrostatic property represented by this term

  • with the same units and shape as reference_values.

to_backend(backend: Literal['numpy', 'torch'])

Converts the tensors associated with this term to a particular backend.

Parameters

backend – The backend to convert the tensors to.