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(multipole_records: list[MoleculeGDMARecord | MoleculeMBISRecord], 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, fit_limit: int | None = None) → Generator[tuple[MPFITObjectiveTerm, dict] | MPFITObjectiveTerm, None, None]

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

Parameters:

fit_limit – Optional maximum multipole rank (0-indexed) for fitting. See extract_arrays for details.

classmethod extract_arrays(multipole_record: MoleculeGDMARecord | MoleculeMBISRecord, fit_limit: int | None = None) → dict

Extract numerical arrays from a single multipole record (GDMA or MBIS).

Parameters:

• multipole_record – The record (GDMA or MBIS) containing multipoles and settings.

• fit_limit – Optional maximum multipole rank (0-indexed) to use for fitting. When provided and less than the record’s available rank, the multipole tensor is truncated so only terms up to this rank are included in the fit. Allows running the QM/multipole step once at a high rank and fitting charges at multiple lower ranks without rerunning the QM calculation.

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:

• multipole_record (MultipoleRecord | None) – Reference to the source multipole record (GDMA or MBIS).

• 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]