molsysmt.interactions.ionic.get_ionic_interactions#

molsysmt.interactions.ionic.get_ionic_interactions(molecular_system, distance_threshold, selection='all', selection_2=None, structure_indices='all', chemical_state='reference', method='minimum_distance', selection_mode='internal', pbc=True, assume_complete_connectivity=False, output_type='molsysmt.Interactions', syntax='MolSysMT', skip_digestion=False, *, heavy_mode='auto')[source]#

Detecting minimum-distance contacts between opposite formal-charge centers.

Use the bounded formal-charge definition of get_charge_centers. One occurrence represents a positive/negative center pair in one structure, with the minimum distance between their geometry-reference atoms. The criterion is geometric evidence, not an electrostatic energy or bond.

Parameters:

  • molecular_system (molecular system) – Molecular system with coordinates and explicit selected-state chemistry.

  • distance_threshold (quantity or str) – Explicit, finite positive distance cutoff with length units. Accept distances less than or equal to the cutoff, allowing one float64 ULP for unit-conversion roundoff; no universal default is used.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Atom selection. A selection intersecting a compound center must include all its atoms. Original atom indices are preserved.

  • selection_2 (str, list, tuple, or numpy.ndarray or None, default=None) – Disjoint second atom selection, required only for selection_mode=’between’.

  • structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based) to evaluate. Repeated indices are evaluated once, in sorted order. Empty evaluated frames remain explicit.

  • chemical_state ({'reference', 'structure'}, int, or None, default='reference') – State used to identify centers. Structure-assigned states must resolve to the same state for every requested structure.

  • method (str, default='minimum_distance') – Supported geometric criterion; only ‘minimum_distance’ is implemented.

  • selection_mode ({'internal', 'incident', 'between'}, default='internal') – Search within selection, from selection to any eligible center in the system, or between selection and selection_2, respectively.

  • pbc (bool, default=True) – Use MIC distances when a box exists. Boxes use row lattice vectors. Compound participants requiring internal MIC image shifts are rejected.

  • assume_complete_connectivity (bool, default=False) – Explicitly declare supplied connectivity complete when stored metadata is insufficient. Record the assumption without modifying the source.

  • output_type ({'molsysmt.Interactions', 'molsysmt.InteractionsDict'}, default='molsysmt.Interactions') – Sparse analysis object or its typed, versioned serialization dictionary.

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

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

  • heavy_mode ({'auto', 'force', 'off'}, default='auto') – Keyword-only execution policy. Chunked execution supports native MolSys and H5MSM 0.5 paths with atom-index selections or ‘all’. Auto also considers selected-block working estimates. Off requests eager execution within the budget; force processes bounded coordinate blocks.

Returns:

Sparse ionic_contact observations with positive and negative participant roles, distance in nm, and participant charges in elementary charge units. Each relation contains whole-center atoms; distance references follow the recorded recognition-rule version. Source axes, evaluated frames, eligible atom scope, parameters, evidence, and producer version remain explicit. Periodic images shift the whole negative participant relative to the positive participant. Empty measure columns have (0,).

Return type:

molsysmt.Interactions or dict

Raises:

  • ArgumentError – If the threshold, method, selections, or search mode are invalid.

  • StructuralInconsistencyError – If required chemistry or finite coordinates/boxes are missing.

  • NotImplementedMethodError – If periodic participants require internal image shifts.

  • UnsupportedHeavyOperationError – If chunked execution is needed for an unsupported form/selection, or selected coordinate buffers cannot fit the configured working estimate.

  • MemoryBudgetExceededError – If candidate or resident sparse-result working estimates exceed their allocated portions of configure.max_ram_usage. No partial result is returned.

Notes

Analysis parameters retain the minimum_distance criterion and compact bibliography. Completed calculations also contribute to an optional Ackredit session; loading or querying an analysis does not credit a new calculation. Bibliographic metadata is identical without Ackredit.

This experimental definition recognizes carboxylate and guanidinium plus literal formal-charge atoms/clusters; phosphate, sulfate, and aromatic delocalization are not resolved universally. Intramolecular contacts are included. Self/overlapping centers cannot occur in the recognizer’s disjoint partition. Directly covalently bonded centers are excluded; dative bonds do not impose this exclusion. No residue, component, or energy exclusion is inferred. All source chemistry is examined before filtering centers. The calculation neither attaches an analysis nor modifies coordinates. Chemistry is prepared once. Chunked H5MSM 0.5 calculations load topology, chemical states, and association metadata without loading structural series or saved analyses. Atom axes must have declared identity links. A structure selection must resolve to one state when chemical_state=’structure’. Rich string selections retain the eager route; chunked requests reject them. The complete sparse result remains resident. Coordinate blocks reserve one quarter of the configured budget, candidate searches one eighth each, and sparse accumulation/packing one half. Estimates include numerical workspace factors, not caller-owned coordinates, chemistry tables, Python overhead, or a process RSS guarantee. There is no incremental result writer or public checkpoint/resume route. Candidate batching uses a conservative possible-pair bound and can reject a budget even when actual neighbors would be sparse.

See also

molsysmt.physchem.get_charge_centers

Identifying state-specific chemical participants.

molsysmt.Interactions.query

Filtering calculated occurrences by atoms and structures.

Examples

>>> import molsysmt as msm
>>> import numpy as np
>>> from molsysmt import pyunitwizard as puw
>>> from molsysmt.native import MolSys, Topology
>>> from molsysmt.interactions.ionic.get_ionic_interactions import get_ionic_interactions
>>> molsys = MolSys()
>>> molsys.topology = Topology(n_atoms=2)
>>> molsys.topology.atoms['atom_type'] = ['Na', 'Cl']
>>> msm.set(molsys, element='atom', formal_charge=[1, -1])
>>> molsys.structures.append(coordinates=puw.quantity(
...     np.array([[[0., 0., 0.], [0.3, 0., 0.]]]), 'nm'))
>>> result = get_ionic_interactions(molsys, '0.4 nm', pbc=False,
...     assume_complete_connectivity=True)
>>> result.n_interactions
1
>>> result.measure_units['distance']
'nm'

User guide

See Getting ionic interactions.

Added in version 1.0.0.