synkit 1.6.5__py3-none-win_amd64.whl

synkit/Vis/mtg_drawer.py

@@ -0,0 +1,34 @@
+"""Compatibility import for :mod:`synkit.Vis.mtg.drawer`.
+
+New code should use :mod:`synkit.Vis.mtg`. This module remains available so
+existing imports continue to work.
+"""
+
+from __future__ import annotations
+
+from synkit.Vis.mtg import drawer as _implementation
+
+draw_mtg_graph = _implementation.draw_mtg_graph
+draw_mtg_steps = _implementation.draw_mtg_steps
+
+__all__ = ["draw_mtg_graph", "draw_mtg_steps"]
+
+
+def __getattr__(name: str) -> object:
+    """Delegate legacy module attributes to the canonical implementation.
+
+    :param name: Attribute requested by the caller.
+    :type name: str
+    :return: Attribute from :mod:`synkit.Vis.mtg.drawer`.
+    :rtype: object
+    """
+    return getattr(_implementation, name)
+
+
+def __dir__() -> list[str]:
+    """Return canonical and compatibility-module attributes.
+
+    :return: Sorted attribute names.
+    :rtype: list[str]
+    """
+    return sorted(set(globals()) | set(dir(_implementation)))

synkit/Vis/pdf_writer.py

