synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Reaction/neutralize.py

@@ -0,0 +1,207 @@
+from rdkit import Chem
+from joblib import Parallel, delayed
+from typing import Dict, Any, List, Union, Tuple, Optional
+
+
+class Neutralize:
+    """Neutralize unbalanced charges in chemical reactions by adding
+    counter‑ions.
+
+    Provides utilities to calculate formal charges, parse reaction
+    SMILES, and adjust reactants/products with [Na+] or [Cl‑] to restore
+    neutrality.
+    """
+
+    @staticmethod
+    def calculate_charge(smiles: str) -> int:
+        """Calculate the formal charge of a molecule.
+
+        :param smiles: SMILES string of the molecule.
+        :type smiles: str
+        :return: Formal charge of the molecule (0 if invalid SMILES).
+        :rtype: int
+        """
+        mol = Chem.MolFromSmiles(smiles)
+        if mol is None:
+            return 0
+        return Chem.rdmolops.GetFormalCharge(mol)
+
+    @staticmethod
+    def parse_reaction(reaction_smiles: str) -> Tuple[Optional[str], Optional[str]]:
+        """Split a reaction SMILES into reactants and products.
+
+        :param reaction_smiles: Reaction SMILES in 'reactants>>products'
+            format.
+        :type reaction_smiles: str
+        :return: Tuple of (reactants, products) SMILES, or (None, None)
+            if parse fails.
+        :rtype: Tuple[Optional[str], Optional[str]]
+        """
+        try:
+            reactants, products = reaction_smiles.split(">>")
+            return reactants, products
+        except ValueError:
+            return None, None
+
+    @staticmethod
+    def calculate_charge_dict(
+        reaction: Dict[str, Any], reaction_column: str
+    ) -> Dict[str, Union[str, int]]:
+        """Compute and store the total formal charge of the products in a
+        reaction dict.
+
+        :param reaction: Dictionary containing at least `reaction_column` with a reaction SMILES.
+        :type reaction: Dict[str, Any]
+        :param reaction_column: Key under which the reaction SMILES is stored.
+        :type reaction_column: str
+        :return: The same dictionary updated with:
+                  - 'reactants': reactant SMILES or None
+                  - 'products': product SMILES or None
+                  - 'total_charge_in_products': integer sum of product charges or None
+        :rtype: Dict[str, Union[str, int]]
+        """
+        reactants, products = Neutralize.parse_reaction(
+            reaction.get(reaction_column, "")
+        )
+        if reactants is None or products is None:
+            reaction.update(
+                {"reactants": None, "products": None, "total_charge_in_products": None}
+            )
+        else:
+            reaction["reactants"] = reactants
+            reaction["products"] = products
+            total = sum(Neutralize.calculate_charge(p) for p in products.split("."))
+            reaction["total_charge_in_products"] = total
+        return reaction
+
+    @staticmethod
+    def fix_negative_charge(
+        reaction_dict: Dict[str, Any],
+        charges_column: str = "total_charge_in_products",
+        id_column: str = "R-id",
+        reaction_column: str = "reactions",
+    ) -> Dict[str, Any]:
+        """Add [Na+] ions to neutralize negative product charge.
+
+        :param reaction_dict: Dictionary with 'reactants', 'products', and charge info.
+        :type reaction_dict: Dict[str, Any]
+        :param charges_column: Key for product total charge. Defaults to 'total_charge_in_products'.
+        :type charges_column: str
+        :param id_column: Key for reaction identifier. Defaults to 'R-id'.
+        :type id_column: str
+        :param reaction_column: Key for reaction SMILES to update. Defaults to 'reactions'.
+        :type reaction_column: str
+        :return: New dictionary with:
+                  - updated `reaction_column` including added [Na+] ions
+                  - 'reactants' and 'products' with ions appended
+                  - charge column set to 0
+        :rtype: Dict[str, Any]
+        """
+        num_to_add = abs(reaction_dict.get(charges_column, 0))
+        sodium = "[Na+]"
+        addition = ("." + ".".join([sodium] * num_to_add)) if num_to_add else ""
+        new_react = reaction_dict["reactants"] + addition
+        new_prod = reaction_dict["products"] + addition
+        new_reaction = f"{new_react}>>{new_prod}"
+
+        reaction_dict.update(
+            {
+                id_column: reaction_dict.get(id_column),
+                reaction_column: new_reaction,
+                "reactants": new_react,
+                "products": new_prod,
+                charges_column: 0,
+            }
+        )
+        return reaction_dict
+
+    @staticmethod
+    def fix_positive_charge(
+        reaction_dict: Dict[str, Any],
+        charges_column: str = "total_charge_in_products",
+        id_column: str = "R-id",
+        reaction_column: str = "reactions",
+    ) -> Dict[str, Any]:
+        """Add [Cl‑] ions to neutralize positive product charge.
+
+        :param reaction_dict: Dictionary with 'reactants', 'products', and charge info.
+        :type reaction_dict: Dict[str, Any]
+        :param charges_column: Key for product total charge. Defaults to 'total_charge_in_products'.
+        :type charges_column: str
+        :param id_column: Key for reaction identifier. Defaults to 'R-id'.
+        :type id_column: str
+        :param reaction_column: Key for reaction SMILES to update. Defaults to 'reactions'.
+        :type reaction_column: str
+        :return: New dictionary with:
+                  - updated `reaction_column` including added [Cl‑] ions
+                  - 'reactants' and 'products' with ions appended
+                  - charge column set to 0
+        :rtype: Dict[str, Any]
+        """
+        num_to_add = abs(reaction_dict.get(charges_column, 0))
+        chloride = "[Cl-]"
+        addition = ("." + ".".join([chloride] * num_to_add)) if num_to_add else ""
+        new_react = reaction_dict["reactants"] + addition
+        new_prod = reaction_dict["products"] + addition
+        new_reaction = f"{new_react}>>{new_prod}"
+        reaction_dict.update(
+            {
+                id_column: reaction_dict.get(id_column),
+                reaction_column: new_reaction,
+                "reactants": new_react,
+                "products": new_prod,
+                charges_column: 0,
+            }
+        )
+        return reaction_dict
+
+    @staticmethod
+    def fix_unbalanced_charged(
+        reaction_dict: Dict[str, Any],
+        reaction_column: str,
+    ) -> Dict[str, Any]:
+        """Detect and neutralize unbalanced product charge by adding
+        counter‑ions.
+
+        :param reaction_dict: Dictionary with raw reaction SMILES under `reaction_column`.
+        :type reaction_dict: Dict[str, Any]
+        :param reaction_column: Key for reaction SMILES in the input dict.
+        :type reaction_column: str
+        :return: Dictionary with balanced charges and updated SMILES.
+        :rtype: Dict[str, Any]
+        """
+        rd = Neutralize.calculate_charge_dict(reaction_dict, reaction_column)
+        total = rd.get("total_charge_in_products", 0)
+        if total > 0:
+            return Neutralize.fix_positive_charge(rd)
+        if total < 0:
+            return Neutralize.fix_negative_charge(rd)
+        return rd
+
+    @classmethod
+    def parallel_fix_unbalanced_charge(
+        cls,
+        reaction_dicts: List[Dict[str, Any]],
+        reaction_column: str,
+        n_jobs: int = 4,
+    ) -> List[Dict[str, Any]]:
+        """Neutralize charges in multiple reaction dictionaries in parallel.
+
+        :param reaction_dicts: List of reaction dictionaries to process.
+        :type reaction_dicts: List[Dict[str, Any]]
+        :param reaction_column: Key for reaction SMILES in each dict.
+        :type reaction_column: str
+        :param n_jobs: Number of parallel jobs (use -1 for all cores).
+            Defaults to 4.
+        :type n_jobs: int
+        :return: List of dictionaries with balanced charges and updated
+            SMILES.
+        :rtype: List[Dict[str, Any]]
+        """
+        return Parallel(n_jobs=n_jobs)(
+            delayed(cls.fix_unbalanced_charged)(
+                d,
+                reaction_column,
+            )
+            for d in reaction_dicts
+        )

