synkit 1.6.5__py3-none-win_amd64.whl

synkit/Synthesis/Reactor/workflow/batch.py

@@ -0,0 +1,550 @@
+import logging
+import weakref
+from typing import Any, Dict, Iterable, List, Optional, Union
+
+import networkx as nx
+from joblib import Parallel, delayed
+
+from synkit.IO import smiles_to_graph, rsmi_to_its
+from .rule_filter import RuleFilter
+from ..core.engine import SynReactor
+
+__all__ = ["BatchReactor"]
+
+_UNSUPPORTED_CACHE_VALUE = object()
+
+
+def _freeze_cache_value(value: Any, active: set[int] | None = None) -> Any:
+    """Return an exact hashable value, or a sentinel for unsupported state."""
+    value_type = type(value)
+    if value_type in {str, int, float, bool, bytes, type(None)}:
+        return value_type, value
+    if active is None:
+        active = set()
+    value_id = id(value)
+    if value_id in active:
+        return _UNSUPPORTED_CACHE_VALUE
+    active.add(value_id)
+    try:
+        if isinstance(value, dict):
+            records = []
+            for key, item in value.items():
+                frozen_key = _freeze_cache_value(key, active)
+                frozen_item = _freeze_cache_value(item, active)
+                if (
+                    frozen_key is _UNSUPPORTED_CACHE_VALUE
+                    or frozen_item is _UNSUPPORTED_CACHE_VALUE
+                ):
+                    return _UNSUPPORTED_CACHE_VALUE
+                records.append((frozen_key, frozen_item))
+            return dict, frozenset(records)
+        if isinstance(value, list):
+            records = tuple(_freeze_cache_value(item, active) for item in value)
+            return (
+                _UNSUPPORTED_CACHE_VALUE
+                if _UNSUPPORTED_CACHE_VALUE in records
+                else (list, records)
+            )
+        if isinstance(value, tuple):
+            records = tuple(_freeze_cache_value(item, active) for item in value)
+            return (
+                _UNSUPPORTED_CACHE_VALUE
+                if _UNSUPPORTED_CACHE_VALUE in records
+                else (tuple, records)
+            )
+        if isinstance(value, (set, frozenset)):
+            records = tuple(_freeze_cache_value(item, active) for item in value)
+            return (
+                _UNSUPPORTED_CACHE_VALUE
+                if _UNSUPPORTED_CACHE_VALUE in records
+                else (value_type, frozenset(records))
+            )
+        # A lossy repr or identity token could conflate states after object-id
+        # reuse. Failing open preserves correctness for third-party objects.
+        return _UNSUPPORTED_CACHE_VALUE
+    finally:
+        active.remove(value_id)
+
+
+def _graph_cache_state(graph: nx.Graph) -> Any:
+    """Capture exact graph topology and supported attribute state."""
+    graph_attrs = _freeze_cache_value(graph.graph)
+    node_records = []
+    for node, attrs in graph.nodes(data=True):
+        frozen_node = _freeze_cache_value(node)
+        frozen_attrs = _freeze_cache_value(attrs)
+        if (
+            frozen_node is _UNSUPPORTED_CACHE_VALUE
+            or frozen_attrs is _UNSUPPORTED_CACHE_VALUE
+        ):
+            return _UNSUPPORTED_CACHE_VALUE
+        node_records.append((frozen_node, frozen_attrs))
+
+    edge_records = []
+    edges = (
+        graph.edges(keys=True, data=True)
+        if graph.is_multigraph()
+        else (
+            (left, right, None, attrs) for left, right, attrs in graph.edges(data=True)
+        )
+    )
+    for left, right, key, attrs in edges:
+        frozen = tuple(
+            _freeze_cache_value(value) for value in (left, right, key, attrs)
+        )
+        if _UNSUPPORTED_CACHE_VALUE in frozen:
+            return _UNSUPPORTED_CACHE_VALUE
+        edge_records.append(frozen)
+    if graph_attrs is _UNSUPPORTED_CACHE_VALUE:
+        return _UNSUPPORTED_CACHE_VALUE
+    return (
+        type(graph),
+        graph_attrs,
+        frozenset(node_records),
+        frozenset(edge_records),
+    )
+
+
+# =============================================================================
+# Low-level rule application
+# =============================================================================
+
+
+def _apply_rule_raw(
+    substrate: nx.Graph,
+    rule: nx.Graph,
+    invert: bool,
+    *,
+    strategy: str,
+    explicit_h: bool,
+    implicit_temp: bool,
+) -> List[str]:
+    """Apply one rule graph to a substrate graph using SynReactor.
+
+    :param substrate: Graph representing the substrate molecule.
+    :type substrate: networkx.Graph
+    :param rule: Graph representing the reaction rule (ITS template).
+    :type rule: networkx.Graph
+    :param invert: Whether to apply the rule in reverse.
+    :type invert: bool
+    :param strategy: Matching strategy passed to SynReactor.
+    :type strategy: str
+    :param explicit_h: Use explicit hydrogens in SynReactor.
+    :type explicit_h: bool
+    :param implicit_temp: Use implicit templates in SynReactor.
+    :type implicit_temp: bool
+    :return: A list of product SMARTS strings or reaction SMILES.
+    :rtype: list of str
+    """
+    try:
+        reactor = SynReactor(
+            substrate=substrate,
+            template=rule,
+            invert=invert,
+            strategy=strategy,
+            explicit_h=explicit_h,
+            implicit_temp=implicit_temp,
+        )
+        return list(getattr(reactor, "smarts_list", getattr(reactor, "smarts", [])))
+
+    except Exception as exc:  # pragma: no cover
+        logging.getLogger(__name__).debug(
+            "SynReactor failed (invert=%s): %s", invert, exc
+        )
+        return []
+
+
+# =============================================================================
+# Picklable rule-applier with small FIFO cache
+# =============================================================================
+
+
+class _RuleApplier:
+    """
+    Callable wrapper around `_apply_rule_raw` with a FIFO cache.
+
+    Entries are indexed by object identity and validated against exact graph
+    snapshots before reuse, so graph mutation and Python id reuse cannot
+    produce stale results.
+    """
+
+    __slots__ = (
+        "_strategy",
+        "_explicit_h",
+        "_implicit_temp",
+        "_cache",
+        "_cache_max",
+    )
+
+    def __init__(
+        self,
+        *,
+        strategy: str,
+        explicit_h: bool,
+        implicit_temp: bool,
+        cache_enabled: bool,
+        cache_maxsize: int,
+    ) -> None:
+        """
+        Initialize the rule applier.
+
+        :param strategy: Matching strategy for SynReactor.
+        :param explicit_h: Pass explicit hydrogens to SynReactor.
+        :param implicit_temp: Pass implicit template flag to SynReactor.
+        :param cache_enabled: Whether to enable in-process caching.
+        :param cache_maxsize: Maximum cache entries before eviction.
+        """
+        self._strategy = strategy
+        self._explicit_h = explicit_h
+        self._implicit_temp = implicit_temp
+        self._cache = (  # type: ignore[var-annotated]
+            {} if cache_enabled and cache_maxsize > 0 else None
+        )
+        self._cache_max = max(0, int(cache_maxsize))
+
+    def _execute(
+        self,
+        substrate: nx.Graph,
+        rule: nx.Graph,
+        inv: bool,
+    ) -> List[str]:
+        """Directly call `_apply_rule_raw` without caching."""
+        return _apply_rule_raw(
+            substrate,
+            rule,
+            inv,
+            strategy=self._strategy,
+            explicit_h=self._explicit_h,
+            implicit_temp=self._implicit_temp,
+        )
+
+    def __call__(
+        self,
+        substrate: nx.Graph,
+        rule: nx.Graph,
+        inv: bool,
+    ) -> List[str]:
+        """Apply a rule to a substrate, using the cache if enabled.
+
+        :param substrate: Substrate graph.
+        :param rule: Rule graph.
+        :param inv: Inversion flag.
+        :return: List of reaction outputs.
+        """
+        if self._cache is None:
+            return self._execute(substrate, rule, inv)
+
+        key = (id(substrate), id(rule), inv)
+        entry = self._cache.get(key)
+        substrate_state = _graph_cache_state(substrate)
+        rule_state = _graph_cache_state(rule)
+        cacheable = (
+            substrate_state is not _UNSUPPORTED_CACHE_VALUE
+            and rule_state is not _UNSUPPORTED_CACHE_VALUE
+        )
+        if entry is not None and cacheable:
+            substrate_ref, rule_ref, old_substrate_state, old_rule_state, result = entry
+            if (
+                substrate_ref() is substrate
+                and rule_ref() is rule
+                and old_substrate_state == substrate_state
+                and old_rule_state == rule_state
+            ):
+                return list(result)
+
+        res = self._execute(substrate, rule, inv)
+        if not cacheable:
+            return res
+        if len(self._cache) >= self._cache_max:
+            self._cache.pop(next(iter(self._cache)))  # FIFO eviction
+        self._cache[key] = (
+            weakref.ref(substrate),
+            weakref.ref(rule),
+            substrate_state,
+            rule_state,
+            tuple(res),
+        )
+        return res
+
+
+# =============================================================================
+# Helper utilities
+# =============================================================================
+
+
+def _dedupe(items: Iterable[Any]) -> List[Any]:
+    """Remove duplicates while preserving order."""
+    seen: set[Any] = set()
+    out: List[Any] = []
+    for x in items:
+        if x not in seen:
+            seen.add(x)
+            out.append(x)
+    return out
+
+
+# =============================================================================
+# Public API
+# =============================================================================
+
+
+class BatchReactor:
+    """
+    Parallel, cache-aware batch application of reaction rules to SMILES substrates.
+
+    :param data: List of SMILES strings or dicts containing SMILES under `host_key`.
+    :type data: list of str or dict
+    :param host_key: Key to extract SMILES from dict entries (optional).
+    :type host_key: str or None
+    :param pre_filter_engine: Pre-filtering engine for rules (None to skip).
+    :type pre_filter_engine: str or None
+    :param explicit_h: Use explicit hydrogens in SynReactor.
+    :type explicit_h: bool
+    :param implicit_temp: Use implicit templates in SynReactor.
+    :type implicit_temp: bool
+    :param strategy: Matching strategy for SynReactor.
+    :type strategy: str
+    :param dedupe: Deduplicate results per-substrate.
+    :type dedupe: bool
+    :param entry_n_jobs: Number of parallel jobs for substrates.
+    :type entry_n_jobs: int
+    :param rule_n_jobs: Number of parallel jobs for rules per substrate.
+    :type rule_n_jobs: int
+    :param parallel_rules: Enable parallelism over rules.
+    :type parallel_rules: bool
+    :param allow_nested: Allow nested parallelism.
+    :type allow_nested: bool
+    :param cache_enabled: Enable in-process per-rule caching.
+    :type cache_enabled: bool
+    :param cache_maxsize: Max entries in per-process cache.
+    :type cache_maxsize: int
+    :param logger: Optional custom logger.
+    :type logger: logging.Logger or None
+
+    :raises ValueError: If SMILES/rule conversion fails.
+    """
+
+    def __init__(
+        self,
+        data: List[Union[str, Dict[str, Any]]],
+        host_key: Optional[str] = None,
+        *,
+        pre_filter_engine: Optional[str] = None,
+        explicit_h: bool = True,
+        implicit_temp: bool = False,
+        strategy: str = "bt",
+        dedupe: bool = True,
+        entry_n_jobs: int = 1,
+        rule_n_jobs: int = 1,
+        parallel_rules: bool = False,
+        allow_nested: bool = False,
+        cache_enabled: bool = True,
+        cache_maxsize: int = 32768,
+        logger: Optional[logging.Logger] = None,
+        enable_logging: bool = True,
+    ) -> None:
+        """
+        Initialize the BatchReactor.
+
+        See class docstring for parameter details.
+        """
+        self._data = list(data)
+        self._host_key = host_key
+        self._engine = "syn"
+        self._pre_filter = pre_filter_engine.lower() if pre_filter_engine else None
+        self._explicit_h = explicit_h
+        self._implicit_temp = implicit_temp
+        self._strategy = strategy
+        self._dedupe = dedupe
+        self._entry_jobs = max(1, entry_n_jobs)
+        self._rule_jobs = max(1, rule_n_jobs)
+        self._parallel_rules = parallel_rules
+        self._allow_nested = allow_nested
+        self._log = logger or logging.getLogger(__name__)
+        if enable_logging is False:
+            logging.disable(logging.CRITICAL)
+
+        self._apply_rule = _RuleApplier(
+            strategy=strategy,
+            explicit_h=explicit_h,
+            implicit_temp=implicit_temp,
+            cache_enabled=cache_enabled,
+            cache_maxsize=cache_maxsize,
+        )
+
+    def help(self) -> str:
+        """Return usage examples and API description.
+
+        :return: Multi-line help text.
+        :rtype: str
+        """
+        return (
+            "BatchReactor(data, host_key=None, pre_filter_engine=None, "
+            "explicit_h=True, implicit_temp=False, strategy='bt', dedupe=True, "
+            "entry_n_jobs=1, rule_n_jobs=1, parallel_rules=False, allow_nested=False, "
+            "cache_enabled=True, cache_maxsize=32768, logger=None)" + "\n"
+            "Use .fit(rules, invert=False) to apply reaction rules to the SMILES batch."
+        )
+
+    def describe(self) -> str:
+        """Return a configuration summary.
+
+        :return: Human-readable settings overview.
+        :rtype: str
+        """
+        lines = [
+            "BatchReactor configuration:",
+            f"  entries         : {len(self._data)}",
+            f"  engine          : {self._engine}",
+            f"  pre_filter      : {self._pre_filter}",
+            f"  explicit_h      : {self._explicit_h}",
+            f"  implicit_temp   : {self._implicit_temp}",
+            f"  strategy        : {self._strategy}",
+            f"  dedupe          : {self._dedupe}",
+            f"  entry_n_jobs    : {self._entry_jobs}",
+            f"  rule_n_jobs     : {self._rule_jobs}",
+            f"  parallel_rules  : {self._parallel_rules}",
+            f"  allow_nested    : {self._allow_nested}",
+            f"  cache_enabled   : {self._apply_rule._cache is not None}",
+            f"  cache_maxsize   : {self._apply_rule._cache_max}",
+        ]
+        return "\n".join(lines)
+
+    def __len__(self) -> int:
+        """Return the number of substrates in the batch."""
+        return len(self._data)
+
+    def __iter__(self):
+        """Yield each entry from the batch data."""
+        yield from self._data
+
+    def __getitem__(self, idx: int) -> Union[str, Dict[str, Any]]:
+        """Get the data entry at index `idx`."""
+        return self._data[idx]
+
+    def __repr__(self) -> str:
+        """Concise summary of the BatchReactor instance."""
+        return (
+            f"<BatchReactor entries={len(self._data)} engine={self._engine} "
+            f"pre_filter={self._pre_filter} entry_jobs={self._entry_jobs} "
+            f"rule_jobs={self._rule_jobs} parallel_rules={self._parallel_rules}>"
+        )
+
+    def fit(
+        self,
+        rules: Iterable[Any],
+        *,
+        invert: bool = False,
+    ) -> List[Dict[str, Any]]:
+        """Apply reaction rules to each substrate in the batch.
+
+        :param rules: Iterable of rule graphs or SMILES strings.
+        :type rules: iterable
+        :param invert: Whether to apply rules in reverse direction.
+        :type invert: bool
+        :return: A list of dicts, each with:
+            - "out": list of product SMARTS/reaction SMILES
+            - "count": number of outputs
+        :rtype: list of dict
+        """
+        rule_graphs = self._ensure_graph_rules(rules)
+        direction = "bw" if invert else "fw"
+
+        def worker(entry: Union[str, Dict[str, Any]]) -> Dict[str, Any]:
+            g = self._to_graph(entry)
+            filtered = (
+                RuleFilter(g, rule_graphs, invert=invert, engine=self._pre_filter).new_rules  # type: ignore[arg-type]
+                if self._pre_filter
+                else rule_graphs
+            )
+            out = self._apply_bulk(g, filtered, invert)
+            return {f"{self._engine}_{direction}": out, "count": len(out)}
+
+        if self._entry_jobs == 1:
+            return [worker(e) for e in self._data]
+
+        return Parallel(
+            n_jobs=self._entry_jobs,
+            backend="loky",
+            prefer="processes",
+        )(delayed(worker)(e) for e in self._data)
+
+    # ------------------------------------------------------------------
+    # Additional helpers
+    # ------------------------------------------------------------------
+
+    def _to_graph(self, entry: Union[str, Dict[str, Any]]) -> nx.Graph:
+        """Convert a SMILES string or dict entry into a networkx Graph.
+
+        :param entry: SMILES or dict holding SMILES under host_key.
+        :type entry: str or dict
+        :return: Molecule graph.
+        :rtype: networkx.Graph
+        :raises KeyError: if host_key is missing for dict.
+        :raises TypeError: if entry is not str or dict.
+        :raises ValueError: if SMILES conversion fails.
+        """
+        if isinstance(entry, dict):
+            if self._host_key is None:
+                raise KeyError("host_key missing for dict entry")
+            entry = entry[self._host_key]
+        if not isinstance(entry, str):
+            raise TypeError("Each entry must be a SMILES string or dict containing one")
+        g = smiles_to_graph(entry, drop_non_aam=False, use_index_as_atom_map=False)
+        if g is None:
+            raise ValueError(f"Invalid SMILES: {entry}")
+        return g
+
+    @staticmethod
+    def _ensure_graph_rules(rules: Iterable[Any]) -> List[nx.Graph]:
+        """Convert an iterable of SMILES or graph rules into graph objects.
+
+        :param rules: Iterable of rule SMILES or networkx.Graph.
+        :type rules: iterable
+        :return: List of rule graphs.
+        :rtype: list of networkx.Graph
+        :raises ValueError: if a rule SMILES is invalid.
+        :raises TypeError: for unsupported rule types.
+        """
+        out: List[nx.Graph] = []
+        for r in rules:
+            if isinstance(r, str):
+                g = rsmi_to_its(r, core=True)
+                if g is None:
+                    raise ValueError(f"Invalid rule SMILES: {r}")
+                out.append(g)
+            elif isinstance(r, nx.Graph):
+                out.append(r)
+            else:
+                raise TypeError("Rules must be str or nx.Graph")
+        return out
+
+    def _apply_bulk(
+        self, g: nx.Graph, rules: List[nx.Graph], invert: bool
+    ) -> List[str]:
+        """Apply a list of rule graphs to a substrate graph.
+
+        :param g: Substrate graph.
+        :type g: networkx.Graph
+        :param rules: List of rule graphs.
+        :type rules: list of networkx.Graph
+        :param invert: Direction flag.
+        :type invert: bool
+        :return: Flattened list of reaction outputs.
+        :rtype: list of str
+        """
+        jobs = 1
+        if (
+            self._parallel_rules
+            and self._rule_jobs > 1
+            and (self._allow_nested or self._entry_jobs == 1)
+        ):
+            jobs = self._rule_jobs
+        if jobs == 1:
+            nested = [self._apply_rule(g, r, invert) for r in rules]
+        else:
+            nested = Parallel(n_jobs=jobs, backend="loky", prefer="processes")(
+                delayed(self._apply_rule)(g, r, invert) for r in rules
+            )
+        flat = [x for sub in nested for x in sub]
+        return _dedupe(flat) if self._dedupe else flat

