molsysmt.physchem.get_charge_centers#

molsysmt.physchem.get_charge_centers(molecular_system, selection='all', definition='formal_charge', chemical_state='reference', structure_indices='all', assume_complete_connectivity=False, syntax='MolSysMT', skip_digestion=False)[source]#

Identifying formal-charge centers in a selected chemical state.

Recognize carboxyl and guanidine motifs and combine directly covalently connected charged atoms. Omit groups whose formal charges sum to zero. Other nonzero formal charges remain explicitly labeled atomic centers. This bounded definition does not infer protonation, partial charges, aromatic delocalization, or every possible ionic functional group.

Parameters:

  • molecular_system (molecular system) – Molecular system in a supported MolSysMT format with atom elements, complete declared connectivity, bond orders, and formal charges.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Selection string or integer array specifying atoms. A selection intersecting a center must include all its participant atoms.

  • definition (str, default='formal_charge') – Named recognition definition; only ‘formal_charge’ is supported.

  • chemical_state ({'reference', 'structure'}, int, or None, default='reference') – Chemical state used to resolve state-dependent attributes. Explicit states follow the native MolSysMT basic-query contract.

  • structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices used to resolve chemical_state=’structure’; all requested structures must have the same assigned chemical state. Recognition computes chemistry once. Coordinate-based selections may read coordinates through the standard selection API.

  • assume_complete_connectivity (bool, default=False) – Explicitly declare the supplied connectivity complete when the stored completeness metadata is unavailable or partial. This assumption is recorded and does not fill bonds or change the source.

  • syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection.

  • skip_digestion (bool, default=False) – Whether to skip MolSysMT’s internal argument digestion mechanism.

Returns:

Typed sparse membership: atom_indices and atom_offsets describe whole centers; geometry_atom_indices and geometry_atom_offsets describe distance-reference atoms. Carboxylate references are its oxygens, guanidinium references its nitrogens. charges is a quantity of shape (n_centers,) in elementary charge units. center_types labels the recognition rules. Metadata includes n_atoms, source_atom_indices, selection_atom_indices, examined_atom_indices, chemical_state_index, charge_source, definition, rule_version, evidence, and software. Indices are zero-based indices in the full source system, never IDs. Centers and their memberships are ordered by atom indices. Empty results have int64 membership arrays, offsets [0], and charges (0,).

Return type:

dict

Raises:

  • ArgumentError – If the definition or selection is invalid, including a cut center.

  • StructuralInconsistencyError – If chemistry is missing, connectivity is not declared complete, bond relationships/orders are unsupported, or no state is resolved.

Notes

Recognition examines the full state before selecting complete centers. Source charges are not modified or parameterized. Atomic/cluster labels are formal-charge evidence, not proof of a particular ionic interaction. The current rules do not group phosphate, sulfate, or aromatic ions. Coordinate geometry and periodic images belong to a subsequent detector. The returned dictionary is a chemical-feature result, not InteractionsDict.

See also

molsysmt.basic.get

Querying stored formal or partial charges.

molsysmt.physchem.get_charge

Getting named residue descriptors or OpenMM partial charges.

Examples

>>> import molsysmt as msm
>>> from molsysmt import pyunitwizard as puw
>>> from molsysmt.native import Topology
>>> from molsysmt.physchem.get_charge_centers import get_charge_centers
>>> molsys = Topology(n_atoms=2)
>>> molsys.atoms['atom_type'] = ['Na', 'Cl']
>>> msm.set(molsys, element='atom', formal_charge=[1, -1])
>>> centers = get_charge_centers(
...     molsys, assume_complete_connectivity=True)
>>> centers['atom_indices'].tolist()
[0, 1]
>>> puw.get_value(centers['charges'], to_unit='e').tolist()
[1.0, -1.0]

User guide

See Getting charge centers.

Added in version 1.0.0.

On this page