molsysmt.interactions.pi_pi.get_pi_pi_interactions#

molsysmt.interactions.pi_pi.get_pi_pi_interactions(molecular_system, distance_threshold=None, angle_threshold=None, offset_threshold=None, planarity_threshold=None, selection='all', selection_2=None, structure_indices='all', chemical_state='reference', method='centroid_angle_offset', selection_mode='internal', pbc=True, assume_complete_connectivity=False, output_type='molsysmt.Interactions', syntax='MolSysMT', skip_digestion=False, *, geometry='both', max_cyclic_block_size=256, max_matches=100000, heavy_mode='auto', profile=None)[source]#

Detecting aromatic ring geometries with explicit attributed criteria.

Choose ProLIF, Mol*/MDTraj geometric profiles or the separate MolSysMT proposal. Reference recognition and plane construction remain explicit. Geometric cutoffs define candidates; the result does not establish attraction, binding energy or a chemical bond.

Parameters:

molecular_system (molecular system) – Any supported form providing coordinates and explicit selected-state atom/bond aromatic flags and complete covalent connectivity.
distance_threshold (quantity, str, or None, default=None) – Finite positive centroid-distance cutoff with length units. Required for the custom method. None uses 0.55 nm for Mol* or separate 0.55/0.65 nm face/edge limits for ProLIF and MDTraj. An explicit value overrides both limits for those profiles.
angle_threshold (quantity, str, or None, default=None) – Custom/Mol* maximum deviation from parallel or perpendicular planes, with angular units. Must be nonnegative and strictly below 45 degrees, keeping the two geometry classes disjoint. Mol* defaults to 30 degrees. Leave None for ProLIF/MDTraj, which use their named angular intervals. Internally evaluated in radians.
offset_threshold (quantity, str, or None, default=None) – Finite nonnegative lateral offset cutoff with length units. Custom parallel geometries must satisfy both planes’ offsets; edge-to-face geometries must satisfy at least one. Mol* defaults to 0.2 nm and accepts either offset for both classes. Leave None for ProLIF/MDTraj, which use angular and plane-intersection criteria instead.
planarity_threshold (quantity, str, or None, default=None) – Custom method’s required finite nonnegative maximum orthogonal atom deviation from each ring’s fitted plane, with length units. Warped rings exceeding it are excluded. Zero requires numerically exact planarity; no absolute tolerance is added. Leave None for reference profiles, which do not filter planarity.
selection (str, list, tuple, or numpy.ndarray, default='all') – Atom selection. Include every atom of any intersected aromatic ring, including adjacent fused rings sharing selected atoms.
selection_2 (str, list, tuple, 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; evaluated frames without observations stay explicit.
chemical_state ({'reference', 'structure'}, int, or None, default='reference') – State supplying the chemistry. Structure-assigned states must resolve to one state across the requested frames.
method (str, default='centroid_angle_offset') – centroid_angle_offset or plane_angle_intersection. Profiles distinguish the proposal and adapted reference definitions. Historical prolif, molstar_geometry and mdtraj_geometry selectors remain exact aliases; geometric adaptations do not reproduce complete feature pipelines.
selection_mode ({'internal', 'incident', 'between'}, default='internal') – Search within selection, from selection to every eligible system ring, or between selection and selection_2, respectively.
pbc (bool, default=True) – Use MIC when a box exists. Participants must already be whole in the anchor-relative image. Split rings fail; coordinates are not unwrapped.
assume_complete_connectivity (bool, default=False) – Explicitly assume 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.
geometry ({'parallel', 'edge_to_face', 'both'}, default='both') – Keyword-only choice of accepted geometric classes.
max_cyclic_block_size (int, default=256) – Keyword-only ring-basis limit per aromatic cyclic biconnected block. Increasing it can substantially increase recognition time and memory.
max_matches (int, default=100000) – Keyword-only bound per ProLIF ring SMARTS query before selection. An exceeded limit raises rather than returning a truncated participant set.
heavy_mode ({'auto', 'force', 'off'}, default='auto') – Keyword-only execution policy. Streaming follows the form’s declared coordinate support. Other supported forms use their ordinary getters eagerly when the selected working estimate fits the budget.
profile (str or None, default=None) – Keyword-only profile. centroid_angle_offset defaults to least_squares; three_atom_plane selects the adapted Mol* geometry. For plane_angle_intersection, smarts_5_6 is the default ProLIF profile and aromatic_cycles uses the adapted MDTraj geometry on declared rings.

Returns:

Sparse pi_pi relations with ring_a/ring_b whole-ring participants, ordered by their source memberships. Occurrences retain centroid distance, acute plane angle, both lateral offsets, and each ring’s RMS/maximum deviation (nm and radians). Evidence distinguishes parallel and edge-to-face observations. Images shift ring_b relative to ring_a using row box vectors. Source axes, evaluated frames, examined aromatic atom scope, chemistry evidence, parameters and producer versions are explicit. Reference profiles also retain both normal/centroid acute angles and the tested intersection distance (nm); the latter is NaN where the intersection test was not applied. Empty columns have (0,).

Return type:

molsysmt.Interactions or molsysmt.InteractionsDict

Raises:

ArgumentError – If cutoffs, selections, method, geometry or structure indices are invalid.
StructuralInconsistencyError – If chemistry is missing/contradictory, coordinates or boxes are invalid, or a ring does not define a unique plane.
NotImplementedMethodError – If a periodic ring requires internal image reconstruction.
UnsupportedHeavyOperationError – If the form cannot supply required streaming, or one coordinate block cannot fit its allotted numerical working estimate.
MemoryBudgetExceededError – If source axes, candidates or the resident sparse-result estimate exceed their configured RAM allocation. No partial result is returned.

Notes

Canonical method/profile identities and their definition version accompany the effective cutoffs and pinned reference implementation. The detached parameters[‘attribution’] bibliography survives typed and H5MSM storage; optional Ackredit tracking credits the application’s current session.

For the custom method, let d be the observed MIC centroid displacement and n_a/n_b the unit normals. The acute plane angle is atan2(norm(cross(n_a,n_b)), abs(dot(n_a,n_b))). Each offset is norm(d-dot(d,n)*n). Parallel accepts angle <= angle_threshold and max(offset_a,offset_b) <= offset_threshold. Edge-to-face accepts pi/2-angle <= angle_threshold and min(offset_a,offset_b) <= offset_threshold. Both require a positive centroid distance within distance_threshold and both maximum deviations within planarity_threshold. Inclusive comparisons allow one float64 ULP, without an additional absolute tolerance. Angular roundoff is capped strictly below pi/4 so the two classes remain disjoint even near the numerical boundary.

The custom method excludes self, overlapping/fused and directly covalently linked rings. Other intramolecular contacts are included; dative links do not exclude a pair. Reference profiles add no overlap/covalent exclusion; undefined normals and zero displacements are skipped explicitly. There is no energy, residue or component filter. A minimum cycle basis is not all cycles or SymmSSSR. Chemistry is examined across the full source; observation coverage contains only eligible aromatic atom scopes. Every selected frame is searched, without first-frame candidate pruning. The calculation neither attaches an analysis nor modifies its source.

ProLIF uses its original five/six-member ring SMARTS and normals formed from centroid-to-first-two matched atoms. MDTraj geometry uses the same normal construction with supplied basis-member order. Face accepts distance <=0.55 nm, acute plane angle <=35 degrees and either normal/centroid angle <=33 degrees. Edge accepts distance <=0.65 nm, plane angle >=50 degrees, either normal/centroid angle <=30 degrees and the projected intersection within 0.15 nm of either centroid. The original core projects ring_a’s centroid on the intersection line: this is role-dependent. Canonical source memberships fix ring_a/ring_b; atom reordering can therefore affect this criterion. It is not silently symmetrized. ProLIF checks exact determinant singularity; MDTraj uses NumPy isclose, without reproducing its random replacement of singular matrices. No first-frame pruning is performed.

Mol* geometry uses the first three basis atoms for its triangle normal, distance <=0.55 nm, deviation <=30 degrees from parallel/perpendicular, and min(offset_a,offset_b)<=0.2 nm for both classes. Its valence-based feature recognition and contact refinement are not reproduced. Reference comparisons add no ULP allowance. Computation uses float64; MDTraj’s float32 coordinates can yield different decisions exactly at thresholds. Coherent whole-ring MIC geometry is a MolSysMT extension; MDTraj’s original pi routine wraps centroid distances but uses raw centroid vectors for angles/intersections. Producer versions and pinned references are separate metadata. No reference profile establishes attractive energy.

H5MSM 0.5 index selections load chemistry/association metadata once and projected coordinate blocks, without saved analyses. Rich file selections use the eager route only within the full source-coordinate estimate; forced streaming requires index selections or ‘all’. Coordinates/plane work reserve one quarter of configure.max_ram_usage, each bounded candidate search one eighth, and sparse accumulation/packing one half. The complete sparse result remains resident. Estimates bound numeric work, not caller-owned arrays, chemistry tables, Python overhead or process RSS. No incremental result writer is provided. No new Rust dependency is required: plane fitting and spatial search reuse bundled kernels; candidate geometry is vectorized NumPy.