molsysmt.interactions.hbonds.get_hbonds#

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

Detecting sparse hydrogen bonds with an explicitly attributed criterion.

Calculate individual donor-H-acceptor observations for every requested structure. Existing Buch and Luzard–Chandler functions retain their outputs.

Parameters:

molecular_system (molecular system) – Any supported form with element symbols, complete declared covalent connectivity and coordinates. ProLIF additionally needs formal charges, bond orders and explicit atom/bond aromatic flags.
selection (str, list, tuple, or numpy.ndarray, default='all') – Source atom selection defining the calculation scope. An individual hydrogen may be selected in incident mode; roles remain separate 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 in sorted order; evaluated structures without observations stay explicit.
chemical_state ({'reference', 'structure'}, int, or None, default='reference') – State supplying chemical sites. Structure assignments must resolve to one state across all requested structures.
method (str, default='baker_hubbard') – baker_hubbard, wernet_nilsson, or donor_acceptor_distance_angle. The profile fixes recognition and exact geometric conventions. cpptraj, prolif and mdanalysis_geometry remain compatibility aliases.
distance_threshold (quantity, str, or None, default=None) – Positive scalar cutoff with length units. None uses H-A <0.25 nm for Baker–Hubbard, D-A <=0.30 nm for CPPTRAJ/MDAnalysis, D-A <=0.35 nm for ProLIF, or the 0.33 nm intercept of Wernet–Nilsson’s angular curve.
angle_threshold (quantity, str, or None, default=None) – Scalar minimum D-H-A angle with angular units, within 0 to 180 degrees. None uses >120 degrees for Baker–Hubbard, >=135 degrees for CPPTRAJ, >=130 degrees for ProLIF, or >150 degrees for MDAnalysis. Leave None for Wernet–Nilsson, whose angular criterion is its distance curve.
selection_mode ({'internal', 'incident', 'between'}, default='internal') – Require all three atoms in selection, at least one in selection, or all in the union of both selections and at least one in each, respectively.
pbc (bool, default=True) – Use MIC when a box exists. Stored images reproduce measured geometry; inconsistent independent image choices raise. CPPTRAJ requires whole donor-H coordinates, matching its source’s unwrapped donor-H vector.
assume_complete_connectivity (bool, default=False) – Explicitly assume supplied connectivity complete when metadata is insufficient. Record the assumption without changing the source.
output_type (str, default='molsysmt.Interactions') – Sparse molsysmt.Interactions or its typed molsysmt.InteractionsDict form.
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.
donor_hydrogen_pairs (list, tuple, numpy.ndarray, or None, default=None) – Keyword-only source atom pairs with shape (n_pairs, 2), in donor/H order. Both explicit site arrays must be supplied together. Each pair must be a declared covalent bond to an indexed hydrogen; duplicates are removed.
acceptor_atom_indices (list, tuple, numpy.ndarray, or None, default=None) – Keyword-only explicit source acceptor indices. No automatic chemical acceptor rule is applied to this supplied set; hydrogens are rejected.
max_matches (int, default=100000) – Keyword-only bound per ProLIF chemical SMARTS query before selection.
heavy_mode ({'auto', 'force', 'off'}, default='auto') – Keyword-only execution policy. Native/H5MSM projected coordinate routes process bounded blocks; other forms require bounded eager delivery.
profile (str or None, default=None) – Keyword-only calculation profile. donor_acceptor_distance_angle uses elemental_fon by default; smarts_donor_acceptor and explicit_sites select the adapted ProLIF and MDAnalysis definitions respectively. explicit_sites requires both site arrays. Author-named methods use nitrogen_oxygen. An alias already fixes its profile.

Returns:

Sparse hbond relations with donor, hydrogen and acceptor singleton participants. Measurements retain all three observed distances in nm and D-H-A/H-D-A angles in radians, including empty (0,) columns. Coverage, source indices, chemical scope, parameters, evidence, reference method and actual producer versions remain explicit and serialize in H5MSM 0.5. Periodic image vectors shift each atom relative to the donor using row box vectors. No result is automatically attached to the source.

Return type:

molsysmt.Interactions or molsysmt.InteractionsDict

Raises:

ArgumentError – If cutoffs, explicit sites, selections, method or indices are invalid.
StructuralInconsistencyError – If required chemistry, coordinates or coherent periodic geometry are absent.
UnsupportedHeavyOperationError – If streamed delivery is unavailable or a coordinate block exceeds budget.
MemoryBudgetExceededError – If candidate work or the resident sparse result exceeds the RAM estimate.

Notes

Completed calculations retain an offline bibliography in parameters[‘attribution’], including results with zero observations. Optional Ackredit tracking contributes to the current application session. Reference implementations are distinguished from executed software; loading a stored analysis does not credit a new calculation.

This reproduces supported reference cores, not whole package workflows: no occupancy aggregation, residue/solvent/sidechain pruning, water bridges, force-field energy or implicit coordinate construction. ProLIF recognition uses its original SMARTS. CPPTRAJ uses F/O/N elemental sites, MDTraj N/O. MDAnalysis retains its >0.10 nm lower D-A limit, but no partial-charge guesses. Explicit sites are caller declarations, recorded separately from automatic recognition. Undefined angles are skipped.

Wernet–Nilsson follows MDTraj’s implemented curve: D-A < distance_threshold - 0.000044 nm/degree**2 * (H-D-A in degrees)**2. Its source’s additional comparison with the literal 45 is in radians and has no effect on defined angles; no extra 45-degree cutoff is invented. N/O generalization and water inclusion extend the original water criterion. Baker–Hubbard is evaluated per frame rather than using MDTraj’s default frequency filter. CPPTRAJ source inequalities are inclusive despite the strict inequalities printed in its help text.

Geometry at H uses donor-H then H-acceptor images. Wernet–Nilsson uses donor-H and donor-acceptor images. D-A methods reject incompatible H-centered and independently wrapped D-A geometry rather than storing misleading images. Numeric block work reserves one quarter of configure.max_ram_usage, candidate search one eighth and resident sparse accumulation one half. Caller-owned arrays, chemistry, Python overhead and process RSS are outside these estimates. Source chemistry is recognized once; no dense all-pairs matrix or per-occurrence Python object list is materialized.