orthonym.assembly.metal_offer

Note

Internal API. Names and behaviour may change between releases.

The other drawing of a metal drawing, offered beside the drawing as written.

Standard InChI ignores metal-ligand bonds, so Cl[Zn]Cl and [Cl-].[Cl-].[Zn+2] are one compound with one standard InChIKey, and the producers name the second where they cannot name the first.:func:metal_disconnected_spelling_and_order writes the ionic drawing of an input when the scope table (data/metal_scope.py, mechanism DISCONNECT) admits the metal, and metal_connected_spelling_and_order() writes the bonded drawing of an organometallic cation drawn beside its anion ([Cl-].[Zn+]c1ccccc1 gives Cl[Zn]c1ccccc1; mechanism CONNECT_ANION), the one the producers of organometallic names read. make_metal_offer_scope() builds the decorator of Orthonym.name that names the drawing as written and the other drawing (metal_rewrite_spelling_and_order()), each as an outermost name call of its own, and keeps the better result (name_with_metal_offer()). The name of the other drawing is recorded as a non-PIN label (record_metal_rewrite_non_pin()).

RDKit gives a drawing with dative bonds no standard InChIKey, so no name can be read back against it.:func:metal_dative_split_spelling_and_order writes the same drawing without those bonds (mechanism DATIVE); the key of that drawing is the reference key, an independent count of atoms and charges ties it to the drawing given, and:func:metal_offer_for offers it, followed by its own ionic drawing when DISCONNECT applies to it.

Kept out of namer.py so that file stays within its size budget; the namer imports these names back.

orthonym.assembly.metal_offer.METAL_REWRITE_RUN = <ContextVar name='orthonym_metal_rewrite_run' default=False>

Set while:func:name_with_metal_offer names the other drawing of a metal drawing; read by record_metal_rewrite_non_pin().

orthonym.assembly.metal_offer.METAL_OFFER_OWNED = <ContextVar name='orthonym_metal_offer_owned' default=False>

Set for the whole of:func:name_with_metal_offer, so that the calls it makes name the strings they are given and offer nothing of their own.

orthonym.assembly.metal_offer.METAL_DATIVE_SPLIT_RUN = <ContextVar name='orthonym_metal_dative_split_run' default=False>

Set, with:data:METAL_REWRITE_RUN, while:func:name_with_metal_offer names a drawing that derives from the dative split of the caller’s drawing; read by record_metal_rewrite_non_pin().

orthonym.assembly.metal_offer.METAL_REWRITE_RULE = 'P-68.1.6.1'

The Blue Book rule a name reached through another drawing of a metal drawing breaks: ‘Structures for Lewis ‘adducts’’ (the Blue Book), sentence:37540 ‘One of the fundamental principles of organic chemical nomenclature is to name the structure that is drawn’.

orthonym.assembly.metal_offer.record_metal_rewrite_non_pin(name)

The name of the other drawing of a metal drawing is recorded as a non-PIN label, so it is labelled below the PIN (systematic_verified) and the default tier declines it with the rule; the wider tiers keep it (the same molecule, named through a drawing that has the same standard InChIKey). The drawing as written is the one the name must describe , so the name of another drawing is never certified as its PIN, whatever label the other drawing’s own name earns (zinc dichloride for [Cl-].[Cl-].[Zn+2]).

A name of a drawing that derives from the dative split of the caller’s drawing is also recorded as read back to that drawing, not to the drawing as written (metrics.provenance.record_verified_through_split): its row says opsin_split.

orthonym.assembly.metal_offer.metal_disconnected_spelling_and_order(smiles)

(the string to name, the atom order) of the ionic drawing of smiles when a metal is joined to non-carbon atoms by single bonds and the scope table admits the metal to DISCONNECT (data/metal_scope.py), else None.

The ionic drawing is the one a charge-conserving heterolytic disconnection gives: every single bond from the metal to an atom that is neither carbon nor a metal is broken, the metal gains +1 and the other atom -1 for each, and the atoms keep their hydrogens (Cl[Zn]Cl gives [Cl-].[Cl-].[Zn+2]). Standard InChI ignores metal-ligand bonds, so the two drawings of a compound have one standard InChIKey, and a drawing that the producers cannot name can be named through the one they can. The key does not bound the metal’s charge, and it is blind to the position of a charge on an ambident anion, so the rewrite is accepted only when, beside the equal key,

