orthonym.rules.pin_vocabulary

Note

Internal API. Names and behaviour may change between releases.

Name vocabulary that is never part of a Preferred IUPAC Name (PIN).

non_pin_vocabulary(name) returns the first token of name that a PIN never contains, or None. It is a CLOSED list of name forms the Blue Book names as the non-preferred alternative of a PIN form, each cited below. It never rewrites a name: callers use it to (a) keep a name that carries such a token off the PIN label, and (b) let a producer that runs at the PIN tier decline such a name.

Each pattern is checked against the Blue Book’s own PIN strings (tests/unit/test_pin_vocabulary.py): a pattern that matches a BB PIN is wrong.

orthonym.rules.pin_vocabulary.non_pin_vocabulary(name, *, label_forms=True)

The first token of name that no PIN contains, or None.

label_forms=False leaves out the forms added by the branch review fixes (the S/P oxoacid ester prefixes beside a junior suffix, indicated hydrogen on a six-membered azine parent) – used by the PIN tier’s promotion re-run to decide which of its names ship at all, a decision these label-only forms must not change: every re-run name is labelled below the PIN anyway (metrics.provenance.record_pin_promotion_rerun), so they would only remove a name the default tier shipped before.

orthonym.rules.pin_vocabulary.identical_parent_units(mol, sys_a, sys_b)

False only when two ring systems of the same skeleton are shown NOT to be identical parent units of a multiplicative name; True otherwise (identical, or undecidable here: the caller keeps treating them as a multiplicative candidate).

“Preferred IUPAC multiplicative names” (the Blue Book): a

multiplicative PIN needs “(2) the multiplicative groups, other than the central multiplicative group, are symmetrically substituted; and (3) the locants of all substituent groups on the identical parent structures, including suffix groups, are identical” (:23183-23184); “all substituent groups, including the principal characteristic groups must be identical and have the same locant” (:23186). When they are not, “preferred IUPAC names are generated by substitutive nomenclature” ,:6231): ‘4-chloro-2-[(3-cyanophenyl)methyl]benzonitrile (PIN)’ (:6235), ‘1-bromo-3-[(3-chlorophenyl)methyl]benzene (PIN)’ (:6279); units that differ only in configuration are not identical either (:22587).

A unit is its ring system with every atom still connected to it once the atoms of the shortest path to the other system (the linker) are removed; the linker atom next to the unit is written as a dummy atom, so the attachment position is part of the comparison. Units whose canonical isomeric SMILES differ are not identical. Undecidable (True): the systems are bonded directly (a ring assembly), the two units share an atom (a second path joins them), or any error.

orthonym.rules.pin_vocabulary.multiplicative_candidate(mol)

True when the molecule may take a multiplicative PIN, so a substitutive name built by the PIN tier’s re-run is not known to be its PIN.

The molecule-level form of the strict producers’ ring-branch guard (suite fix j6, assembly.substituent_naming._ring_branch_may_need_other_parent): two or more ring systems with the same skeleton, and either - the principal characteristic group sits on (or directly on) two of them

(‘2,2’-methylenedibenzonitrile’, the Blue Book; ‘2,2’-[ethane-1,2- diylbis(oxymethylene)]di(cyclohexane-1-carboxylic acid)’), or

• there is no principal characteristic group and that skeleton is the senior ring system of the molecule: N-heterocycle, heterocycle, more rings, more ring atoms) – ‘1,1’-(1-chloroethane-1,2-diyl)dibenzene’, not ‘(1-chloro-2-phenylethyl)benzene’.

A skeleton that is only a substituent of a senior parent (‘2,5-bis[(4-methoxy phenyl)methyl]-4-methylpyrimidine’) or a principal group on the linking chain (‘bis(4-chlorophenyl)methanol’) does not count, nor do exactly two ring systems that identical_parent_units shows are not identically substituted units

conditions (2) and (3)). Fails closed (True) on error.

orthonym.rules.pin_vocabulary.multiplicative_pin_expected(mol)

True when the molecule’s PIN is a multiplicative name, so no other name built for it is its PIN.

“Preferred IUPAC multiplicative names” (the Blue Book):

