orthonym.validation.twin_spellings

Note

Internal API. Names and behaviour may change between releases.

Twin spellings: a Blue Book PIN spelling that OPSIN 2.9.0 has no grammar for, checked through a spelling of the same structure that OPSIN reads.

A twin is a token-level rewrite of the PIN spelling into a general-nomenclature spelling that names the same structure. It proves the structure and never the spelling: the producer that builds the PIN spelling owns its correctness, and the twin replaces only the OPSIN read-back. A name ships through its twin when OPSIN rejects the name, the twin reads to the input’s FULL InChIKey (namer._shipped_name_round_trip: the radical and the protonation site are checked too) and OPSIN gives no APPEARS_AMBIGUOUS warning for the twin. The twin is never shipped.

Why the ambiguity check: Citation of locants (the Blue Book) “if any locants are essential for defining the structure of the parent structure…, then all locants must be cited”. A twin that OPSIN reads only by choosing among readings does not prove the structure of the name it stands for.

The families (the rules of:data:TWIN_RULES, in table order):

• bridge_sulfano, bridge_disulfano, bridge_azano: Divalent bridges,

  (the Blue Book-14110): “The following names are now recommended as

  preselected (see bridge prefixes: ‘sulfano’, –S–;’disulfano’, –SS–;… ‘azano’, –NH–” and “The bridge prefixes ‘epithio’, ‘epidithio’, ‘episeleno’, ‘epitelluro’, and ‘epimino’… may be used in general nomenclature” (:14097); the PIN example ‘1,4-dihydro-1,4- sulfanonaphthalene (PIN)’ stands under CYCLIC ETHERS, SULFIDES, SELENIDES AND TELLURIDES (:28063). The twins are ‘epithio’, ‘epidithio’ and ‘epimino’. ‘selano’ and ‘tellano’ have no twin: OPSIN reads ‘episeleno’ and ‘epitelluro’ as a [SeH2] / [TeH2] bridge, another structure. A bridge cited more than once (‘1,4:5,8-’ before the prefix) has no twin rule: ‘disulfano’ is the name of the –S–S– bridge (:14105), so it cannot stand for two –S– bridges.

• interior_phenalene: Numbering of interior carbon atoms (the Blue Book),

  (:12658): “The locant for the interior atom is that of the peripheral atom with a

  superscript number corresponding to the number of bonds between the two atoms. The previous rule … recommended that interior atoms follow the highest numbered peripheral atom adding Roman letters in sequence to the appropriate peripheral number.” The interior atom of phenalene is ‘3a^1’ (the former ‘9b’), as in ‘1,3a^1,4,9-tetraazaphenalene (PIN)’,:14470, example:14491). OPSIN reads the former locant: ‘1,9b,4,9-tetraazaphenalene’. The numbering of the peripheral atoms is the same in both, so the twin is the same structure; the rule applies to a name of the parent ‘phenalene’ only.

• isotope_letter_once: (heading NAMES,:43824, example:43830) “In a name consisting of one word, the isotopic descriptor is placed before the name, with an appropriate locant”, ‘(N-2H2)aniline (PIN)’: a letter locant is cited once for a nuclide that is multiplied. OPSIN reads the letter once per atom: ‘(N,N-2H2)aniline’.

• isotope_count_one: (heading Omission of locants,:44184) “ethan(2H)ol (PIN) (as in ethanol)”, (:44214) ‘(1-2H1)ethan-1-(2H)ol (PIN)’, (heading

  ORDER OF NUCLIDE SYMBOLS,:43832; the rule:43834) ‘methan(2H,18O)ol (PIN)’ (:43840): a

  hydrogen nuclide that needs neither a count nor a locant is cited bare. OPSIN reads such a nuclide with a count: ‘(2H1)’. A hydrogen nuclide with a locant in its descriptor (‘(O-2H)acetic acid’) is read as written and is not rewritten, and the (2H) / (3H) that follows a locant, primed or not (‘naphthalen-2(3H)-one’, ‘[1,1’-biphenyl]-4’(2H)-one’), is the added-hydrogen mark.

• polyester_acyloxy (validation.polyester_twin): method (1), the functional-class polyol polyester name ‘propane-1,2,3-triyl 1,3-diacetate 2-propanoate (PIN)’ (the Blue Book) and its acyloxy spelling ‘1,3-bis[acetyloxy]-2-[propanoyloxy]propane’, substitutive nomenclature of the same ester,:31968). OPSIN reads the second and not the first. A half ester of a polybasic acid has no acyloxy spelling OPSIN reads, and its name does not ship.

• halido_o (validation.halido_twin): (the Blue Book) ‘trichlorido(methyl)titanium’ (:39789) and the long-established ligand spelling ‘trichloro(methyl)titanium’,:39761,:39767), which OPSIN reads; the additive names of the transition-metal producer, without a hapto descriptor.

• uide_lambda (validation.uide_twin): ANIONS FORMED BY ADDITION OF HYDRIDE IONS (the Blue Book), method (1) ‘diphenyliodanuide (PIN)’ and its method (2) spelling ‘diphenyl-lambda3-iodanide’ (:41110), which OPSIN reads. The family is structure-blind like the others but is not a rewrite of the name alone: the lambda number is the one method (2) pairs with an unmarked -uide name of the element, so it lives in its own module and is reached from twin_round_trip(); a general tier ships a name through its twin for this family and the next.

