synkit 1.6.5__py3-none-win_amd64.whl

synkit/Data/paracetamol.json.gz

@@ -0,0 +1 @@
+[{"R-id": 1, "aam": "[c:4]1([H:11])[cH:5][cH:6][cH:7][cH:8][cH:9]1.[CH3:1][CH:2]([CH3:3])[Cl:10]>>[CH3:1][CH:2]([CH3:3])[c:4]1[cH:5][cH:6][cH:7][cH:8][cH:9]1.[H:11][Cl:10]"}, {"R-id": 2, "aam": "[CH3:1][C:2]([H:12])([CH3:3])[c:6]1[cH:7][cH:8][cH:9][cH:10][cH:11]1.[O:4]=[O:5]>>[CH3:1][C:2]([CH3:3])([O:4][O:5][H:12])[c:6]1[cH:7][cH:8][cH:9][cH:10][cH:11]1"}, {"R-id": 3, "aam": "[CH3:8][C:9]([CH3:11])([O:10][OH:1])[c:2]1[cH:3][cH:4][cH:5][cH:6][cH:7]1>>[OH:1][c:2]1[cH:3][cH:4][cH:5][cH:6][cH:7]1.[CH3:8][C:9](=[O:10])[CH3:11]"}, {"R-id": 4, "aam": "[H:12][O:4][c:5]1[cH:6][cH:7][cH:8][cH:9][cH:10]1.[CH3:1][C:2](=[O:3])[Cl:11]>>[CH3:1][C:2](=[O:3])[O:4][c:5]1[cH:6][cH:7][cH:8][cH:9][cH:10]1.[Cl:11][H:12]"}, {"R-id": 5, "aam": "[CH3:11][C:9](=[O:10])[O:8][c:7]1[cH:6][cH:5][c:4]([H:15])[cH:13][cH:12]1.[O:1]=[N+:2]([O-:3])[OH:14]>>[O:1]=[N+:2]([O-:3])[c:4]1[cH:5][cH:6][c:7]([O:8][C:9](=[O:10])[CH3:11])[cH:12][cH:13]1.[OH:14][H:15]"}, {"R-id": 6, "aam": "[O:12]=[N+:1]([O-:13])[c:2]1[cH:3][cH:4][c:5]([O:6][C:7](=[O:8])[CH3:9])[cH:10][cH:11]1.[H:14][H:15].[H:16][H:18].[H:17][H:19]>>[N:1]([H:18])([H:19])[c:2]1[cH:3][cH:4][c:5]([O:6][C:7](=[O:8])[CH3:9])[cH:10][cH:11]1.[H:14][O:12][H:15].[H:16][O:13][H:17]"}, {"R-id": 7, "aam": "[NH2:1][c:2]1[cH:3][cH:4][c:5]([O:6][C:10](=[O:11])[CH3:9])[cH:7][cH:8]1.[OH:12][H:13]>>[NH2:1][c:2]1[cH:3][cH:4][c:5]([O:6][H:13])[cH:7][cH:8]1.[CH3:9][C:10](=[O:11])[OH:12]"}, {"R-id": 8, "aam": "[H:13][NH:4][c:5]1[cH:6][cH:7][c:8]([OH:9])[cH:10][cH:11]1.[CH3:1][C:2](=[O:3])[Cl:12]>>[CH3:1][C:2](=[O:3])[NH:4][c:5]1[cH:6][cH:7][c:8]([OH:9])[cH:10][cH:11]1.[Cl:12][H:13]"}, {"R-id": 9, "aam": "[CH3:19][C:17](=[O:18])[NH:16][c:13]1[cH:12][cH:11][c:10]([O:9][H:21])[cH:15][cH:14]1.[CH3:1][CH2:2][N:3]([CH2:4][CH3:5])[CH2:6][C:7](=[O:8])[Cl:20]>>[CH3:1][CH2:2][N:3]([CH2:4][CH3:5])[CH2:6][C:7](=[O:8])[O:9][C:10]1=[CH:11][CH:12]=[C:13]([NH:16][C:17](=[O:18])[CH3:19])[CH:14]=[CH:15]1.[Cl:20][H:21]"}]