“Multiplicative nomenclature is preferred to substitutive nomenclature for generating preferred IUPAC names to express multiple occurrences of identical parent structures, other than alkanes when (1) the linking bonds… are identical and (2) the multiplicative groups… are symmetrically substituted; and (3) the locants of all substituent groups on the identical parent structures, including suffix groups, are identical” (:23180-23184); ‘1,1’-oxybis(4-bromo benzene) (PIN)’,:6186); esters of such parents follow it ,:31790, ‘dimethyl butanedioylbis(oxy-2,1-phenylene) dibutanedioate (PIN)’,:31806).

Narrower than multiplicative_candidate (which also answers True when it cannot decide): the molecule has a principal characteristic group (or, which the perception does not report, an N-substituted carbamic acid ester); two ring systems of one skeleton each own an instance of it (the group lies in the unit’s ring system or is bonded to it and to no other ring system); their decorated units are identical (_unit_identity); the linker between them is symmetrical; and the two units hold more instances of the group than the rest of the molecule. A ring assembly, a principal group on the linker, no principal group, or anything undecidable gives False.

class orthonym.rules.pin_vocabulary.PromotionProbe

Bases: object

What the first run did at the sites the promotion re-run changes.

active

sites

overflow

orthonym.rules.pin_vocabulary.promotion_site_probe()

Record what the enclosed (first) naming run did at the sites whose behaviour the PIN tier’s promotion re-run changes; yields a PromotionProbe.

orthonym.rules.pin_vocabulary.promotion_could_change(probe)

False only when the PIN tier’s promotion re-run is known to repeat the first run: no active site ran, the promotion calls fit the preview limit, and the promoted producer of every call returns no kept name. Then every promotion call of the re-run returns None, as in the first run, so the re-run takes the same path to the same (failed) result. Measured on the 452 dev2000 PIN-tier abstentions whose first run reached a promotion call: 275 of them.

orthonym.rules.pin_vocabulary.at_pin_tier()

True when no breadth context is set: the default (PIN) tier, where a best-effort-gated producer runs only through promote_at_pin_tier. These are the four breadth contexts the substituent memo keys on, so a producer that reads this cannot return different names under one memo key.

orthonym.rules.pin_vocabulary.in_pin_promotion()

True inside the PIN tier’s promotion re-run (assembly.memo. pin_promotion_var set by Orthonym.name) with no breadth context set.

The systematic generators (terminal_ring_name, terminal_fragment_name, the acyclic chain composer) decline here: they build a deterministic, complete name, not the PIN (“The backbone choice is deterministic, NOT the

seniority cascade”, rules/terminal_fragment), so their numbering can

differ from the one the Blue Book prescribes – ‘2,5-dioxo-1-[…]-7-oxa- bicyclo[4.1.0]hept-3-en-4-yl’, where (c) before (e) (the Blue Book: 3256, “principal characteristic groups and free valences (suffixes)”, ahead of the ‘ene’ endings) gives the free valence the lower locant (’…-6-[…]-7-oxa- bicyclo[4.1.0]hept-3-en-3-yl’). Only the composition producers are promoted.

orthonym.rules.pin_vocabulary.pin_promotion_active()

True inside the PIN tier’s promotion re-run with no breadth context set (the reading behind in_pin_promotion). A site that reads it with no breadth context set is a site the re-run changes, so the first run’s probe (promotion_site_probe) notes it.

orthonym.rules.pin_vocabulary.promote_at_pin_tier(produce)

Run a best-effort-gated substituent producer at the PIN tier, keeping only a name whose vocabulary is all PIN vocabulary.

produce is a zero-argument call of the producer with its breadth switch (allow_mancude) on. The name it returns is kept only when it is a single token, carries no non_pin_vocabulary token, did not set the whole-call general_ring_prefix flag (a prefix only the general tier builds), and contains no fragment a producer recorded as non-PIN during the call. Otherwise the provenance recorded during the call is rolled back and None is returned, so the caller’s PIN-tier behaviour is exactly as before – apart from the name-scoped non-PIN records, which restore_provenance keeps: the call’s cache entries survive the rejection, and a later hit on one of them must still meet the record its computation made (else the same string passes this guard with the memo on and fails it with the memo off). The round trip

still judges the whole name afterwards.

Active only in the PIN tier’s re-run of a molecule its first run could not name (assembly.memo.pin_promotion_var, set by Orthonym.name): a molecule the PIN tier names today keeps its name byte for byte, and a route that becomes reachable only through a promoted prefix can never pre-empt the route that named it.