molsysmt.physchem.get_cip_stereochemistry#

molsysmt.physchem.get_cip_stereochemistry(molecular_system, selection='all', structure_indices='all', chemical_state='reference', engine='rdkit', syntax='MolSysMT', skip_digestion=False, *, from_coordinates=False)[source]#

Getting accurate CIP labels from declared stereo or one selected 3D structure.

Parameters:

  • molecular_system (molecular system) – Any supported form supplying chemical elements, complete connectivity, explicit charges and bond orders. SDF source hydrogen atoms are retained.

  • selection (str, list, tuple or numpy.ndarray, default='all') – Atoms to include in the result. The full graph is analyzed first; only bonds with both endpoints in the selection are returned.

  • structure_indices (int, list, tuple or numpy.ndarray, default='all') – Structure indices (0-based) for state resolution and spatial selections. Coordinate inference requires exactly one selected structure.

  • chemical_state (str or int, default='reference') – Selected chemical state; ‘structure’ must resolve to one state.

  • engine (str, default='rdkit') – Explicit optional provider implementing the Hanson et al. 2018 CIP algorithm. Missing RDKit raises; no alternative engine is selected.

  • syntax (str, default='MolSysMT') – Syntax used for selection.

  • skip_digestion (bool, default=False) – Whether to skip argument digestion.

  • from_coordinates (bool, default=False) – Keyword-only flag to infer tetrahedral and double-bond stereo from exactly one nonperiodic 3D conformer, replacing its declared tags on a copy.

Returns:

Source atom_indices, bond_indices, bonded_atom_pairs and aligned atom_stereochemistry/bond_stereochemistry arrays. None means no assigned CIP label. bond_stereo_atom_indices contains RDKit reference atoms, with [-1, -1] for unassigned bonds. It is not a priority-ranking table. bond_reference_stereochemistry gives cis/trans relative to those atoms, independently of the absolute E/Z labels. Empty arrays retain (0,), (0, 2) shapes. Metadata identifies method, provider/software versions, selected state, evidence and references.

Return type:

dict

Raises:

  • ArgumentError – If a provider, selection or structure request is invalid.

  • StructuralInconsistencyError – If chemistry is incomplete, assignment fails, a non-tetrahedral descriptor is encountered or coordinate inference lacks one conformer.

  • FormatError – If an SDF source uses unsupported query or enhanced stereo encodings.

Notes

Uses rdCIPLabeler.AssignCIPLabels, implementing Hanson et al. (2018), DOI 10.1021/acs.jcim.8b00324. The scientific method is distinct from the optional RDKit provider. The function changes neither source labels, reference state, hydrogens nor coordinates. Full-graph CIP assignment precedes selection. It does not reconstruct periodic molecules: supply compatible compact coordinates before requesting geometry inference. Explicit SDF directions are interpreted by the provider; query, enhanced stereo and unsupported relative-only encodings remain rejected. Optional Ackredit failures preserve completed labels and detached references, including under warnings-as-errors. Diagnostic failures use a fallback log; scientific exceptions and unrelated scientific warnings remain unchanged.

See also

molsysmt.topology.get_substructure_matches

Query a complete chemical graph.

Examples

>>> import molsysmt as msm
>>> from rdkit import Chem
>>> result = msm.physchem.get_cip_stereochemistry(Chem.MolFromSmiles('N[C@@H](C)C(=O)O'))
>>> result['atom_stereochemistry'].tolist()
[None, 'S', None, None, None, None]

User guide

See Getting CIP stereochemistry for evidence and selection rules.

Added in version 1.0.0.