orthonym.validation.opsin_ambiguity#

Note

Internal API. Names and behaviour may change between releases.

A name that OPSIN reads as ambiguous.

OPSIN raises the warning APPEARS_AMBIGUOUS when part of a name has more than one reading and it had to choose (“Positioning of radical on: aziridin”, “Position of isotope on benz”, “Connection of phenyl to eth”). Such a name can round-trip, because OPSIN’s choice happens to be the input, and still not say which structure it names. Citation of locants (the Blue Book): “In preferred IUPAC names, if any locants are essential for defining the structure of the parent structure or of a unit of structure as defined by its appropriate enclosing marks, then all locants must be cited for the parent structure or that structural unit.” So the final validity check reads the warning and withdraws such a name, and the callers look for a name OPSIN reads once: the same producers once more with every omission licence switched off (locant_omission.forced_locant_scope, reason FORCED_LOCANT_REASON), then the other classes of the cascade.

Two things keep a withdrawn name from being lost.

  • A class the Blue Book itself prints in a form OPSIN reads as ambiguous (a specific-method carbenium, a label on a delocalized group, the pseudoketone of a peroxy chain) is not withdrawn (licensed_ambiguity()): the class is read from the structure by the rule that builds it, and the name is the PIN.

  • A molecule that has no other name keeps the withdrawn one (restore_withdrawn()), recorded as a name that is not the PIN: a name that round-trips is a better answer than none at the best-effort tier, where it is labelled below the PIN. The default tier ships a preferred name or declines (NO_VERIFIED_PIN: the engine built a name that is not a verified PIN), so the record is what makes it decline there.

orthonym.validation.opsin_ambiguity.AMBIGUITY_WARNING = 'APPEARS_AMBIGUOUS'#

the OPSIN warning type that says a name has more than one reading

orthonym.validation.opsin_ambiguity.FORCED_LOCANT_REASON = 'opsin_ambiguity'#

the reason of the forced_locant_scope of the retry

orthonym.validation.opsin_ambiguity.ambiguity_messages(name)#

The APPEARS_AMBIGUOUS messages OPSIN gives for name, read with the radical setting of the validity gate’s oracle; empty when OPSIN gives none, rejects the name or cannot be asked in process (the round trip of the same name fails closed on an unavailable OPSIN, so this check adds no verdict there).

orthonym.validation.opsin_ambiguity.licensed_ambiguity(name, smiles)#

The Blue Book rule whose class name belongs to, when that rule prints the name although OPSIN reads it as ambiguous, else None.

  • Specific method (the Blue Book): ‘propylium (PIN)’, ‘methylium (PIN)’ (:41557). The class is a terminal cation of a saturated unbranched acyclic hydrocarbon, read from smiles by rules.ions.specific_method_cation_name, the producer’s own class predicate; the name is the one the rule builds for it. The method names the terminal atom by definition, so the name has one position.

  • DELOCALIZED RADICALS AND IONS (:43540): a heavy nuclide on an atom of a delocalized group is one species whatever atom carries it, so its descriptor cites no locant (rules.isotopes.heavy_label_on_delocalized_atoms); only when the warnings OPSIN gives are about the position of that isotope.

  • Pseudoesters (:32074): “When ‘E’ is an element belonging to Group 16, the pseudoester is named as a pseudoketone”, example ‘[1-(methylperoxy)sulfanyl]butan-1-one (PIN)’ (:32078), the locant inside the marks of the prefix. The class is an acyl group on S, Se or Te with a peroxy chain that ends in an organyl group, read from smiles by rules.pseudoketones.pseudoester_book_name, the producer’s own class predicate; the name is the one the producer builds for it. The book spells the pseudoketones of

    (the diacyl analogue) and of with the locant in front of the marks,

    and those names are read once, so they are not in this class.

orthonym.validation.opsin_ambiguity.reject_ambiguous(name, smiles, decided, stats=None)#

The last step of the validity gate for a name that OPSIN parsed.

decided is what the constitution check answered for name: the name itself, or the fallback that replaced it. A name it kept is withdrawn to the fallback when OPSIN reads it as ambiguous, and the gate outcome is recorded for the fallback.

orthonym.validation.opsin_ambiguity.withdrawn_name(name, smiles)#

True when name is OPSIN-ambiguous and is not the name kept for smiles as the last resort: the check of the exit of a naming call.

orthonym.validation.opsin_ambiguity.restore_withdrawn(name, smiles)#

The last resort of a molecule left without a name: the name that was withdrawn for it because OPSIN reads it as ambiguous, with the provenance it had when it was withdrawn and recorded as a name that is not the PIN.

name is what the call has at its end. It is returned unchanged unless it is a failure name and a name was withdrawn for this structure in this call, and that name is verified: its gate outcome says so, or its full round trip does. The record of a name that is not the PIN labels it below the PIN at the best-effort tier and makes the default tier decline it. Never raises.