synkit/Chem/Reaction/radical_wildcard.py

@@ -0,0 +1,224 @@
+from rdkit import Chem
+from rdkit.Chem import SanitizeFlags
+import re
+from typing import Tuple, List, Optional, Dict
+
+
+def clean_wc(
+    rsmi: str, invert: bool = False, max_frag: bool = False, wild_card: bool = True
+) -> str:
+    """Clean wildcard-containing fragments from one side of a reaction SMILES,
+    optionally selecting the largest remaining fragment.
+
+    :param rsmi: Reaction SMILES string in the form 'R>>P'.
+    :type rsmi: str
+    :param invert: If True, process the reactant side; otherwise the product side.
+    :type invert: bool
+    :param max_frag: If True, force fragment selection (implies wild_card=True).
+    :type max_frag: bool
+    :param wild_card: If True, remove fragments containing '*' before selection.
+    :type wild_card: bool
+    :return: The processed reaction SMILES.
+    :rtype: str
+    :raises ValueError: If input does not split into reactant and product.
+
+    .. rubric:: Example
+
+    >>> clean_wc('A.B>>C.*', invert=False, wild_card=True)
+    'A.B>>C'
+    >>> clean_wc('A.B>>C.D', invert=False, max_frag=True)
+    'A.B>>C'
+    """
+    # Ensure max_frag implies wild_card
+    if max_frag:
+        wild_card = True
+
+    # Split into reactant and product
+    parts = rsmi.split(">>")
+    if len(parts) != 2:
+        raise ValueError("Reaction SMILES must contain exactly one '>>'.")
+    react, prod = parts
+
+    # Select side to process
+    side = react if invert else prod
+
+    processed = side
+    if wild_card:
+        frags = side.split(".")
+        # Filter out fragments containing wildcards
+        filtered = [frag for frag in frags if "*" not in frag]
+        if len(filtered) > 1:
+            # select the longest fragment
+            processed = max(filtered, key=len)
+        elif len(filtered) == 1:
+            processed = filtered[0]
+        # if no filtered fragments or single fragment, keep original side
+
+    # Reconstruct and return
+    if invert:
+        return f"{processed}>>{prod}"
+    return f"{react}>>{processed}"
+
+
+class RadicalWildcardAdder:
+    """A utility for adding wildcard dummy atoms ([*]) to radical centers in
+    reaction SMILES, with unique incremental atom-map indices and correct
+    propagation into products.
+
+    Each reactive radical atom in the reactant block is identified by its unpaired electron count,
+    assigned one or more wildcard map indices, and recorded. The same wildcard(s) are then appended
+    to the corresponding atom(s) in the product block, ensuring consistent mapping.
+
+    :param start_map: If provided, this integer will be the first atom-map index
+                      used for wildcard dummy atoms; subsequent radicals get incremented indices.
+                      If None, the next unused index is auto-determined from the input SMILES.
+    :type start_map: Optional[int]
+
+    .. rubric:: Example
+
+    >>> adder = RadicalWildcardAdder(start_map=8)
+    >>> rxn = "[C:2][OH:4].[O:6][H:7]>>[C:2][O:6].[OH:4][H:7]"
+    >>> print(adder.transform(rxn))
+    [C:2]([OH:4])[*:8].[O:6]([H:7])[*:9]>>[C:2]([O:6][*:9])[*:8].[OH:4][H:7]
+    """
+
+    def __init__(self, start_map: Optional[int] = None) -> None:
+        """Initialize the adder with an optional starting map index.
+
+        :param start_map: Starting atom-map index for wildcards or None
+            to auto-pick.
+        :type start_map: Optional[int]
+        """
+        self.start_map = start_map
+
+    def __repr__(self) -> str:
+        """Official representation."""
+        return f"<RadicalWildcardAdder(start_map={self.start_map})>"
+
+    def __str__(self) -> str:
+        """User-friendly description."""
+        m = self.start_map if self.start_map is not None else "auto"
+        return f"RadicalWildcardAdder(start_map={m})"
+
+    def transform(self, rxn_smiles: str) -> str:
+        """Append wildcard dummy atoms to each radical center in the reactant
+        block and propagate the same wildcards to the matching atoms in the
+        product block.
+
+        :param rxn_smiles: Reaction SMILES string, two-component or
+            three-component.
+        :type rxn_smiles: str
+        :return: Modified reaction SMILES with consistent wildcard
+            attachments.
+        :rtype: str
+        :raises ValueError: If the SMILES is not valid or fragments fail
+            to parse.
+        """
+        # Split into reactants > agents? > products
+        react_blk, agents_blk, prod_blk = self._split_reaction(rxn_smiles)
+
+        # Determine first wildcard map index
+        existing = [int(n) for n in re.findall(r":(\d+)", rxn_smiles)]
+        next_map = (
+            self.start_map
+            if self.start_map is not None
+            else max(existing, default=0) + 1
+        )
+
+        # Record mapping: original atom-map -> list of wildcard_maps
+        wildcard_map_for: Dict[int, List[int]] = {}
+
+        # Build sanitizeOps mask (skip H-adjustment)
+        keep_ops = SanitizeFlags.SANITIZE_ADJUSTHS
+
+        # Process one block (helper)
+        def _process(frags: List[str], propagate: bool) -> List[str]:
+            nonlocal next_map
+            out = []
+            for smi in frags:
+                if not smi:
+                    continue
+                # Load unsanitized then re-sanitize to preserve explicit H
+                # mol = Chem.MolFromSmiles(smi, sanitize=False)
+                # if mol is None:
+                #     raise ValueError(f"Cannot parse SMILES fragment: {smi}")
+                # Chem.SanitizeMol(mol, sanitizeOps=keep_ops)
+                mol = Chem.MolFromSmiles(smi, sanitize=False)
+                Chem.SanitizeMol(mol)
+                rw = Chem.RWMol(mol)
+
+                atoms = list(rw.GetAtoms())
+                changed = False
+
+                for atom in atoms:
+                    rad = atom.GetNumRadicalElectrons()
+                    orig_map = atom.GetAtomMapNum()
+                    if rad > 0:
+                        # Initialize list for this orig_map
+                        if propagate and orig_map not in wildcard_map_for:
+                            wildcard_map_for[orig_map] = []
+                        # For each unpaired electron, attach a wildcard
+                        for _ in range(rad):
+                            if propagate:
+                                wm = next_map
+                                wildcard_map_for[orig_map].append(wm)
+                                next_map += 1
+                            else:
+                                # in products, use already-recorded wm sequentially
+                                wm_list = wildcard_map_for.get(orig_map, [])
+                                if not wm_list:
+                                    continue
+                                wm = wm_list.pop(0)
+                            # add dummy wildcard
+                            dummy = Chem.Atom(0)
+                            dummy.SetAtomMapNum(wm)
+                            dummy.SetNoImplicit(True)
+                            rw.AddAtom(dummy)
+                            rw.AddBond(
+                                atom.GetIdx(),
+                                rw.GetNumAtoms() - 1,
+                                Chem.BondType.SINGLE,
+                            )
+                            changed = True
+
+                if changed:
+                    Chem.SanitizeMol(rw.GetMol(), sanitizeOps=keep_ops)
+
+                out.append(
+                    Chem.MolToSmiles(
+                        rw.GetMol(), isomericSmiles=True, allHsExplicit=True
+                    )
+                )
+            return out
+
+        react_frags = react_blk.split(".") if react_blk else []
+        new_reacts = _process(react_frags, propagate=True)
+
+        prod_frags = prod_blk.split(".") if prod_blk else []
+        new_prods = _process(prod_frags, propagate=False)
+
+        react_str = ".".join(new_reacts)
+        prod_str = ".".join(new_prods)
+        if agents_blk is None:
+            return f"{react_str}>>{prod_str}"
+        return f"{react_str}>{agents_blk}>{prod_str}"
+
+    @staticmethod
+    def _split_reaction(rxn: str) -> Tuple[str, Optional[str], str]:
+        """Split a reaction SMILES into reactants, agents (optional), and
+        products.
+
+        :param rxn: The reaction SMILES string.
+        :type rxn: str
+        :return: Tuple of (reactants_block, agents_block or None,
+            products_block).
+        :rtype: Tuple[str, Optional[str], str]
+        :raises ValueError: If the SMILES does not contain 2 or 3 '>'
+            symbols.
+        """
+        parts = rxn.split(">")
+        if len(parts) == 2:
+            return parts[0], None, parts[1]
+        if len(parts) == 3:
+            return parts[0], parts[1], parts[2]
+        raise ValueError("Reaction SMILES must contain 2 or 3 '>' symbols")