synkit/Graph/Canon/__init__.py

@@ -0,0 +1,16 @@
+from .canon_graph import GraphCanonicaliser, CanonicalGraph
+from .exact import (
+    CanonicalSearchIncomplete,
+    ExactCanonicalResult,
+    ExactColoredGraphCanonicalizer,
+    IncompleteCanonicalResult,
+)
+
+__all__ = [
+    "CanonicalGraph",
+    "CanonicalSearchIncomplete",
+    "ExactCanonicalResult",
+    "ExactColoredGraphCanonicalizer",
+    "GraphCanonicaliser",
+    "IncompleteCanonicalResult",
+]

synkit/Graph/Canon/_native/__init__.py

@@ -0,0 +1,13 @@
+"""Opt-in native graph backend using a bundled or explicitly built library."""
+
+from .build import build_native_canon
+from .runtime import CancellationToken, bundled_native_canon
+from .search import NativeCanonicalResult, canonicalize_native_graph
+
+__all__ = [
+    "build_native_canon",
+    "bundled_native_canon",
+    "CancellationToken",
+    "NativeCanonicalResult",
+    "canonicalize_native_graph",
+]

synkit/Graph/Canon/_native/build.py

@@ -0,0 +1,93 @@
+"""Explicit immutable CMake builds of the dependency-free C++17 graph core."""
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import platform
+import shutil
+import subprocess
+import sys
+import tempfile
+
+
+def _digest(path):
+    return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+
+def _verify(path):
+    probe = subprocess.run(
+        [sys.executable, "-c", "import ctypes,sys; assert ctypes.CDLL(sys.argv[1]).synkit_canon_abi()==1", str(path)],
+        capture_output=True, text=True,
+    )
+    if probe.returncode:
+        raise RuntimeError("Built graph core advertises an incompatible ABI")
+
+
+def _run(command):
+    result = subprocess.run(command, capture_output=True, text=True)
+    if result.returncode:
+        raise RuntimeError("Native graph build failed:\n" + (result.stdout + result.stderr)[-6000:])
+
+
+def build_native_canon(output_dir, *, compiler=None):
+    """Build explicitly and return a content-addressed library with provenance.
+
+    No native build or dependency download occurs during package import.
+    CMake and a C++17 compiler are developer requirements, not runtime SDKs.
+    """
+    cmake = shutil.which("cmake")
+    if cmake is None:
+        raise RuntimeError("CMake is required for an explicit native graph build")
+    if compiler is not None:
+        compiler = shutil.which(compiler)
+        if compiler is None:
+            raise RuntimeError("Requested C++ compiler is unavailable")
+    source = Path(__file__).resolve().parents[1] / "cpp"
+    inputs = [p for p in source.rglob("*") if p.is_file()
+              and (p.name in {"CMakeLists.txt", "README.md"}
+                   or p.relative_to(source).parts[0] in {"include", "src", "examples", "tests"})]
+    detected_compiler = compiler or shutil.which(os.environ.get("CXX", "cl" if os.name == "nt" else "c++"))
+    compiler_info = subprocess.run([detected_compiler, "--version"], capture_output=True, text=True) \
+        if detected_compiler else None
+    config = {
+        "abi": 1, "builder_sha256": _digest(__file__),
+        "sources": {str(p.relative_to(source)): _digest(p) for p in sorted(inputs)},
+        "cmake": subprocess.check_output([cmake, "--version"], text=True),
+        "compiler": compiler, "platform": sys.platform, "machine": platform.machine(),
+        "detected_compiler": detected_compiler,
+        "compiler_version": (compiler_info.stdout + compiler_info.stderr) if compiler_info else None,
+        "environment": {k: os.environ.get(k) for k in ("CXX", "CXXFLAGS", "CMAKE_GENERATOR")},
+    }
+    key = hashlib.sha256(json.dumps(config, sort_keys=True).encode()).hexdigest()
+    output = Path(output_dir).expanduser().resolve()
+    output.mkdir(parents=True, exist_ok=True)
+    suffix = ".dll" if os.name == "nt" else ".dylib" if sys.platform == "darwin" else ".so"
+    library = output / ("libsynkit_canon_" + key[:20] + suffix)
+    manifest = library.with_suffix(".json")
+    if library.exists():
+        if not manifest.exists():
+            raise RuntimeError("Existing graph library has no build manifest")
+        saved = json.loads(manifest.read_text())
+        if saved.get("configuration") != config or saved.get("library_sha256") != _digest(library):
+            raise RuntimeError("Native graph build integrity verification failed")
+        _verify(library)
+        return library
+    with tempfile.TemporaryDirectory(prefix="synkit-canon-build-", dir=output) as name:
+        work = Path(name)
+        configure = [cmake, "-S", str(source), "-B", str(work), "-DCMAKE_BUILD_TYPE=Release"]
+        if compiler:
+            configure.append("-DCMAKE_CXX_COMPILER=" + compiler)
+        _run(configure)
+        _run([cmake, "--build", str(work), "--config", "Release", "--parallel", "2"])
+        built = list(work.rglob("*synkit_canon" + suffix))
+        if len(built) != 1:
+            raise RuntimeError(f"Expected one native graph library, found {built}")
+        _verify(built[0])
+        cache = (work / "CMakeCache.txt").read_text()
+        shutil.copy2(built[0], library)
+        manifest.write_text(json.dumps({
+            "configuration": config, "library_sha256": _digest(library),
+            "cmake_cache": cache,
+        }, indent=2) + "\n")
+    return library