synkit/Synthesis/Reactor/workflow/benchmark.py

@@ -0,0 +1,143 @@
+import logging
+from typing import Any, Dict, Iterable, List, Optional
+from .batch import BatchReactor
+
+# =============================================================================
+# Benchmark subclass
+# =============================================================================
+
+
+class Benchmark(BatchReactor):  # pylint: disable=too-many-arguments
+    """
+    Extension of BatchReactor to benchmark forward/backward application on reaction-SMILES entries.
+
+    :param data: List of dicts containing reaction SMILES under `reaction_key`.
+    :type data: list of dict
+    :param reaction_key: Key for reaction-SMILES strings (format 'reactants>>products').
+    :type reaction_key: str
+    :param pre_filter_engine: Pre-filtering engine for rules (None to skip).
+    :type pre_filter_engine: str or None
+    :param explicit_h: Use explicit hydrogens in SynReactor.
+    :type explicit_h: bool
+    :param implicit_temp: Use implicit templates in SynReactor.
+    :type implicit_temp: bool
+    :param strategy: Matching strategy for SynReactor.
+    :type strategy: str
+    :param dedupe: Deduplicate results per substrate.
+    :type dedupe: bool
+    :param entry_n_jobs: Parallel jobs for substrates.
+    :type entry_n_jobs: int
+    :param rule_n_jobs: Parallel jobs for rules per substrate.
+    :type rule_n_jobs: int
+    :param parallel_rules: Enable rule-level parallelism.
+    :type parallel_rules: bool
+    :param allow_nested: Allow nested parallelism.
+    :type allow_nested: bool
+    :param cache_enabled: Enable per-process caching.
+    :type cache_enabled: bool
+    :param cache_maxsize: Max cache entries before eviction.
+    :type cache_maxsize: int
+    :param logger: Optional custom logger.
+    :type logger: logging.Logger or None
+    :raises ValueError: If reaction_key entry malformed or SMILES invalid.
+    """
+
+    def __init__(
+        self,
+        data: List[Dict[str, Any]],
+        reaction_key: str = "reactions",
+        *,
+        pre_filter_engine: Optional[str] = None,
+        explicit_h: bool = True,
+        implicit_temp: bool = False,
+        strategy: str = "bt",
+        dedupe: bool = True,
+        entry_n_jobs: int = 1,
+        rule_n_jobs: int = 1,
+        parallel_rules: bool = False,
+        allow_nested: bool = False,
+        cache_enabled: bool = True,
+        cache_maxsize: int = 32768,
+        logger: Optional[logging.Logger] = None,
+        enable_logging: bool = True,
+    ) -> None:
+        """
+        Initialize Benchmark with reaction entries.
+
+        Splits each reaction-SMILES into reactant 'r' and product 'p'.
+        All other parameters mirror BatchReactor (host_key set to 'r').
+        """
+        data_prepped = self._get_host(data, reaction_key)
+        super().__init__(
+            data_prepped,
+            host_key="r",
+            pre_filter_engine=pre_filter_engine,
+            explicit_h=explicit_h,
+            implicit_temp=implicit_temp,
+            strategy=strategy,
+            dedupe=dedupe,
+            entry_n_jobs=entry_n_jobs,
+            rule_n_jobs=rule_n_jobs,
+            parallel_rules=parallel_rules,
+            allow_nested=allow_nested,
+            cache_enabled=cache_enabled,
+            cache_maxsize=cache_maxsize,
+            logger=logger,
+            enable_logging=enable_logging,
+        )
+
+    @staticmethod
+    def _get_host(
+        data: List[Dict[str, Any]], reaction_key: str = "reactions"
+    ) -> List[Dict[str, Any]]:
+        """Populate 'r' and 'p' SMILES fields for each dict entry.
+
+        :param data: List of dict entries.
+        :type data: list of dict
+        :param reaction_key: Key for reaction-SMILES string.
+        :type reaction_key: str
+        :return: Same list with 'r' and 'p' keys added.
+        :rtype: list of dict
+        :raises ValueError: If any string lacks '>>'.
+        """
+        for entry in data:
+            rxn = entry.get(reaction_key)
+            if not isinstance(rxn, str) or ">>" not in rxn:
+                raise ValueError(
+                    f"Invalid reaction string for key '{reaction_key}': {rxn!r}"
+                )
+            r, p = rxn.split(">>", 1)
+            entry["r"], entry["p"] = r, p
+        return data
+
+    def fit(
+        self,
+        rules: Iterable[Any],
+    ) -> List[Dict[str, Any]]:
+        """Perform forward (invert=False) on 'r' and backward (invert=True) on 'p'.
+
+        :param rules: Iterable of rule graphs or SMILES.
+        :type rules: iterable
+        :return: List of dicts each with keys 'fw','bw','fw_count','bw_count'.
+        :rtype: list of dict
+        """
+        fw_out = super().fit(rules, invert=False)
+        self._host_key = "p"
+        bw_out = super().fit(rules, invert=True)
+        self._host_key = "r"
+
+        for entry, fw, bw in zip(self._data, fw_out, bw_out):
+            entry["fw"] = fw.get(f"{self._engine}_fw", fw.get("out", fw))
+            entry["fw_count"] = fw.get("count", len(entry["fw"]))
+            entry["bw"] = bw.get(f"{self._engine}_bw", bw.get("out", bw))
+            entry["bw_count"] = bw.get("count", len(entry["bw"]))
+        return self._data
+
+    def describe(self) -> str:
+        """Return detailed configuration for Benchmark, including reaction_key.
+
+        :return: Multi-line summary.
+        :rtype: str
+        """
+        base = super().describe().splitlines()
+        return "".join(base + ["Benchmark host_key: 'r' (product host: 'p')"])