synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Reaction/deionize.py

@@ -0,0 +1,199 @@
+import random
+from itertools import combinations, permutations
+from joblib import Parallel, delayed
+from typing import List, Tuple, Callable, Dict, Any
+
+from rdkit import Chem
+from rdkit.Chem.MolStandardize import rdMolStandardize
+
+from synkit.Chem.Reaction.balance_check import BalanceReactionCheck
+
+
+class Deionize:
+    """Neutralize ionic species and mixtures of ions in reactions.
+
+    Provides methods to group ions into neutral combinations, uncharge
+    individual anions/cations, and apply these corrections to SMILES
+    strings or entire reaction dictionaries.
+    """
+
+    @staticmethod
+    def random_pair_ions(
+        charges: List[int], smiles: List[str]
+    ) -> Tuple[List[List[str]], List[List[int]]]:
+        """Identify non‑overlapping groups of ions whose charges sum to zero.
+
+        :param charges: List of integer formal charges for each ion.
+        :type charges: List[int]
+        :param smiles: Corresponding SMILES strings for each ion.
+        :type smiles: List[str]
+        :return: A tuple of two lists:
+                  - groups of SMILES strings forming neutral sets,
+                  - groups of their corresponding charges.
+        :rtype: Tuple[List[List[str]], List[List[int]]]
+        """
+
+        def find_groups(indices: List[int], size: int) -> Tuple[int, ...]:
+            for group in combinations(indices, size):
+                if sum(charges[i] for i in group) == 0:
+                    return group
+            return ()
+
+        indices = list(range(len(charges)))
+        random.shuffle(indices)
+        used = set()
+        grouped_smiles: List[List[str]] = []
+        grouped_charges: List[List[int]] = []
+
+        for group_size in (2, 3, 4):
+            while True:
+                available = [i for i in indices if i not in used]
+                group = find_groups(available, group_size)
+                if not group:
+                    break
+                grouped_smiles.append([smiles[i] for i in group])
+                grouped_charges.append([charges[i] for i in group])
+                used.update(group)
+
+        return grouped_smiles, grouped_charges
+
+    @staticmethod
+    def uncharge_anion(smiles: str, charges: int = -1) -> str:
+        """Neutralize an anionic SMILES string.
+
+        :param smiles: SMILES of the anion to neutralize.
+        :type smiles: str
+        :param charges: Formal charge of the ion (negative integer).
+            Defaults to -1.
+        :type charges: int
+        :return: SMILES of the uncharged molecule.
+        :rtype: str
+        """
+        if smiles == "[N-]=[N+]=[N-]":
+            return "[N-]=[N+]=[N]"
+        if charges == -1:
+            mol = Chem.MolFromSmiles(smiles)
+            uncharger = rdMolStandardize.Uncharger()
+            uncharged = uncharger.uncharge(mol)
+            return Chem.MolToSmiles(uncharged)
+        # for multi‐charged anions
+        return smiles.replace(f"{charges}", "").replace("[", "").replace("]", "")
+
+    @staticmethod
+    def uncharge_cation(smiles: str, charges: int = 1) -> str:
+        """Neutralize a cationic SMILES string.
+
+        :param smiles: SMILES of the cation to neutralize.
+        :type smiles: str
+        :param charges: Formal charge of the ion (positive integer).
+            Defaults to 1.
+        :type charges: int
+        :return: SMILES of the uncharged molecule.
+        :rtype: str
+        """
+        if charges == 1:
+            return smiles.replace("+", "")
+        return smiles.replace(f"+{charges}", "")
+
+    @staticmethod
+    def uncharge_smiles(charge_smiles: str) -> str:
+        """Neutralize all ionic components in a dot‑separated SMILES string.
+
+        Splits into components, identifies ionic species, groups
+        them into neutral sets via `random_pair_ions`, then
+        applies `uncharge_anion` or `uncharge_cation` and recombines.
+
+        :param charge_smiles: SMILES string with ionic and non‑ionic parts.
+        :type charge_smiles: str
+        :return: SMILES string with charges neutralized.
+        :rtype: str
+        """
+        parts = charge_smiles.split(".")
+        charges = [Chem.rdmolops.GetFormalCharge(Chem.MolFromSmiles(p)) for p in parts]
+        if all(c == 0 for c in charges):
+            return charge_smiles
+
+        non_ionic, ionic_parts, ionic_charges = [], [], []
+        for p, c in zip(parts, charges):
+            if c == 0:
+                non_ionic.append(p)
+            else:
+                ionic_parts.append(p)
+                ionic_charges.append(c)
+
+        valid = non_ionic.copy()
+        groups, group_chs = Deionize.random_pair_ions(ionic_charges, ionic_parts)
+        for smiles_group, charge_group in zip(groups, group_chs):
+            candidates = []
+            for smi, ch in zip(smiles_group, charge_group):
+                if ch > 0:
+                    candidates.append(Deionize.uncharge_cation(smi, ch))
+                else:
+                    candidates.append(Deionize.uncharge_anion(smi, ch))
+            # try permutations for valid SMILES
+            for perm in permutations(candidates):
+                combo = "".join(perm)
+                if Chem.MolFromSmiles(combo):
+                    valid.append(Chem.CanonSmiles(combo))
+                    break
+            else:
+                valid.extend(smiles_group)
+        return ".".join(valid)
+
+    @staticmethod
+    def ammonia_hydroxide_standardize(reaction_smiles: str) -> str:
+        """Simplify ammonium hydroxide pairs in a reaction SMILES.
+
+        :param reaction_smiles: Reaction SMILES string.
+        :type reaction_smiles: str
+        :return: Reaction SMILES with '[NH4+].[OH-]' replaced by 'N.O'
+            or 'O.N'.
+        :rtype: str
+        """
+        return reaction_smiles.replace("[NH4+].[OH-]", "N.O").replace(
+            "[OH-].[NH4+]", "O.N"
+        )
+
+    @classmethod
+    def apply_uncharge_smiles_to_reactions(
+        cls,
+        reactions: List[Dict[str, Any]],
+        uncharge_smiles_func: Callable[[str], str],
+        n_jobs: int = 4,
+    ) -> List[Dict[str, Any]]:
+        """Apply a neutralization function to each reaction’s
+        reactants/products in parallel.
+
+        Adds keys 'new_reactants', 'new_products', and 'standardized_reactions'
+        based on uncharged SMILES and verifies formula balance.
+
+        :param reactions: List of reaction dicts with 'reactants' and 'products' keys.
+        :type reactions: List[Dict[str, Any]]
+        :param uncharge_smiles_func: Function to neutralize a SMILES string.
+        :type uncharge_smiles_func: Callable[[str], str]
+        :param n_jobs: Number of parallel jobs to run. Defaults to 4.
+        :type n_jobs: int
+        :return: List of updated reaction dicts with:
+                  - 'success': bool indicating formula match
+                  - 'new_reactants' / 'new_products'
+                  - 'standardized_reactions'
+        :rtype: List[Dict[str, Any]]
+        """
+
+        def process(reaction: Dict[str, Any]) -> Dict[str, Any]:
+            # pre‐standardize ammonia hydroxide
+            r_fix = cls.ammonia_hydroxide_standardize(reaction["reactants"])
+            p_fix = cls.ammonia_hydroxide_standardize(reaction["products"])
+            ur = uncharge_smiles_func(r_fix)
+            up = uncharge_smiles_func(p_fix)
+            r_formula = BalanceReactionCheck().get_combined_molecular_formula(ur)
+            p_formula = BalanceReactionCheck().get_combined_molecular_formula(up)
+            reaction["success"] = r_formula == p_formula
+            reaction["new_reactants"] = ur if reaction["success"] else r_fix
+            reaction["new_products"] = up if reaction["success"] else p_fix
+            reaction["standardized_reactions"] = (
+                f"{reaction['new_reactants']}>>{reaction['new_products']}"
+            )
+            return reaction
+
+        return Parallel(n_jobs=n_jobs)(delayed(process)(rxn) for rxn in reactions)