@@ -0,0 +1,146 @@
+"""This module comprises several functions adapted from the work of Klaus
+Weinbauer.
+
+The original code can be found at his GitHub repository: https://github.com/klausweinbauer/FGUtils.
+Adaptations were made to enhance functionality and integrate with other system components.
+"""
+
+import matplotlib.pyplot as plt
+from matplotlib.backends.backend_pdf import PdfPages
+from typing import List, Callable, Union, Tuple, Optional
+import tqdm
+
+
+class PdfWriter:
+    """A utility class to create PDF reports with plots from a list of figures
+    or dynamically generated plots.
+
+    :param file: The file name of the output PDF.
+    :type file: str
+    :param plot_fn: Function to create a plot for a single data entry or row.
+                    Expected interface: `plot_fn(data_entry, axis, **kwargs)`. Default is None.
+    :type plot_fn: Optional[Callable], optional
+    :param plot_per_row: If True, calls `plot_fn` for an entire row instead of individual subplots.
+                         Default is False.
+    :type plot_per_row: bool, optional
+    :param max_pages: Maximum number of pages to create. Default is 999.
+    :type max_pages: int, optional
+    :param rows: Number of plot rows per page. Default is 7.
+    :type rows: int, optional
+    :param cols: Number of plot columns per page. Default is 2.
+    :type cols: int, optional
+    :param pagesize: Size of a single page (in inches). Default is (21, 29.7).
+    :type pagesize: Tuple[float, float], optional
+    :param width_ratios: Column width ratios. Default is None.
+    :type width_ratios: Optional[List[float]], optional
+    :param show_progress: If True, displays a progress bar using `tqdm`. Default is True.
+    :type show_progress: bool, optional
+    """
+
+    def __init__(
+        self,
+        file: str,
+        plot_fn: Optional[Callable] = None,
+        plot_per_row: bool = False,
+        max_pages: int = 999,
+        rows: int = 7,
+        cols: int = 2,
+        pagesize: Tuple[float, float] = (21, 29.7),
+        width_ratios: Optional[List[float]] = None,
+        show_progress: bool = True,
+    ):
+        self.pdf_pages = PdfPages(file)
+        self.plot_fn = plot_fn
+        self.plot_per_row = plot_per_row
+        self.max_pages = max_pages
+        self.rows = rows
+        self.cols = cols
+        self.pagesize = pagesize
+        self.width_ratios = width_ratios
+        self.show_progress = show_progress
+
+    def plot(self, data: Union[List[plt.Figure], List], **kwargs):
+        """Generate plots from data or save pre-generated figures to the PDF.
+
+        :param data: Input data or figures. Figures are saved directly;
+                     otherwise ``plot_fn`` is called for each entry.
+        :type data: Union[List[matplotlib.figure.Figure], List]
+        :param kwargs: Additional keyword arguments passed to ``plot_fn``.
+
+        :return: None
+        """
+        # Case 1: Pre-generated figures
+        if all(isinstance(item, plt.Figure) for item in data):
+            for fig in tqdm.tqdm(
+                data, disable=not self.show_progress, desc="Saving Figures"
+            ):
+                self.save_figure(fig)
+            return
+
+        # Case 2: Generate plots dynamically using `plot_fn`
+        if self.plot_fn is None:
+            raise ValueError(
+                "plot_fn must be provided when input is not a list of figures."
+            )
+
+        if not isinstance(data, list):
+            raise ValueError(
+                "Data must be a list or a list of matplotlib.figure.Figure."
+            )
+
+        plots_per_page = self.rows if self.plot_per_row else self.rows * self.cols
+        max_plots = self.max_pages * plots_per_page
+        step = max(len(data) / max_plots, 1)
+        pages = int((len(data) / step + plots_per_page - 1) // plots_per_page)
+
+        for p in tqdm.tqdm(
+            range(pages), disable=not self.show_progress, desc="Generating Pages"
+        ):
+            fig, ax = plt.subplots(
+                self.rows,
+                self.cols,
+                figsize=self.pagesize,
+                squeeze=False,
+                gridspec_kw=(
+                    {"width_ratios": self.width_ratios} if self.width_ratios else None
+                ),
+            )
+            done = False
+            for r in range(self.rows):
+                if self.plot_per_row:
+                    _idx = int((p * self.rows + r) * step)
+                    if _idx >= len(data):
+                        done = True
+                        break
+                    self.plot_fn(data[_idx], ax[r, :], index=_idx, **kwargs)
+                else:
+                    for c in range(self.cols):
+                        _idx = int((p * plots_per_page + r * self.cols + c) * step)
+                        if _idx >= len(data):
+                            done = True
+                            break
+                        self.plot_fn(data[_idx], ax[r, c], index=_idx, **kwargs)
+            plt.tight_layout()
+            self.pdf_pages.savefig(fig, bbox_inches="tight", pad_inches=1)
+            plt.close(fig)
+            if done:
+                break
+
+    def save_figure(self, figure: plt.Figure):
+        """Save a pre-generated matplotlib figure directly to the PDF.
+
+        :param figure: The figure to save.
+        :type figure: matplotlib.figure.Figure
+
+        :return: None
+        """
+        if not isinstance(figure, plt.Figure):
+            raise ValueError("Input must be a matplotlib.figure.Figure.")
+        self.pdf_pages.savefig(figure, bbox_inches="tight", pad_inches=1)
+
+    def close(self):
+        """Close the PDF file, ensuring all pages are written.
+
+        :return: None
+        """
+        self.pdf_pages.close()

synkit/Vis/reaction/__init__.py

@@ -0,0 +1,19 @@
+"""Reaction and rule visualization namespace.
+
+This namespace contains image-based reaction rendering and reaction-rule
+visualization helpers. Graph-panel reaction drawing lives in
+:mod:`synkit.Vis.molecule`.
+
+.. rubric:: Example
+
+.. code-block:: python
+
+    from synkit.Vis.reaction import RXNVis
+
+    image = RXNVis(show_atom_map=True).render("[CH3:1][Cl:2]>>[CH3:1].[Cl:2]")
+"""
+
+from synkit.Vis.reaction.rxn import RXNVis
+from synkit.Vis.reaction.rule import RuleVis
+
+__all__ = ["RXNVis", "RuleVis"]

synkit/Vis/reaction/rule.py

@@ -0,0 +1,141 @@
+import networkx as nx
+import matplotlib.pyplot as plt
+from typing import Union, Tuple, List
+
+from synkit.Vis.graph_visualizer import GraphVisualizer
+from synkit.IO.chem_converter import rsmi_to_graph
+from synkit.Graph.ITS.its_construction import ITSConstruction
+from synkit.IO.gml_to_nx import GMLToNX
+
+
+class RuleVis:
+    def __init__(self, backend: str = "nx") -> None:
+        if backend != "nx":
+            raise ValueError("RuleVis supports only the native 'nx' backend.")
+        self.backend = backend
+        self.vis_graph = GraphVisualizer()
+
+    def vis(self, input: Union[str, Tuple[nx.Graph, nx.Graph, nx.Graph]], **kwargs):
+        """Visualize native graph tuples, reaction SMILES, or GML rules."""
+        if isinstance(input, str) and (
+            input.strip().startswith("graph [") or "rule [" in input
+        ):
+            r, p, its = GMLToNX(input).transform()
+            return self.nx_vis((r, p, its), **kwargs)
+        return self.nx_vis(input, **kwargs)
+
+    def nx_vis(
+        self,
+        input: Union[str, Tuple[nx.Graph, nx.Graph, nx.Graph]],
+        sanitize: bool = False,
+        figsize: Tuple[int, int] = (18, 5),
+        orientation: str = "horizontal",
+        show_titles: bool = True,
+        show_atom_map: bool = False,
+        titles: Tuple[str, str, str] = (
+            "Reactant",
+            "Imaginary Transition State",
+            "Product",
+        ),
+        add_gridbox: bool = False,
+        rule: bool = False,
+    ) -> plt.Figure:
+        """Visualize reactants, ITS, and products side-by-side or vertically,
+        with interactive plotting turned off to prevent double-display, and
+        correct handling of matplotlib axes arrays."""
+        # Disable interactive mode & clear any leftover figures
+        was_interactive = plt.isinteractive()
+        plt.ioff()
+        plt.close("all")
+
+        try:
+            # 1) Parse input
+            if isinstance(input, str):
+                r, p = rsmi_to_graph(input, sanitize=sanitize)
+                its = ITSConstruction().ITSGraph(r, p)
+            elif isinstance(input, tuple) and len(input) == 3:
+                r, p, its = input
+            else:
+                raise ValueError("Input must be reaction SMILES or a tuple (r,p,its)")
+
+            # 2) Create subplots
+            if orientation == "horizontal":
+                fig, axes = plt.subplots(1, 3, figsize=figsize)
+            elif orientation == "vertical":
+                fig, axes = plt.subplots(3, 1, figsize=figsize)
+            else:
+                raise ValueError("orientation must be 'horizontal' or 'vertical'")
+
+            # 3) Flatten axes to a simple list of Axes
+            if isinstance(axes, (list, tuple)):
+                ax_list: List[plt.Axes] = list(axes)
+            elif hasattr(axes, "flat") or hasattr(axes, "ravel"):
+                ax_list = list(axes.flatten())
+            else:
+                ax_list = [axes]
+
+            # 4) Plot each panel
+            # Reactants
+            self.vis_graph.plot_as_mol(
+                r,
+                ax=ax_list[0],
+                show_atom_map=show_atom_map,
+                font_size=12,
+                node_size=800,
+                edge_width=2.0,
+            )
+            if show_titles:
+                ax_list[0].set_title(titles[0])
+
+            # ITS
+            self.vis_graph.plot_its(
+                its,
+                ax_list[1],
+                use_edge_color=True,
+                show_atom_map=show_atom_map,
+                rule=rule,
+            )
+            if show_titles:
+                ax_list[1].set_title(titles[1])
+
+            # Products
+            self.vis_graph.plot_as_mol(
+                p,
+                ax=ax_list[2],
+                show_atom_map=show_atom_map,
+                font_size=12,
+                node_size=800,
+                edge_width=2.0,
+            )
+            if show_titles:
+                ax_list[2].set_title(titles[2])
+
+            # 5) Optional gridbox frame
+            if add_gridbox:
+                for ax in ax_list:
+                    ax.set_axisbelow(False)
+                    for spine in ax.spines.values():
+                        spine.set_visible(True)
+                        spine.set_linewidth(2)
+                        spine.set_color("black")
+                    ax.grid(True, which="both", linestyle="--", color="gray", alpha=0.5)
+
+            return fig
+
+        except Exception as e:
+            raise RuntimeError(f"An error occurred during visualization: {e}")
+
+        finally:
+            # Restore the interactive state
+            if was_interactive:
+                plt.ion()
+
+    def help(self) -> None:
+        print(
+            "RuleVis Usage:\n"
+            "  rv = RuleVis(backend='nx')\n"
+            "  rv.vis(input_smiles_or_gml)\n"
+        )
+
+    def __repr__(self) -> str:
+        return f"<RuleVis backend={self.backend!r}>"