chython 3.0.2__tar.gz → 3.1__tar.gz

{chython-3.0.2/chython.egg-info → chython-3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chython
-Version: 3.0.2
+Version: 3.1
 Summary: Library for processing molecules and reactions in python way
 Author-email: Ramil Nugmanov <nougmanoff@protonmail.com>
 License-Expression: LGPL-3.0-or-later

{chython-3.0.2 → chython-3.1}/chython/chemistry/_canonicalize.py

@@ -62,9 +62,13 @@ def canonicalize(molecule: MoleculeContainer, *, fix_tautomers: bool = True,
     needing the aromatic form.
 
     CHARGES ARE PAIRED OFF, not preserved atom by atom: glycine's zwitterion and its neutral drawing
-    share a key, because step 4 runs `neutralize()`.  The NET charge is untouched, so sodium acetate
-    stays sodium acetate -- there is no proton in it to move -- while ammonium acetate becomes acetic
-    acid and ammonia, both drawings of one salt.
+    share a key, because step 4 runs `neutralize()`.  `neutralize()` leaves the NET charge untouched, so
+    sodium acetate stays sodium acetate -- there is no proton in it to move -- while ammonium acetate
+    becomes acetic acid and ammonia, both drawings of one salt.
+
+    One stage does move the net charge, `standardize()`'s organometallic completion: a zinc or magnesium
+    holding one carbon and no halide is charged rather than left as a neutral one-coordinate metal.  It
+    is the only place in the pipeline where the total changes, and it says so in the log.
     """
     # A refusal at the answer boundary, which is the only place one belongs.  `smiles()` returns
     # whichever container its string describes, so a `>>` in a structure column arrives here as a

chython-3.1/chython/chemistry/_organometallics.py

@@ -0,0 +1,133 @@
+# -*- coding: utf-8 -*-
+#
+#  Copyright 2026 Ramil Nugmanov <nougmanoff@protonmail.com>
+#  This file is part of chython.
+#
+#  chython is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+"""An organozinc or Grignard drawn apart from its halide: `CC[Zn+].[Cl-]` is one `CC[Zn]Cl`.
+
+A ONE-COORDINATE ZINC OR MAGNESIUM HOLDING A CARBON IS AN INCOMPLETE DRAWING, and this stage completes
+it two ways.  A free halide in the record is the halide that belongs on the metal, so it is bonded there.
+A metal left without one is charged `+`: the halide is missing from the drawing rather than from the
+compound, and a neutral one-coordinate metal is not a species anybody meant.  Both readings apply to
+zinc and magnesium alike.
+
+A `standardize()` stage rather than a `standardize_metals.tsv` row, and for one reason: a rule table
+applies whichever match the isomorphism search returned first, so a drawing offering more than one
+candidate would be settled by its atom order.  Pairing is a question about all the candidates at once.
+
+Two orderings answer it, and neither can see the input's spelling:
+
+* **halides** by `Cl > Br > I > F`, a fact about the reagents rather than about the graph;
+* **metals** by canonical rank, which is `_isomers._ranks` without the stripping step -- the bond being
+  placed is the one that is absent, so the molecule as it arrived already is the placement-free frame.
+
+Ties are left tied.  Two candidates of equal rank are automorphic, so which one is taken is not
+observable in the result, and the sort being stable makes the arbitrary half of the choice cheap.
+Charging needs no order at all, being one atom's charge and nothing else's.
+
+NET CHARGE MOVES HERE, which no other `standardize()` stage does, and every spelling that moves it is
+accepted: a lone `[Zn+]` beside a neutral halogen sits at `+1`, a neutral metal beside `[Cl-]` at `-1`,
+and a charged metal with no halide leaves `0` for `+1`.  A dropped sign is the premise of the stage, so
+the record states which way the total went rather than the pass declining to move it.
+"""
+from collections.abc import MutableSequence
+from ..core import LogRecord, MoleculeContainer
+
+
+__all__ = ['unite_organometallics']
+
+#: Table-qualified, as every rule id must be -- never a bare index.  Two and not one: bonding a halide
+#: the record HAS and charging a metal whose halide the record LACKS are different claims about the
+#: drawing, and a consumer filtering the log can decline the second while keeping the first.
+_RULE = 'organometallics:unite'
+_RULE_CHARGE = 'organometallics:charge'
+
+#: `Cl > Br > I > F`, low wins.  Chloride and bromide are the reagent halides; fluoride is last because
+#: a free `[F-]` beside a magnesium is more often a separate salt than a bond somebody forgot to draw.
+_PREFERENCE = {17: 0, 35: 1, 53: 2, 9: 3}
+
+#: Zinc and magnesium only.  Widening this is a chemical claim per element, not a constant to grow.
+_METALS = frozenset({12, 30})
+
+
+def _candidates(molecule: MoleculeContainer) -> tuple[list[int], list[int]]:
+    """The one-bonded metals holding a carbon, and the free halides, in arena order.
+
+    A metal is a candidate at charge `0` or `+1` and at exactly one single bond to carbon: two bonds
+    means it is already satisfied, and an alkoxide or amide is a different compound rather than a
+    reagent drawn apart.  A halide is a candidate at charge `0` or `-1` with no bonds at all -- bonded,
+    it belongs to whatever it is bonded to.  Radicals are nobody's dropped sign.
+    """
+    metals: list[int] = []
+    halides: list[int] = []
+    for atom in molecule.atoms():
+        n = atom.n
+        if atom.is_radical:
+            continue
+        if atom.element in _METALS:
+            if atom.degree == 1 and atom.charge in (0, 1):
+                m = next(iter(molecule.neighbors_of(n)))
+                if molecule.atom(m).element == 6 and molecule.order_of(n, m) == 1:
+                    metals.append(n)
+        elif atom.element in _PREFERENCE and not atom.degree and atom.charge in (0, -1):
+            halides.append(n)
+    return metals, halides
+
+
+def unite_organometallics(molecule: MoleculeContainer, log: MutableSequence) -> set[int]:
+    """Bond each candidate metal to one candidate halide, and charge whichever went without.  Written ids.
+
+    Spare halides are left as drawn -- a second chloride beside a satisfied metal is a counterion -- so
+    only the metal side is completed either way.
+    """
+    metals, halides = _candidates(molecule)
+    if not metals:
+        return set()
+
+    pairs: list[tuple[int, int, int]] = []
+    if halides:
+        # before the edit scope, which answers reads from the pre-scope arena.  `atoms_order` is the
+        # expensive word here, so it is asked for only when there is a pairing to decide.
+        ranks = molecule.atoms_order
+        metals.sort(key=lambda n: ranks[n])
+        halides.sort(key=lambda n: (_PREFERENCE[molecule.atom(n).element], molecule.atom(n).isotope,
+                                    ranks[n]))
+        pairs = [(n, m, molecule.charge_of(n) + molecule.charge_of(m)) for n, m in zip(metals, halides)]
+
+    # a metal that took a halide is neutral by the join; one that did not is charged, unless the drawing
+    # already said `+`.  Ranking cannot matter to this half -- every leftover is treated alike.
+    bonded = {n for n, _, _ in pairs}
+    stranded = [n for n in metals if n not in bonded and not molecule.charge_of(n)]
+    if not pairs and not stranded:
+        return set()
+
+    with molecule.edit():
+        for n, m, _ in pairs:
+            molecule.add_bond(n, m, 1)
+            molecule.set_charge(n, 0)
+            molecule.set_charge(m, 0)
+        for n in stranded:
+            molecule.set_charge(n, 1)
+
+    for n, m, before in pairs:
+        moved = f', and the net charge of the pair moved {before:+d} -> 0' if before else ''
+        log.append(LogRecord(_RULE, (n, m), f'atoms {n} and {m} are one organometallic reagent drawn '
+                                            f'apart; joined by a single bond{moved}'))
+    for n in stranded:
+        log.append(LogRecord(_RULE_CHARGE, (n,), f'atom {n} holds one carbon and no halide; charged +1, '
+                                                 f'the halide being absent from the drawing rather than '
+                                                 f'from the compound, so the net charge moves 0 -> +1'))
+    return bonded | {m for _, m, _ in pairs} | set(stranded)

{chython-3.0.2 → chython-3.1}/chython/chemistry/_standardize.py

@@ -22,9 +22,15 @@ A repair pass the caller asks for -- no reader or writer runs it.  The patch lan
 charge delta and an optional absolute radical flag per matched atom, plus a new order in {1,2,3,8}
 per matched bond; no rule touches the atom or bond set, an isotope, an aromatic order or a hydrogen
 count.  A patch is validated in full before any of it is written.
+
+`standardize()` closes with one stage that is not a table row, `_organometallics`: completing a
+one-coordinate zinc or magnesium adds a bond, and which halide joins which metal is a question about
+every candidate at once, neither of which a rule table can state.  It is also the one stage that moves
+net charge, a metal nobody drew a halide for being charged instead.
 """
 from collections.abc import MutableSequence
 from ._implicit import calc_implicit
+from ._organometallics import unite_organometallics
 from ._tables import Rule, groups_rules, metals_rules
 from ..core import LogRecord, MoleculeContainer, recording
 
@@ -128,7 +134,9 @@ def standardize(molecule: MoleculeContainer, *, fix_hydrogens: bool = True,
                 fix_tautomers: bool = True) -> bool:
     """Repair mis-drawn functional groups and metal-organic bonding in place.  Did anything change?
 
-    Runs the functional-group rules and then the metal-organic ones, then recomputes the implicit
+    Runs the functional-group rules, then the metal-organic ones, then completes any organozinc or
+    Grignard that arrived one-coordinate -- bonding a free halide to it, or charging it when the drawing
+    offers none -- then recomputes the implicit
     hydrogen count of every atom a patch wrote -- charge, radical state and bond order all change what
     the valence collection gives an atom.  `fix_hydrogens=False` skips that recompute, for a caller about
     to kekulise anyway.  `molecule.log` takes a record per patch applied and per patch refused.
@@ -141,6 +149,9 @@ def standardize(molecule: MoleculeContainer, *, fix_hydrogens: bool = True,
     with recording(molecule, stage='standardize') as lg:
         written = _pass(molecule, groups_rules(), lg, fix_tautomers)
         written |= _pass(molecule, metals_rules(), lg, fix_tautomers)
+        # last, and the order is not observable: no `metals:` row matches a sigma metal-carbon bond, so
+        # none of them can see either the ion pair this reads or the covalent form it writes.
+        written |= unite_organometallics(molecule, lg)
     if not written:
         return False
     if fix_hydrogens:

{chython-3.0.2 → chython-3.1}/chython/chemistry/tables/salts.tsv

@@ -87,6 +87,7 @@ salts:benzoic	counterion	OC(=O)c1ccccc1	-	benzoic
 salts:salicylic	counterion	OC(=O)c1ccccc1O	-	salicylic
 salts:gentisic	counterion	OC(=O)c1cc(O)ccc1O	-	gentisic
 salts:xinafoic	counterion	OC(=O)c1c(O)ccc2ccccc12	-	1-hydroxy-2-naphthoic (xinafoic)
+salts:oxynaphthoic	counterion	OC(=O)c1cc2ccccc2cc1O	-	3-hydroxy-2-naphthoic (beta-oxynaphthoic, BON).  Same formula as `salts:xinafoic` and a different constitution, so the key mechanism keeps them apart and both are needed
 salts:pamoic	counterion	OC(=O)c1c(O)c(Cc2c(O)c(C(O)=O)c3ccccc3c2)cc4ccccc14	-	pamoic (embonic)
 salts:hippuric	counterion	OC(=O)CNC(=O)c1ccccc1	-	hippuric
 salts:nicotinic	counterion	OC(=O)c1cccnc1	-	nicotinic

{chython-3.0.2 → chython-3.1}/chython/chemistry/tables/standardize_metals.tsv

@@ -18,6 +18,13 @@
 #
 # The examples are one metal with one ligand each.  Nine of the 19 rules are also exercised by real drawings,
 # in `test/_corpus.py`.
+#
+# NO ROW HERE COMPLETES A ONE-COORDINATE ORGANOZINC OR GRIGNARD, and none can: `bonds_fix` changes the order
+# of a bond that exists, and which of several free halides joins which metal is a question about all the
+# candidates at once rather than about one match.  `_organometallics.py` is that stage, run by `standardize()`
+# after this table -- it bonds a free halide to the metal, or charges the metal when the drawing offers none.
+# Its direction is the opposite of these 19 rows and does not compete with them: they break a DATIVE contact
+# from a lone pair, it makes a polar covalent sigma metal-carbon bond.
 
 id	smarts	atom_fix	bonds_fix	tautomer	after	examples	why
 metals:00	[M;*;^,!^:1]=[C:2]-1-[N;D3;x0;z1:3]-[C;z2:5]-,=[C;z2:6]-[N;D3;x0;z1:4]-1	2:-1:-;3:1:-	1:2:8;2:3:2	0	-	C=1N(C)C(=[Cu]I)N(C)C=1>>[C-]=1(N(C)C=C[N+]=1C)~[Cu]I	An N-heterocyclic carbene drawn with a covalent M=C double bond; the carbene carbon becomes the [C-] that donates to the metal and the imidazolium charge is restored on a ring nitrogen

chython-3.1/chython/chemistry/test/test_organometallics.py

@@ -0,0 +1,219 @@
+# -*- coding: utf-8 -*-
+#
+#  Copyright 2026 Ramil Nugmanov <nougmanoff@protonmail.com>
+#  This file is part of chython.
+#
+#  chython is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+"""Completing a one-coordinate organozinc or Grignard: `[Zn+].[Cl-]` joins, and a halide-less one charges.
+
+The invariant under test is that THE RESULT DOES NOT DEPEND ON INPUT ATOM ORDER.  Two orderings settle
+it -- halides by `Cl > Br > I > F`, metals by canonical rank -- and every test that could see an order
+effect permutes its input and demands one answer.  Charging needs no order, so what is tested there is
+that net charge moves, that it moves once, and that it is a record of its own.
+"""
+# `__all__` and not the package object: `from ... import chemistry` would execute the facade, which
+# `test_dependency_direction.py` ratchets against.
+from itertools import permutations
+from .. import canonicalize, standardize
+from ...core import read_smiles as smiles
+
+
+def _std(s):
+    """`standardize()` then a canonical string, so two spellings of one answer compare equal."""
+    m = smiles(s)
+    standardize(m)
+    m.canonicalize()
+    return format(m, '')
+
+
+def _one(spellings):
+    """The single canonical answer every spelling gives, or an assertion naming the ones that differ."""
+    got = {s: _std(s) for s in spellings}
+    assert len(set(got.values())) == 1, got
+    return next(iter(got.values()))
+
+
+# what gets joined
+
+
+def test_every_charge_spelling_of_a_drawn_apart_reagent_reaches_the_covalent_form():
+    """All four spellings are the same reagent: ethylzinc chloride, and phenylmagnesium bromide.
+
+    Two of the four do not conserve net charge -- a lone `[Zn+]` beside a neutral halogen is at `+1`, a
+    neutral metal beside `[Cl-]` at `-1` -- and both are joined anyway, the premise being that the
+    drawing dropped a sign rather than that a cation and a radical were meant.
+    """
+    assert _one(['CC[Zn+].[Cl-]', 'CC[Zn+].[Cl]', 'CC[Zn].[Cl-]', 'CC[Zn].[Cl]']) == _std('CC[Zn]Cl')
+    assert _one(['c1ccccc1[Mg+].[Br-]', 'c1ccccc1[Mg].[Br-]']) == _std('c1ccccc1[Mg]Br')
+
+
+def test_all_four_halogens_are_joined():
+    for x in ('F', 'Cl', 'Br', 'I'):
+        assert _std(f'CC[Zn+].[{x}-]') == _std(f'CC[Zn]{x}'), x
+
+
+def test_the_joined_form_is_a_fixed_point_and_a_plain_molecule_is_untouched():
+    assert _std('CC[Zn]Cl') == _std(_std('CC[Zn]Cl'))
+    m = smiles('c1ccccc1O')
+    assert not standardize(m)
+
+
+# what is left alone
+
+
+def test_only_a_one_bonded_metal_holding_a_carbon_takes_a_halide():
+    for s in ('C[Zn](C)C.[Cl-]',        # already two-coordinate: no room
+              'CO[Zn].[Cl-]',           # bonded to oxygen, not to carbon: an alkoxide, not a reagent
+              'CC[Zn]Cl.[Cl-]',         # the metal is satisfied; the second chloride is a counterion
+              'CC[Zn+].C[Cl]',          # the halogen is bonded, so it is not a free halide
+              'CC[Cu+].[Cl-]'):         # not Zn or Mg
+        m = smiles(s)
+        before = format(m, '')
+        standardize(m)
+        assert format(m, '') == before, s
+
+
+def test_a_metal_with_no_halide_anywhere_is_charged_instead():
+    """A neutral one-coordinate metal is not a species: the halide is missing from the DRAWING.
+
+    Zinc and magnesium alike, and it is the one thing `standardize()` does that moves net charge.
+    """
+    for s, expect in [('CC[Zn]', 'CC[Zn+]'), ('CC[Mg]', 'CC[Mg+]'),
+                      ('c1ccccc1[Mg]', 'c1ccccc1[Mg+]')]:
+        m = smiles(s)
+        assert standardize(m), s
+        assert _std(s) == _std(expect), s
+        assert sum(m.charge_of(n) for n in m) == 1, s
+        assert not m.check_valence(), s
+
+
+def test_a_metal_the_drawing_already_charged_is_not_charged_twice():
+    m = smiles('CC[Zn+]')
+    assert not standardize(m)
+    assert sum(m.charge_of(n) for n in m) == 1
+
+
+def test_a_metal_left_over_when_the_halides_run_short_is_charged():
+    """One chloride between two reagents: rank decides who takes it, and the other is charged."""
+    assert _one(['C[Zn+].CC[Zn].[Cl-]', '[Cl-].CC[Zn].C[Zn+]', 'CC[Zn].[Cl-].C[Zn+]'])
+
+
+# the two orderings, each proved by permuting the input
+
+
+def test_a_mixed_halide_set_is_decided_by_element_and_not_by_input_order():
+    """`Cl > Br > I > F`: the metal takes the preferred halogen and the rest stay as counterions."""
+    assert _one(['CC[Zn+].[Cl-].[Br-]', 'CC[Zn+].[Br-].[Cl-]',
+                 '[Br-].[Cl-].CC[Zn+]']) == _std('CC[Zn]Cl.[Br-]')
+    assert _one(['CC[Zn+].[Br-].[I-]', '[I-].CC[Zn+].[Br-]']) == _std('CC[Zn]Br.[I-]')
+    assert _one(['CC[Zn+].[I-].[F-]', '[F-].[I-].CC[Zn+]']) == _std('CC[Zn]I.[F-]')
+
+
+def test_interchangeable_halides_give_one_answer_whichever_is_picked():
+    """Two identical chlorides are the same choice twice, so the tie needs no breaking."""
+    assert _one(['CC[Zn+].[Cl-].[Cl-]', '[Cl-].CC[Zn+].[Cl-]',
+                 '[Cl-].[Cl-].CC[Zn+]']) == _std('CC[Zn]Cl.[Cl-]')
+
+
+def test_which_metal_takes_the_single_halide_is_decided_by_canonical_rank():
+    """Two different reagents drawn with one chloride between them: rank picks, and picks the same way.
+
+    This is the case that cannot be a rule-table row -- the table applies whichever match the
+    isomorphism search returned first, which is what the input order decides.
+    """
+    assert _one(['C[Zn+].CC[Zn+].[Cl-]', 'CC[Zn+].C[Zn+].[Cl-]', '[Cl-].CC[Zn+].C[Zn+]',
+                 'C[Zn+].[Cl-].CC[Zn+]'])
+
+
+def test_equivalent_metals_are_automorphic_so_the_tie_is_not_observable():
+    assert _one(['C[Zn+].C[Zn+].[Cl-]', '[Cl-].C[Zn+].C[Zn+]', 'C[Zn+].[Cl-].C[Zn+]'])
+
+
+def test_several_metals_and_several_halides_are_paired_one_each():
+    """Two reagents, two chlorides: each metal takes one, and no permutation changes the pairing."""
+    assert _one([f'{a}.{b}.{c}.{d}' for a, b, c, d in
+                 permutations(['C[Zn+]', 'CC[Zn+]', '[Cl-]', '[Cl-]'])]) == _std('C[Zn]Cl.CC[Zn]Cl')
+
+
+# what the join is worth downstream
+
+
+def test_the_joined_form_is_the_one_the_reaction_corpus_names():
+    """The ion pair answers with the generic carbanion; joined, each reagent names itself."""
+    for s, group in [('CC[Zn+].[Cl-]', 'alkyl_zinc'), ('c1ccccc1[Mg+].[Br-]', 'aryl_grignard')]:
+        m = smiles(s)
+        assert 'metalate_carbanion' in m.functional_groups()
+        standardize(m)
+        assert group in m.functional_groups(), s
+
+
+def test_the_join_leaves_a_clean_valence_and_recomputes_the_hydrogen_count():
+    for s in ('CC[Zn+].[Cl-]', 'CC[Zn].[Cl]', 'c1ccccc1[Mg+].[Br-]'):
+        m = smiles(s)
+        standardize(m)
+        assert not m.check_valence(), s
+
+
+# the record
+
+
+def test_the_join_is_recorded_against_a_table_qualified_id():
+    m = smiles('CC[Zn+].[Cl-]')
+    standardize(m)
+    records = [r for r in m.log if r.rule.startswith('organometallics:')]
+    assert len(records) == 1, [r.rule for r in m.log]
+    assert records[0].rule == 'organometallics:unite'
+    assert m.log.by_stage('standardize')
+
+
+def test_charging_a_stranded_metal_is_a_separate_record_from_joining_one():
+    """A consumer can decline the weaker claim -- the halide nobody drew -- and keep the join."""
+    m = smiles('CC[Zn]')
+    standardize(m)
+    records = [r for r in m.log if r.rule.startswith('organometallics:')]
+    assert [r.rule for r in records] == ['organometallics:charge']
+    assert 'no halide' in records[0].message
+
+    both = smiles('C[Zn].CC[Zn].[Cl-]')
+    standardize(both)
+    assert {r.rule for r in both.log if r.rule.startswith('organometallics:')} == \
+        {'organometallics:unite', 'organometallics:charge'}
+
+    # and the two halves compose to one answer: whether the leftover metal arrived neutral or already
+    # `+`, the halide goes to the same reagent and the other ends up charged either way.
+    assert _std('C[Zn].CC[Zn].[Cl-]') == _std('C[Zn+].CC[Zn].[Cl-]') == _std('CC[Zn]Cl.C[Zn+]')
+
+
+def test_a_join_that_moves_net_charge_says_so_and_one_that_does_not_stays_quiet_about_it():
+    def charge(m):
+        return sum(m.charge_of(n) for n in m)
+
+    conserving, moving = smiles('CC[Zn+].[Cl-]'), smiles('CC[Zn+].[Cl]')
+    assert charge(conserving) == 0 and charge(moving) == 1
+    for m in (conserving, moving):
+        standardize(m)
+    assert charge(conserving) == 0 and charge(moving) == 0
+    said = [r for r in moving.log if r.rule == 'organometallics:unite'][0].message
+    assert 'charge' in said
+    assert 'charge' not in [r for r in conserving.log if r.rule == 'organometallics:unite'][0].message
+
+
+# the pipeline
+
+
+def test_canonicalize_joins_it_too():
+    m = smiles('CC[Zn+].[Cl-]')
+    canonicalize(m)
+    assert format(m, '') == _std('CC[Zn]Cl')

{chython-3.0.2 → chython-3.1}/chython/core/_smiles_read.pxi

@@ -1936,6 +1936,26 @@ cdef int smi_marks(smi_parse_t *p, MoleculeContainer mol, object log) except -1:
                     refused.append(mc_record('smiles:cip-refused', (),
                                              'atom %d: the CIP descriptor the `{...}` block names '
                                              'cannot be stored (%s)' % (i + 1, e), mc_lost()))
+                else:
+                    # A STORED DESCRIPTOR PUTS ITS CENTRE IN THE ABSOLUTE COLLECTION.  The field states
+                    # two things -- somebody's completed determination, and that the centre is one such a
+                    # determination could be made about -- and the dialect has no `a:` to spell the second
+                    # with.  The descriptor alone is the weaker half: beside a drawing it is one letter,
+                    # while the collection is what says the configuration is THIS one and not one of a set.
+                    #
+                    # Two guards, both because this reading is the READER'S and not the input's words.
+                    # `sg_kind` must be unnamed, a group field being the input saying so directly and the
+                    # stronger statement wherever the block spells it -- `{A19=r;A22=r;o1:19,22}` keeps its
+                    # OR collection, and would in either field order, the loop above having settled every
+                    # group before this line runs for any atom.  And the configuration must be STATED: `@?`
+                    # and a bare `C` have nothing to be absolute about, and marking them would draw an `a`
+                    # beside a methyl in every depiction.
+                    #
+                    # Identity is untouched -- a configured atom in no collection already means absolute,
+                    # so the canonical form does not separate the two -- and `set_stereo_group` cannot
+                    # refuse ABS: it forces the group to 0 and validates only the stable id.
+                    if not a.sg_kind and (a.chiral == SMI_CHIRAL_AT or a.chiral == SMI_CHIRAL_ATAT):
+                        mol.set_stereo_group(a.sid, <int> SMI_SG_ABS, 0)
     log.extend(refused)
     return 0
 

{chython-3.0.2 → chython-3.1}/chython/core/_smiles_write.pxi

@@ -2318,12 +2318,18 @@ cdef str smw_tail_text(tuple t, list fgroups=None):
         parts.append('$%s$' % ';'.join(group))
     if radicals:
         parts.append('^1:' + ','.join(map(str, sorted(radicals))))
-    if abs_atoms and (and_groups or or_groups):
-        # ONLY BESIDE AN AND OR OR COLLECTION, where it says which centres are NOT in one.  Alone it
-        # says only "these centres are absolute", which is what a configured atom outside any
-        # collection already means, so the field would separate two spellings of one structure -- a
-        # molfile that named STEABS and a SMILES that had nowhere to name it.  The cost is that a
-        # round trip through SMILES turns a lone explicit ABS kind into an unspecified one.
+    if abs_atoms:
+        # WHENEVER AN ATOM CARRIES THE ABS KIND, alone or beside an AND or OR collection, so the field
+        # round-trips: an explicit ABS collection is what the arena was told, and a writer that dropped
+        # it would answer "unspecified" to a reader who asked what the input said.  Only an EXPLICIT
+        # kind reaches `abs_atoms` -- `smw_tail_parts` collects `kind == 1` and a configured atom in no
+        # collection is kind 0 -- so a plain `F[C@H](Cl)Br` still writes bare.
+        #
+        # The cost, and it is the reason this field was once suppressed alone: a configured atom in no
+        # collection ALREADY means absolute, so `a:` states nothing new about the structure and two
+        # spellings of one compound now write two strings.  They still compare and hash EQUAL, the
+        # collection not being part of the canonical form, so the split is in the text only -- and a
+        # cache keyed on the string rather than on the container will store both.
         parts.append('a:' + ','.join(map(str, sorted(abs_atoms))))
     for key in sorted(and_groups):
         parts.append('&%d:%s' % (key, ','.join(map(str, sorted(and_groups[key])))))

{chython-3.0.2 → chython-3.1}/chython/core/test/test_smiles_read.py

@@ -1132,6 +1132,55 @@ def test_the_q_descriptor_states_no_determination_and_is_not_a_loss():
     assert len(log) == 1 and log[0].rule == 'smiles:cip-undetermined'
 
 
+def test_a_stated_descriptor_puts_its_centre_in_the_absolute_collection():
+    # `A<i>=<letter>` is TWO statements about the centre: somebody's completed determination, and that
+    # the centre is absolutely configured -- nothing determines a descriptor for a member of an OR or
+    # AND collection.  The dialect has no `a:` field beside a descriptor, so the collection is read off
+    # the descriptor, which is the statement that survives a reader who does not want the letter.
+    log = []
+    mol = read_smiles('CC(=O)c1cc2CN(C(=O)OC(C)(C)C)[C@H](C)Cn2n1 {A15=R}', log)
+    assert not log, log
+    assert mol.atom_cips() == {16: 'R'}
+    assert mol.stereo_groups() == {(STEREO_ABS, 0): [16]}
+    # and it is the same collection the pipe dialect spells, so nothing downstream sees two kinds of ABS
+    assert mol.stereo_groups() == read_smiles(
+        'CC(=O)c1cc2CN(C(=O)OC(C)(C)C)[C@H](C)Cn2n1 |a:15|').stereo_groups()
+
+
+def test_a_descriptor_never_moves_a_centre_out_of_the_collection_a_field_named():
+    # the group fields are the stronger statement and field ORDER must not decide it, so the reading
+    # above applies only where no field of the block named a group for that atom at all.
+    assert read_smiles(BRACE_OR).stereo_groups() == {(STEREO_OR, 1): [20, 23]}
+    for s in ('F[C@H](Cl)Br {o1:1;A1=R}', 'F[C@H](Cl)Br {A1=R;o1:1}'):
+        assert read_smiles(s).stereo_groups() == {(STEREO_OR, 1): [2]}, s
+
+
+def test_only_a_configured_centre_is_made_absolute_by_its_descriptor():
+    # the collection is the READER's inference and not the input's words, so it is drawn only where
+    # there is a configuration to be absolute about.  Otherwise a block that states a descriptor for a
+    # methyl carbon puts an `a` beside a methyl in every depiction of it.
+    assert read_smiles('C[C@H](N)C {A0=R}').stereo_groups() == {}      # `A0` is the methyl
+    assert read_smiles('C[C@?H](N)O {A1=R}').stereo_groups() == {}     # `@?`: no configuration stated
+    assert read_smiles('C[C@H](N)O {A1=q}').stereo_groups() == {}      # `q`: no determination stated
+    assert read_smiles('C[C@H](N)C {A1=E}').stereo_groups() == {}      # refused, so nothing to infer from
+
+
+def test_the_absolute_collection_a_descriptor_implies_is_written_but_is_not_identity():
+    # a configured atom in no collection already means absolute, so the two molecules below are one
+    # compound: they compare and hash EQUAL, the collection not being part of the canonical form.  This
+    # is the test that fails if ABS ever enters the canonical bytes.
+    a, b = read_smiles('F[C@H](Cl)Br'), read_smiles('F[C@H](Cl)Br {A1=R}')
+    a.canonicalize()
+    b.canonicalize()
+    assert a == b and hash(a) == hash(b)
+    # and the writer states the collection anyway, so what the input said survives a round trip.  The
+    # cost is here and only here: one compound, two strings, so a cache keyed on the TEXT stores both
+    # while one keyed on the container does not.
+    assert format(a, '') == '[C@@H](F)(Cl)Br'
+    assert format(b, '') == '[C@@H](F)(Cl)Br |a:0|'
+    assert format(read_smiles(format(b, '')), '') == format(b, '')
+
+
 def test_the_cx_relative_flag_is_a_loss_only_where_it_stands_alone():
     # `r` carries no atom list. Beside an `&`/`o` group it restates the group -- the output is
     # byte-identical to the same string without it -- and alone it is the only statement that the

{chython-3.0.2 → chython-3.1}/chython/core/test/test_smiles_write.py

@@ -470,6 +470,24 @@ def test_an_alias_is_written_as_the_tail_s_label_field():
     assert write_smiles(m, '!x') == 'C(C)C'
 
 
+def test_the_abs_collection_is_written_alone_and_beside_another_one():
+    # `a:` is written wherever an atom carries the ABS kind, so what the input stated survives the round
+    # trip.  Alone it says nothing new about the STRUCTURE -- a configured atom in no collection already
+    # means absolute -- which is why only an EXPLICIT kind reaches the field: the last line is the
+    # negative control that a plain configured centre still writes bare.
+    assert write_smiles(read_smiles('F[C@H](Cl)Br |a:1|')) == '[C@@H](F)(Cl)Br |a:0|'
+    assert write_smiles(read_smiles('F[C@H](Cl)Br {a:1}')) == '[C@@H](F)(Cl)Br |a:0|'
+    # beside an AND or OR collection it keeps its older job as well, naming the centres NOT in one
+    text = write_smiles(read_smiles('C[C@H](O)[C@H](N)[C@H](F)C |a:1,&1:3,o1:5|'))
+    assert text == 'C[C@@H](F)[C@H]([C@@H](O)C)N |a:4,&1:3,o1:1|'
+    # a fixed point, which is the round trip stated without naming a stable id: reading the string back
+    # and writing it again reproduces it, so every collection landed on the atom it named
+    assert write_smiles(read_smiles(text)) == text
+    # and `!x` suppresses this field with the rest of the block
+    assert write_smiles(read_smiles('F[C@H](Cl)Br |a:1|'), '!x') == '[C@@H](F)(Cl)Br'
+    assert write_smiles(read_smiles('F[C@H](Cl)Br')) == '[C@@H](F)(Cl)Br'
+
+
 def test_an_alias_survives_a_round_trip_through_the_string():
     # the atoms are re-ordered canonically, so what a round trip preserves is the PAIRING of a label
     # to its atom, which is what comparing the two molecules asserts

{chython-3.0.2 → chython-3.1}/chython/reactions/tables/functional.tsv

@@ -44,6 +44,12 @@
 # it).  A sulfone/sulfonyl/nitro centre is `z5`, but a row already writing both `=[O]` out has stated
 # that, so the rows below do not repeat it.  `x` counts heteroatom neighbours, and B, S, Si, Sn and Mg
 # all count -- a CF3 carbon bonded to sulfur is `x4`, not `x3`.
+#
+# THE RADICAL STATE IS THE CXSMARTS `|^1:0|` TAIL, there being no in-bracket radical primitive, so a
+# radical row carries one and its `example` carries the matching CXSMILES tail.  EACH RADICAL ROW COVERS
+# EXACTLY ONE RADICAL ATOM, which is what lets a caller ask whether every radical in a record is named: the
+# radical rows' counts sum to the radical atom count when they are, and fall short when one is a drawing
+# error.  A `decoys` cell splits on commas, so a decoy's tail may name one atom only.
 id	name	smarts	example	decoys	description
 1	terminal_alkene	[C;z2;x0;D1:1]=[C;z2;x0;D2,D3:2]	C=CCC	CC=CC,C=CN	monosubstituted C=C
 2	alkene	[C;z2;x0;D2,D3:1]=[C;z2;x0;D2,D3:2]	CC=CC	C=CCC,CC=CO	internal C=C, no heteroatom on either carbon
@@ -308,3 +314,8 @@ id	name	smarts	example	decoys	description
 247	lactam_4_halide	[F,Cl,Br,I;D1]-[C;z2;r6:1]=1-[C;D3;z2;M]-[N;D3;M]-[C,N;z2,z4;M]=,:[C,N;z2,z4;M]-[C,N;z2;M]=1	O=C1N(C)C=CC=C1Cl	O=C1N(C)C=CC(Cl)=C1	Activated C(sp2)-X on an N-substituted six-membered lactam, halide at C3 of a 2-pyridinone, adjacent to the carbonyl
 248	lactam_5_halide	[F,Cl,Br,I;D1]-[C;z2;r6:1]1=[C,N;z2;M]-[N;D3;M]-[C,N;z2,z4;M]=,:[C,N;z2,z4;M]-[C;D3;z2;M]1	O=C1C(Cl)=CN(C)C=C1	O=C1C=C(Cl)N(C)C=C1	Activated C(sp2)-X on an N-substituted six-membered lactam, halide at C3 of a 4-pyridinone, adjacent to the carbonyl
 249	lactam_6_halide	[F,Cl,Br,I;D1]-[C;z2;r6:1]1=[C,N;z2;M]-[N;D3;M]-[C;D3;z2;M]-[C,N;z2,z4;M]=,:[C,N;z2,z4;M]1	O=C1N(C)C=C(Cl)C=C1	O=C1N(C)C(Cl)=CC=C1	Activated C(sp2)-X on an N-substituted six-membered lactam, halide at C5 of a 2-pyridinone
+# --- the persistent radicals, where the substituents are what make the radical isolable ---
+250	nitroxide	[O;D1;h0;z1:1]-[N;D3;z1:2](-[C;z1,z4;D3,D4:3])-[C;z1,z4;D3,D4:4] |^1:0|	CC1(C)CCCC(C)(C)N1[O] |^1:10|	CC1(C)CCCC(C)(C)N1O,CC1(C)CCCC(C)(C)[N+]1=O,C[N]([O])C |^1:2|	R2N-O•, the radical on oxygen -- TEMPO and its kin.  `D3,D4` on both alpha carbons is the isolability: a nitroxide with an alpha hydrogen disproportionates, so dimethylnitroxide is a decoy and not a match.  The hydroxylamine and the oxoammonium cation are the same skeleton at the other two oxidation states
+251	hindered_aryloxyl	[O;D1;h0;z1:1]-[C;a:2](:[C;a:3]-[C;D4;z1:4]):[C;a:5]-[C;D4;z1:6] |^1:0|	[O]c1c(C(C)(C)C)cc(C(C)(C)C)cc1C(C)(C)C |^1:0|	[O]c1ccccc1 |^1:0|,Oc1c(C(C)(C)C)cc(C)cc1C(C)(C)C	Ar-O• with a quaternary carbon at BOTH ortho positions, which is what makes it isolable; the unhindered phenoxyl radical is a decoy
+252	hydrazyl	[N;D2;h0;z1:1](-[C;a:2])-[N;D3;z1:3](-[C;a:4])-[C;a:5] |^1:0|	[N](N(c1ccccc1)c1ccccc1)c1c([N+](=O)[O-])cc([N+](=O)[O-])cc1[N+](=O)[O-] |^1:0|	c1ccccc1N(c1ccccc1)Nc1ccccc1,C[N]N(C)C |^1:1|	Ar2N-N•-Ar, the DPPH class: three aryl rings to delocalise over, and the trialkyl hydrazyl with none of them is a decoy
+253	triarylmethyl_radical	[C;D3;h0;z1:1](-[C;a:2])(-[C;a:3])-[C;a:4] |^1:0|	[C](c1ccccc1)(c1ccccc1)c1ccccc1 |^1:0|	C(c1ccccc1)(c1ccccc1)c1ccccc1,[C+](c1ccccc1)(c1ccccc1)c1ccccc1,C[C](C)c1ccccc1 |^1:1|	Ar3C•, Gomberg's radical and the trityl spin labels.  `_radical` is in the name because `protective.tsv`'s trityl rows are this skeleton without one

{chython-3.0.2 → chython-3.1}/chython/reactions/test/_frozen_ids.py

@@ -26,7 +26,7 @@ and read the diff.  A new line is a new row; a CHANGED line is a renumber, which
 means.  Never hand-edit a line to make the ratchet pass.
 """
 
-#: `functional.tsv`: 249 rows, id -> the row it names.
+#: `functional.tsv`: 253 rows, id -> the row it names.
 FUNCTIONAL = {
     'functional:1': 'terminal_alkene',
     'functional:2': 'alkene',
@@ -277,6 +277,10 @@ FUNCTIONAL = {
     'functional:247': 'lactam_4_halide',
     'functional:248': 'lactam_5_halide',
     'functional:249': 'lactam_6_halide',
+    'functional:250': 'nitroxide',
+    'functional:251': 'hindered_aryloxyl',
+    'functional:252': 'hydrazyl',
+    'functional:253': 'triarylmethyl_radical',
 }
 
 #: `protective.tsv`: 103 rows, id -> the row it names.

{chython-3.0.2 → chython-3.1}/chython/test/test_facade_names.py

@@ -177,7 +177,7 @@ def test_the_whole_corpus_is_reachable_without_a_molecule():
     import chython
 
     functional, protective = chython.functional_rules(), chython.protective_rules()
-    assert len(functional) == 249 and len(protective) == 103
+    assert len(functional) == 253 and len(protective) == 103
     assert all(isinstance(k, str) and v.name == k for k, v in functional.items())
     assert all(isinstance(k, str) and v.name == k for k, v in protective.items())
     assert functional['carboxylic_acid'].smarts and protective['amine_boc'].protects == ('amine',)

{chython-3.0.2 → chython-3.1/chython.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chython
-Version: 3.0.2
+Version: 3.1
 Summary: Library for processing molecules and reactions in python way
 Author-email: Ramil Nugmanov <nougmanoff@protonmail.com>
 License-Expression: LGPL-3.0-or-later