molsysmt.physchem.get_hbond_sites#

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

Recognizing donor-hydrogen pairs and acceptors with an attributed rule.

This chemical tool does not calculate hydrogen bonds or infer hydrogens from coordinates. Every returned hydrogen is an indexed source atom.

Parameters:

  • molecular_system (molecular system) – Any supported form supplying element symbols and complete declared covalent connectivity. ProLIF also requires declared formal charges, bond orders and atom/bond aromatic flags.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Atom selection. Retain donor-hydrogen pairs only when both atoms are selected, and acceptors when selected. Match the full source first.

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

  • chemical_state ({'reference', 'structure'}, int, or None, default='reference') – State supplying connectivity and chemistry. Structure-assigned states must resolve to one state across the requested frames.

  • method (str, default='elemental_nitrogen_oxygen') – elemental_nitrogen_oxygen recognizes N/O donors bonded to indexed H and all N/O acceptors; elemental_fluorine_oxygen_nitrogen uses F/O/N for both roles. smarts_donor_acceptor uses the attributed ProLIF 2.2.2 SMARTS. mdtraj, cpptraj and prolif remain compatibility aliases.

  • assume_complete_connectivity (bool, default=False) – Explicitly assume supplied connectivity complete when metadata is insufficient. The assumption does not change the source chemistry.

  • 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 matches per ProLIF SMARTS query, before selection. An exceeded limit raises rather than returning a truncated site set.

Returns:

int64 donor_hydrogen_pairs with shape (n_pairs, 2), acceptor_atom_indices with shape (n_acceptors,), source atom indices, selected indices, state, method reference, chemical evidence and producer versions. No physical units apply to these indices. Empty pairs have shape (0, 2).

Return type:

dict

Raises:

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

  • StructuralInconsistencyError – If elements/connectivity or the required declared chemistry are absent.

  • UnsupportedHeavyOperationError – If a ProLIF query exceeds max_matches.

Notes

The returned attribution field contains a detached bibliography, with reference implementations distinguished from executed dependencies. Optional Ackredit records this completed recognition in the current session.

These are candidate-site definitions, not universal donor/acceptor chemistry. Elemental profiles intentionally include chemically unsuitable N/O atoms; they reproduce the reference rules. No water, sidechain, residue or solvent pruning is applied. ProLIF SMARTS are reproduced with Apache-2.0 attribution. RDKit is optional for that profile; MDTraj, CPPTRAJ and ProLIF packages are not production dependencies. Dative links do not create donor-H pairs.

See also

molsysmt.interactions.hbonds.get_hbonds

Applying geometric criteria to candidate sites.

molsysmt.topology.get_substructure_matches

Matching general chemical SMARTS on declared source graphs.

Examples

>>> import molsysmt as msm
>>> from rdkit import Chem
>>> sites = msm.physchem.get_hbond_sites(Chem.AddHs(Chem.MolFromSmiles('O')))
>>> sites['donor_hydrogen_pairs'].tolist(), sites['acceptor_atom_indices'].tolist()
([[0, 1], [0, 2]], [0])

User guide

See Getting hydrogen-bond sites.

Added in version 1.0.0.

On this page