orthonym.assembly.form_choice

Note

Internal API. Names and behaviour may change between releases.

Which name of one species’ charge forms stands.

A cation whose +1 can sit on several nitrogen atoms is one species (namer._charge_forms), and Orthonym._name_with_form_choice names each of its forms and keeps one name. This module is the rule that ranks two of those names. It is pure string logic (no RDKit, no handlers), and it compares only the names of one species, so what it reads from a name is what the Blue Book orders by.

The order, each step a whole criterion before the next, the first that differs deciding:

0. More of the input’s configured stereo elements kept (the *_stereo counts of:func:beats, from perception.charge_shift.kept_stereo, counted on each form’s own mol against the drawn input): a form is written from a Kekule structure whose double bonds are not the drawing’s, and a bond that is single in it cannot carry the E/Z the input configures, so the name of such a form is the name of a less specific compound than the input. STERODESCRIPTORS (the Blue Book), “The configuration of an organic compound is systematically indicated by one or more affixes added to a name that does not itself prescribe configuration; such affixes are called ‘stereodescriptors’” (:44570); Omission of stereodescriptors (:44635) allows omitting them for double bonds only in three- to seven-membered alicyclic rings and in the ring systems it lists, “From nine-membered rings onwards, stereodescriptors are required” (:44637), never for an acyclic polymethine. NAMING OF STEREOISOMERS (:44639) says the descriptors “do not change the name or the numbering of a compound established by the principles, rules and conventions”, so the Blue Book gives no rank between this and the choices below: ASSUMED order, the one that never lets the choice drop a configuration the input carries (the contributor guide core principle 2). The standard InChIKey that admits a form does not see these bonds, so no other gate does either. Where the counts are equal or not given, this is a tie.

1. Fewer constructs the engine records as not PIN (non_pin_parts(), the fragments): a construction the Blue Book does not allow in a PIN, or allows only where no fusion or Hantzsch-Widman name exists

   “Five-membered ring requirement” (:23708), “When fusion names are not allowed, unsaturated von

   Baeyer ring system names are preferred IUPAC names” (:23710); (:23682), “Preferred IUPAC names for heteromonocyclic rings with no more than ten ring members are Hantzsch-Widman names”; ‘azamethane’ is no Blue Book name (0 occurrences in the Blue Book), the one-atom nitrogen parent being azane, “General rule for systematically naming cationic centers in parent hydrides”,:41366). A name that is built from a construction of that kind is no candidate for the preferred name, whatever its parent, so this comes first; for the names of one species that use the same constructions it is a tie.

2. ** CHOICE OF A PARENT STRUCTURE** (the Blue Book): “A parent cationic structure is chosen by applying the following criteria in order until a definitive choice is achieved: (a) parent with the maximum number of cationic, including cationic suffixes” (:42334; its example, 2-(piperidin-1-ium-3-yl)propane-1,2-bis(aminium) over 3-(1,2-diaminiumylpropan-2-yl)piperidin-1-ium, “bis(aminium) is senior to piperidinium”). A name whose parent holds the cation stands over one that moves the cation into a substituent prefix and leaves the parent neutral (cationic_parent_centres()).

3. ** NUMBERING** (:3219), for two names that are one skeleton with other locants (lower_locants()): (b) indicated hydrogen, (c) “principal characteristic groups and free valences (suffixes)” (the ionic suffix ‘ium’ and the free valence ‘yl’, of the parent, then of a prefix), (e)(i) “low locants are given to hydro/dehydro prefixes… and ‘ene’ and ‘yne’ endings”, with, for the ene list of a von Baeyer name, **** (:16633, “If there is a choice of names and numbering, the following criteria are considered in order until a decision is reached”): “(1) a minimum number of compound locants” (:16635), “(2) when comparing double bond locants that also include compound locants, any number in parentheses is ignored” (:16655), “(3) if there is still a choice, low locants are selected considering all locants (including those in parentheses) as a set” (:16667); then (f) “detachable alphabetized prefixes, all considered together in a series of increasing numerical order” (:3301), (g) “lowest locants for the substituent cited first as a prefix in the name” (:3307), then (j) “the lower locant is assigned to CIP stereodescriptors Z, R, M, and r” (:3346) for the leading configuration block. Between two Kekule structures of one ring system says the same thing (“A benzene ring is shown and described as a cyclohexatriene corresponding to the Kekule structure. Other aromatic rings are treated similarly, when required”,:16635). ASSUMED (the Blue Book orders the criteria for numbering one structure, not for choosing between two drawings of a delocalised cation): that the same order ranks the names of two drawings.

4. Fewer parts the engine records as label-only non-PIN (the second number of:func:non_pin_parts): a part that is never the PIN spelling but that the PIN tier’s promotion re-run still ships.

The caller keeps the form that comes first by canonical SMILES where none of these decides, so one species gets one name whichever drawing it came from (the contributor guide core principle 4).

