chython 3.0.1__tar.gz → 3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chython
-Version: 3.0.1
+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.1 → 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.1 → 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.1 → 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.1 → 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')