molsysmt.physchem.get_water_sites#

molsysmt.physchem.get_water_sites(molecular_system, selection='all', structure_indices='all', chemical_state='reference', method='explicit_water_graph', assume_complete_connectivity=False, syntax='MolSysMT', skip_digestion=False, *, max_matches=100000)[source]#

Recognizing neutral water molecules with three explicitly indexed atoms.

Parameters:

  • molecular_system (molecular system) – Any supported form supplying elements, complete connectivity, covalent orders, formal charges and atom/bond aromatic flags.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Source atom selection. Retain water only when all three atoms belong to the selection. Recognize the full chemical graph before filtering.

  • structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based) for state resolution and spatial selections. Recognition itself does not require coordinates.

  • chemical_state ({'reference', 'structure'}, int, or None, default='reference') – State supplying chemistry. Structure assignments must resolve one state.

  • method (str, default='explicit_water_graph') – Neutral O with exactly two single-bonded, degree-one neutral indexed H.

  • assume_complete_connectivity (bool, default=False) – Record a completeness assumption without repairing chemical assignments.

  • syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection.

  • skip_digestion (bool, default=False) – Whether to skip MolSysMT’s internal argument digestion mechanism.

  • max_matches (int, default=100000) – Keyword-only maximum full-source SMARTS matches before selection. Exceeded limits raise rather than silently truncating water molecules.

Returns:

int64 water_atom_indices with shape (n_waters, 3), ordered oxygen then ascending hydrogen indices, plus source/selected axes, chemical state, recognition evidence, actual producer versions and bibliography. Empty water_atom_indices has shape (0, 3).

Return type:

dict

Raises:

  • ArgumentError – If method, selection, state or match limit is invalid.

  • StructuralInconsistencyError – If required chemistry is absent or altered by sanitization.

  • UnsupportedHeavyOperationError – If chemical matching exceeds max_matches.

  • MemoryBudgetExceededError – If numerical chemical matching exceeds its working estimate.

Notes

Recognize the explicit molecular graph rather than a water residue name. Oxygen-only water with implicit hydrogens, hydroxide, hydronium, alcohols, peroxide and covalently shared hydrogens are excluded. Isotopic hydrogen remains an indexed H. No hydrogens or coordinates are added. Dative links are independent of the covalent graph, so metal-coordinated water remains eligible. Virtual-site water models with additional covalent sites need a separately specified recognition profile. This definition does not certify a force-field water model or hydrogen-bond donor/acceptor rule.

See also

molsysmt.physchem.get_hbond_sites

Recognizing hydrogen-bond roles independently of water identity.

molsysmt.interactions.water_bridges.get_water_bridges

Composing single-water paths from two observed hydrogen bonds.

Examples

>>> import molsysmt as msm
>>> from rdkit import Chem
>>> sites = msm.physchem.get_water_sites(Chem.AddHs(Chem.MolFromSmiles('O.CO')))
>>> sites['water_atom_indices'].tolist()
[[0, 3, 4]]

User guide

See Getting water sites.

Added in version 1.0.0.

On this page