chython 3.1__tar.gz → 3.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chython
-Version: 3.1
+Version: 3.3
 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.1 → chython-3.3}/chython/chemistry/__init__.py

@@ -36,6 +36,7 @@ from ._crippen import crippen_logp, crippen_mr
 from ._hydrogens import explicify_hydrogens, implicify_hydrogens
 from ._implicit import calc_implicit, check_valence
 from ._isomers import standardize_isomers
+from ._kekule_form import standardize_kekule
 from ._maccs import maccs_bit_set, maccs_keys
 from ._perceive import perceive_bonds
 from ._pharmacophore import pharmacophore_invariants
@@ -44,23 +45,25 @@ from ._qed import alert_count, qed, qed_properties
 from ._residues import (RESIDUE_KINDS, ResidueTemplate, normalize_atom_name, residue_template,
                         residue_templates)
 from ._resonance import fix_resonance
-from ._salts import SaltComposition, decompose_salts, split_salts
+from ._salts import ComponentRow, DEFAULT_STABILIZER_CLASSES, SaltComposition, decompose_salts, split_salts
 from ._saturate import saturate
 from ._smarts import SmartsSyntaxError, compile_smarts
 from ._standardize import LogRecord, standardize
-from ._tables import (ACID_ROLES, AbbreviationRow, AcidRow, Endpoint, RESONANCE_ROLES, Rule, SALT_ROLES,
-                      SaltRow, abbreviation_row, abbreviations_rows, acids_rules, acids_rules_by_role,
-                      acids_table_text, groups_rules,
+from ._tables import (ACID_ROLES, AbbreviationRow, AcidRow, Endpoint, RESONANCE_ROLES, Rule,
+                      SALT_CLASSES, SALT_MATCHES, SaltRow, abbreviation_row, abbreviations_rows,
+                      acids_rules, acids_rules_by_role, acids_table_text, groups_rules,
                       metals_rules, read_table, resonance_rules, resonance_rules_by_role,
-                      resonance_table_text, salts_rows, salts_rows_by_role, salts_species_keys,
+                      resonance_table_text, salts_rows, salts_rows_by_klass, salts_species_keys,
                       salts_table_text, standardize_rules)
 from ._tpsa import tpsa
 from ..core._core import (_set_canonicalize_fn, _set_featurizer_fns, _set_hydrogens_fns,
-                          _set_isomers_fn, _set_protomers_fn, _set_resonance_fn, _set_salts_fns,
-                          _set_standardize_fn, _set_valence_fn)
+                          _set_isomers_fn, _set_kekule_form_fn, _set_protomers_fn,
+                          _set_resonance_fn, _set_salts_fns, _set_standardize_fn,
+                          _set_valence_fn)
 
 
-__all__ = ['ACID_ROLES', 'AbbreviationRow', 'LogRecord', 'SALT_ROLES', 'SaltComposition',
+__all__ = ['ACID_ROLES', 'AbbreviationRow', 'ComponentRow', 'DEFAULT_STABILIZER_CLASSES',
+           'LogRecord', 'SALT_CLASSES', 'SALT_MATCHES', 'SaltComposition',
            'abbreviation_row', 'abbreviations_rows', 'alert_count',
            'calc_implicit', 'canonicalize', 'check_valence', 'crippen_logp', 'crippen_mr',
            'decompose_salts', 'expand_abbreviations', 'explicify_hydrogens', 'fix_resonance',
@@ -68,12 +71,14 @@ __all__ = ['ACID_ROLES', 'AbbreviationRow', 'LogRecord', 'SALT_ROLES', 'SaltComp
            'hydrogen_bond_donors_count', 'implicify_hydrogens', 'maccs_bit_set', 'maccs_keys',
            'neutralize', 'perceive_bonds', 'pharmacophore_invariants', 'qed', 'qed_properties',
            'rotatable_bonds_count',
-           'saturate', 'split_salts', 'standardize', 'standardize_isomers', 'tpsa']
+           'saturate', 'split_salts', 'standardize', 'standardize_isomers',
+           'standardize_kekule', 'tpsa']
 
 _set_standardize_fn(standardize)
 _set_canonicalize_fn(canonicalize)
 _set_hydrogens_fns(implicify_hydrogens, explicify_hydrogens)
 _set_isomers_fn(standardize_isomers)
+_set_kekule_form_fn(standardize_kekule)
 _set_valence_fn(check_valence)
 _set_salts_fns(split_salts=split_salts, decompose_salts=decompose_salts)
 _set_protomers_fn(neutralize)

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

@@ -18,16 +18,18 @@
 #
 """`canonicalize()` -- the pre-pass that makes `canonical_bytes` a compound identity rather than a
 drawing identity, so equal compounds hash equal and a corpus deduplicates by hash.  The stage order
-is a correctness constraint, not taste: `kekule()`, `standardize()`, `implicify_hydrogens()`,
-`neutralize()`, `thiele()`, `standardize_isomers()`, and `kekule()` again only under
-`keep_kekule=True`.  Each ordering pair is justified at its numbered step below.
+is a correctness constraint, not taste: `kekule()`, `validate_stereo()`, `standardize()`,
+`implicify_hydrogens()`, `neutralize()`, `standardize_kekule()`, `thiele()`, `standardize_isomers()`, and
+`kekule()` again only under `keep_kekule=True`.  Each ordering pair is justified at its numbered step
+below.
 
-The order alone is not enough, because the last stage can unblock the second one: a `tautomer` row
+The order alone is not enough, because the last stage can unblock the third one: a `tautomer` row
 wanting a free ring nitrogen cannot fire while the mobile hydrogen sits on it, and the placement is
-what moves that hydrogen off.  So steps 2 to 6 run to a fixed point rather than once -- step 7.
+what moves that hydrogen off.  So steps 3 to 8 run to a fixed point rather than once -- step 9.
 """
 from ._hydrogens import implicify_hydrogens
 from ._isomers import standardize_isomers
+from ._kekule_form import standardize_kekule
 from ._protomers import neutralize
 from ._standardize import standardize
 from ..core import LOST, LogRecord, MoleculeContainer, recording
@@ -38,7 +40,7 @@ __all__ = ['canonicalize']
 
 _RULE_ROUNDS = 'canonicalize:rounds'
 
-#: How many times steps 2 to 6 may be re-run before the pipeline gives up and says so.  Every shape
+#: How many times steps 3 to 8 may be re-run before the pipeline gives up and says so.  Every shape
 #: measured converges in two, and the loop cannot cycle in principle: the `tautomer` rows move a
 #: hydrogen from oxygen or sulfur to nitrogen and never back, and the placement stage never makes an
 #: oxygen or a sulfur a site.  The cap is here so a rule table that breaks either half is reported as
@@ -62,13 +64,16 @@ 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()`.  `neutralize()` leaves the NET charge untouched, so
+    share a key, because step 5 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.
+    `standardize()` moves the net charge wherever a drawing omitted one: the organometallic completion
+    charges a metal nobody drew a halide for; `fix_salt_charges()` pairs each free metal with the acid
+    that belongs to it, deprotonating the acid and charging the metal only when it arrives neutral -- a
+    metal already drawn charged takes the proton and the total falls.  Both say so in the log, and
+    `neutralize()` two steps later leaves the repair alone: `acids.tsv`'s rows are charged sites only,
+    so a sodium cation is no donor to any of them.
     """
     # 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
@@ -79,7 +84,7 @@ def canonicalize(molecule: MoleculeContainer, *, fix_tautomers: bool = True,
                         f'{type(molecule).__name__}; a ReactionContainer has its own canonicalize(), '
                         f'which runs this pass on each of its molecules')
 
-    # the bool is measured, not accumulated: steps 1 and 5 are a round trip, so summing the stages'
+    # the bool is measured, not accumulated: steps 1 and 6 are a round trip, so summing the stages'
     # own flags would report a change through both ends of a no-op on an already-canonical molecule.
     before = molecule.canonical_bytes
 
@@ -92,43 +97,64 @@ def canonicalize(molecule: MoleculeContainer, *, fix_tautomers: bool = True,
     #    event already reported.  `check_valence()` is still how those atoms are found.
     molecule.kekule()
 
-    # 2. Repair the drawing.
+    # 2. Drop the parities the constitution does not justify, on the localised form and before step 6
+    #    hides a bond order behind an aromatic one.  A cis/trans sign on a double bond an alternating
+    #    cycle can move states which Kekule form was drawn, not the compound's geometry, and it enters
+    #    `canonical_bytes` whether or not the unit is stereogenic -- so the two bond-shift drawings of
+    #    1,2-dimethylcyclooctatetraene keep two keys until it is gone.  The report is not recorded: the
+    #    parities it names are the reader's own input and `validate_stereo()` returns them to a caller
+    #    that wants them.
+    molecule.validate_stereo()
+
+    # 3. Repair the drawing.
     standardize(molecule, fix_tautomers=fix_tautomers)
 
-    # 3. Explicit hydrogens are a `canonical_bytes` difference, so they have to go.
+    # 4. Explicit hydrogens are a `canonical_bytes` difference, so they have to go.
     implicify_hydrogens(molecule)
 
-    # 4. Pair off the charges an acid/base row can pair off, so a zwitterion and its neutral drawing
-    #    hash equal.  AFTER step 3, because `acids.tsv` reads implicit hydrogens: a cation drawn with
+    # 5. Pair off the charges an acid/base row can pair off, so a zwitterion and its neutral drawing
+    #    hash equal.  AFTER step 4, because `acids.tsv` reads implicit hydrogens: a cation drawn with
     #    hydrogen ATOMS is invisible to it until they have been folded in.  `keep_charge` stays at its
     #    default -- the net charge is part of the compound, so a canonical form may move a proton but
     #    never create or destroy one.  A quaternary ammonium keeps its counterion: it has no proton to
     #    give, so the pass finds no donor and declines.
     neutralize(molecule)
 
-    # 5. Back to the aromatic form, which is the representation callers compare.  Ahead of step 6,
+    # 6. Which Kekule form, decided before step 7 reads one.  `thiele()` refuses a candidate ring whose
+    #    atom holds its double bond outside the ring, so a compound with several Kekule forms has one
+    #    aromatic form per form until this stage picks between them; a ring too big for `thiele()` to
+    #    consider gets a canonical alternation here instead, nothing later collapsing its two.  AFTER
+    #    step 3, whose group rules are written against the orders the drawing carried, and after step 2,
+    #    whose parities would otherwise pin the very bond this stage moves.
+    standardize_kekule(molecule)
+
+    # 7. Back to the aromatic form, which is the representation callers compare.  Ahead of step 8,
     #    because a mobile hydrogen is a property of the aromatic form: step 1's definite orders already
     #    say where the hydrogen is, leaving the placement stage nothing to choose.
     #    `result.refused` is not recorded on top of the pass's own records either, and for the same
     #    reason -- with the severity the aromatiser itself states, which is `REFUSED` and not a loss.
     molecule.thiele()
 
-    # 6. Canonical placement of mobile hydrogens and charges -- what makes the two N-H forms of
+    # 8. Canonical placement of mobile hydrogens and charges -- what makes the two N-H forms of
     #    4-methylimidazole hash equal.  Not gated by `fix_tautomers`: that flag withholds local repair
     #    rules, and this picks which of two valid drawings to keep rather than repairing one.
     moved = standardize_isomers(molecule)
 
-    # 7. Steps 2 to 6 again, while the placement keeps unblocking a repair.  `Oc1[nH]cnc2nncc1-2` is
+    # 9. Steps 3 to 8 again, while the placement keeps unblocking a repair.  `Oc1[nH]cnc2nncc1-2` is
     #    the shape: its mobile hydrogen sits on the one ring nitrogen the hydroxy-azine rows need free,
-    #    so step 2 declines, and by the time step 6 has moved it the repair is behind us -- the drawing
+    #    so step 3 declines, and by the time step 8 has moved it the repair is behind us -- the drawing
     #    kept its hydroxy form and the same compound drawn the other way got the oxo form and a
     #    different key.  Only the placement is re-entered from, since it is the one stage that can put
     #    the molecule back into a shape an earlier stage would have acted on.
     #
     #    `kekule()` leads, and not for the reason step 1 does: the `tautomer` rows are written against
-    #    definite bond orders, so on the aromatic form step 5 left behind they match nothing at all and
-    #    re-running step 2 would be a guaranteed no-op.  Step 4 is re-entered only behind a repair,
-    #    which is the only thing that can hand it a charged site it has not already seen.
+    #    definite bond orders, so on the aromatic form step 7 left behind they match nothing at all and
+    #    re-running step 3 would be a guaranteed no-op.  Step 5 is re-entered only behind a repair,
+    #    which is the only thing that can hand it a charged site it has not already seen.  Step 6 rides
+    #    with the aromatisation and not with the repair: the kekulisation above is free to come back with
+    #    a different Kekule form than the one it was handed, which is the form step 7 would then read.
+    #    Step 2 is not re-entered: the parities it can justify are a property of the constitution, which
+    #    no stage from here on changes.
     for _ in range(_ROUNDS_MAX):
         if not moved:
             break
@@ -137,7 +163,8 @@ def canonicalize(molecule: MoleculeContainer, *, fix_tautomers: bool = True,
         if changed:
             implicify_hydrogens(molecule)
             neutralize(molecule)
-        molecule.thiele()               # unconditional: step 5's form is what a caller compares, and
+        standardize_kekule(molecule)
+        molecule.thiele()               # unconditional: step 6's form is what a caller compares, and
         if not changed:                 # the kekulisation above has to be undone either way
             break
         moved = standardize_isomers(molecule)
@@ -148,8 +175,10 @@ def canonicalize(molecule: MoleculeContainer, *, fix_tautomers: bool = True,
                                  f'this molecule is not a fixed point and two drawings of it may not '
                                  f'share a key', LOST))
 
-    # 8. `keep_kekule` undoes step 5 rather than skipping it: skipping 5 would skip 6 with it, and the
-    #    flag would then decide which tautomer the caller gets.
+    # 10. `keep_kekule` undoes step 7 rather than skipping it: skipping 7 would skip 8 with it, and the
+    #     flag would then decide which tautomer the caller gets.  Step 6 is not re-run behind it and
+    #     would have nothing to do: an aromatic ring is unwound into a ring holding every double bond it
+    #     has room for, and which of its alternations comes back is the kekuliser's answer to give.
     if keep_kekule:
         molecule.kekule()
 

{chython-3.1 → chython-3.3}/chython/chemistry/_implicit.py

@@ -82,6 +82,8 @@ def check_valence(molecule: MoleculeContainer) -> list[tuple[int, str]]:
     Merging them is how a coverage hole gets mistaken for bad input, so they stay apart.
 
     An aromatic atom is a violation only when neither Kekule reading has a row, since a claim about
-    the molecule must survive every form the ring could take.  Never raises and never edits.
+    the molecule must survive every form the ring could take.  A hydrogen is read the same way,
+    drawn or counted: `[H][Ca][H]` and the `[CaH2]` that `canonicalize()` folds it into are one
+    compound and get one verdict.  Never raises and never edits.
     """
     return valence_report(molecule)