• thioperoxol_sulfenic, thioperoxol_peroxol (validation.thioperoxol_twin): THE SUFFIXES ‘SO-THIOPEROXOL’, AND CHALOGEN ANALOGUES (the Blue Book), ‘CH3-S-OH methane-SO-thioperoxol (PIN) (not methanesulfenic acid)’ (:24326); Basic functional suffixes (:17456), “-OS-thioperoxol for -OSH” is ‘peroxol’ modified by functional replacement (:17460). The twin of ‘-SO-thioperoxol’ is ‘-sulfenic acid’, that of ‘-OS-thioperoxol’ is ‘-peroxol’ read against the structure with the sulfur an oxygen; OPSIN has no grammar for either suffix at any tier. The default tier ships them through the twin; a general tier ships the name OPSIN reads itself, ‘(hydroxysulfanyl)methane’, and the twin only for the anion of -S-OH, which has no such name, and as the safety net of a molecule that only the PIN path names (validation.thioperoxol_twin).

• anhydride_acids (validation.anhydride_acids): Di- and polyanhydrides (the Blue Book) ‘diacetic butanedioic dianhydride (PIN)’ (:32386). No twin spelling of such a name exists (OPSIN reads a two-word anhydride only), so the check reads each acid word as <acid> acid and builds the poly-anhydride from those acids; it ships a name at the default tier only.

orthonym.validation.twin_spellings.descriptor_spans(name)

(start, end) of every isotopic descriptor of name: a parenthesised group of nuclide items that no locant precedes.

orthonym.validation.twin_spellings.bare_hydrogen_groups(name)

(start, end) of every descriptor of name that cites a hydrogen nuclide without count and locant, the groups of the rule isotope_count_one.

orthonym.validation.twin_spellings.TWIN_RULES: Tuple[Tuple[str, Callable[[str], str]], ...] = (('bridge_sulfano', <function _bridge_rule.<locals>.<lambda>>), ('bridge_disulfano', <function _bridge_rule.<locals>.<lambda>>), ('bridge_azano', <function _bridge_rule.<locals>.<lambda>>), ('interior_phenalene', <function _interior_phenalene>), ('isotope_letter_once', <function _letter_once>), ('isotope_count_one', <function _count_one>), ('polyester_acyloxy', <function polyester_twin>), ('halido_o', <function halido_twin>))

(rule id, rewrite) in the order the rules apply; each rewrite is pure and deterministic

orthonym.validation.twin_spellings.twin_of(name)

(twin, rule ids in table order) of name, or None when no rule applies.

orthonym.validation.twin_spellings.twin_round_trip(name, smiles)

The applied rule ids joined by + when the twin of name reads to the FULL InChIKey of smiles and OPSIN reads it once; else None (no twin, a twin of another structure, an unavailable OPSIN, an ambiguous reading). A halogen -uide name and a thioperoxol name have a family of their own (validation.uide_twin, validation.thioperoxol_twin), and a poly-anhydride name is read through its acids (validation.anhydride_acids). This is the check of the default tier: a thioperoxol name ships through its twin there always, at a general tier only the anion does, and a neutral name as the safety net (general_tier_twin_round_trip()).

orthonym.validation.twin_spellings.general_tier_twin_round_trip(name, smiles)

The twin families a general tier ships a name through: a name no OPSIN grammar reads at any tier and for which the engine has no other spelling (the halogen -uide names, validation.uide_twin), and an additive organometallic name with ‘chlorido’ ligands, validation.halido_twin, whose Blue Book ligand word no OPSIN grammar reads either); the other families spell the form OPSIN reads there. The anion of -S-OH, a thioperoxolate name, belongs here too: the engine has no other spelling for it (validation.thioperoxol_twin). A neutral thioperoxol name has one, the name by prefixes that OPSIN reads (‘(hydroxysulfanyl)methane’): it ships through its twin only inside thioperoxol_twin.last_resort_scope, for a molecule that has no other name. The rule id, or None.

orthonym.validation.twin_spellings.opsin_spelling(name, radical=False)

The spelling to give OPSIN to read the structure of name: name, or its twin when OPSIN rejects name and reads the twin. For the checks of a builder that read the name it is about to return (the tautomer of the drawing, the stereo of a prefix); radical is True for a name with a free valence (a prefix), which OPSIN reads with its radical setting on. The validity gate still refuses a twin OPSIN reads as ambiguous (twin_round_trip()).

orthonym.validation.twin_spellings.twin_opsin_parse(name)

OPSIN’s SMILES for the twin of name at a default-tier call; None at a wider tier, when no rule applies, when OPSIN rejects the twin or reads it as ambiguous (twin_round_trip()). The isotope placement search reads its candidates through this.

orthonym.validation.twin_spellings.twin_gate_ships(name, smiles, general_tier=False)

The twin branch of the validity gate: True, with the outcome twin_verified:<rules> recorded for name, when:func:twin_round_trip verifies the twin of name. A general tier (general_tier) ships only a name of:func:general_tier_twin_round_trip through its twin.

orthonym.validation.twin_spellings.twin_outcome_holds(name, smiles)

None unless the gate recorded a twin outcome for exactly this string; else whether the twin still reads back to smiles (the OPSIN parse is memoized: no new JVM call).

orthonym.validation.twin_spellings.twin_offer_holds(name, smiles)

Whether the twin of name, an offer no gate has seen yet (an isotope-labelled name is gated at the exit of the call), reads back to smiles; False at a wider tier.

orthonym.validation.twin_spellings.publish_tier_flags(wider)

Publish the tier of a naming call for the producers: ps_tier_ctx as the call’s own flag and, for a wider tier, wider_tier_ctx (metrics.provenance). The (variable, token) pairs are returned for the caller to reset when its call ends.

orthonym.validation.twin_spellings.pin_spellings_on()

True where the producers spell the Blue Book PIN form: a default-tier call. A wider tier (wider_tier_ctx) spells the general form OPSIN reads.