molsysmt.physchem.get_halogen_bond_sites#

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

Recognizing ordered donor-halogen and acceptor-reference atom pairs.

Match complete source chemistry before filtering sites by atom selection. No coordinates or interaction geometry are inferred by recognition.

Parameters:

  • molecular_system (molecular system) – Any supported form supplying explicit 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 a site only when both its atoms belong to the selection; full-source matching precedes this filter.

  • 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='smarts_donor_acceptor') – ProLIF 2.2.2 ordered chemical SMARTS profile, without geometric criteria.

  • assume_complete_connectivity (bool, default=False) – Record an explicit completeness assumption when metadata is insufficient; do not repair the chemical graph or infer missing bonds.

  • 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 query before selection. Exceeded limits raise instead of silently truncating the site inventory.

Returns:

int64 donor_halogen_pairs and acceptor_reference_pairs with shapes (n_sites, 2), preserving role order rather than independently sorting columns. Empty arrays have shape (0, 2). Metadata contains source and selected indices, chemical state, SMARTS, evidence, producer versions and detached reference bibliography. Indices are unitless, not IDs.

Return type:

dict

Raises:

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

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

  • UnsupportedHeavyOperationError – If the query exceeds max_matches.

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

Notes

The donor is [C,N,Si,F,Cl,Br,I]-[Cl,Br,I,At], excluding F as the terminal halogen. Acceptor-reference matches use [N,O,P,S,Se,Te,a;!positive]!#[*]: non-triple links, including carbonyl and aromatic links. The acceptor definition is intentionally distinct from hydrogen-bond acceptors. Each eligible reference neighbor retains its own ordered pair. SMARTS sanitization preserves declared chemistry and uses RDKit valence rules. Water without indexed bonded atoms has no acceptor-reference match. These are candidate sites, not a universal chemical or energy model.

ProLIF’s Apache-2.0 rules are attributed; the ProLIF package is not needed. Optional Ackredit credits this recognition, while original geometric-paper attribution belongs to the detector that actually evaluates its criterion.

See also

molsysmt.topology.get_substructure_matches

Matching arbitrary SMARTS on declared chemical graphs.

molsysmt.interactions.halogen_bonds.get_halogen_bonds

Evaluating sparse distance and directional-angle observations.

Examples

>>> import molsysmt as msm
>>> from rdkit import Chem
>>> sites = msm.physchem.get_halogen_bond_sites(Chem.MolFromSmiles('CCl.C=O'))
>>> sites['donor_halogen_pairs'].tolist(), sites['acceptor_reference_pairs'].tolist()
([[0, 1]], [[3, 2]])

User guide

See Getting halogen-bond sites.

Added in version 1.0.0.