synkit 1.6.5__py3-none-win_amd64.whl

synkit/Synthesis/MSR/path_finder.py

@@ -0,0 +1,239 @@
+"""Route search over rounds of reaction SMILES for multi-step retrosynthesis.
+
+This is the *synthesis-planning* path finder: it consumes the round-structured
+reaction SMILES produced by an MSR expansion and searches molecule-to-molecule
+routes under a carbon-count constraint. It has no notion of stoichiometry,
+markings or reaction networks.
+
+For pathway search over a reaction *network* —
+:class:`~synkit.CRN.Structure.syncrn.SynCRN` incidence, reaction flows, and
+Petri-net realizability of a candidate route — use
+:class:`synkit.CRN.Pathway.pathfinder.PathwayFinder` instead. The two solve
+different problems and are not alternative implementations of one algorithm.
+"""
+
+import heapq
+from collections import deque
+from typing import List, Dict, Optional
+from synkit.Chem.utils import count_carbons
+
+
+class PathFinder:
+    """Search synthesis routes through rounds of reaction SMILES.
+
+    See the module docstring for how this relates to
+    :class:`synkit.CRN.Pathway.pathfinder.PathwayFinder`.
+    """
+
+    def __init__(
+        self,
+        reaction_rounds: List[Dict[str, List[str]]],
+    ):
+        """Initialize with a list of dictionaries, each representing a reaction
+        round, plus an optional random state for reproducible Monte Carlo
+        search.
+
+        :param reaction_rounds: A list where each dictionary
+                                contains the reaction SMILES strings for a given round
+                                (e.g. {"Round 1": [...] }).
+        :type reaction_rounds: List[Dict[str, List[str]]]
+        """
+        self.reaction_rounds = reaction_rounds
+
+        # Build adjacency structure:
+        # self._adjacency[round_idx] => { reactant_smiles: [(reaction_smiles, [products])] }
+        self._adjacency = []
+        for round_idx, round_dict in enumerate(self.reaction_rounds):
+            round_key = f"Round {round_idx + 1}"
+            reactions = round_dict.get(round_key, [])
+            adjacency_map = {}
+            for rxn in reactions:
+                reactants, products = rxn.split(">>")
+                reactant_list = reactants.split(".")
+                product_list = products.split(".")
+                for rct in reactant_list:
+                    adjacency_map.setdefault(rct, []).append((rxn, product_list))
+            self._adjacency.append(adjacency_map)
+
+    def _valid_intermediate(
+        self, smiles: str, input_smiles: str, target_smiles: str
+    ) -> bool:
+        """
+        Checks whether the given molecule satisfies the carbon_distance constraint:
+            n_C(input_smiles) <= n_C(smiles) <= n_C(target_smiles)
+        """
+        return (
+            count_carbons(input_smiles)
+            <= count_carbons(smiles)
+            <= count_carbons(target_smiles)
+        )
+
+    def search_paths(
+        self,
+        input_smiles: str,
+        target_smiles: str,
+        method: str = "bfs",
+        max_solutions: Optional[int] = None,
+        cheapest: bool = True,
+    ) -> List[List[str]]:
+        """Search for reaction pathways from the input molecule to the target
+        molecule using a specified method, optionally limiting the number of
+        solutions.
+
+        Additionally, `cheapest` can be set to True or False:
+          - If cheapest=True, BFS uses a visited set and A* prunes costlier routes (typical approach).
+          - If cheapest=False, BFS does *not* track visited states (returns more solutions),
+            and A* does *not* prune costlier routes (also returns more solutions).
+            (May lead to duplicates or many solutions if cycles exist.)
+
+        :param input_smiles: SMILES of the starting molecule.
+        :type input_smiles: str
+        :param target_smiles: SMILES of the target molecule.
+        :type target_smiles: str
+        :param method: 'bfs', 'astar', or 'mc'.
+        :type method: str, optional
+        :param max_solutions: If set, stop after finding this many solutions.
+        :type max_solutions: int, optional
+        :param cheapest: Controls pruning.
+                         Default True => standard BFS/A*; False => "unrestricted" BFS/A*.
+        :type cheapest: bool, optional
+
+        :return: Each solution path is a list of reaction SMILES from start to target.
+        :rtype: List[List[str]]
+        """
+        if method == "bfs":
+            return self._bfs(input_smiles, target_smiles, max_solutions, cheapest)
+        elif method == "astar":
+            return self._astar(input_smiles, target_smiles, max_solutions, cheapest)
+        else:
+            raise ValueError("Invalid method. Choose 'bfs', 'astar', or 'mc'.")
+
+    def _bfs(
+        self,
+        input_smiles: str,
+        target_smiles: str,
+        max_solutions: Optional[int],
+        cheapest: bool,
+    ) -> List[List[str]]:
+        """Perform a BFS search. If cheapest=True, use a visited set to avoid
+        re-processing the same (molecule, round_index). If cheapest=False, skip
+        that pruning and collect *all* possible solutions (potentially large if
+        cycles exist).
+
+        Returns a list of successful reaction pathways, up to
+        max_solutions if specified.
+        """
+
+        queue = deque([(input_smiles, [], 0)])
+        pathways = []
+        visited = set() if cheapest else None  # Only track visited if cheapest=True
+
+        while queue:
+            current_smiles, current_path, round_index = queue.popleft()
+            if round_index >= len(self._adjacency):
+                continue
+
+            # For BFS with cheapest=True, skip repeated states
+            if cheapest:
+                if (current_smiles, round_index) in visited:
+                    continue
+                visited.add((current_smiles, round_index))
+
+            adjacency_map = self._adjacency[round_index]
+            if current_smiles not in adjacency_map:
+                continue
+
+            for rxn_string, product_list in adjacency_map[current_smiles]:
+                updated_path = current_path + [rxn_string]
+                # If any product is the target, record a solution
+                if target_smiles in product_list:
+                    pathways.append(updated_path)
+                    if max_solutions is not None and len(pathways) >= max_solutions:
+                        return pathways
+                # Otherwise queue each valid product
+                for product in product_list:
+                    if self._valid_intermediate(product, input_smiles, target_smiles):
+                        queue.append((product, updated_path, round_index + 1))
+
+        return pathways
+
+    def _heuristic(self, smiles: str, target_smiles: str) -> int:
+        """Heuristic function for A* search.
+
+        Returns difference in SMILES lengths as a stand-in for
+        "distance."
+        """
+        return abs(len(smiles) - len(target_smiles))
+
+    def _astar(
+        self,
+        input_smiles: str,
+        target_smiles: str,
+        max_solutions: Optional[int],
+        cheapest: bool,
+    ) -> List[List[str]]:
+        """A* search. If cheapest=True, we track the best cost visited for each
+        state and prune costlier paths. If cheapest=False, we do not prune, so
+        we collect all solutions (but it may be large).
+
+        Returns a list of successful reaction pathways, up to
+        max_solutions if specified.
+        """
+        start_cost = self._heuristic(input_smiles, target_smiles)
+        # Heap stores (cost, current_smiles, current_path, round_index)
+        heap = [(start_cost, input_smiles, [], 0)]
+        pathways = []
+        visited_cost = {} if cheapest else None
+
+        while heap:
+            cost, current_smiles, current_path, round_index = heapq.heappop(heap)
+
+            if cheapest and visited_cost is not None:
+                # If we've seen this state with a cheaper or equal cost, skip
+                if (current_smiles, round_index) in visited_cost:
+                    if visited_cost[(current_smiles, round_index)] <= cost:
+                        continue
+                visited_cost[(current_smiles, round_index)] = cost
+
+            if round_index >= len(self._adjacency):
+                continue
+
+            adjacency_map = self._adjacency[round_index]
+            if current_smiles not in adjacency_map:
+                continue
+
+            for rxn_string, product_list in adjacency_map[current_smiles]:
+                updated_path = current_path + [rxn_string]
+
+                # If any product is the target, record a solution
+                if target_smiles in product_list:
+                    pathways.append(updated_path)
+                    if max_solutions is not None and len(pathways) >= max_solutions:
+                        return pathways
+                else:
+                    # Otherwise expand each product
+                    next_round = round_index + 1
+                    for product in product_list:
+                        if self._valid_intermediate(
+                            product, input_smiles, target_smiles
+                        ):
+                            new_cost = len(updated_path) + self._heuristic(
+                                product, target_smiles
+                            )
+                            if cheapest and visited_cost is not None:
+                                old_cost = visited_cost.get(
+                                    (product, next_round), float("inf")
+                                )
+                                # Only push if cheaper route
+                                if new_cost < old_cost:
+                                    heapq.heappush(
+                                        heap,
+                                        (new_cost, product, updated_path, next_round),
+                                    )
+                            else:
+                                # cheapest=False => always push
+                                heapq.heappush(
+                                    heap, (new_cost, product, updated_path, next_round)
+                                )
+
+        return pathways

