molsysmt.interactions.hydrophobic.get_hydrophobic_interactions#

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

Detecting sparse hydrophobic atom pairs with an inclusive distance cutoff.

Return an independent analysis; attachment to a molecular system is explicit.

Parameters:

molecular_system (molecular system) – Any supported form supplying coordinates, elements, complete connectivity, covalent orders, formal charges and aromatic atom/bond flags.
selection (str, list, tuple, or numpy.ndarray, default='all') – Source atom selection defining the calculation scope. Full source chemistry is recognized before filtering eligible atoms.
selection_2 (str, list, tuple, numpy.ndarray, or None, default=None) – Disjoint second selection, required only for between mode.
structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based). Repeated indices are evaluated once, sorted; frames without observations retain explicit evaluated coverage.
chemical_state ({'reference', 'structure'}, int, or None, default='reference') – Chemical state supplying sites. Structure assignments must resolve one known state across all selected structures.
method (str, default='atom_pair_distance') – Descriptive distance criterion. Exact chemical recognition and numerical reference conventions are selected by profile and recorded separately.
distance_threshold (quantity, str, or None, default=None) – Finite positive scalar length cutoff. None uses 0.45 nm. Bounds are inclusive, without an added geometric tolerance.
selection_mode ({'internal', 'incident', 'between'}, default='internal') – Require both atoms in selection, either atom in selection, or one atom in each of two disjoint selections, respectively.
pbc (bool, default=True) – Use MIC when a valid box exists, anchored on the lower atom index. Preserve the actual periodic image used for the measured distance.
assume_complete_connectivity (bool, default=False) – Record an explicit completeness assumption without repairing chemistry.
output_type (str, default='molsysmt.Interactions') – Sparse molsysmt.Interactions or typed molsysmt.InteractionsDict.
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.
max_matches (int, default=100000) – Keyword-only maximum full-source chemical matches before selection.
heavy_mode ({'auto', 'force', 'off'}, default='auto') – Keyword-only execution policy. Eligible native/H5MSM inputs deliver projected coordinate blocks; accepted sparse output remains in RAM.
profile (str or None, default=None) – Keyword-only smarts_hydrophobic_atoms profile from ProLIF 2.2.2. None selects that profile. The ProLIF package is not required at runtime.

Returns:

Distinct unordered atom pairs, in ascending source-index order, with singleton roles hydrophobic_1 and hydrophobic_2 and distance in nm. Coverage, actual search scope, chemistry evidence, reference bibliography, producer versions and periodic images accompany every named analysis.

Return type:

molsysmt.Interactions or molsysmt.InteractionsDict

Raises:

ArgumentError – If units, cutoff, method, profile, selections, state or indices are invalid.
StructuralInconsistencyError – If required chemistry, finite coordinates or valid periodic boxes are absent.
UnsupportedHeavyOperationError – If a forced streaming route is unsupported or a chemical match cap is exceeded.
MemoryBudgetExceededError – If numerical matching, candidate or resident-result estimates exceed budget.

Notes

Reproduce the ProLIF 2.2.2 Hydrophobic/Distance core with its SMARTS sites and inclusive distance rule. Source patterns incorporate RDKit chemical features; reference attribution does not claim invented authorship of the criterion. Recognition is independently available in physchem.get_hydrophobic_sites. This typed proximity definition is not a residue hydrophobicity scale, interaction energy or proof of solvent-mediated attraction. Mol* uses a different elemental/neighbor rule, pair exclusion and default cutoff.

Within one source system, same-atom observations and reverse duplicates are excluded. Distinct coincident atoms may have zero distance. No extra covalent or intramolecular exclusion is inferred from the reference core. Use between mode with disjoint ligand/environment selections for an interfacial analysis. All default scope modes preserve unordered identity and canonical MIC images. Pair roles do not encode which selection was the ligand. This is not the reference application’s residue fingerprint pruning or all-periodic-images enumeration. Roundoff at an exact cutoff can affect reference membership.

Source chemistry and accepted sparse output remain resident. Projected coordinate blocks reserve one quarter of the configured numeric RAM budget, candidates one eighth and accumulation/packing one half. Graphs, Python overhead and process RSS are outside these estimates. Rich H5MSM selections require bounded eager loading; forced unsupported routes fail explicitly. There is no incremental result writer. Optional Ackredit credits completed calculations, including known-empty results; reading saved results does not credit a newly performed scientific calculation.