synkit/Chem/Reaction/standardize.py

@@ -0,0 +1,203 @@
+from typing import List, Optional, Tuple
+from rdkit import Chem
+
+
+class Standardize:
+    """Utilities to normalize and filter reaction and molecule SMILES.
+
+    This class provides methods to remove atom‑mapping, filter invalid molecules,
+    canonicalize reaction SMILES, and a full pipeline via `fit`.
+
+    :ivar None: Stateless helper class.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the Standardize helper.
+
+        No instance attributes are set.
+        """
+        pass
+
+    @staticmethod
+    def remove_atom_mapping(reaction_smiles: str, symbol: str = ">>") -> str:
+        """Remove atom‑map numbers from a reaction SMILES string.
+
+        :param reaction_smiles: Reaction SMILES with atom maps, e.g.
+            'C[CH3:1]>>C'.
+        :type reaction_smiles: str
+        :param symbol: Separator between reactants and products.
+            Defaults to '>>'.
+        :type symbol: str
+        :return: Reaction SMILES without atom‑mapping annotations.
+        :rtype: str
+        :raises ValueError: If the input format is invalid or contains
+            invalid SMILES.
+        """
+        parts = reaction_smiles.split(symbol)
+        if len(parts) != 2:
+            raise ValueError(
+                "Invalid reaction SMILES format. Expected 'reactants>>products'."
+            )
+
+        def clean_smiles(smi: str) -> str:
+            mol = Chem.MolFromSmiles(smi)
+            if mol is None:
+                raise ValueError(f"Invalid SMILES string: {smi}")
+            for atom in mol.GetAtoms():
+                atom.SetAtomMapNum(0)
+            return Chem.MolToSmiles(mol, canonical=True)
+
+        react, prod = map(clean_smiles, parts)
+        return f"{react}{symbol}{prod}"
+
+    @staticmethod
+    def filter_valid_molecules(smiles_list: List[str]) -> List[Chem.Mol]:
+        """Filter and sanitize a list of SMILES, returning only valid Mol
+        objects.
+
+        :param smiles_list: List of SMILES strings to validate.
+        :type smiles_list: List[str]
+        :return: List of sanitized RDKit Mol objects.
+        :rtype: List[rdkit.Chem.Mol]
+        """
+        valid: List[Chem.Mol] = []
+        for smi in smiles_list:
+            mol = Chem.MolFromSmiles(smi, sanitize=False)
+            if mol:
+                try:
+                    Chem.SanitizeMol(mol)
+                    valid.append(mol)
+                except Exception:
+                    continue
+        return valid
+
+    @staticmethod
+    def _parse_molecule_fragments(
+        smiles_list: List[str],
+    ) -> Tuple[List[Chem.Mol], bool]:
+        """Parse and sanitize SMILES fragments.
+
+        :param smiles_list: List of SMILES strings to validate.
+        :type smiles_list: List[str]
+        :return: Tuple of valid molecules and whether any fragment was invalid.
+        :rtype: Tuple[List[rdkit.Chem.Mol], bool]
+        """
+        valid: List[Chem.Mol] = []
+        had_invalid = False
+        for smi in smiles_list:
+            mol = Chem.MolFromSmiles(smi, sanitize=False)
+            if mol:
+                try:
+                    Chem.SanitizeMol(mol)
+                    valid.append(mol)
+                except Exception:
+                    had_invalid = True
+            else:
+                had_invalid = True
+        return valid, had_invalid
+
+    @staticmethod
+    def standardize_rsmi(
+        rsmi: str, stereo: bool = False, remove_invalid: bool = True
+    ) -> Optional[str]:
+        """Normalize a reaction SMILES: validate molecules, sort fragments, optionally keep stereo.
+
+        :param rsmi: Reaction SMILES in 'reactants>>products' format.
+        :type rsmi: str
+        :param stereo: If True, include stereochemistry in the output. Defaults to False.
+        :type stereo: bool
+        :param remove_invalid: If True, drop invalid fragments and standardize
+            remaining molecules. If False, return None when any invalid fragment
+            exists. Defaults to True.
+        :type remove_invalid: bool
+        :return: Standardized reaction SMILES or None if no valid molecules remain.
+        :rtype: Optional[str]
+        :raises ValueError: If the input format is invalid.
+        """
+        try:
+            react_str, prod_str = rsmi.split(">>")
+        except ValueError:
+            raise ValueError(
+                "Invalid reaction SMILES format. Expected 'reactants>>products'."
+            )
+
+        react_mols, react_invalid = Standardize._parse_molecule_fragments(
+            react_str.split(".")
+        )
+        prod_mols, prod_invalid = Standardize._parse_molecule_fragments(
+            prod_str.split(".")
+        )
+
+        if not remove_invalid and (react_invalid or prod_invalid):
+            return None
+
+        if not react_mols or not prod_mols:
+            return None
+
+        sorted_react = ".".join(
+            sorted(Chem.MolToSmiles(m, isomericSmiles=stereo) for m in react_mols)
+        )
+        sorted_prod = ".".join(
+            sorted(Chem.MolToSmiles(m, isomericSmiles=stereo) for m in prod_mols)
+        )
+
+        return f"{sorted_react}>>{sorted_prod}"
+
+    def fit(
+        self,
+        rsmi: str,
+        remove_aam: bool = True,
+        ignore_stereo: bool = True,
+        remove_invalid: bool = True,
+    ) -> Optional[str]:
+        """Full standardization pipeline: strip atom‑mapping, normalize SMILES, fix hydrogen notation.
+
+        :param rsmi: Reaction SMILES to process.
+        :type rsmi: str
+        :param remove_aam: If True, remove atom‑mapping annotations. Defaults to True.
+        :type remove_aam: bool
+        :param ignore_stereo: If True, drop stereochemistry. Defaults to True.
+        :type ignore_stereo: bool
+        :param remove_invalid: If True, drop invalid fragments and standardize
+            remaining molecules. If False, return None when any invalid fragment
+            exists. Defaults to True.
+        :type remove_invalid: bool
+        :return: The standardized reaction SMILES, or None if standardization fails.
+        :rtype: Optional[str]
+        """
+        std = self.standardize_rsmi(
+            rsmi, stereo=not ignore_stereo, remove_invalid=remove_invalid
+        )
+        if std is None:
+            return None
+
+        if remove_aam:
+            std = self.remove_atom_mapping(std)
+
+        # Format any double‑hydrogen notation
+        return std.replace("[HH]", "[H][H]")
+
+    @staticmethod
+    def categorize_reactions(
+        reactions: List[str], target_reaction: str
+    ) -> Tuple[List[str], List[str]]:
+        """Partition reactions into those matching a target and those not.
+
+        :param reactions: List of reaction SMILES to categorize.
+        :type reactions: List[str]
+        :param target_reaction: Benchmark reaction SMILES for comparison.
+        :type target_reaction: str
+        :return: Tuple of (matches, non_matches):
+                  - matches: reactions equal to standardized target
+                  - non_matches: all others
+        :rtype: Tuple[List[str], List[str]]
+        """
+        tgt = Standardize.standardize_rsmi(target_reaction, stereo=False)
+        matches: List[str] = []
+        non_matches: List[str] = []
+        for rxn in reactions:
+            if rxn == tgt:
+                matches.append(rxn)
+            else:
+                non_matches.append(rxn)
+        return matches, non_matches