molsysmt.build.assign_partial_charges#

molsysmt.build.assign_partial_charges(molecular_system, method, structure_indices='all', chemical_state='reference', forcefield=None, water_model=None, expected_total_charge=None, return_report=False, skip_digestion=False)[source]#

Assigning validated full-atom charges to a detached single-state MolSys.

Parameters:

molecular_system (molecular system) – Any supported form providing the selected model’s chemical prerequisites. Exactly one chemical state is required for native mechanical storage.
method (str) – Explicit ‘gasteiger_marsili’ or ‘forcefield’ charge model.
structure_indices (int, list, tuple or numpy.ndarray, default='all') – Structure indices (0-based) for resolving chemical_state=’structure’. All source structures are retained; coordinates are not used by the model.
chemical_state (str or int, default='reference') – State to calculate. Multi-state inputs must first be reduced explicitly; the experimental MolecularMechanics store holds one assignment.
forcefield (str, default=None) – Required named force field for method=’forcefield’; otherwise None.
water_model (str, default=None) – Optional force-field water template set; otherwise None.
expected_total_charge (int or quantity, default=None) – Full-system total declaration, as an integer in elementary charge or a scalar charge quantity. Complete formal charges supply it when absent.
return_report (bool, default=False) – Return the new molecular_system and its detached report when True.
skip_digestion (bool, default=False) – Whether to skip argument digestion.

Returns:

New MolSys retaining atoms, IDs, chemistry, coordinates and named analyses. Its molecular_mechanics stores full atom-aligned partial_charge values in elementary charge and partial_charge_assignment provenance. A report is returned separately when requested. The source is unchanged on failure.

Return type:

molsysmt.MolSys or dict

Raises:

ArgumentError – If a method parameter or state request is invalid.
StructuralInconsistencyError – If more than one state is present or the calculation cannot provide a finite, complete, total-charge-consistent assignment.
ImportError – If the explicitly required optional provider is unavailable.

Notes

Delegates the scientific calculation to physchem.get_partial_charges. Named analyses retain their original snapshots. As with other mechanics edits, callers must explicitly invalidate/recalculate analyses that depend on those parameters; native automatic coupling covers geometry and ChemicalStates. Replaces existing charges explicitly; it does not assign force-field atom types or other force-field parameters. A force-field charge calculation is not full parameterization of MolecularMechanics. Assignment provenance is retained by native copying and extraction; extracted charges are a projection of the original calculation, not a new isolated-fragment calculation. The PDBQT writer checks a stored assignment against its bound chemistry and values before use. Direct manual charge replacement clears this attribution. MolecularMechanics remains experimental and is excluded from H5MSM 0.5 (planned for 0.6). Native attachment copies the complete system, including source coordinates; it does not offer out-of-core trajectory assignment.