molsysmt.interactions.cation_pi.get_cation_pi_interactions#

molsysmt.interactions.cation_pi.get_cation_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_distance_angle', selection_mode='internal', pbc=True, assume_complete_connectivity=False, output_type='molsysmt.Interactions', syntax='MolSysMT', skip_digestion=False, *, max_cyclic_block_size=256, max_matches=100000, heavy_mode='auto', profile=None)[source]#

Detecting cation-pi geometries using an attributed or experimental method.

The default reproduces ProLIF 2.2.2’s CationPi SMARTS, centroid/normal construction and distance/angle acceptance. The separately named centroid_angle_offset method is a MolSysMT proposal, not a published method. Both return geometric evidence, without establishing attractive energy.

Parameters:

molecular_system (molecular system) – Any supported form supplying coordinates, elements, complete declared selected-state connectivity, bond orders, formal charges and explicit aromatic atom/bond flags. A chemical-only domain has no element inventory.
distance_threshold (quantity, str, or None, default=None) – Finite positive cation-point/ring-centroid cutoff with length units. None uses ProLIF’s 0.45 nm or Mol* geometry’s 0.60 nm; the custom method requires an explicit value.
angle_threshold (quantity, str, or None, default=None) – Acute displacement/normal angle cutoff with angular units. ProLIF accepts a scalar maximum (minimum zero) or a quantity with two values [minimum, maximum] within 0 to 90 degrees; None uses [0, 30] degrees. The custom method requires an explicit nonnegative scalar below 90 degrees. Leave None for Mol* geometry, which has no angular filter. Calculations and stored parameters use radians.
offset_threshold (quantity, str, or None, default=None) – Custom method’s finite nonnegative lateral displacement cutoff, with length units. Required for the custom method; must be None for ProLIF, which applies no offset filter. Mol* geometry defaults to 0.20 nm.
planarity_threshold (quantity, str, or None, default=None) – Custom method’s finite nonnegative maximum ring-plane deviation cutoff, with length units. Required for the custom method; must be None for ProLIF/Mol* geometry, which apply no planarity filter. Zero adds no absolute tolerance.
selection (str, list, tuple, or numpy.ndarray, default='all') – Include every atom of any intersected eligible participant. ProLIF cations are singleton matched atoms; custom cations may be compound. Fused rings sharing atoms can require extending a selection.
selection_2 (str, list, tuple, numpy.ndarray, or None, default=None) – Disjoint second selection, required only for selection_mode=’between’. Either selection may contain cations, rings or both.
structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Zero-based structure indices. Repeated indices are evaluated once in sorted order; evaluated structures without candidates remain explicit.
chemical_state ({'reference', 'structure'}, int, or None, default='reference') – Selected chemistry. Structure assignments must resolve one state across the requested structures; no protonation or parameterization is inferred.
method (str, default='centroid_distance_angle') – centroid_distance_angle, centroid_distance_offset, or the separately identified centroid_angle_offset proposal. Historical prolif and molstar_geometry selectors remain exact compatibility aliases. Reference implementations and adaptations are recorded separately.
selection_mode ({'internal', 'incident', 'between'}, default='internal') – Search within selection, from selection to every eligible system participant, or between selection and selection_2, respectively.
pbc (bool, default=True) – Explicit MolSysMT extension: use MIC when a box exists. Participants must already be whole in their anchor-relative image; split groups fail.
assume_complete_connectivity (bool, default=False) – Record an explicit completeness 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') – Syntax used to evaluate selection and selection_2.
skip_digestion (bool, default=False) – Whether to skip MolSysMT’s internal argument digestion mechanism.
max_cyclic_block_size (int, default=256) – Keyword-only aromatic basis limit for the custom method. ProLIF uses its original SMARTS ring recognition and does not use this limit.
max_matches (int, default=100000) – Keyword-only bound per SMARTS query for ProLIF. Exceeding it raises instead of silently truncating. The custom method does not use this limit.
heavy_mode ({'auto', 'force', 'off'}, default='auto') – Keyword-only execution policy. Streaming requires the form’s declared coordinate route; other supported forms use bounded eager getters.
profile (str or None, default=None) – Keyword-only profile. centroid_distance_angle uses smarts_5_6; centroid_distance_offset uses three_atom_plane; centroid_angle_offset uses least_squares. These preserve the distinct recognition, normal construction and comparisons of each referenced definition.

Returns:

Sparse cation_pi relations with cation/ring roles and complete source memberships. ProLIF rings preserve SMARTS atom order for reconstructing the normal; this is not sorted membership order. Measures include distance, acute normal angle, lateral offset, absolute height, ring RMS/maximum deviation and cation charge (nm, radians, elementary charge). For ProLIF, cation_charge is the matched atom’s stored formal charge: a neutral nitrogen matched by the resonance pattern can have zero. For the custom method, it is the whole center’s positive net charge. For ProLIF, oriented_normal_angle also preserves the original reported angle in [0, pi], before acute folding for acceptance. ProLIF deviations describe its centroid-edge plane, not a least-squares fit. They are diagnostic and do not filter its observations. Images shift the ring relative to the cation using row box vectors. Empty frames, eligible atom scope, producer version, original method reference and parameters are explicit; empty measure columns have (0,).

Return type:

molsysmt.Interactions or molsysmt.InteractionsDict

Raises:

ArgumentError – If cutoffs, method, selections or structure indices are invalid.
StructuralInconsistencyError – If declared chemistry is missing/contradictory, coordinates/boxes are invalid or a custom-method ring fails to define a unique fitted plane.
NotImplementedMethodError – If a periodic participant requires internal image reconstruction.
UnsupportedHeavyOperationError – If SMARTS matches exceed their limit, required streaming is unavailable or one projected frame exceeds its numerical working estimate.
MemoryBudgetExceededError – If matching, axes, candidates or resident sparse output exceed their configured allocation. No partial analysis is returned.

Notes

Canonical method names describe the criterion. Profiles and pinned source references preserve the complete reproduced definition. The detached parameters[‘attribution’] bibliography survives typed and H5MSM storage, independently of optional Ackredit tracking in the application’s session.

ProLIF uses its original cation SMARTS, including amidine/guanidine resonance and opposite-charge exclusions, and aromatic 5/6-member ring SMARTS. The ring centroid is the arithmetic mean; its normal is the cross product of centroid-to-first and centroid-to-second matched atom vectors. Require distance <= cutoff and angle within the inclusive acute interval, without an extra ULP allowance. Undefined normals or zero displacements produce no angular candidates. No least-squares, offset, planarity, overlap or direct-covalent exclusion is added to this method.

MolSysMT extends the calculation to a single source with explicit scopes, all requested frames, bounded coordinate/candidate execution and optional MIC. It does not reproduce ProLIF’s residue-pair/ligand preprocessing or fingerprint aggregation. RDKit is an optional dependency required by ProLIF recognition; ProLIF itself is not a runtime dependency. Native recognition reuses the chemistry-aware RDKit converter without coordinates and requires sanitization to preserve declared charges and aromaticity.

The custom method uses positive formal-charge centers and declared aromatic minimum-cycle-basis rings. Its cation point is the unweighted mean of ALL participant atoms, not an electrical center or the ionic distance-reference subset. Planes are unweighted least squares. For d=point-ring_centroid and unit n: height=abs(dot(d,n)), offset=norm(d-dot(d,n)*n), and angle=atan2(offset,height). Require positive distance, angle/offset and maximum ring deviation within their cutoffs. Inclusive comparisons allow one float64 ULP, capped below pi/2 for angles. Overlap and direct covalent links exclude a pair; other intramolecular candidates remain included. This experimental proposal has no established accuracy advantage; its comparison is tracked in uibcdf/molsysmt#271.

molstar_geometry reproduces the charged.ts geometric tester using distance <=0.60 nm and lateral offset <=0.20 nm, with a normal from the first three basis member atoms. It adds no angle/planarity or covalent exclusion. Its participants are MolSysMT declared formal-charge centers and aromatic basis rings, not Mol*’s valence-model/residue feature discovery. Their centroid uses all participating atoms; Mol* can mark atoms that do not contribute to its feature centroid. This named profile therefore compares geometry on supplied features and does not claim full Mol* detector parity. Undefined triangles/zero displacements are skipped; whole-participant MIC is an explicit extension. The pinned source reference survives serialization.

Coverage contains eligible participants, not every atom examined during full-state recognition. Results are never attached automatically. H5MSM index selections read chemistry once and projected coordinates without saved analyses; rich file selections require bounded eager materialization. Numeric coordinate/geometry work reserves one quarter of the RAM budget, candidate search one eighth, sparse accumulation/packing one half. Source arrays, chemistry, Python overhead and process RSS are outside these estimates. The sparse result remains resident. Plane/spatial kernels are reused; no new compiled backend or incremental writer is introduced.