ElectricFieldObjectiveTerm
- class openff.recharge.optimize.ElectricFieldObjectiveTerm(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 electric field vectors and a set computed using a set of fixed partial charges.
See the
`predict
andloss
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
whereR
is either an inverse distance [1 / Bohr] or vector field [1 / Bohr^2] matrix andT
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, andlocal_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.