synkit/Graph/Canon/_native/prepare.py

@@ -0,0 +1,49 @@
+"""Snapshot exact typed colors and simple graph incidence for the native core."""
+
+from dataclasses import dataclass
+import json
+
+import networkx as nx
+
+from ..exact import _encode_color, _selector_value
+
+
+@dataclass(frozen=True)
+class PreparedGraph:
+    """Immutable Python-owned CSR snapshot; input handles are output witnesses."""
+
+    nodes: tuple
+    offsets: tuple[int, ...]
+    neighbors: tuple[int, ...]
+    colors: tuple[int, ...]
+    palette_bytes: bytes
+
+
+def prepare_graph(graph, *, node_color="color", edge_color=None):
+    """Prepare a simple undirected vertex-colored graph without normalization.
+
+    Edge attributes are intentionally outside this prepared graph contract.
+    An explicit edge-color selector is refused; encode typed edges as colored
+    incidence vertices first, as the stereo expansion already does.
+    """
+    if not isinstance(graph, nx.Graph) or graph.is_directed() or graph.is_multigraph():
+        raise TypeError("Native graph search requires a simple undirected graph")
+    if edge_color is not None:
+        raise NotImplementedError("Encode edge colors as incidence vertices before native search")
+    if nx.number_of_selfloops(graph):
+        raise ValueError("Native graph search does not support self loops")
+    nodes = tuple(graph)
+    if len(nodes) > 2**31 - 1:
+        raise ValueError("Native graph dimensions exceed int32 vertex capacity")
+    tokens = tuple(_encode_color(_selector_value(graph.nodes[v], node_color)) for v in nodes)
+    palette = sorted(set(tokens))
+    ranks = {token: i for i, token in enumerate(palette)}
+    indices = {v: i for i, v in enumerate(nodes)}
+    offsets, neighbors = [0], []
+    for v in nodes:
+        neighbors.extend(sorted(indices[w] for w in graph[v]))
+        offsets.append(len(neighbors))
+    return PreparedGraph(
+        nodes, tuple(offsets), tuple(neighbors), tuple(ranks[t] for t in tokens),
+        json.dumps(palette, separators=(",", ":"), ensure_ascii=True).encode("ascii"),
+    )

synkit/Graph/Canon/_native/runtime.py