synkit/Synthesis/Metrics/_base.py

@@ -0,0 +1,52 @@
+from typing import List, Dict
+from ._ranking import (
+    _novelty_rate,
+    _coverage,
+    _recognition_rate,
+    _top_k_accuracy,
+    _calculate_f_beta_score,
+)
+
+
+def _compute_metrics(
+    reactions_data: List[Dict[str, any]],
+    key_ground_truth: str,
+    key_prediction: str,
+    k: int = 5,
+    beta: float = 1,
+) -> Dict[str, float]:
+    """Computes the metrics for a list of reactions data.
+
+    :param reactions_data: List of dictionaries containing RSMI strings.
+    :type reactions_data: List[Dict[str, any]]
+    :param key_ground_truth: Key in the dictionary for the ground truth RSMI.
+    :type key_ground_truth: str
+    :param key_prediction: Key in the dictionary for the predicted RSMIs
+                           (list of predictions).
+    :type key_prediction: str
+    :param k: The number of top predictions to consider. Defaults to 5.
+    :type k: int, optional
+    :param beta: Beta parameter for the F-beta score. Defaults to 1.
+    :type beta: float, optional
+
+    :return: A dictionary with the metrics.
+    :rtype: Dict[str, float]
+    """
+    return {
+        "Novelty": _novelty_rate(reactions_data, key_ground_truth, key_prediction)
+        / 100,
+        "Coverage": _coverage(reactions_data, key_ground_truth, key_prediction) / 100,
+        "Recognition": _recognition_rate(
+            reactions_data, key_ground_truth, key_prediction
+        )
+        / 100,
+        f"Top_{k}_Accuracy": _top_k_accuracy(
+            reactions_data, key_ground_truth, key_prediction, k
+        )
+        / 100,
+        f"F{beta}_score": _calculate_f_beta_score(
+            _recognition_rate(reactions_data, key_ground_truth, key_prediction),
+            _coverage(reactions_data, key_ground_truth, key_prediction),
+            beta,
+        ),
+    }

