synkit 0.0.8__tar.gz → 0.0.9__tar.gz

{synkit-0.0.8 → synkit-0.0.9}/.gitignore

@@ -19,4 +19,5 @@ Data/Benchmark/*
 # *.png
 *.json.gz
 run.sh
-docs/*
+docs/*
+run_rdcanon.py

synkit-0.0.9/.readthedocs.yml

@@ -0,0 +1,24 @@
+# Read the Docs configuration file
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+# 1) Tell RTD this is v2 of the schema
+version: 2
+
+# 2) Pick your build image and interpreter
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# 3) Install your package + any doc-only extras
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements: 
+        - docs
+
+# 4) Point Sphinx at your conf.py and choose HTML
+sphinx:
+  configuration: doc/conf.py
+  builder: html

{synkit-0.0.8 → synkit-0.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synkit
-Version: 0.0.8
+Version: 0.0.9
 Summary: Utility for reaction modeling using graph grammar
 Project-URL: homepage, https://github.com/TieuLongPhan/SynKit
 Project-URL: source, https://github.com/TieuLongPhan/SynKit
@@ -22,6 +22,10 @@ Requires-Dist: seaborn>=0.13.2
 Provides-Extra: all
 Requires-Dist: numpy>=2.2.0; extra == 'all'
 Requires-Dist: torch>=2.2.0; extra == 'all'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Requires-Dist: sphinxcontrib-bibtex; extra == 'docs'
 Description-Content-Type: text/markdown
 
 # SynKit

{synkit-0.0.8 → synkit-0.0.9}/Test/Chem/Reaction/test_canon_rsmi.py

@@ -7,7 +7,11 @@ from synkit.IO.chem_converter import rsmi_to_graph
 class TestCanonRSMI(unittest.TestCase):
     def setUp(self):
         # Use generic backend for deterministic behavior
-        self.canon = CanonRSMI(backend="wl", wl_iterations=5)
+        self.canon = CanonRSMI(
+            backend="wl",
+            wl_iterations=5,
+            node_attrs=["element", "aromatic", "charge", "hcount", "neighbors"],
+        )
         # Example reaction SMILES with atom-map labels
         self.input_rsmi = "[CH3:3][CH2:5][OH:10]>>[CH2:3]=[CH2:5].[OH2:10]"
         # After expand_aam and canonicalisation, since backend is generic,

{synkit-0.0.8 → synkit-0.0.9}/Test/Rule/Modify/test_molecule_rule.py

@@ -1,6 +1,6 @@
 import unittest
 from synkit.Rule.Modify.molecule_rule import MoleculeRule
-from synkit.Graph.Matcher import GraphMatcherEngine
+from synkit.Graph.Matcher.graph_matcher import GraphMatcherEngine
 import importlib
 
 MOD_AVAILABLE = importlib.util.find_spec("mod") is not None

{synkit-0.0.8 → synkit-0.0.9}/Test/Rule/Modify/test_rule_utils.py

@@ -7,7 +7,8 @@ from synkit.Rule.Modify.rule_utils import (
     strip_context,
     _increment_gml_ids,
 )
-from synkit.Graph.Matcher import GraphMatcherEngine, SubgraphMatch
+from synkit.Graph.Matcher.graph_matcher import GraphMatcherEngine
+from synkit.Graph.Matcher.subgraph_matcher import SubgraphMatch
 import importlib
 
 MOD_AVAILABLE = importlib.util.find_spec("mod") is not None

{synkit-0.0.8 → synkit-0.0.9}/doc/conf.py

@@ -1,31 +1,34 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+import os
+import sys
 
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+sys.path.insert(0, os.path.abspath(".."))
 
+# -- Project information -----------------------------------------------------
 project = "synkit"
-copyright = "2025, Tieu-Long Phan"
 author = "Tieu-Long Phan"
+release = "0.0.8"
+version = release
 
 # -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.githubpages",
     "sphinxcontrib.bibtex",
+    # "sphinx.ext.napoleon",  # un-comment if using Google/NumPy docstrings
 ]
+
 bibtex_bibfiles = ["refs.bib"]
 templates_path = ["_templates"]
 exclude_patterns = []
 autosectionlabel_prefix_document = True
 
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+}
 
+# -- Options for HTML output -------------------------------------------------
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]

{synkit-0.0.8 → synkit-0.0.9}/doc/index.rst

@@ -1,5 +1,6 @@
 Welcome to synkit documentation!
 ================================
+This is documentation for synkit version |version| (release |release|).
 
 .. toctree::
    :caption: Contents

synkit-0.0.9/doc/requirements.txt

@@ -0,0 +1,3 @@
+sphinx
+sphinx-rtd-theme
+sphinxcontrib-bibtex

{synkit-0.0.8 → synkit-0.0.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "synkit"
-version = "0.0.8"
+version = "0.0.9"
 authors = [
     {name="Tieu Long Phan", email="tieu@bioinf.uni-leipzig.de"}
 ]
@@ -30,7 +30,11 @@ dependencies = [
 
 [project.optional-dependencies]
 all = ["numpy>=2.2.0", "torch>=2.2.0"]
-
+docs = [
+  "sphinx>=6.0",
+  "sphinx-rtd-theme",
+  "sphinxcontrib-bibtex",
+]
 [project.urls]
 homepage = "https://github.com/TieuLongPhan/SynKit"
 source = "https://github.com/TieuLongPhan/SynKit"

synkit-0.0.9/synkit/Graph/Canon/__init__.py

@@ -0,0 +1,3 @@
+from .canon_graph import GraphCanonicaliser, CanonicalGraph
+
+__all__ = ["GraphCanonicaliser", "CanonicalGraph"]

{synkit-0.0.8/synkit/Graph → synkit-0.0.9/synkit/Graph/Canon}/canon_graph.py

@@ -63,6 +63,7 @@ from networkx.algorithms.graph_hashing import (
     weisfeiler_lehman_subgraph_hashes as _wl_hashes,
 )
 from .canon_algs import canon_morgan
+from .nauty import NautyCanonicalizer
 
 __all__: list[str] = ["CanonicalGraph", "GraphCanonicaliser", "CanonicalRule"]
 
@@ -145,14 +146,14 @@ class GraphCanonicaliser:
     def __init__(
         self,
         *,
-        backend: Literal["generic", "wl", "morgan"] = "generic",
+        backend: Literal["generic", "wl", "morgan", "nauty"] = "generic",
         wl_iterations: int = 3,
         morgan_radius: int = 3,
         node_attrs: List[str] = ["element", "aromatic", "charge", "hcount"],
         node_sort_key: T_NodeSortKey = _default_node_key,
         edge_sort_key: T_EdgeSortKey = _default_edge_key,
     ) -> None:
-        if backend not in {"generic", "wl", "morgan"}:
+        if backend not in {"generic", "wl", "morgan", "nauty"}:
             raise ValueError("backend must be 'generic' or 'wl' or 'morgan' ")
         self.backend: Literal["generic", "wl", "morgan"] = backend
         self._wl_k: int = wl_iterations
@@ -161,6 +162,8 @@ class GraphCanonicaliser:
         self._edge_key: T_EdgeSortKey = edge_sort_key
         self._wl_node_attrs: Tuple[str, ...] = tuple(node_attrs)
         self._mg_node_attrs: List[str] = node_attrs
+        if self.backend == "nauty":
+            self.nauty = NautyCanonicalizer(node_attrs=node_attrs, edge_attrs=["order"])
 
     # ------------------------------------------------------------------ #
     # High‑level helpers                                                 #
@@ -220,6 +223,8 @@ class GraphCanonicaliser:
             return self._canon_generic(g)
         elif self.backend == "wl":
             return self._canon_wl(g)
+        elif self.backend == "nauty":
+            return self._canon_nauty(g)
         else:
             return canon_morgan(
                 g, morgan_radius=self._mg_k, node_attributes=self._mg_node_attrs
@@ -228,6 +233,9 @@ class GraphCanonicaliser:
         #     self._canon_generic(g) if self.backend == "generic" else self._canon_wl(g)
         # )
 
+    def _canon_nauty(self, g: nx.Graph) -> nx.Graph:
+        return self.nauty.canonical_form(g)
+
     def _canon_generic(self, g: nx.Graph) -> nx.Graph:
         """Pure attribute‑sort strategy – O(|V| log |V| + |E| log |E|)."""
         nodes_sorted = sorted(g.nodes(data=True), key=lambda x: self._node_key(*x))
@@ -274,6 +282,7 @@ class GraphCanonicaliser:
         wl_hash = _wl_hashes(
             g2,
             node_attr=node_attr,
+            edge_attr="order",
             iterations=self._wl_k,
         )
 

synkit-0.0.9/synkit/Graph/Canon/nauty.py

@@ -0,0 +1,292 @@
+import networkx as nx
+import hashlib
+from synkit.IO import setup_logging
+
+logger = setup_logging()
+
+
+class NautyCanonicalizer:
+    __slots__ = ("node_attrs", "edge_attrs")
+
+    def __init__(self, node_attrs=None, edge_attrs=None):
+        self.node_attrs = list(node_attrs) if node_attrs else []
+        self.edge_attrs = list(edge_attrs) if edge_attrs else []
+
+    @staticmethod
+    def _freeze(x):
+        if isinstance(x, list):
+            return tuple(NautyCanonicalizer._freeze(v) for v in x)
+        if isinstance(x, dict):
+            return frozenset(
+                (k, NautyCanonicalizer._freeze(v)) for k, v in sorted(x.items())
+            )
+        return x
+
+    def canonical_form(
+        self,
+        G,
+        return_aut=False,
+        remap_aut=False,
+        return_orbits=False,
+        return_perm=False,
+        max_depth=None,
+    ):
+        """
+        Compute canonical form of graph G with optional automorphisms, orbits, and early stopping.
+
+        :param G: NetworkX graph to canonicalize.
+        :param return_aut: bool, whether to return list of automorphism permutations.
+        Default: False.
+        :param remap_aut: bool, whether to remap automorphisms to canonical labels
+        (only valid if return_aut=True). Default: False.
+        :param return_orbits: bool, whether to return node orbits (symmetry groups). Default: False.
+        :param return_perm: bool, whether to return canonical permutation (ordering of nodes). Default: False.
+        :param max_depth: int or None, max recursion depth for backtracking search (early stopping).
+        Default: None (unlimited).
+        :return: tuple containing requested results and a boolean early_stop flag indicating if search terminated early.
+                 The order of outputs is (G_canon, perm?, automorphisms?, orbits?, early_stop).
+        """
+        logger.debug(
+            f"Starting canonical_form: max_depth={max_depth},"
+            + f" return_aut={return_aut}, remap_aut={remap_aut},"
+            + f" return_orbits={return_orbits}, return_perm={return_perm}"
+        )
+
+        best = {"label": None, "perm": None}
+        aut_perms = []
+
+        initial_partition = self._initial_partition(G)
+        logger.debug(f"Initial partition: {initial_partition}")
+
+        early_stop_occurred = self._search(
+            G, initial_partition, [], best, aut_perms, depth=0, max_depth=max_depth
+        )
+
+        perm = best["perm"]
+        if perm is None:
+            logger.error(
+                f"Canonical form not found: search stopped early (max_depth={max_depth} too small)."
+            )
+            raise RuntimeError(
+                f"Canonical form not found: search stopped early (max_depth={max_depth} too small)."
+            )
+
+        mapping = {v: i + 1 for i, v in enumerate(perm)}
+        G_can = nx.relabel_nodes(G, mapping, copy=True)
+        self._update_atom_map(G_can)
+
+        results = [G_can]
+        if return_perm:
+            results.append(perm)
+
+        if return_aut:
+            if remap_aut:
+                remapped = [[mapping[v] for v in p] for p in aut_perms]
+                results.append(remapped)
+            else:
+                results.append(aut_perms)
+
+        if return_orbits:
+            orbits = self.compute_orbits(aut_perms)
+            if remap_aut and return_aut:
+                orbits = [set(mapping[v] for v in orbit) for orbit in orbits]
+            results.append(orbits)
+
+        results.append(early_stop_occurred)
+
+        logger.debug(
+            f"canonical_form completed, early_stop_occurred={early_stop_occurred}"
+        )
+        return tuple(results) if len(results) > 2 else results[0]
+
+    def _update_atom_map(self, G):
+        for n in G.nodes():
+            G.nodes[n]["atom_map"] = n
+
+    def _initial_partition(self, G):
+        if not self.node_attrs:
+            return [sorted(G.nodes())]
+        buckets = {}
+        for v in G.nodes():
+            key = tuple(
+                self._freeze(G.nodes[v].get(attr, None)) for attr in self.node_attrs
+            )
+            buckets.setdefault(key, []).append(v)
+        return [sorted(nodes) for _, nodes in sorted(buckets.items())]
+
+    def _node_signature(self, G, v, partition):
+        node_attrs = tuple(
+            self._freeze(G.nodes[v].get(a, None)) for a in self.node_attrs
+        )
+        degree = G.degree[v]
+
+        nbr_part_counts = []
+        for cell in partition:
+            count = sum(1 for nbr in G.neighbors(v) if nbr in cell)
+            nbr_part_counts.append(count)
+        nbr_part_counts = tuple(nbr_part_counts)
+
+        edge_attr_multiset = []
+        for nbr in G.neighbors(v):
+            attrs = G[v][nbr]
+            edge_attrs = []
+            for a in self.edge_attrs:
+                val = attrs.get(a, None)
+                if a == "order" and isinstance(val, tuple):
+                    val = tuple(sorted(round(float(x), 3) for x in val))
+                edge_attrs.append(self._freeze(val))
+            edge_attr_multiset.append(tuple(edge_attrs))
+        edge_attr_multiset = tuple(sorted(edge_attr_multiset))
+
+        return (node_attrs, degree, nbr_part_counts, edge_attr_multiset)
+
+    def _refine(self, G, partition):
+        changed = True
+        while changed:
+            changed = False
+            new_partition = []
+            sig_cache = {}
+            for cell in partition:
+                if len(cell) <= 1:
+                    new_partition.append(cell)
+                    continue
+                sigs = {}
+                for v in cell:
+                    if v not in sig_cache:
+                        sig_cache[v] = self._node_signature(G, v, partition)
+                    sig = sig_cache[v]
+                    sigs.setdefault(sig, []).append(v)
+                if len(sigs) > 1:
+                    changed = True
+                    for sig in sorted(sigs):
+                        new_partition.append(sorted(sigs[sig]))
+                else:
+                    new_partition.append(cell)
+            partition = new_partition
+        return partition
+
+    def _search(self, G, partition, prefix, best, aut_perms, depth=0, max_depth=None):
+        if max_depth is not None and depth > max_depth:
+            logger.debug(
+                f"Early stopping at depth {depth} due to max_depth={max_depth}"
+            )
+            return True  # early stop triggered
+
+        partition = self._refine(G, partition)
+        if all(len(c) == 1 for c in partition):
+            perm = prefix + [v for c in partition for v in c]
+            label = self._build_label(G, perm)
+            if best["label"] is None or label < best["label"]:
+                best["label"], best["perm"] = label, perm
+                aut_perms.clear()
+                aut_perms.append(perm)
+                logger.debug(f"New best label found at depth {depth}")
+            elif label == best["label"]:
+                aut_perms.append(perm)
+                logger.debug(f"Equivalent label found at depth {depth}")
+            return False
+
+        idx = next(i for i, c in enumerate(partition) if len(c) > 1)
+        cell = partition[idx]
+        sorted_cell = sorted(cell, key=lambda n: G.nodes[n].get("atom_map", n))
+
+        for v in sorted_cell:
+            rest = [w for w in cell if w != v]
+            # fmt: off
+            new_partition = (
+                partition[:idx]
+                + [[v]]
+                + ([sorted(rest)] if rest else [])
+                + partition[idx + 1:]
+            )
+            # fmt: on
+            candidate_prefix = prefix + [v]
+
+            partial_label = self._build_partial_label(G, candidate_prefix)
+
+            if best["label"] is not None and partial_label > best["label"]:
+                logger.debug(f"Pruning branch at depth {depth} due to partial label")
+                continue  # prune branch early
+
+            if self._search(
+                G,
+                new_partition,
+                candidate_prefix,
+                best,
+                aut_perms,
+                depth=depth + 1,
+                max_depth=max_depth,
+            ):
+                return True  # propagate early stop upward
+
+        return False
+
+    def _build_label(self, G, perm):
+        node_segment = "|".join(
+            ":".join(
+                str(self._freeze(G.nodes[v].get(attr, ""))) for attr in self.node_attrs
+            )
+            for v in perm
+        )
+        n = len(perm)
+        edge_bits = []
+        for i in range(n):
+            vi = perm[i]
+            for j in range(i + 1, n):
+                vj = perm[j]
+                if G.has_edge(vi, vj):
+                    attrs = G[vi][vj]
+                    frozen_attrs = tuple(
+                        self._freeze(attrs.get(a, "")) for a in self.edge_attrs
+                    )
+                    edge_bits.append("1:" + ":".join(str(x) for x in frozen_attrs))
+                else:
+                    edge_bits.append("0:" + ":".join("" for _ in self.edge_attrs))
+        edge_segment = "|".join(edge_bits)
+        return node_segment + "||" + edge_segment
+
+    def _build_partial_label(self, G, prefix):
+        node_segment = "|".join(
+            ":".join(
+                str(self._freeze(G.nodes[v].get(attr, ""))) for attr in self.node_attrs
+            )
+            for v in prefix
+        )
+        suffix = "{" * 1000  # lexicographically larger than any label char
+        return node_segment + suffix
+
+    def compute_orbits(self, aut_perms):
+        if not aut_perms:
+            return []
+
+        orbit_map = {}
+        orbits = []
+
+        def union_orbits(i, j):
+            if i == j:
+                return
+            o1 = orbits[i]
+            o2 = orbits[j]
+            if len(o1) < len(o2):
+                i, j = j, i
+                o1, o2 = o2, o1
+            o1.update(o2)
+            orbits[j] = set()
+            for v in o2:
+                orbit_map[v] = i
+
+        first_perm = aut_perms[0]
+        for idx, node in enumerate(first_perm):
+            orbit_map[node] = idx
+            orbits.append({node})
+
+        for perm in aut_perms:
+            for idx, node in enumerate(perm):
+                union_orbits(idx, orbit_map[node])
+
+        return [o for o in orbits if o]
+
+    def graph_signature(self, G):
+        G_canon = self.canonical_form(G)
+        label = self._build_label(G_canon, sorted(G_canon.nodes()))
+        return hashlib.sha256(label.encode("utf-8")).hexdigest()

{synkit-0.0.8 → synkit-0.0.9}/synkit/Graph/Hyrogen/_misc.py

@@ -1,7 +1,7 @@
 from copy import copy
 import networkx as nx
 from operator import eq
-from typing import List, Any, Set, Tuple
+from typing import List, Set, Any, Tuple
 from networkx.algorithms.isomorphism import generic_node_match, generic_edge_match
 
 from synkit.Graph.Feature.graph_descriptors import GraphDescriptor
@@ -91,7 +91,22 @@ def h_to_implicit(G: nx.Graph) -> nx.Graph:
     return H2
 
 
-def h_to_explicit(G: nx.Graph, nodes: List[int] = None) -> nx.Graph:
+def normalize_edge_orders(G: nx.Graph) -> None:
+    """
+    In-place normalize all edge attributes in G:
+      - If 'order' is a float or int, replace it with (order, order).
+      - If 'standard_order' is missing, set it to 0.0.
+    """
+    for _, _, data in G.edges(data=True):
+        o = data.get("order")
+        # Wrap scalar orders into tuples
+        if isinstance(o, (int, float)):
+            data["order"] = (float(o), float(o))
+        if "standard_order" not in data:
+            data["standard_order"] = 0.0
+
+
+def h_to_explicit(G: nx.Graph, nodes: List[int] = None, its: bool = False) -> nx.Graph:
     """
     Convert implicit hydrogen counts on heavy atoms into explicit hydrogen nodes.
 
@@ -146,6 +161,8 @@ def h_to_explicit(G: nx.Graph, nodes: List[int] = None) -> nx.Graph:
             tgh_list = [list(row) for row in tgh]
             tgh_list[0][2] -= count  # Assume hcount is stored at position [0][2]
             H2.nodes[heavy]["typesGH"] = tuple(tuple(row) for row in tgh_list)
+    if its:
+        normalize_edge_orders(H2)
 
     return H2
 

synkit-0.0.9/synkit/Graph/Matcher/__init__.py

@@ -0,0 +1,10 @@
+# from .graph_matcher import GraphMatcherEngine
+# from .subgraph_matcher import SubgraphMatch, SubgraphSearchEngine
+# from .graph_cluster import GraphCluster
+
+# __all__ = [
+#     "GraphMatcherEngine",
+#     "SubgraphMatch",
+#     "SubgraphSearchEngine",
+#     "GraphCluster",
+# ]