orthonym.rules.relative_stereo#

Note

Internal API. Names and behaviour may change between releases.

cis/trans names for ring pairs at the best-effort tier.

A ring pair that the Blue Book names with lowercase r/s descriptors has a second, general name with cis or trans in front:

(1r,4r)-cyclohexane-1,4-diol (PIN) trans-cyclohexane-1,4-diol (the Blue Book) bis[(1r,4r)-4-methylcyclohexyl]phosphane (PIN)

bis(trans-4-methylcyclohexyl)phosphane (:48117)

“Achiral cyclic compounds” (:48103) gives the lowercase descriptors the PIN

status; ### Relative configuration: the stereodescriptors 'cis' and 'trans' (:48155) gives the general name: “When one ligand and one hydrogen atom are attached at each of two positions of a monocycle, the steric relation (the relative configuration) of the two ligands is expressed as ‘cis’ or ‘trans’, followed by a hyphen and placed before the name of the compound. No locants are required before the stereodescriptors.”

The best-effort tier ships only a name that OPSIN reads back to the input’s full InChIKey, and OPSIN reads no lowercase r/s, so the strict path’s name is withdrawn there. This module turns such a withdrawn name into the general name. It works from what the descriptor check accepted (validation.stereo_descriptors.stereo_block_units: the span of each descriptor block, its multiplicity and the stereo units the reading binds to it), never from a locant read out of the string, and the caller audits every candidate: the completeness predicates below, then the full-key round trip.

note_withdrawn_name/withdrawn_names are the slot that hands the withdrawn names from the validity gate to the offer builder,:func:append_relative_stereo_offer (Orthonym._maybe_append_relative_stereo_offer calls it).

orthonym.rules.relative_stereo.holds_pseudoasymmetric_block(name)#

Does name carry a descriptor block with a lowercase r or s?

orthonym.rules.relative_stereo.names_a_replacement_chain(name)#

Does name spell an acyclic chain or a monocycle by skeletal replacement, such as ...-2-oxaeth-1-en-1-yl... or 1-oxacyclopentan-3-yl? A name of this class is not a general name of the Blue Book (the heteroatom has a functional-group or Hantzsch-Widman name), so it is not the start of a relative-stereo offer. READ-ONLY: it classifies a candidate; it never rewrites one.

orthonym.rules.relative_stereo.clear_withdrawn_names()#

Empty the slot. Called at the start and at the end of every outermost name so that a naming reads only the names its own run withdrew.

orthonym.rules.relative_stereo.note_withdrawn_name(name, smiles, caller_input)#

Record that the validity gate withdrew name for smiles at the best-effort tier.

Only a WHOLE-MOLECULE call is recorded: smiles is the string the outermost name was given (caller_input). The cascade also gates the names of fragments of the molecule, and the names of other molecules a producer probes; their strings differ and they are ignored. Only a name with a lowercase r/s block is kept (the name no best-effort name can be: OPSIN reads no such descriptor), once, in the order withdrawn. Never raises: the slot is read by an offer builder that must not break naming.

orthonym.rules.relative_stereo.withdrawn_names(smiles)#

The names with a lowercase r/s block that the gate withdrew for the whole molecule smiles since the slot was cleared, in the order withdrawn.

orthonym.rules.relative_stereo.convert_pair_blocks(name, mol, records)#

The cis/trans names of name, a name with lowercase r/s descriptor blocks, for the input mol; ```` when the blocks cannot all be converted.

records are the:class:validation.stereo_descriptors.StereoBlockUnits of name (text, span, multiplicity, units), the output of the descriptor check that accepted name for this input. Every block with a lowercase code must be a ring pair (_pair_ring()) that is complete for a relative word (_ring_cistrans_is_complete: flipping both centres gives the same molecule; with two blocks also _rings_jointly_complete), and there are at most two such blocks, each in its own ring; a block with only uppercase codes (a stereocentre beside the pair, a meso pair) keeps its absolute descriptors. Every block is replaced at its span by cis- or trans-, in both senses, rightmost first so that the spans of the blocks to its left still hold; the enclosing marks of the groups that held a block, and of every group around them, are re-derived after each replacement (the stereo parentheses count toward the nesting order,, the Blue Book, and the word has none: [(1r,4r)-4-methylcyclohexyl]acetic acid becomes (trans-4-methylcyclohexyl)acetic acid, not [trans-4-methylcyclohexyl]acetic acid).

The candidates are in a fixed order (the senses of the leftmost block vary slowest, cis first). A candidate names the right molecule only if OPSIN reads it back to the input’s full InChIKey; the caller checks that, which also picks the sense.

Each candidate is a string built from name, so the producer that built name for the whole molecule is the one that built the candidate: the label of name in the producer record of the call (metrics.producer_trail) passes to every candidate, which is what makes the row of a molecule that ships a cis/trans name say which code built it.

orthonym.rules.relative_stereo.append_relative_stereo_offer(offers, mol, smiles, primary_name, primary_is_failure, *, rt_ok, self01_lookup)#

: append the cis/trans name of a ring pair to offers as an Offer above the systematic floor, IF the primary winner does not already full-RT-pass.

The best-effort tier ships only a name that OPSIN reads, and OPSIN 2.9.0 reads no lowercase r/s (BE-STRICT, _final_opsin_validity_gate), so the name of a ring pair that cites them – (1r,4r)-cyclohexane-1,4-diol, the Blue Book “Achiral cyclic compounds”) – is withdrawn there and the molecule is left with the floor’s trans-1,4-dihydroxycyclohexane. The Blue Book gives the same pair a general name, trans-cyclohexane-1,4-diol “Relative configuration: the stereodescriptors ‘cis’ and ‘trans’”, :48155).

The names the gate withdrew for this whole molecule are in:func:withdrawn_names, in the order they were withdrawn; the cascade builds them (the strict path is one source of them, not the only one). A withdrawn name is ELIGIBLE when

  • it does not spell a chain or a monocycle by skeletal replacement (names_a_replacement_chain());

  • the descriptor check (validation.stereo_descriptors.stereo_block_units, the check the default tier’s stereo-layer carve-out applies) accepts it for this input: every lowercase block is one it located, at the front of the name or of a prefix, never in the middle of the name, and its r/s descriptors are proven right;

*convert_pair_blocks() converts every lowercase block (a ring pair that both

completeness predicates make complete for a relative word) and re-derives the enclosing marks; and

  • OPSIN reads a converted name back to the input’s full InChIKey (rt_ok, which has no fail-open branch for a name no gate has seen).

The first candidate of the first eligible name is appended: tier systematic_verified (a correct name that is not the preferred one), never a PIN. The floor offer stays in the pool, so a name that does not read back leaves today’s floor name.

rt_ok(name, smiles) is the full-InChIKey round-trip predicate of the offer pool (namer._offer_rt_ok) and self01_lookup(name) the verdict the coverage audit reuses (namer._self01_lookup); the caller passes them so that they are resolved in the namer module at call time.

Best-effort ONLY, like the floor: both call sites in Orthonym._finish sit inside the _general_fallback_unverified guard. Nothing is built when the slot holds no name for this input, which is every input without a lowercase r/s block.

Never raises past the candidate loop – a failure there must leave offers as it was.