• the metal’s charge after the disconnection is one of its valences in the table (perception.metals.single_bond_metal_heteroatom_sites(): Cl[Zn](Cl)N would give [Zn+3] with the same key and is left as it is);

• an independent count of atoms and charges holds (perception.metals.atom_and_charge_ledger_ok(): element, isotope, hydrogens, radicals, the charge change declared by the broken bonds, the bond set and the net charge), on the molecule and again on the written string read back;

• the string reads back as the molecule (equal canonical isomeric SMILES).

A drawing with a metal-carbon bond, a multiple or dative bond from the metal, a bond direction or a chiral tag at a broken bond, a CXSMILES extension or a lone-pair stereocentre is not rewritten, and an ionic drawing has no bond to break, so a second application finds nothing. order[k] is the atom of RDKit’s reading of smiles that atom k of the string stands for. Structures for Lewis ‘adducts’, “One of the fundamental principles of organic chemical nomenclature is to name the structure that is drawn”: the caller offers the drawing as written as well (name_with_metal_offer()).

orthonym.assembly.metal_offer.metal_connected_spelling_and_order(smiles)

(the string to name, the atom order) of the bonded drawing of smiles when it holds an organometallic cation drawn beside the free anion that neutralises it and the scope table admits the metal to CONNECT_ANION (data/metal_scope.py), else None.

The bonded drawing joins the donor atom of the anion to the metal by a single bond; the metal and the donor each lose one charge ([Cl-].[Zn+]c1ccccc1 gives Cl[Zn]c1ccccc1) and the atoms keep their hydrogens. It is the reverse of:func:metal_disconnected_spelling_and_order for the bond to the anion, and the bond to carbon stays: the standard InChIKey of the two drawings is equal (VERIFIED for an alkyl, an aryl and a benzyl cation), which is what lets the producers of organometallic names, which read a bonded drawing, name the drawing as written. The rewrite is accepted only under the conditions of perception.metals.connect_anion_to_organometal_cation_sites() (one cation, as many free anions as it has charges, no choice of pairing, an allowed metal valence), the equal key, the count of atoms and charges of:func:perception.metals.atom_and_charge_ledger_ok read the other way (the bonded drawing with its new bonds broken is the molecule), on the molecule and again on the written string read back, and the equal canonical isomeric SMILES of that read-back.

A bonded drawing has no free anion to connect, so a second application finds nothing. A drawing of a carbanion beside a halometal cation ([CH2-]C.[Zn+]Br) is not a drawing of this kind: the carbon of the carbanion is no donor, and the bonded drawing that joins it has another key. Structures for Lewis ‘adducts’, “One of the fundamental principles of organic chemical nomenclature is to name the structure that is drawn”: the caller offers the drawing as written as well (name_with_metal_offer()).

orthonym.assembly.metal_offer.metal_rewrite_spelling_and_order(smiles)

The other drawing the offer makes beside the drawing as written: the ionic drawing (metal_disconnected_spelling_and_order()) or, when that is none, the bonded drawing of an organometallic cation with its anion (metal_connected_spelling_and_order()). The two never both apply: the first refuses a drawing with a bond from a metal to carbon, the second needs one.

orthonym.assembly.metal_offer.metal_dative_split_spelling_and_order(smiles)

(the string to name, the atom order) of the drawing of smiles without its dative bonds when every dative bond of it ends at a metal that the scope table admits to DATIVE (data/metal_scope.py), else None.

The split drawing keeps everything but the bonds: the donor its lone pair and its hydrogens, the metal its charge (CC(=O)[O-]->[Zn+2]<-[O-]C(C)=O gives CC(=O)[O-].[Zn+2].[O-]C(C)=O). RDKit gives a drawing with dative bonds no standard InChIKey, so the key of the split drawing is the reference key of the read-back of a name, and the rewrite is accepted only when it has one and when, beside it,

• the sites are those of:func:perception.metals.dative_bond_split_sites (a metal admitted to DATIVE, no stereo information at the bonds);

• an independent count of atoms and charges holds (perception.metals.atom_and_charge_ledger_ok() with no charge moved: element, isotope, hydrogens, radicals, the charge of each atom, the bond set without the dative bonds and the net charge), on the molecule and again on the written string read back;

• the string reads back as the molecule (equal canonical isomeric SMILES).

