molsysmt.interactions.halogen_bonds.get_halogen_bonds#

molsysmt.interactions.halogen_bonds.get_halogen_bonds(molecular_system, selection='all', selection_2=None, structure_indices='all', chemical_state='reference', method='distance_two_angles', distance_threshold=None, donor_angle_range=None, acceptor_angle_range=None, selection_mode='internal', pbc=True, assume_complete_connectivity=False, output_type='molsysmt.Interactions', syntax='MolSysMT', skip_digestion=False, *, max_matches=100000, heavy_mode='auto', profile=None)[source]#

Detecting sparse halogen bonds by distance and two directional angles.

Evaluate D-X…A-R chemical sites using a separately identified recognition profile. Return observations without automatically attaching them to MolSys.

Parameters:

molecular_system (molecular system) – Any supported form supplying coordinates and declared elements, connectivity, covalent orders, formal charges and aromatic flags.
selection (str, list, tuple, or numpy.ndarray, default='all') – Source atom selection defining the calculation scope. All four roles count for internal, incident and between membership.
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). Evaluate repeated indices once, sorted; evaluated frames without observations remain explicit.
chemical_state ({'reference', 'structure'}, int, or None, default='reference') – State supplying chemical sites. Structure-assigned states must resolve one known state across all requested frames.
method (str, default='distance_two_angles') – Distance and two inclusive angular intervals. The recognition profile and exact reference definition are recorded separately.
distance_threshold (quantity, str, or None, default=None) – Finite positive scalar length cutoff for X-A. None uses 0.35 nm.
donor_angle_range (quantity, str, or None, default=None) – Two-value angular quantity [minimum, maximum] for D-X-A, ordered within zero to pi radians. None uses [130, 180] degrees.
acceptor_angle_range (quantity, str, or None, default=None) – Two-value angular quantity [minimum, maximum] for X-A-R, ordered within zero to pi radians. None uses [80, 140] degrees.
selection_mode ({'internal', 'incident', 'between'}, default='internal') – Require all four atoms in selection, any atom in selection, or all in the union of both selections with at least one in each, respectively.
pbc (bool, default=True) – Use MIC when a box exists. Reconstruct the observed D-X-A-R chain from adjacent MIC vectors and retain its integer images, anchored on D.
assume_complete_connectivity (bool, default=False) – Record an explicit completeness assumption without repairing source chemistry when connectivity metadata is insufficient.
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.
max_matches (int, default=100000) – Keyword-only maximum matches per chemical SMARTS before selection.
heavy_mode ({'auto', 'force', 'off'}, default='auto') – Keyword-only execution policy. Native/H5MSM projected coordinates use bounded blocks; accepted sparse observations remain in memory.
profile (str or None, default=None) – Keyword-only smarts_donor_acceptor profile from ProLIF 2.2.2. None selects that profile. The ProLIF package is not a runtime dependency.

Returns:

Four singleton roles donor, halogen, acceptor, acceptor_reference; X-A, D-X and A-R distances in nm and D-X-A/X-A-R angles in radians. Distinct reference neighbors remain distinct relations. Coverage, actual atom scope, versions, scientific/reference bibliography and periodic images serialize without a dense pair-by-frame matrix.

Return type:

molsysmt.Interactions or molsysmt.InteractionsDict

Raises:

ArgumentError – If units, intervals, method, selections, state or indices are invalid.
StructuralInconsistencyError – If required chemistry, finite coordinates or valid boxes are absent.
UnsupportedHeavyOperationError – If forced streaming is unavailable, a block exceeds budget or a chemical match limit is exceeded.
MemoryBudgetExceededError – If chemical matching, candidates or resident sparse output exceed their numerical working estimates.

Notes

Reproduce ProLIF 2.2.2 XBAcceptor/DoubleAngle core on the full source graph, without ligand/protein residue fingerprinting or covalent/intramolecular exclusions. Geometry adapts Auffinger et al., PNAS 2004, doi:10.1073/pnas.0407607101. This is not the paper’s exact element-specific van der Waals criterion or proof of attractive energy. All interval bounds are inclusive with no added geometric tolerance; undefined angles are skipped. Floating-point evaluation and angstrom-to-nanometer conversion can change membership exactly on a cutoff even when measured angles agree to roundoff. Chemical acceptor rules differ from hydrogen bonds. Every A-R neighbor matching the profile supplies a separately identifiable directional observation.

Coherent chain MIC is a MolSysMT periodic extension to the raw reference coordinates. It reconstructs listed adjacent vectors, not ring closure or a whole molecular component. Stored row-box shifts reproduce both measured angles and the contact distance. Numeric coordinate blocks reserve one quarter of the configured RAM budget, candidates one eighth and sparse accumulation one half; graphs, Python overhead and process RSS are outside those estimates. There is no incremental result writer.

Completed empty calculations retain coverage and attribution. Optional Ackredit credits the active workflow; reading results does not credit a new calculation. RDKit is lazy and used for chemical matching, not ProLIF.