@@ -0,0 +1,140 @@
+"""Versioned ctypes declarations and cancellation ownership for graph search."""
+
+import ctypes as ct
+from contextlib import contextmanager
+from functools import lru_cache
+from pathlib import Path
+from threading import Lock
+
+from synkit._native import bundled_library, verify_wheel_library
+
+
+def bundled_native_canon():
+    """Return the graph/stereograph library installed with a platform wheel."""
+    return bundled_library(Path(__file__).parent, "synkit_canon")
+
+
+def resolve_library_path(library_path=None):
+    return (Path(library_path).expanduser().resolve()
+            if library_path is not None else bundled_native_canon())
+
+
+class Request(ct.Structure):
+    _fields_ = [
+        ("abi_version", ct.c_int32), ("struct_size", ct.c_int32),
+        ("n", ct.c_int64), ("arcs", ct.c_int64),
+        ("offsets", ct.POINTER(ct.c_int64)),
+        ("neighbors", ct.POINTER(ct.c_int32)),
+        ("colors", ct.POINTER(ct.c_int32)), ("seconds", ct.c_double),
+        ("max_nodes", ct.c_int64), ("workspace_bytes", ct.c_int64),
+        ("output_bytes", ct.c_int64), ("max_depth", ct.c_int32),
+        ("cancel_token", ct.c_void_p),
+    ]
+
+
+class Statistics(ct.Structure):
+    _fields_ = [
+        ("complete", ct.c_int32), ("reason", ct.c_int32),
+        ("nodes", ct.c_int64), ("leaves", ct.c_int64),
+        ("refinement_rounds", ct.c_int64), ("peak_workspace_bytes", ct.c_int64),
+        ("elapsed_seconds", ct.c_double),
+        ("validation_seconds", ct.c_double), ("search_seconds", ct.c_double),
+        ("serialization_seconds", ct.c_double),
+    ]
+
+
+class PruningStatistics(ct.Structure):
+    _fields_ = [(name, ct.c_int64) for name in (
+        "implicit_twin_factors", "twin_vertices", "automorphism_generators", "orbit_rebuilds",
+        "symmetry_pruned_branches", "stabilizer_calls", "stabilizer_fallbacks",
+    )]
+
+
+@lru_cache(maxsize=8)
+def load_library(path):
+    """Load a selected library without compiling or selecting a fallback."""
+    path = Path(path).expanduser().resolve()
+    if path.parent == Path(__file__).resolve().parent / "lib":
+        verify_wheel_library(path)
+    lib = ct.CDLL(str(path))
+    if lib.synkit_canon_abi() != 1:
+        raise RuntimeError("Unsupported graph canonicalization ABI")
+    lib.synkit_canon_error.restype = ct.c_char_p
+    lib.synkit_canon_search.argtypes = [ct.POINTER(Request), ct.POINTER(ct.c_void_p)]
+    lib.synkit_canon_search.restype = ct.c_int
+    lib.synkit_canon_statistics.argtypes = [ct.c_void_p]
+    lib.synkit_canon_statistics.restype = ct.POINTER(Statistics)
+    if hasattr(lib, "synkit_canon_pruning_statistics"):
+        lib.synkit_canon_pruning_statistics.argtypes = [ct.c_void_p]
+        lib.synkit_canon_pruning_statistics.restype = ct.POINTER(PruningStatistics)
+    lib.synkit_canon_bytes.argtypes = [ct.c_void_p, ct.POINTER(ct.c_int64)]
+    lib.synkit_canon_bytes.restype = ct.POINTER(ct.c_uint8)
+    lib.synkit_canon_order.argtypes = [ct.c_void_p, ct.POINTER(ct.c_int64)]
+    lib.synkit_canon_order.restype = ct.POINTER(ct.c_int32)
+    lib.synkit_canon_free.argtypes = [ct.c_void_p]
+    lib.synkit_canon_free.restype = None
+    lib.synkit_canon_cancel_create.restype = ct.c_void_p
+    for name in ("synkit_canon_cancel_request", "synkit_canon_cancel_free"):
+        getattr(lib, name).argtypes = [ct.c_void_p]
+        getattr(lib, name).restype = None
+    return lib
+
+
+class CancellationToken:
+    """Own a one-shot native cancellation flag shared by explicitly chosen calls."""
+
+    def __init__(self, library_path=None):
+        self.library = load_library(str(resolve_library_path(library_path)))
+        self._lock = Lock()
+        self._active = 0
+        self._cancelled = False
+        self._handle = self.library.synkit_canon_cancel_create()
+        if not self._handle:
+            raise MemoryError("Cannot allocate native cancellation token")
+
+    @contextmanager
+    def borrow(self, library):
+        """Keep the token alive until the native call has returned."""
+        with self._lock:
+            if not self._handle:
+                raise RuntimeError("Cancellation token is closed")
+            if library is not self.library:
+                raise ValueError("Cancellation token belongs to a different library")
+            self._active += 1
+            handle = self._handle
+        try:
+            yield handle
+        finally:
+            with self._lock:
+                self._active -= 1
+
+    def cancel(self):
+        """Request cancellation without waiting for the active search."""
+        with self._lock:
+            if not self._handle:
+                raise RuntimeError("Cancellation token is closed")
+            self._cancelled = True
+            self.library.synkit_canon_cancel_request(self._handle)
+
+    @property
+    def cancelled(self):
+        return self._cancelled
+
+    def close(self):
+        """Free an idle token; refuse to invalidate a running call's pointer."""
+        with self._lock:
+            if self._active:
+                raise RuntimeError("Cancellation token is in use")
+            if self._handle:
+                self.library.synkit_canon_cancel_free(self._handle)
+                self._handle = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *unused):
+        self.close()
+
+    def __del__(self):
+        if getattr(self, "_handle", None) and not getattr(self, "_active", 0):
+            self.library.synkit_canon_cancel_free(self._handle)