The proof is of the atoms, the charges and the organic part; the dative bonds themselves are not compared, which is the strength of the proof for a drawing with covalent metal-ligand bonds as well (standard InChI ignores those bonds too). A drawing that holds a dative bond that no metal accepts is not split, and a split drawing has no dative bond, so a second application finds nothing. order[k] is the atom of RDKit’s reading of smiles that atom k of the string stands for. Structures for Lewis ‘adducts’ draws the ‘dative’ bond as structure (I) and says “One of the fundamental principles of organic chemical nomenclature is to name the structure that is drawn”: a name reached through the split drawing is not the name of that structure (record_metal_rewrite_non_pin()).

class orthonym.assembly.metal_offer.MetalOffer(drawings, keyless=False)

Bases: NamedTuple

The drawings the offer names beside the drawing as written: drawings are (string, atom order) pairs, the nearest to the caller’s drawing first, the order being relative to RDKit’s reading of the caller’s string; keyless is True for a drawing that has no standard InChIKey (dative bonds).

drawings: Tuple[Tuple[str, Tuple[int, ...]], ...]

Alias for field number 0

keyless: bool

Alias for field number 1

orthonym.assembly.metal_offer.metal_offer_for(smiles)

The drawings:func:name_with_metal_offer names beside the drawing smiles as written, or None when there is none.

A dative drawing is offered as its split drawing (metal_dative_split_spelling_and_order()) and, when that drawing has an ionic drawing of its own (metal_rewrite_spelling_and_order(): the split drawing is treated as any drawing), that one as well; the order of the second is composed to the caller’s atoms. Any other drawing is offered its other drawing, as before.

orthonym.assembly.metal_offer.form_result_rank(namer, string, result)

The rank of the result of an outermost name run of string by namer, read right after the run (its provenance and its default-tier row are this run’s): (the label rank, 0) for a name (namer._LABEL_RANK; a name whose row cannot be derived ranks 1), (0, 1) for a decline of the default tier that says a name exists below the PIN, (0, 0) for any other failure label: of two runs that name nothing at the default tier, the one whose decline is NO_VERIFIED_PIN (a wider tier keeps its name) stands over one that names nothing.

orthonym.assembly.metal_offer.name_with_metal_offer(namer, fn, offer, args, kwargs)

The drawing of the caller’s input as written and the other drawings of offer (MetalOffer: the ionic drawing of:func:metal_disconnected_spelling_and_order, the bonded drawing of an organometallic cation of:func:metal_connected_spelling_and_order, or the split drawing of a dative drawing and its ionic drawing), each named as an outermost name call of its own by fn(namer,...); the call returns the best result, with the provenance and records of the run that gave it (the run that gave it is run again last when it was not the last run).

Better is the higher rank (form_result_rank(): the label, and for two failures the decline that says a name exists below the PIN, which a wider tier returns); on equal ranks a drawing that gives a name stands over one that gives none, and of two that give a name the one nearer the ionic drawing, so two drawings of one compound with one standard InChIKey get one name; when none gives a name, the drawing as written, as before. The result is never lower than the one the drawing as written gave, so no name that exists without the rewrite is lost or lowered. The name of another drawing is recorded as a non-PIN label (record_metal_rewrite_non_pin()) during its run. Each run goes through every gate, the round trip included, against the string it names; the standard InChIKey of that string is the input’s, or, for a dative drawing, the reference key of its split drawing.

A dative drawing has no standard InChIKey, so no name can be read back against it and the gates decline a name of the drawing as written (the key of the input is None). It is run last, and only when no other drawing names or declines with NO_VERIFIED_PIN: the result of that run is the one the engine gave without the offer.

Offer, not return (the contributor guide a project rule): a rewrite that fails, or lands below the drawing as written, ships nothing.

orthonym.assembly.metal_offer.make_metal_offer_scope(owned_elsewhere)

The decorator of Orthonym.name that offers the other drawing of a metal drawing beside the drawing as written (name_with_metal_offer()) and keeps the better name.

owned_elsewhere are the context variables of the other scopes that name strings of their own (the charge-form run and the strict PIN twin of namer): while one is set, a call names the string it is given. The decorator is outside _form_choice_scope (each drawing gets its own charge-form choice), for the caller’s own name call only: a nested call, a call inside a form’s run or inside the offer itself call fn directly. An input without a metal drawing to rewrite is named as it always was.