orthonym.rules.isotopes#

Note

Internal API. Names and behaviour may change between releases.

Isotopically substituted compound names (IUPAC +.

Fail-closed decorator layer. Orthonym’s core pipeline strips isotope labels (RDKit perception ignores GetIsotope for skeleton naming), so a labeled mol would otherwise emit the UNLABELED name — a wrong PIN. This module runs as an EARLY branch in Orthonym.name: it strips the labels, names the skeleton in systematic style (locanted parents), then re-derives the isotopic descriptor by an INTERNAL ORACLE (OPSIN-parse a candidate name; compare rdkit canonical SMILES — with isotopes — to the original). If no candidate round-trips, it returns None and the label is never mis-placed.

BB (the Blue Book): the nuclide symbol(s) in parentheses, preceded by any necessary locant(s), are inserted before the isotopically substituted part; polysubstitution count is a right subscript to the symbol. BB /.4.2/.4.3 (the Blue Book-22232): lowest locants to modified positions; then to higher atomic number; then to higher mass number.

orthonym.rules.isotopes.has_isotopes(mol)#

True iff any atom of mol carries a non-zero isotope label.

orthonym.rules.isotopes.strip_isotopes(mol)#

Return an isotope-cleared COPY of mol and a {atom_idx: mass} map.

Atom indices are preserved by RWMol copy, so the returned map indexes the stripped mol AND the original identically. Used to name the skeleton and later to place isotopic descriptors at the correct positions.

orthonym.rules.isotopes.nuclide_symbol(mass, element)#

Nuclide symbol with the mass number as a leading integer (ASCII form).

Orthonym emits ASCII (no <sup>); OPSIN accepts the leading-digit form (probe: (2-14C)ethan-1-ol -> C([14CH3])O)..

orthonym.rules.isotopes.format_isotope_descriptor(groups, force_show=False, bracket=False)#

Build the parenthesized isotopic descriptor from grouped labels.

bracket=True (FIX-F, / renders the SPECIFICALLY-LABELLED form [2H1] / [13C] in square brackets instead of the substituted form (2H1) / (13C). It is OPT-IN and OFF on the default single-call path by design: a labelled compound is STRUCTURALLY IDENTICAL to its substituted counterpart ([13CH4] is one graph), so nothing in a bare SMILES selects between the two conventions – the whole of chapter is therefore a permanent RIGHT_MOL_NONPIN ceiling under the default parenthetical form, not a reclaimable gap. The renderer exists and is testable so a caller that KNOWS it wants the labelled convention (e.g. a future explicit-mode API) can request it; the swap of the enclosing marks around a nested complex prefix is a documented extension point, not built here. See internal notes

force_show=True restores the pre-FIX-A always-emit-the-subscript form regardless of max_at_pos. The placement search uses it as a FALLBACK: the BB-preferred omitted form (2H) / (13C) is tried first, but OPSIN 2.9.0 does not parse every omitted spelling in every position (e.g. an O-bound single (2H) before an -oic acid suffix), so when the omitted form does not round-trip the forced form (2H1) is tried before abstaining – the right molecule at a non-preferred spelling beats silence (never a wrong name; every candidate stays OPSIN-RT gated).

groups = list of (locant, mass, element, count[, max_at_pos]):
locant None -> no leading locant (single-position parent / front

descriptor, e.g. (2H3)methoxybenzene, (12C)methane).

locant int -> the count locants are repeated then hyphen-joined to the

nuclide, e.g. (2,2,2-2H3), (2-14C).

max_at_pos -> OPTIONAL 5th field, the polysubstitution quantity

(_max_atoms_at_position()). Absent (legacy 4-tuple) -> the count subscript is kept unconditionally (the pre-FIX-A behaviour), so only a caller that supplies max_at_pos gets the omission.

Multiple groups at (possibly) the same place are cited alphabetically by element then by mass number /; groups are comma-joined.

(the Blue Book-43720): the count subscript is shown “when polysubstitution

at a single position is possible”. So it is emitted iff count > 1 (more than one atom of the nuclide is cited together) OR max_at_pos > 1 (the single position could carry a second atom of that element) – e.g. a lone D on a CH3 keeps (2H1) (3 H can occupy) but a lone 13C keeps no subscript (13C) (a carbon position holds one carbon) and a lone D on a CH keeps none (2H) (1 H can occupy). Verbatim witnesses: trichloro(12C)methane, (2-13C)ethan-1-ol, (2S)-(2-2H)butan-2-ol.

orthonym.rules.isotopes.decorate_isotopic_name(smiles, style, namer)#

Fail-closed isotopic-substitution PIN +.

  1. Parse + strip isotopes; if none, None.

  2. Name the skeleton in systematic style (locanted parents).

  3. Enumerate candidate descriptors (lowest-locant-first, and accept the first whose OPSIN round-trip reproduces the original mol.

  4. None if nothing round-trips (never a wrong labeled name).