A form that no producer names is not ranked, and it does not lower the label of the name the species gets (decision LO9, internal notes): an unnamed form has the rank (0, 0), below every label. pin_verified says that the shipped name is the PIN of the structure, which the Blue Book’s criteria decide; whether every drawing of the structure could be named is not one of them. INTRODUCTION (the Blue Book),:42411: “in zwitterionic compounds anionic centers are preferred for lower locants and become the parent structure, into which the cationic part is substituted”; CHOICE OF A PARENT STRUCTURE (:42330), (a) “parent with the maximum number of cationic, including cationic suffixes” (:42334). So the form whose cation sits in the parent (a ring ‘ium’, ‘2-amino-4,5-dihydro-1,3-thiazol-3-ium-4-carboxylate’) stands over the form whose cation can only be a prefix (‘2-azaniumylidene-1,3-thiazolidine-4-carboxylate’, CATIONIC PREFIX NAMES,:42290) whether or not that prefix name could be built, and the label stays. An unnamed form of the same ring cation with other locants is another matter: it can outrank the survivor on (b), (c), (f), which nobody computed. That is closed by naming the form (rules/azolium_cations.azolium_hydron_site_name for an azolium that carries a principal group; the rule of this module then ranks it), never by withdrawing the label of a name for which the Blue Book gives no proof that it is not the PIN.

orthonym.assembly.form_choice.cationic_parent_centres(name)

The number of cationic centres the parent of each component of name expresses by a suffix: the endings of:data:_CATIONIC_ENDING outside every enclosing mark, a multiplied ending (‘-6,34-diium’, ‘bis(aminium)’) counted by its multiplier. (a), the Blue Book. The components of a salt or a solvate (’… chloride’, ‘…-ium dibromide’, ‘…-ium pentanedioate pentahydrate’) are the words that stand outside every enclosing mark, so a cation of one species that one name multiplies (‘bis[…-ium]’) and the other writes twice is a different number of components, which:func:beats does not compare. Names compared here are the names of one species, so what differs is where the cation sits, in the parent or in a prefix.

orthonym.assembly.form_choice.locant_roles(name)

(the name with its locants taken out, then the roles ‘NUMBERING’ (the Blue Book) ranks in turn: (b) indicated hydrogen, (c) the principal characteristic group or ionic suffix (those of the parent, outside every enclosing mark, then those of the prefixes), (e) the hydro prefixes, then the ene and yne locants by (compound locants, the set without and with the numbers in parentheses) or, where a triple bond is present, by (_ene_roles()), (f) the detachable alphabetized prefixes ‘all considered together in a series of increasing numerical order’ (:3301, the sorted set of their locants), then (g) ‘lowest locants for the substituent cited first as a prefix in the name’ (:3307, their locants in the order the name cites them), then (j) ‘the lower locant is assigned to CIP stereodescriptors Z, R, M, and r… that are preferred to E, S, P, and s’ (:3346, cip_locant_rank_key of the leading configuration block)).

The leading configuration block is out of the skeleton, which keeps only its symbols as a set: (j) chooses between numberings of one set of descriptors, so names whose blocks hold other symbols (one atom R in one charge form and S in the other) are not one skeleton and are not compared.

orthonym.assembly.form_choice.lower_locants(a, b)

-1 if the name a has the lower locants by (b), (c), (e), (f), (g), then (j) than b, 1 if b does, 0 if they tie or the two names are not the same skeleton with other locants (the comparison is then left to the next criterion of:func:beats).

The roles are compared in the order of the rule, each as a whole before the next: the set of all the prefix locants (f) is compared before the locants of the first-cited prefix (g) (‘6-bromo-4-chloro-1H-1,3-benzimidazol-3-ium’, the set 4,6, over ‘5-bromo-7-chloro-’, 5,7, although the first cited, bromo, has the higher locant in the first), and the stereodescriptors (j) last: ‘(4S)-4-methyl-’ over ‘(6S)-6-methyl-3,4,5,6-tetrahydro- pyrimidin-1-ium’ by (f), ‘(4R,6S)-’ over ‘(4S,6R)-2,4,6-trimethyl-’ by (j).

orthonym.assembly.form_choice.non_pin_parts(name, provenance)

(the constructs, the label-only parts) the run recorded as not PIN (metrics.provenance) that name contains, each counted as often as the name writes it. The constructs are the name fragments of record_non_pin_fragment; a fragment that holds another carried one is the enclosing substituent that the engine records again for every level of nesting (‘keeps the status of its source’), so only the innermost are counted. The label-only parts are the parts of record_non_pin_label and the names of record_uncertified_pin_name. A record is name-scoped (a fragment of a candidate that was discarded is not in the shipped name), so this counts what the name carries. Two names that write the same number of non-PIN rings are a tie, whichever rings they are: a ring written twice counts twice.

orthonym.assembly.form_choice.beats(challenger, incumbent, challenger_provenance=None, incumbent_provenance=None, challenger_stereo=None, incumbent_stereo=None)

True when challenger is the better name of one species than incumbent, by the order of the module docstring; False for a tie (the form that comes first by canonical SMILES then stands). challenger_stereo and incumbent_stereo are the configured stereo elements of the input that the form of each name keeps (orthonym.perception.charge_shift.kept_stereo()); the most decides first, and the criterion is skipped when either is None.

orthonym.assembly.form_choice.stereo_decides_below_pin(label, incumbent_label, kept, incumbent_kept, pin_rank)

+1 when a name below the PIN that keeps more of the input’s configured stereo elements (criterion 0 of the module docstring) stands over an incumbent below the PIN that keeps fewer, -1 for the reverse, else 0 and the labels decide. Both labels are those of a verified name below the PIN (a label rank of 2 up to pin_rank - 1, not the last-resort floor’s): a name of another drawing that has lost the configuration of the input is the name of a less specific compound than the input,:44568), and such a label does not say that it is the better name of the species, so it does not outrank the drawing’s own name that keeps the configuration.