molsysmt.interactions.hbonds.get_buch_hbonds#

molsysmt.interactions.hbonds.get_buch_hbonds(molecular_system, selection='all', acceptors=None, donors=None, structure_indices='all', molecular_system_2=None, selection_2=None, acceptors_2=None, donors_2=None, structure_indices_2=None, distance_threshold='2.3 angstroms', pbc=True, syntax='MolSysMT', skip_digestion=False, *, output_type='tuple')[source]#

Calculating hydrogen bonds using the Buch geometric criteria.

Parameters:

  • molecular_system (molecular system) – Molecular system in any supported MolSysMT format.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Selection string or boolean/integer array specifying elements.

  • acceptors (numpy.ndarray, list, or tuple, default=None) – Precomputed atom indices of hydrogen bond acceptors.

  • donors (numpy.ndarray, list, or tuple, default=None) – Precomputed atom indices of hydrogen bond donors.

  • structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based) to include or process.

  • molecular_system_2 (object, default=None) – A second molecular system is not supported by this method.

  • selection_2 (str, list, tuple, or numpy.ndarray, default=None) – Second selection string or boolean/integer array.

  • acceptors_2 (numpy.ndarray, list, or tuple, default=None) – Precomputed acceptor atom indices for selection_2.

  • donors_2 (numpy.ndarray, list, or tuple, default=None) – Precomputed donor atom indices for selection_2.

  • structure_indices_2 (int, list, tuple, or numpy.ndarray, default=None) – Structure indices (0-based) for the second selection.

  • distance_threshold (quantity, default='2.3 angstroms') – Maximum hydrogen-to-acceptor separation; equivalent to 0.23 nm.

  • pbc (bool, default=True) – Whether to take periodic boundary conditions into account.

  • syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection (e.g., ‘MolSysMT’, ‘MDTraj’).

  • output_type ({'tuple', 'molsysmt.Interactions'}, default='tuple') – Return the established triples and distances, or a sparse analysis with evaluated coverage, participant scope, and periodic images. The analysis currently requires automatically identified roles and one selection, two disjoint participant universes, or identical role selections.

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

Returns:

By default, (atoms, distances) in requested structure order. Equal per-structure counts give an integer array with shape (n_structures, n_hbonds, 3) and a nanometer distance quantity with shape (n_structures, n_hbonds). Varying counts give aligned lists of (n_hbonds, 3) arrays and (n_hbonds,) quantities, including shaped empty entries. Triples use donor, hydrogen, acceptor order and original system atom indices. The optional sparse analysis preserves original atom and structure indices and deduplicates repeated requested structures.

Return type:

tuple or molsysmt.Interactions

Raises:

  • NotImplementedMethodError – If a second molecular system is supplied, or the optional analysis uses supplied role arrays, a second structure axis, or partially overlapping participant universes.

  • InternalAlgorithmError – If observed periodic images disagree with the detected H-A distances or cannot be represented with int32 lattice shifts.

Notes

The detector returns an independent analysis. Attach it to molsys.interactions under an explicit name to retain it with the system. This method uses eager execution and does not stream large trajectories. The optional analysis records the calculation-time MolSysMT version in software; serialization preserves it independently of the reader version. Its parameters retain the descriptive hydrogen_acceptor_distance criterion and a bibliography without inventing an unverified original Buch paper. Completed calculations contribute to an optional Ackredit workflow session; tuple outputs retain their existing layout without embedded metadata.

Examples

>>> import molsysmt as msm
>>> from molsysmt.interactions.hbonds.get_buch_hbonds import get_buch_hbonds
>>> molsys = msm.convert(msm.systems["chicken villin HP35"][
...     "chicken_villin_HP35.h5msm"], to_form="molsysmt.MolSys")
>>> result = get_buch_hbonds(molsys, selection=[0],
...                         output_type="molsysmt.Interactions")
>>> result.n_interactions
0

User guide

See Get Buch hydrogen bonds for the distance criterion and Querying interaction results for sparse queries and persistence.

Added in version 1.0.0.

On this page