synkit/Graph/Canon/_native/search.py

@@ -0,0 +1,137 @@
+"""Bounded sparse graph canonicalization under an explicit native convention."""
+
+from contextlib import nullcontext
+import ctypes as ct
+from dataclasses import dataclass
+import hashlib
+import math
+from numbers import Integral, Real
+import struct
+from time import perf_counter
+
+from ..exact import CanonicalSearchIncomplete
+from .prepare import prepare_graph
+from .runtime import Request, load_library
+
+SCHEMA = "synkit.native-sparse-canonical-graph/1"
+REASONS = {0: None, 1: "time_limit", 2: "node_limit", 3: "workspace_limit",
+           4: "output_limit", 5: "cancelled", 6: "depth_limit"}
+
+
+@dataclass(frozen=True)
+class NativeCanonicalResult:
+    """Exact native certificate or a stopped request without any usable key."""
+
+    complete: bool
+    reason: str | None
+    canonical_code: bytes | None
+    canonical_order: tuple
+    statistics: dict
+    schema: str = SCHEMA
+
+    @property
+    def exact(self):
+        return self.complete
+
+    @property
+    def canonical_digest(self):
+        return hashlib.sha256(self.canonical_code).hexdigest() if self.complete else None
+
+    def require_complete(self):
+        """Refuse promotion of bounded-search evidence to an identity key."""
+        if not self.complete:
+            raise CanonicalSearchIncomplete(f"Native canonical search is incomplete: {self.reason}")
+        return self
+
+    def same_canonical_graph(self, other):
+        """Compare full same-convention bytes; unfinished requests raise."""
+        self.require_complete()
+        if not isinstance(other, NativeCanonicalResult) or other.schema != self.schema:
+            raise TypeError("Cannot compare different canonical conventions")
+        other.require_complete()
+        return self.canonical_code == other.canonical_code
+
+
+def _cap(value, name):
+    if value is None:
+        return -1
+    if isinstance(value, bool) or not isinstance(value, Integral) or not 0 < value < 2**63:
+        raise ValueError(f"{name} must be a positive int64 or None")
+    return int(value)
+
+
+def _timeout(value):
+    if value is None:
+        return -1.0
+    if isinstance(value, bool) or not isinstance(value, Real) or not math.isfinite(value) or value < 0:
+        raise ValueError("timeout_seconds must be finite and nonnegative, or None")
+    return float(value)
+
+
+def canonicalize_native_graph(
+    graph, *, library_path=None, node_color="color", edge_color=None,
+    timeout_seconds=None, max_search_nodes=None, max_workspace_bytes=None,
+    max_output_bytes=None, max_depth=1024, cancel_token=None,
+):
+    """Canonicalize a simple colored graph with an explicitly selected library.
+
+    The new sparse byte convention is NOT interchangeable with the reference
+    JSON certificate. The deadline includes Python preparation but its checks
+    there are cooperative (before/after stages). Workspace bounds tracked
+    native allocations, not Python/NetworkX or process RSS. No group is emitted.
+    """
+    started = perf_counter()
+    seconds = _timeout(timeout_seconds)
+    caps = [_cap(v, n) for v, n in (
+        (max_search_nodes, "max_search_nodes"), (max_workspace_bytes, "max_workspace_bytes"),
+        (max_output_bytes, "max_output_bytes"),
+    )]
+    if isinstance(max_depth, bool) or not isinstance(max_depth, Integral) or not 0 <= max_depth <= 1024:
+        raise ValueError("max_depth must be an integer between zero and 1024")
+    from .runtime import resolve_library_path
+
+    library = load_library(str(resolve_library_path(library_path)))
+    prepared = prepare_graph(graph, node_color=node_color, edge_color=edge_color)
+    preparation = perf_counter() - started
+    n = len(prepared.nodes)
+    offsets = (ct.c_int64 * (n + 1))(*prepared.offsets)
+    neighbors = (ct.c_int32 * len(prepared.neighbors))(*prepared.neighbors)
+    colors = (ct.c_int32 * n)(*prepared.colors)
+    prefix = SCHEMA.encode("ascii") + b"\0" + struct.pack("<Q", len(prepared.palette_bytes)) + prepared.palette_bytes
+    output_limit = caps[2] - len(prefix) if caps[2] >= 0 else -1
+    if caps[2] >= 0 and output_limit <= 0:
+        return NativeCanonicalResult(False, "output_limit", None, (), {"preparation_seconds": preparation})
+    remaining = max(0.0, seconds - (perf_counter() - started)) if seconds >= 0 else -1.0
+    context = cancel_token.borrow(library) if cancel_token is not None else nullcontext(None)
+    with context as token:
+        request = Request(1, ct.sizeof(Request), n, len(prepared.neighbors), offsets,
+                          neighbors, colors, remaining, caps[0], caps[1], output_limit, int(max_depth), token)
+        handle = ct.c_void_p()
+        if library.synkit_canon_search(ct.byref(request), ct.byref(handle)):
+            raise ValueError(library.synkit_canon_error().decode("utf-8"))
+        try:
+            stat = library.synkit_canon_statistics(handle).contents
+            metrics = {name: getattr(stat, name) for name, _ in stat._fields_}
+            if hasattr(library, "synkit_canon_pruning_statistics"):
+                pruning = library.synkit_canon_pruning_statistics(handle).contents
+                metrics.update((name, getattr(pruning, name)) for name, _ in pruning._fields_)
+            metrics["preparation_seconds"] = preparation
+            metrics["packing_seconds"] = max(0.0, perf_counter() - started - preparation - stat.elapsed_seconds)
+            if not stat.complete:
+                return NativeCanonicalResult(False, REASONS[stat.reason], None, (), metrics)
+            size = ct.c_int64()
+            data = library.synkit_canon_bytes(handle, ct.byref(size))
+            code = prefix + ct.string_at(data, size.value)
+            order = library.synkit_canon_order(handle, ct.byref(size))
+            indices = tuple(order[i] for i in range(size.value))
+            if len(indices) != n or set(indices) != set(range(n)):
+                raise RuntimeError("Native graph core returned an invalid permutation")
+            elapsed = perf_counter() - started
+            metrics["total_seconds"] = elapsed
+            if cancel_token is not None and cancel_token.cancelled:
+                return NativeCanonicalResult(False, "cancelled", None, (), metrics)
+            if seconds >= 0 and elapsed >= seconds:
+                return NativeCanonicalResult(False, "time_limit", None, (), metrics)
+            return NativeCanonicalResult(True, None, code, tuple(prepared.nodes[i] for i in indices), metrics)
+        finally:
+            library.synkit_canon_free(handle)