synkit/Synthesis/Metrics/_plot.py

@@ -0,0 +1,129 @@
+import pandas as pd
+import matplotlib.pyplot as plt
+import seaborn as sns
+import matplotlib
+
+# Enable LaTeX rendering in Matplotlib
+matplotlib.rcParams["text.usetex"] = True
+matplotlib.rcParams["text.latex.preamble"] = r"\usepackage{amsmath}"
+
+
+def plot_recognition_coverage_curve(
+    data,
+    coverage_col="Coverage",
+    recognition_col="Recognition",
+    f2_score_col="F2_score",
+    figsize=(8, 6),
+    show_f2=True,
+    show_legend=True,
+):
+    """Plots a Recognition-Coverage curve using provided data, including
+    optional F2 scores annotated. Styled with Seaborn for enhanced visual
+    appearance.
+
+    :param data: Nested dictionary containing the data for each radii,
+                 formatted as shown in example.
+    :type data: dict
+    :param coverage_col: Key name for the coverage data in the dictionary.
+    :type coverage_col: str
+    :param recognition_col: Key name for the recognition data in the dictionary.
+    :type recognition_col: str
+    :param f2_score_col: Key name for the F2 score data in the dictionary.
+    :type f2_score_col: str
+    :param figsize: Figure size for the plot, default is (8, 6).
+    :type figsize: tuple
+    :param show_f2: Whether to show F2 scores on the curve, default is True.
+
+                    Example Data format:
+                    {'radii_0': {'Novelty': 96.44, 'Coverage': 93.98, 'Recognition': 3.55, ...}}
+    :type show_f2: bool
+    """
+    df = pd.DataFrame(data).T
+
+    sns.set_theme(style="whitegrid")
+
+    plt.figure(figsize=figsize)
+    ax = sns.lineplot(
+        data=df,
+        x=coverage_col,
+        y=recognition_col,
+        marker="o",
+        label="Recognition-Coverage Curve" if show_legend else None,
+    )
+
+    if show_f2:
+        for i, txt in enumerate(df[f2_score_col]):
+            ax.annotate(
+                r"$F_2=" + f"{txt:.2f}" + "$",
+                (df[coverage_col].iloc[i], df[recognition_col].iloc[i]),
+                textcoords="offset points",
+                xytext=(0, 10),
+                ha="center",
+            )
+
+    # Adding labels, title, and legend with LaTeX
+    plt.xlabel(r"$\mathrm{{Coverage\%}}$", fontsize=18)
+    plt.ylabel(r"$\mathrm{{Recognition\%}}$", fontsize=18)
+    plt.title(r"Recognition-Coverage Curve", fontsize=24)
+    plt.legend()
+    plt.grid(True)
+    plt.show()
+
+
+def plot_f2_scores_line(data, figsize=(8, 6), show_f2=True, show_legend=True):
+    """Plots F2 scores across different radii using a line plot, showing the
+    trend of F2 score changes, and annotated with optional F2 scores.
+
+    :param data: Dictionary containing nested dictionaries with 'F2_score'
+                 and possibly other metrics.
+    :type data: dict
+    :param figsize: Figure size for the plot, default is (8, 6).
+    :type figsize: tuple
+    :param show_f2: Whether to show F2 scores on the curve, default is True.
+    :type show_f2: bool
+    :param show_legend: Whether to show the legend on the plot, default is True.
+
+                        Example Data format:
+                        {'radii_0': {'Novelty': 96.44, 'Coverage': 93.98, 'Recognition': 3.55,
+                        'F2_score': 0.15}, ...}
+    :type show_legend: bool
+    """
+    # Convert the nested dictionary into a DataFrame and prepare for plotting
+    df = pd.DataFrame(data).T
+    df["Radii"] = [int(key.split("_")[1]) for key in data.keys()]
+    df.sort_values("Radii", inplace=True)  # Ensure data is sorted by radii
+
+    # Setting up Seaborn for enhanced plotting style
+    sns.set_theme(style="whitegrid")
+
+    # Create the plot
+    plt.figure(figsize=figsize)
+    sns.lineplot(
+        data=df,
+        x="Radii",
+        y="F2_score",
+        marker="o",
+        label="F2 Score Trend" if show_legend else None,
+    )
+
+    # Optionally annotate each point with its F2 score
+    if show_f2:
+        for i in range(len(df)):
+            plt.text(
+                df.iloc[i]["Radii"],
+                df.iloc[i]["F2_score"] + 0.01,
+                r"$F_2=" + f'{df.iloc[i]["F2_score"]:.2f}' + "$",
+                color="black",
+                ha="center",
+                va="bottom",
+            )
+
+    # Adding labels, title, and legend with LaTeX
+    plt.xlabel(r"$\text{Radii}$", fontsize=18)
+    plt.ylabel(r"$F_2\ \text{Score}$", fontsize=18)
+    plt.title(r"$F_2\ \text{Score}$ Across Different Radii", fontsize=24)
+    if show_legend:
+        plt.legend()
+
+    plt.grid(True)
+    plt.show()

