molsysmt.interactions.water_bridges.get_water_bridges#

molsysmt.interactions.water_bridges.get_water_bridges(molecular_system, selection='all', selection_2=None, structure_indices='all', chemical_state='reference', method='hbond_water_path', distance_threshold=None, angle_threshold=None, selection_mode='internal', pbc=True, assume_complete_connectivity=False, output_type='molsysmt.Interactions', syntax='MolSysMT', skip_digestion=False, *, hbond_method='baker_hubbard', hbond_profile=None, max_matches=100000, heavy_mode='auto', profile=None, order=1)[source]#

Observing simultaneous hydrogen bonds through one or two indexed waters.

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

Parameters:

molecular_system (molecular system) – Any supported form supplying coordinates and complete declared chemistry: elements, covalent orders, formal charges and atom/bond aromatic flags. Waters require two explicitly indexed hydrogens.
selection (str, list, tuple, or numpy.ndarray, default='all') – Source atom selection. All-participant scope includes mediator atoms and hydrogens actually used by the observed legs.
selection_2 (str, list, tuple, numpy.ndarray, or None, default=None) – Disjoint second selection, required only for between mode. Mediator atoms must be in the union for between mode; use incident for endpoint-only sets.
structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based). Evaluate repeated indices once, sorted. Frames without bridges retain explicit evaluated coverage.
chemical_state ({'reference', 'structure'}, int, or None, default='reference') – State supplying waters and leg sites. Requested frames must resolve one state.
method (str, default='hbond_water_path') – Simple paths of observed D-H-A legs through the requested water order. The previous two_hbonds_one_water selector remains available for order one.
distance_threshold (quantity, str, or None, default=None) – Positive scalar length cutoff passed to the leg detector. None uses its named scientific default: H-A <0.25 nm for Baker-Hubbard, for example.
angle_threshold (quantity, str, or None, default=None) – Angular minimum passed to the leg detector. None uses its scientific default; leave None for the Wernet-Nilsson distance-angle curve.
selection_mode ({'internal', 'incident', 'between'}, default='internal') – All participating atoms in selection, any in selection, or all in the union of disjoint selections with at least one in each, respectively. These are atom scopes, not implicit ligand/protein endpoint selections.
pbc (bool, default=True) – Preserve observed leg MIC images when a valid box exists. Translate the next leg onto its shared water oxygen image, keeping every geometry.
assume_complete_connectivity (bool, default=False) – Record a completeness assumption without repairing chemical assignments.
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.
hbond_method (str, default='baker_hubbard') – Keyword-only criterion for every leg: baker_hubbard, wernet_nilsson, or donor_acceptor_distance_angle with an automatic chemical site profile.
hbond_profile (str or None, default=None) – Keyword-only recognition/geometry profile passed to get_hbonds. None selects the leg method’s default. explicit_sites is unavailable here.
max_matches (int, default=100000) – Keyword-only maximum full-source matches per water or leg SMARTS query.
heavy_mode ({'auto', 'force', 'off'}, default='auto') – Keyword-only leg-coordinate execution policy. Eligible native/H5MSM inputs stream projected coordinates. Accepted legs and bridges remain in RAM.
profile (str or None, default=None) – Keyword-only indexed_water profile. None selects this profile.
order (int, default=1) – Keyword-only exact number of distinct mediator waters: one or two. Two waters require three simultaneous legs. This is not a maximum order; store separate named analyses to retain both one- and two-water paths.

Returns:

Relations of type water_bridge, six or nine singleton roles in D-H-A triples: leg_1_donor, leg_1_hydrogen, leg_1_acceptor, leg_2_donor, leg_2_hydrogen, leg_2_acceptor, plus leg_3 roles for order two. Each mediator oxygen repeats in its adjacent legs; each role retains its own observed image. Measures prefixed leg_1_ and leg_2_ (and leg_3_ for order two) retain nm or radians. Scope, frames, reference/producer provenance, and the complete attributed leg parameters accompany the result.

Return type:

molsysmt.Interactions or molsysmt.InteractionsDict

Raises:

ArgumentError – If units, methods, profiles, state, indices or selections are invalid.
StructuralInconsistencyError – If chemistry/geometry is unavailable or joined shared images conflict.
UnsupportedHeavyOperationError – If forced streaming is unsupported or a chemical match cap is exceeded.
MemoryBudgetExceededError – If numerical graphs, leg/bridge output or join estimates exceed budget.

Notes

The path construction follows the water-mediated hydrogen-bond path concept used by ProLIF WaterBridge and MDAnalysis WaterBridgeAnalysis, adapted to atom-level observations rather than residue fingerprints. Leg science is explicitly chosen and attributed; the default uses Baker-Hubbard criteria, not ProLIF’s default thresholds. No global parity with either application’s pruning, networks, force-field typing or aggregation is claimed.

Join only simultaneous legs with distinct nonwater endpoint heavy atoms. The water can donate both legs, accept both, or donate one and accept one. Different donor hydrogens are different observations, including bifurcated hydrogen bonds; neither branch direction nor hydrogen roles are discarded. Order legs along the path starting from the lower external heavy-atom index, preserving each directed D-H-A tuple. An undirected path appears once per exact leg sequence and frame. Order two requires two distinct water oxygens and their observed connecting leg; cycles and repeated endpoint atoms are excluded. All returned participants are actual leg atoms; an unused water hydrogen is not an additional participant. Internal queries and atom removal use those participants. Neutral explicit waters are recognized by chemical graph, not residue name. Paths through more than two waters, implicit hydrogens, energies and global frequency pruning are excluded.

No dense atom-pair or trajectory tensor is allocated. Leg coordinates use the existing projected executor. Numeric resident leg columns, join arrays and sparse bridge packing are checked against the configured budget; source chemistry, Python overhead and process RSS are not fully modeled. All accepted leg and bridge output must fit in RAM; this is not a streaming writer.