pympfit.optimize

class pympfit.optimize._optimize.MPFITObjective

Bases: Objective

Compute contributions to the MPFIT least squares objective function.

Contains helper functions for capturing the deviation of multipole moments computed using molecular partial charges from GDMA calculations.

classmethod compute_objective_terms(gdma_records: list[MoleculeGDMARecord], vsite_collection: VirtualSiteCollection | None = None, _vsite_charge_parameter_keys: list[Tuple[str, str, str, int]] | None = None, _vsite_coordinate_parameter_keys: list[Tuple[str, str, str, Literal['distance', 'in_plane_angle', 'out_of_plane_angle']]] | None = None, return_quse_masks: bool = False) → Generator[tuple[MPFITObjectiveTerm, dict] | MPFITObjectiveTerm, None, None]

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

classmethod extract_arrays(gdma_record: MoleculeGDMARecord) → dict

Extract numerical arrays from a single GDMA record.

class pympfit.optimize._optimize.MPFITObjectiveTerm(*args, **kwargs)

Bases: ObjectiveTerm

Store precalculated values for multipole moment fitting.

Computes the difference between a reference set of distributed multipole moments and a set computed using fixed partial charges.

Variables:

• gdma_record (MoleculeGDMARecord | None) – Reference to the source GDMA record.

• quse_masks (np.ndarray | None) – Boolean masks indicating which charges are included for each multipole site.

predict(charge_parameters: torch.Tensor, vsite_coordinate_parameters: torch.Tensor | None = None) → list[torch.Tensor]

Predict multipole moment contributions for given charges and vsite positions.

This method is designed for Bayesian inference and rebuilds A matrices with new vsite positions, computing A @ q for each multipole site.

Parameters:

• charge_parameters (torch.Tensor) – Charge values with shape (n_atom_charges + n_vsite_charges, 1).

• vsite_coordinate_parameters (torch.Tensor, optional) – Virtual site local frame coordinates (distance, angles) being sampled. Shape (n_trainable_coords, 1).

Returns:

Predicted multipole contributions for each atom site, matching the shape of reference_values.

Return type:

list[torch.Tensor]

Raises:

ValueError – If called on a term without virtual sites (use SVD solver instead).

predict_from_free_charges(free_charges: torch.Tensor, vsite_charge_increments: torch.Tensor, vsite_coordinate_parameters: torch.Tensor | None = None, formal_charge: float = 0.0) → list[torch.Tensor]

Predict multipoles with automatic charge conservation.

A convenience wrapper around predict() that enforces total charge conservation. Users provide N-1 free atom charges and this method computes the constrained last charge to satisfy the formal charge.

Parameters:

• free_charges (torch.Tensor) – Free charge parameters with shape (n_atoms - 1, 1).

• vsite_charge_increments (torch.Tensor) – Virtual site charge increments with shape (n_vsite_charges, 1).

• vsite_coordinate_parameters (torch.Tensor, optional) – Virtual site local frame coordinates being sampled.

• formal_charge (float) – Total molecular charge (default 0.0 for neutral molecules).

Returns:

Predicted multipole contributions for each atom site.

Return type:

list[torch.Tensor]