synkit/Synthesis/Metrics/_ranking.py

@@ -0,0 +1,179 @@
+import statistics
+from typing import List, Dict
+
+
+def _coverage(
+    reactions_data: List[Dict[str, str]], key_ground_truth: str, key_prediction: str
+) -> float:
+    """Calculates the coverage percentage, which measures how many of the
+    predicted reactions exactly match the ground truth reactions given in a
+    list of dictionaries.
+
+    :param reactions_data: List of dictionaries containing
+                           reaction SMILES strings.
+    :type reactions_data: List[Dict[str, str]]
+    :param key_ground_truth: Key in the dictionary for the ground truth reaction SMILES.
+    :type key_ground_truth: str
+    :param key_prediction: Key in the dictionary for the predicted reaction SMILES.
+    :type key_prediction: str
+
+    :return: The coverage percentage.
+    :rtype: float
+    """
+    correct_matches = sum(
+        1
+        for reaction in reactions_data
+        if reaction.get(key_ground_truth) in reaction.get(key_prediction)
+    )
+    return (correct_matches / len(reactions_data)) * 100 if reactions_data else 0
+
+
+def _novelty_rate(
+    reactions_data: List[Dict[str, any]], key_ground_truth: str, key_prediction: str
+) -> float:
+    """Calculates the False Positive Rate (FPR) for each observation and then
+    averages these values across all observations. The FPR represents the
+    proportion of predictions that do not match the ground truth for each
+    individual entry in the dataset.
+
+    :param reactions_data: List of dictionaries containing
+                           the ground truth and predicted reactions, where predictions are given as
+                           a list of RSMIs.
+    :type reactions_data: List[Dict[str, any]]
+    :param key_ground_truth: Dictionary key to access the ground truth reaction RSMI.
+    :type key_ground_truth: str
+    :param key_prediction: Dictionary key to access the list of predicted reaction RSMIs.
+    :type key_prediction: str
+
+    :return: Average false-positive rate as a percentage.
+    :rtype: float
+    """
+    fpr_list = []  # List to store FPR for each observation
+
+    for entry in reactions_data:
+        ground_truth = entry.get(key_ground_truth)
+        predictions = entry.get(key_prediction, [])
+
+        if not predictions:  # Skip if no predictions
+            continue
+
+        # Calculate FPR for this entry
+        false_positives = sum(1 for pred in predictions if pred != ground_truth)
+        total_predictions = len(predictions)
+        fpr_list.append((false_positives / total_predictions) * 100)
+
+    # Calculate and return the mean FPR
+    return statistics.mean(fpr_list) if fpr_list else 0.0
+
+
+def _recognition_rate(
+    reactions_data: List[Dict[str, any]], key_ground_truth: str, key_prediction: str
+) -> float:
+    """Calculates the recognition rate for each observation and averages these
+    rates across all observations. The recognition rate measures the proportion
+    of the prediction list that matches the single ground truth reaction for
+    each entry.
+
+    :param reactions_data: List of dictionaries containing
+                           the ground truth
+                           and predicted reactions, where the ground truth is a single RSMI and predictions
+                           are lists of RSMIs.
+    :type reactions_data: List[Dict[str, any]]
+    :param key_ground_truth: Dictionary key to access the ground truth reaction RSMIs.
+    :type key_ground_truth: str
+    :param key_prediction: Dictionary key to access the list of predicted reaction RSMIs.
+    :type key_prediction: str
+
+    :return: Average recognition rate as a percentage.
+    :rtype: float
+    """
+    recognition_rates = []
+
+    for entry in reactions_data:
+        ground_truth = entry.get(key_ground_truth)
+        predictions = entry.get(key_prediction, [])
+
+        if predictions:
+
+            matches = sum(1 for pred in predictions if pred == ground_truth)
+
+            recognition_rate = (matches / len(predictions)) * 100
+            recognition_rates.append(recognition_rate)
+        else:
+            recognition_rates.append(0.0)
+
+    return statistics.mean(recognition_rates) if recognition_rates else 0.0
+
+
+def _top_k_accuracy(
+    reactions_data: List[Dict[str, any]],
+    key_ground_truth: str,
+    key_prediction: str,
+    k: int,
+) -> float:
+    """Calculates the Top-K accuracy by using the coverage function on the top
+    K predictions. This measures the probability that the true reaction is
+    within the top K predictions.
+
+    :param reactions_data: List of dictionaries containing
+                           RSMI strings.
+    :type reactions_data: List[Dict[str, any]]
+    :param key_ground_truth: Key in the dictionary for the ground truth RSMI.
+    :type key_ground_truth: str
+    :param key_prediction: Key in the dictionary for the predicted RSMIs
+                           (list of predictions).
+    :type key_prediction: str
+    :param k: The number of top predictions to consider.
+    :type k: int
+
+    :return: The Top-K accuracy percentage.
+    :rtype: float
+    """
+    modified_data = [
+        {**entry, "Top_K_Predictions": entry[key_prediction][:k]}
+        for entry in reactions_data
+    ]
+    return _coverage(modified_data, key_ground_truth, "Top_K_Predictions")
+
+
+def _calculate_f_beta_score(
+    recognition_rate: float,  # This serves as the precision
+    coverage_rate: float,  # This serves as the recall
+    beta: float = 1.0,  # Beta factor, default is 1.0 for F1 score
+) -> float:
+    """Computes the F-beta Score, which is a weighted harmonic mean of
+    recognition rate and coverage rate. The recognition rate (precision) and
+    coverage rate (recall) must be expressed as percentages. A beta value of
+    1.0 means equal importance to precision and recall (F1 Score), greater than
+    1.0 gives more importance to recall (e.g., F2 Score), and less than 1.0
+    prioritizes precision (e.g., F0.5 Score).
+
+    :param recognition_rate: The recognition rate of the predictions,
+                             acting as precision, expected to be between 0 and 100.
+    :type recognition_rate: float
+    :param coverage_rate: The coverage rate of the predictions, acting as recall,
+                          expected to be between 0 and 100.
+    :type coverage_rate: float
+    :param beta: The weight emphasizing recall over precision. Default is 1.0.
+    :type beta: float
+
+    :return: The F-beta Score as a percentage, which balances precision and recall based on the beta factor.
+    :rtype: float
+    """
+    if recognition_rate == 0 or coverage_rate == 0:
+        return 0  # If either rate is zero, F-beta is zero to avoid division by zero
+
+    # Calculate precision and recall
+    precision = recognition_rate / 100
+    recall = coverage_rate / 100
+
+    # Calculate F-beta Score using the formula:
+    # F-beta = (1 + beta^2) * (precision * recall) / (beta^2 * precision + recall)
+    beta_squared = beta**2
+    f_beta_score = (
+        (1 + beta_squared)
+        * (precision * recall)
+        / ((beta_squared * precision) + recall)
+    )
+
+    return f_beta_score