synkit/Chem/Reaction/explicit_h_audit.py

@@ -0,0 +1,232 @@
+"""Selection gate for mapped reactions with hydrogen in the reaction center.
+
+This module deliberately uses a narrow definition suitable for regression and
+conformance data.  An accepted reaction must be fully atom mapped, conserve
+mapped atom identities, molecular formula, and total formal charge, and contain
+at least one explicit mapped hydrogen incident to a changed bond.
+
+The check is stricter than merely searching for ``"[H:"``.  A mapped hydrogen
+which is present but remote from every bond change does not qualify.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+
+from rdkit import Chem
+from rdkit.Chem.rdMolDescriptors import CalcMolFormula
+
+
+@dataclass(frozen=True, order=True)
+class MappedBondChange:
+    """One mapped bond before and after a reaction."""
+
+    atom_maps: tuple[int, int]
+    before: float
+    after: float
+
+    @property
+    def kind(self) -> str:
+        if self.before == 0.0:
+            return "FORMED"
+        if self.after == 0.0:
+            return "BROKEN"
+        return "ORDER_CHANGED"
+
+
+@dataclass(frozen=True)
+class ExplicitHydrogenReactionAudit:
+    """Structured result returned by :func:`audit_explicit_h_reaction`."""
+
+    reaction: str
+    errors: tuple[str, ...] = ()
+    reactant_formula: str | None = None
+    product_formula: str | None = None
+    reactant_charge: int | None = None
+    product_charge: int | None = None
+    atom_maps: tuple[int, ...] = ()
+    explicit_hydrogen_maps: tuple[int, ...] = ()
+    changed_hydrogen_maps: tuple[int, ...] = ()
+    reaction_center_maps: tuple[int, ...] = ()
+    changed_bonds: tuple[MappedBondChange, ...] = ()
+
+    @property
+    def accepted(self) -> bool:
+        """Whether the reaction satisfies every strict selection criterion."""
+
+        return not self.errors
+
+
+@dataclass(frozen=True)
+class _ReactionSide:
+    formula: str
+    elemental_composition: tuple[tuple[tuple[int, int], int], ...]
+    charge: int
+    atoms_by_map: dict[int, tuple[int, int]]
+    bonds_by_maps: dict[tuple[int, int], float]
+    unmapped_atoms: tuple[int, ...]
+    duplicate_maps: tuple[int, ...]
+
+
+def reaction_smiles_from_annotated_text(text: str) -> str:
+    """Return the reaction token from legacy ``SMIRKS arrow-code`` text.
+
+    SynKit's polar and radical CSV files append electron-flow notation after a
+    space.  Ordinary reaction SMILES contains no whitespace, so the first token
+    is the complete reaction in both the annotated and unannotated forms.
+    """
+
+    stripped = str(text).strip()
+    return stripped.split(maxsplit=1)[0] if stripped else ""
+
+
+def _parse_side(smiles: str) -> _ReactionSide | None:
+    parser = Chem.SmilesParserParams()
+    parser.removeHs = False
+    molecule = Chem.MolFromSmiles(smiles, parser)
+    if molecule is None:
+        return None
+
+    atoms_by_map: dict[int, tuple[int, int]] = {}
+    unmapped_atoms = []
+    duplicate_maps = []
+    for atom in molecule.GetAtoms():
+        atom_map = int(atom.GetAtomMapNum())
+        if atom_map <= 0:
+            unmapped_atoms.append(atom.GetIdx())
+            continue
+        if atom_map in atoms_by_map:
+            duplicate_maps.append(atom_map)
+            continue
+        # Charge, radical state, and hydrogen count may legitimately change.
+        # Element and isotope may not change under an atom mapping.
+        atoms_by_map[atom_map] = (atom.GetAtomicNum(), atom.GetIsotope())
+
+    bonds_by_maps = {}
+    for bond in molecule.GetBonds():
+        begin_map = int(bond.GetBeginAtom().GetAtomMapNum())
+        end_map = int(bond.GetEndAtom().GetAtomMapNum())
+        if begin_map <= 0 or end_map <= 0:
+            continue
+        key = tuple(sorted((begin_map, end_map)))
+        bonds_by_maps[key] = float(bond.GetBondTypeAsDouble())
+
+    # CalcMolFormula includes a charge suffix (for example ``H4N+``).  Keep
+    # that human-readable value in the report, but compare mass balance using
+    # an isotope-aware elemental inventory so charge has its own error code.
+    composition: Counter[tuple[int, int]] = Counter()
+    for atom in molecule.GetAtoms():
+        composition[(atom.GetAtomicNum(), atom.GetIsotope())] += 1
+        if atom.GetAtomicNum() != 1:
+            hydrogen_count = atom.GetTotalNumHs(includeNeighbors=False)
+            if hydrogen_count:
+                composition[(1, 0)] += int(hydrogen_count)
+
+    return _ReactionSide(
+        formula=CalcMolFormula(molecule),
+        elemental_composition=tuple(sorted(composition.items())),
+        charge=int(Chem.GetFormalCharge(molecule)),
+        atoms_by_map=atoms_by_map,
+        bonds_by_maps=bonds_by_maps,
+        unmapped_atoms=tuple(unmapped_atoms),
+        duplicate_maps=tuple(sorted(set(duplicate_maps))),
+    )
+
+
+def audit_explicit_h_reaction(text: str) -> ExplicitHydrogenReactionAudit:
+    """Audit a mapped reaction for strict explicit-H-center suitability.
+
+    :param text: A mapped reaction SMILES, optionally followed by SynKit's legacy
+                 whitespace-separated electron-flow annotation.
+
+    :return: A report with stable error codes and the detected mapped bond changes.
+    :rtype: ExplicitHydrogenReactionAudit
+    """
+
+    reaction = reaction_smiles_from_annotated_text(text)
+    if reaction.count(">>") != 1:
+        return ExplicitHydrogenReactionAudit(
+            reaction,
+            errors=("INVALID_REACTION_SEPARATOR",),
+        )
+
+    reactant_text, product_text = reaction.split(">>", 1)
+    reactants = _parse_side(reactant_text)
+    products = _parse_side(product_text)
+    if reactants is None or products is None:
+        errors = []
+        if reactants is None:
+            errors.append("REACTANT_PARSE_FAILED")
+        if products is None:
+            errors.append("PRODUCT_PARSE_FAILED")
+        return ExplicitHydrogenReactionAudit(reaction, errors=tuple(errors))
+
+    errors = []
+    if reactants.unmapped_atoms:
+        errors.append("UNMAPPED_REACTANT_ATOM")
+    if products.unmapped_atoms:
+        errors.append("UNMAPPED_PRODUCT_ATOM")
+    if reactants.duplicate_maps:
+        errors.append("DUPLICATE_REACTANT_MAP")
+    if products.duplicate_maps:
+        errors.append("DUPLICATE_PRODUCT_MAP")
+
+    reactant_maps = set(reactants.atoms_by_map)
+    product_maps = set(products.atoms_by_map)
+    if reactant_maps != product_maps:
+        errors.append("MAP_INVENTORY_MISMATCH")
+    elif reactants.atoms_by_map != products.atoms_by_map:
+        errors.append("MAPPED_ATOM_IDENTITY_MISMATCH")
+
+    if reactants.elemental_composition != products.elemental_composition:
+        errors.append("FORMULA_IMBALANCE")
+    if reactants.charge != products.charge:
+        errors.append("CHARGE_IMBALANCE")
+
+    changed_bonds = []
+    all_bonds = set(reactants.bonds_by_maps) | set(products.bonds_by_maps)
+    for atom_maps in sorted(all_bonds):
+        before = reactants.bonds_by_maps.get(atom_maps, 0.0)
+        after = products.bonds_by_maps.get(atom_maps, 0.0)
+        if before != after:
+            changed_bonds.append(MappedBondChange(atom_maps, before, after))
+
+    hydrogen_maps = tuple(
+        sorted(
+            atom_map
+            for atom_map, identity in reactants.atoms_by_map.items()
+            if identity[0] == 1
+        )
+    )
+    if not hydrogen_maps:
+        errors.append("NO_EXPLICIT_MAPPED_HYDROGEN")
+
+    center_maps = tuple(
+        sorted({atom_map for change in changed_bonds for atom_map in change.atom_maps})
+    )
+    changed_hydrogen_maps = tuple(sorted(set(hydrogen_maps) & set(center_maps)))
+    if not changed_hydrogen_maps:
+        errors.append("NO_CHANGED_EXPLICIT_HYDROGEN")
+
+    return ExplicitHydrogenReactionAudit(
+        reaction=reaction,
+        errors=tuple(errors),
+        reactant_formula=reactants.formula,
+        product_formula=products.formula,
+        reactant_charge=reactants.charge,
+        product_charge=products.charge,
+        atom_maps=tuple(sorted(reactant_maps & product_maps)),
+        explicit_hydrogen_maps=hydrogen_maps,
+        changed_hydrogen_maps=changed_hydrogen_maps,
+        reaction_center_maps=center_maps,
+        changed_bonds=tuple(changed_bonds),
+    )
+
+
+__all__ = [
+    "ExplicitHydrogenReactionAudit",
+    "MappedBondChange",
+    "audit_explicit_h_reaction",
+    "reaction_smiles_from_annotated_text",
+]

synkit/Chem/Reaction/fix_aam.py

@@ -0,0 +1,64 @@
+from rdkit import Chem
+from typing import Optional
+
+
+class FixAAM:
+    """Utilities for incrementing and correcting atom‐atom mapping (AAM)
+    numbers in molecules and reaction SMILES.
+
+    Provides methods to:
+      - Increment AAM on all atoms of an RDKit Mol.
+      - Adjust AAM numbers in a standalone SMILES string.
+      - Apply the same adjustment to both sides of a reaction SMILES (RSMI).
+    """
+
+    @staticmethod
+    def increment_atom_mapping(mol: Chem.Mol) -> Chem.Mol:
+        """Increment the atom‐map number of each atom in an RDKit Mol by 1.
+
+        :param mol: RDKit molecule with existing atom‐map annotations.
+        :type mol: Chem.Mol
+        :return: The same Mol object with each atom’s map number
+            increased by one.
+        :rtype: Chem.Mol
+        """
+        for atom in mol.GetAtoms():
+            atom.SetAtomMapNum(atom.GetAtomMapNum() + 1)
+        return mol
+
+    @staticmethod
+    def fix_aam_smiles(smiles: str) -> str:
+        """Parse a SMILES string, increment all atom map numbers, and return
+        updated SMILES.
+
+        :param smiles: SMILES string containing atom‐map annotations.
+        :type smiles: str
+        :return: SMILES string with every atom‐map number increased by
+            one.
+        :rtype: str
+        :raises ValueError: If the input SMILES cannot be parsed into an
+            RDKit Mol.
+        """
+        mol: Optional[Chem.Mol] = Chem.MolFromSmiles(smiles, sanitize=False)
+        if mol is None:
+            raise ValueError(f"Invalid SMILES string: {smiles!r}")
+        Chem.SanitizeMol(mol)
+        FixAAM.increment_atom_mapping(mol)
+        return Chem.MolToSmiles(mol)
+
+    @staticmethod
+    def fix_aam_rsmi(rsmi: str) -> str:
+        """Apply atom‐map increment to both reactant and product sides of a
+        reaction SMILES.
+
+        :param rsmi: Reaction SMILES in 'reactants>>products' format
+            with atom‐map tags.
+        :type rsmi: str
+        :return: New reaction SMILES string where each atom‐map number
+            in both halves is increased by one.
+        :rtype: str
+        """
+        react, prod = rsmi.split(">>")
+        new_react = FixAAM.fix_aam_smiles(react)
+        new_prod = FixAAM.fix_aam_smiles(prod)
+        return f"{new_react}>>{new_prod}"