synkit/Synthesis/RBL/__init__.py

@@ -0,0 +1,80 @@
+"""Radical-based linking search, validation, and replayable proofs."""
+
+from typing import TYPE_CHECKING
+
+from .overlap import (
+    TypedOverlapCertificate,
+    TypedOverlapLimits,
+    TypedOverlapResult,
+    enumerate_typed_overlaps,
+)
+from .policy import (
+    AcceptanceTask,
+    OverlapScope,
+    ProofLevel,
+    RBLSearchPolicy,
+    SearchOutcomeStatus,
+    SearchScope,
+    TerminationPolicy,
+)
+from .proof import (
+    RBL_PROOF_SCHEMA,
+    RBLProofReplay,
+    RBLReplayCertificate,
+    read_rbl_proof,
+)
+from .state import RBL_RESULT_SCHEMA
+from .validation import (
+    FusionIssue,
+    FusionIssueCode,
+    FusionValidation,
+    WildcardRole,
+    certify_fusion_postprocessing,
+    validate_endpoint_preservation,
+    validate_fusion_rsmi,
+    validate_rbl_candidate,
+    validate_strict_rbl_candidate,
+    validate_wildcard_mapping_roles,
+)
+
+if TYPE_CHECKING:
+    from .engine import RBLEngine
+
+__all__ = [
+    "AcceptanceTask",
+    "FusionIssue",
+    "FusionIssueCode",
+    "FusionValidation",
+    "OverlapScope",
+    "ProofLevel",
+    "RBLEngine",
+    "RBLProofReplay",
+    "RBLReplayCertificate",
+    "RBLSearchPolicy",
+    "RBL_PROOF_SCHEMA",
+    "RBL_RESULT_SCHEMA",
+    "SearchOutcomeStatus",
+    "SearchScope",
+    "TerminationPolicy",
+    "TypedOverlapCertificate",
+    "TypedOverlapLimits",
+    "TypedOverlapResult",
+    "WildcardRole",
+    "certify_fusion_postprocessing",
+    "enumerate_typed_overlaps",
+    "read_rbl_proof",
+    "validate_endpoint_preservation",
+    "validate_fusion_rsmi",
+    "validate_rbl_candidate",
+    "validate_strict_rbl_candidate",
+    "validate_wildcard_mapping_roles",
+]
+
+
+def __getattr__(name: str) -> object:
+    """Load the engine lazily so lightweight policy imports stay cheap."""
+    if name == "RBLEngine":
+        from .engine import RBLEngine
+
+        return RBLEngine
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")