synkit 1.6.0__tar.gz → 1.6.1__tar.gz

synkit-1.6.1/.gitignore

@@ -0,0 +1,108 @@
+*.pyc
+*cachedir
+*.csv
+!Experiment/Lewis/Data/all.csv
+!Experiment/Lewis/Data/combinatorial_all.csv
+!Experiment/Lewis/mech_path/Data/reconstruction_audit/polar-failures.csv
+!Experiment/Lewis/mech_path/Data/reconstruction_audit/radical-failures.csv
+!Experiment/Lewis/mech_path/Data/reconstruction_audit/radical-arrow-review.csv
+*/catboost_info/*
+
+
+*.pkl.gz
+*.pdf
+
+.coverage
+dev/*
+/debug/
+/Test/Conformance/
+*.rdf
+test_syn_reactor.py
+
+Data/Benchmark/*
+!Data/Benchmark/partial_expand/
+!Data/Benchmark/partial_expand/**
+Data/Benchmark/partial_expand/results/
+!Data/Benchmark/mech/
+Data/Benchmark/mech/*
+!Data/Benchmark/mech/README.md
+!Data/Benchmark/mech/polar-failures.csv
+!Data/Benchmark/mech/radical-failures.csv
+*.json.gz
+!Experiment/Lewis/Data/benchmark.json.gz
+# *.png
+
+run.sh
+docs/*
+run_rdcanon.py
+Data/Fragment/*
+test_partial.py
+Data/Benchmark/synthesis/*
+Data/USPTO/*
+crn/*
+test_run.py
+Data/Study/CRN/case_formose/*
+
+synkit/Graph/dev/*
+*.ipynb
+*.json
+# Stereo benchmark inputs are versioned for reproducible fresh-clone runs.
+# Generated reports stay Git-visible so completed results can be committed
+# explicitly, including reports created by the long raw stress stages.
+!Experiment/Stereo/Data/**/*.csv
+!Experiment/Stereo/Data/**/*.json
+!Data/Schema/
+!Data/Schema/attribute_propagation_v1_5.json
+!/tools/python_file_size_baseline.json
+!Data/Mech/polar.json
+!Data/Mech/radical.json
+!Data/Mech/stereo.json
+!Experiment/Lewis/Data/hydrogen.pkl.gz
+# Canonical reviewed MechanismBench partitions are executable test data.
+!Experiment/Lewis/mech_path/Data/MechanismBench/polar.json
+!Experiment/Lewis/mech_path/Data/MechanismBench/radical.json
+!Experiment/Lewis/mech_path/Data/MechanismBench/stereo.json
+!Experiment/Lewis/mech_path/Data/MechanismBench/electrocyclic_machinery.json
+!Experiment/Lewis/mech_path/Data/MechanismBench/stereo_branch_coverage.json
+!Experiment/Lewis/mech_path/Data/MechanismBench/stereo_couplings.json
+!Experiment/Lewis/mech_path/Data/MechanismBench/evidence/mechanismbench_evidence.json
+!Experiment/Lewis/rule_replay/Data/bidirectional-replay/results.json
+!Experiment/Lewis/rule_replay/Data/relative-lone-pair/results.json
+!Experiment/Stereo/Data/manifest.json
+!Experiment/Stereo/Data/Perception/perception_conformance_cases.json
+!Experiment/Stereo/Data/Perception/full_detection_report.json
+!Test/Synthesis/Reactor/fixtures/small_rewrite_conformance.json
+!Data/Conformance/stereomolgraph_graph_conformance.json
+!Data/Benchmark/Stereo/
+!Data/Benchmark/Stereo/**
+*.txt
+!LICENSES/*.txt
+*.log
+/dist/
+sprint/
+sprint/*
+test_syn.py
+.gitignore
+measure_candidate_stages.py
+run_valid_bug_cases.py
+paper/*
+# Nested standalone Git repository.
+/paper/og_paper/
+
+# Fresh benchmark runs are reproducible and can be large. Retained reference
+# outputs live inside each experiment's Data directory.
+Experiment/Lewis/Runs/
+
+# Generated FLOWER intermediates and long-run evidence. The portable
+# full-reaction batch payload is intentionally retained in Git.
+Experiment/Lewis/FLOWER/batches/
+Experiment/Lewis/FLOWER/full_reactions/
+Experiment/Lewis/FLOWER/replay-debug/
+Experiment/Lewis/FLOWER/replay-runs/
+Experiment/Lewis/FLOWER/replay-results*/
+!Experiment/Lewis/FLOWER/full-reaction-batches/manifest.json
+!Experiment/Lewis/FLOWER/full-reaction-replay-summary.json
+
+# Keep generated Python bytecode ignored after directory re-inclusions above.
+**/__pycache__/
+*.py[cod]

synkit-1.6.1/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: synkit
+Version: 1.6.1
+Summary: Utility for reaction modeling using graph grammar
+Project-URL: homepage, https://github.com/TieuLongPhan/SynKit
+Project-URL: source, https://github.com/TieuLongPhan/SynKit
+Project-URL: issues, https://github.com/TieuLongPhan/SynKit/issues
+Project-URL: documentation, https://tieulongphan.github.io/SynKit/
+Author-email: Tieu Long Phan <tieu@bioinf.uni-leipzig.de>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: networkx>=3.3
+Requires-Dist: pandas>=1.5.3
+Requires-Dist: rdkit>=2025.3.1
+Requires-Dist: regex>=2024.11.6
+Requires-Dist: requests>=2.32.3
+Requires-Dist: scikit-learn>=1.4.0
+Requires-Dist: scipy>=1.14.0
+Requires-Dist: seaborn>=0.13.2
+Provides-Extra: all
+Requires-Dist: numpy>=2.2.0; extra == 'all'
+Requires-Dist: sympy>=1.13.1; extra == 'all'
+Requires-Dist: torch>=2.2.0; extra == 'all'
+Provides-Extra: docs
+Requires-Dist: graphviz; extra == 'docs'
+Requires-Dist: myst-parser; extra == 'docs'
+Requires-Dist: pydata-sphinx-theme; extra == 'docs'
+Requires-Dist: sphinx-copybutton; extra == 'docs'
+Requires-Dist: sphinx-design; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme; extra == 'docs'
+Requires-Dist: sphinx-togglebutton; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Requires-Dist: sphinxcontrib-bibtex; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# SynKit
+
+[![PyPI version](https://img.shields.io/pypi/v/synkit.svg)](https://pypi.org/project/synkit/)
+[![Conda version](https://img.shields.io/conda/vn/tieulongphan/synkit.svg)](https://anaconda.org/tieulongphan/synkit)
+[![Docker Pulls](https://img.shields.io/docker/pulls/tieulongphan/synkit.svg)](https://hub.docker.com/r/tieulongphan/synkit)
+[![Docker Image Version](https://img.shields.io/docker/v/tieulongphan/synkit/latest?label=container)](https://hub.docker.com/r/tieulongphan/synkit)
+[![License](https://img.shields.io/github/license/tieulongphan/synkit.svg)](https://github.com/tieulongphan/synkit/blob/main/LICENSE)
+[![Release](https://img.shields.io/github/v/release/tieulongphan/synkit.svg)](https://github.com/tieulongphan/synkit/releases)
+[![Last Commit](https://img.shields.io/github/last-commit/tieulongphan/synkit.svg)](https://github.com/tieulongphan/synkit/commits)
+[![Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.15269901.svg)](https://doi.org/10.5281/zenodo.15269901)
+[![CI](https://github.com/tieulongphan/synkit/actions/workflows/test-and-lint.yml/badge.svg?branch=main)](https://github.com/tieulongphan/synkit/actions/workflows/test-and-lint.yml)
+[![Stars](https://img.shields.io/github/stars/tieulongphan/synkit.svg?style=social&label=Star)](https://github.com/tieulongphan/synkit/stargazers)
+
+**Graph-native reaction informatics and executable electron-flow models**
+
+SynKit is a Python toolkit for atom-mapped reactions, chemical graph
+transformations, Lewis-labelled graphs, and explicitly supplied reaction
+mechanisms. It connects reaction representation, rule extraction, graph
+rewriting, stereochemistry, and mechanism verification through a common
+attributed-graph model.
+
+SynKit verifies mechanisms supplied by the user; it does not claim to predict
+the kinetically or thermodynamically preferred mechanism.
+
+![SynKit graphical abstract](https://raw.githubusercontent.com/TieuLongPhan/SynKit/main/Data/Figure/synkit_graphical_abstract.svg)
+
+## Highlights
+
+- Convert mapped reaction SMILES into ITS and reaction-centre graphs.
+- Extract and apply attributed graph-transformation rules.
+- Represent lone pairs, radicals, and separate sigma and pi occupancies with
+  Lewis-labelled graphs.
+- Execute curved-arrow and atomically coupled fishhook events.
+- Preserve tetrahedral, axial, and extended stereochemical information.
+- Build and analyse mechanism trajectory graphs and chemical reaction
+  networks.
+
+## Installation
+
+SynKit requires Python 3.11 or later.
+
+```bash
+python -m pip install synkit
+```
+
+Install the optional dependencies with:
+
+```bash
+python -m pip install "synkit[all]"
+```
+
+Alternatively, use the published container:
+
+```bash
+docker pull tieulongphan/synkit:latest
+docker run --rm tieulongphan/synkit:latest \
+  python -c "import synkit; print(synkit.__version__)"
+```
+
+## Quick start
+
+This self-contained example converts an atom-mapped substitution into an
+imaginary transition-state graph and reports its changed bonds:
+
+```python
+from synkit.IO import rsmi_to_its
+
+reaction = "[CH3:1][Br:2].[OH-:3]>>[CH3:1][OH:3].[Br-:2]"
+its = rsmi_to_its(reaction, core=False, format="tuple")
+
+changed_bonds = [
+    (source, target, data["order"])
+    for source, target, data in its.edges(data=True)
+    if data["order"][0] != data["order"][1]
+]
+print(changed_bonds)
+```
+
+The output records the broken C-Br bond as `(1.0, 0.0)` and the formed C-O
+bond as `(0.0, 1.0)`. Continue with the
+[graph](https://tieulongphan.github.io/SynKit/graph.html),
+[rule](https://tieulongphan.github.io/SynKit/rule.html), and
+[synthesis](https://tieulongphan.github.io/SynKit/synthesis.html) guides.
+
+## Supplied-mechanism verification
+
+SynKit can parse typed electron-flow annotations, replay their elementary
+steps, and return a verification certificate and mechanism trajectory graph.
+Canonical electron loci distinguish lone pairs, sigma bonds, pi bonds, and
+radical electrons. Curved arrows carry two electrons; fishhooks carry one;
+coupled radical events commit atomically from a common pre-state.
+
+See the
+[mechanism documentation](https://tieulongphan.github.io/SynKit/mechanism.html)
+for the supported interchange formats, verification policies, and complete
+examples.
+
+## Documentation
+
+- [Documentation](https://tieulongphan.github.io/SynKit/)
+- [API reference](https://tieulongphan.github.io/SynKit/api/index.html)
+- [Issue tracker](https://github.com/TieuLongPhan/SynKit/issues)
+- [Changelog](doc/changelog.rst)
+
+## Publications
+
+- [Lewis-labeled graphs: curly arrows and fishhooks as executable electron
+  transfers](https://arxiv.org/abs/2607.26088), arXiv:2607.26088 (2026).
+- [SynKit: A Graph-Based Python Framework for Rule-Based Reaction Modeling and
+  Analysis](https://pubs.acs.org/doi/full/10.1021/acs.jcim.5c02123), *Journal
+  of Chemical Information and Modeling* (2025).
+
+## Contributing
+
+Contributions and bug reports are welcome. Create a branch from the current
+mainline, make a focused change, and run the repository checks before opening
+a pull request:
+
+```bash
+git switch -c feature/short-description
+bash scripts/lint.sh
+bash scripts/pytest.sh
+```
+
+Questions can be sent to
+[tieu@bioinf.uni-leipzig.de](mailto:tieu@bioinf.uni-leipzig.de).
+
+## Contributors
+
+- [Tieu-Long Phan](https://tieulongphan.github.io/)
+- [Klaus Weinbauer](https://github.com/klausweinbauer)
+- [Phuoc-Chung Nguyen Van](https://github.com/phuocchung123)
+- [Tuyet-Minh Phan](https://github.com/tuyetminhphan)
+
+## License
+
+SynKit is distributed under the MIT License. See [LICENSE](LICENSE).
+
+## Acknowledgments
+
+This project received funding from the European Union's Horizon Europe
+Doctoral Network programme under Marie Skłodowska-Curie grant agreement No.
+101072930 ([TACsy](https://tacsy.eu/)).

synkit-1.6.1/README.md

@@ -0,0 +1,143 @@
+# SynKit
+
+[![PyPI version](https://img.shields.io/pypi/v/synkit.svg)](https://pypi.org/project/synkit/)
+[![Conda version](https://img.shields.io/conda/vn/tieulongphan/synkit.svg)](https://anaconda.org/tieulongphan/synkit)
+[![Docker Pulls](https://img.shields.io/docker/pulls/tieulongphan/synkit.svg)](https://hub.docker.com/r/tieulongphan/synkit)
+[![Docker Image Version](https://img.shields.io/docker/v/tieulongphan/synkit/latest?label=container)](https://hub.docker.com/r/tieulongphan/synkit)
+[![License](https://img.shields.io/github/license/tieulongphan/synkit.svg)](https://github.com/tieulongphan/synkit/blob/main/LICENSE)
+[![Release](https://img.shields.io/github/v/release/tieulongphan/synkit.svg)](https://github.com/tieulongphan/synkit/releases)
+[![Last Commit](https://img.shields.io/github/last-commit/tieulongphan/synkit.svg)](https://github.com/tieulongphan/synkit/commits)
+[![Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.15269901.svg)](https://doi.org/10.5281/zenodo.15269901)
+[![CI](https://github.com/tieulongphan/synkit/actions/workflows/test-and-lint.yml/badge.svg?branch=main)](https://github.com/tieulongphan/synkit/actions/workflows/test-and-lint.yml)
+[![Stars](https://img.shields.io/github/stars/tieulongphan/synkit.svg?style=social&label=Star)](https://github.com/tieulongphan/synkit/stargazers)
+
+**Graph-native reaction informatics and executable electron-flow models**
+
+SynKit is a Python toolkit for atom-mapped reactions, chemical graph
+transformations, Lewis-labelled graphs, and explicitly supplied reaction
+mechanisms. It connects reaction representation, rule extraction, graph
+rewriting, stereochemistry, and mechanism verification through a common
+attributed-graph model.
+
+SynKit verifies mechanisms supplied by the user; it does not claim to predict
+the kinetically or thermodynamically preferred mechanism.
+
+![SynKit graphical abstract](https://raw.githubusercontent.com/TieuLongPhan/SynKit/main/Data/Figure/synkit_graphical_abstract.svg)
+
+## Highlights
+
+- Convert mapped reaction SMILES into ITS and reaction-centre graphs.
+- Extract and apply attributed graph-transformation rules.
+- Represent lone pairs, radicals, and separate sigma and pi occupancies with
+  Lewis-labelled graphs.
+- Execute curved-arrow and atomically coupled fishhook events.
+- Preserve tetrahedral, axial, and extended stereochemical information.
+- Build and analyse mechanism trajectory graphs and chemical reaction
+  networks.
+
+## Installation
+
+SynKit requires Python 3.11 or later.
+
+```bash
+python -m pip install synkit
+```
+
+Install the optional dependencies with:
+
+```bash
+python -m pip install "synkit[all]"
+```
+
+Alternatively, use the published container:
+
+```bash
+docker pull tieulongphan/synkit:latest
+docker run --rm tieulongphan/synkit:latest \
+  python -c "import synkit; print(synkit.__version__)"
+```
+
+## Quick start
+
+This self-contained example converts an atom-mapped substitution into an
+imaginary transition-state graph and reports its changed bonds:
+
+```python
+from synkit.IO import rsmi_to_its
+
+reaction = "[CH3:1][Br:2].[OH-:3]>>[CH3:1][OH:3].[Br-:2]"
+its = rsmi_to_its(reaction, core=False, format="tuple")
+
+changed_bonds = [
+    (source, target, data["order"])
+    for source, target, data in its.edges(data=True)
+    if data["order"][0] != data["order"][1]
+]
+print(changed_bonds)
+```
+
+The output records the broken C-Br bond as `(1.0, 0.0)` and the formed C-O
+bond as `(0.0, 1.0)`. Continue with the
+[graph](https://tieulongphan.github.io/SynKit/graph.html),
+[rule](https://tieulongphan.github.io/SynKit/rule.html), and
+[synthesis](https://tieulongphan.github.io/SynKit/synthesis.html) guides.
+
+## Supplied-mechanism verification
+
+SynKit can parse typed electron-flow annotations, replay their elementary
+steps, and return a verification certificate and mechanism trajectory graph.
+Canonical electron loci distinguish lone pairs, sigma bonds, pi bonds, and
+radical electrons. Curved arrows carry two electrons; fishhooks carry one;
+coupled radical events commit atomically from a common pre-state.
+
+See the
+[mechanism documentation](https://tieulongphan.github.io/SynKit/mechanism.html)
+for the supported interchange formats, verification policies, and complete
+examples.
+
+## Documentation
+
+- [Documentation](https://tieulongphan.github.io/SynKit/)
+- [API reference](https://tieulongphan.github.io/SynKit/api/index.html)
+- [Issue tracker](https://github.com/TieuLongPhan/SynKit/issues)
+- [Changelog](doc/changelog.rst)
+
+## Publications
+
+- [Lewis-labeled graphs: curly arrows and fishhooks as executable electron
+  transfers](https://arxiv.org/abs/2607.26088), arXiv:2607.26088 (2026).
+- [SynKit: A Graph-Based Python Framework for Rule-Based Reaction Modeling and
+  Analysis](https://pubs.acs.org/doi/full/10.1021/acs.jcim.5c02123), *Journal
+  of Chemical Information and Modeling* (2025).
+
+## Contributing
+
+Contributions and bug reports are welcome. Create a branch from the current
+mainline, make a focused change, and run the repository checks before opening
+a pull request:
+
+```bash
+git switch -c feature/short-description
+bash scripts/lint.sh
+bash scripts/pytest.sh
+```
+
+Questions can be sent to
+[tieu@bioinf.uni-leipzig.de](mailto:tieu@bioinf.uni-leipzig.de).
+
+## Contributors
+
+- [Tieu-Long Phan](https://tieulongphan.github.io/)
+- [Klaus Weinbauer](https://github.com/klausweinbauer)
+- [Phuoc-Chung Nguyen Van](https://github.com/phuocchung123)
+- [Tuyet-Minh Phan](https://github.com/tuyetminhphan)
+
+## License
+
+SynKit is distributed under the MIT License. See [LICENSE](LICENSE).
+
+## Acknowledgments
+
+This project received funding from the European Union's Horizon Europe
+Doctoral Network programme under Marie Skłodowska-Curie grant agreement No.
+101072930 ([TACsy](https://tacsy.eu/)).

{synkit-1.6.0 → synkit-1.6.1}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "synkit"
-version = "1.6.0"
+version = "1.6.1"
 description = "Utility for reaction modeling using graph grammar"
 readme = "README.md"
 requires-python = ">=3.11"
 license = { text = "MIT" }
-license-files = ["LICENSE", "LICENSES/*"]
+license-files = ["LICENSE", "synkit/Graph/Stereo/LICENSES/*"]
 authors = [
   { name = "Tieu Long Phan", email = "tieu@bioinf.uni-leipzig.de" }
 ]
@@ -67,12 +67,10 @@ packages = ["synkit"]
 [tool.hatch.build.targets.wheel.force-include]
 "synkit/Data/aldol.json.gz" = "synkit/Data/aldol.json.gz"
 "synkit/Data/paracetamol.json.gz" = "synkit/Data/paracetamol.json.gz"
-"Data/Mech" = "synkit/Data/Mech"
 
 [tool.hatch.build.targets.sdist]
 include = [
   "/synkit",
-  "/Data/Mech",
   "/LICENSE",
   "/LICENSES",
   "/README.md",
@@ -82,4 +80,3 @@ include = [
 [tool.hatch.build.targets.sdist.force-include]
 "synkit/Data/aldol.json.gz" = "synkit/Data/aldol.json.gz"
 "synkit/Data/paracetamol.json.gz" = "synkit/Data/paracetamol.json.gz"
-"Data/Mech" = "Data/Mech"

{synkit-1.6.0 → synkit-1.6.1}/synkit/CRN/Symmetry/_ir.py

@@ -7,6 +7,13 @@ from typing import Any, Dict, List, Optional, Sequence, Tuple
 
 import networkx as nx
 
+from synkit.Graph.Canon.exact import (
+    CanonicalSearchIncomplete,
+    ExactCanonicalResult,
+    ExactColoredGraphCanonicalizer,
+    IncompleteCanonicalResult,
+)
+
 from ._common import (
     AutomorphismResult,
     CanonicalResult,
@@ -723,6 +730,91 @@ class IRCanonicalEngine:
             Exact-search internal result.
         :rtype: IRInternalResult
         """
+        if max_count is not None or timeout_sec is not None or stop_after_two:
+            return self._run_bounded_compatibility(
+                max_count=max_count,
+                timeout_sec=timeout_sec,
+                stop_after_two=stop_after_two,
+            )
+        cached = self._reuse_cached_run(
+            max_count=max_count,
+            timeout_sec=timeout_sec,
+            stop_after_two=stop_after_two,
+        )
+        if cached is not None:
+            return cached
+
+        native = ExactColoredGraphCanonicalizer(
+            self.G,
+            node_color=lambda attrs: node_token(attrs, self.config),
+            edge_color=lambda attrs: edge_token(attrs, self.config),
+        ).search(timeout_seconds=timeout_sec)
+        if isinstance(native, IncompleteCanonicalResult):
+            raise CanonicalSearchIncomplete(
+                "CRN canonicalization did not complete: " f"{native.reason}."
+            )
+        if not isinstance(native, ExactCanonicalResult):
+            raise RuntimeError("Native exact canonicalizer returned no result.")
+
+        full_mappings = [witness.as_dict() for witness in native.automorphisms]
+        cap = 2 if stop_after_two else max_count
+        stopped = cap is not None and len(full_mappings) > cap
+        sample_mappings = full_mappings if cap is None else full_mappings[:cap]
+        best_order = list(native.canonical_order)
+        sample_perms = [
+            [mapping[node] for node in best_order] for mapping in sample_mappings
+        ]
+        orbits = orbits_from_mappings(
+            best_order,
+            (
+                sample_mappings
+                if sample_mappings
+                else [{node: node for node in best_order}]
+            ),
+        )
+        result = IRInternalResult(
+            canonical_order=best_order,
+            canonical_key=graph_key_from_order(
+                self.G,
+                best_order,
+                self.config,
+            ),
+            automorphism_count=len(sample_mappings),
+            sample_permutations=sample_perms,
+            sample_mappings=sample_mappings,
+            orbits=orbits,
+            elapsed_seconds=native.statistics.elapsed_seconds,
+            stopped_early=stopped,
+        )
+        if timeout_sec is None:
+            full_result = IRInternalResult(
+                canonical_order=best_order,
+                canonical_key=result.canonical_key,
+                automorphism_count=len(full_mappings),
+                sample_permutations=[
+                    [mapping[node] for node in best_order] for mapping in full_mappings
+                ],
+                sample_mappings=full_mappings,
+                orbits=[set(cell) for cell in native.orbits],
+                elapsed_seconds=native.statistics.elapsed_seconds,
+                stopped_early=False,
+            )
+            self._exact_full_cache = full_result
+        return result
+
+    def _run_bounded_compatibility(
+        self,
+        *,
+        max_count: Optional[int],
+        timeout_sec: Optional[float],
+        stop_after_two: bool,
+    ) -> IRInternalResult:
+        """Run the historical bounded diagnostic IR traversal.
+
+        This path preserves CRN automorphism-count and timeout diagnostics.
+        ``stopped_early`` is authoritative: callers may inspect the partial
+        evidence, but :meth:`canonical_result` refuses to promote it.
+        """
         cached = self._reuse_cached_run(
             max_count=max_count,
             timeout_sec=timeout_sec,
@@ -742,7 +834,12 @@ class IRCanonicalEngine:
             nonlocal best_key, best_order, sample_perms, count, stopped
             if stopped:
                 return
-            if should_stop(start, timeout_sec, count=count, max_count=max_count):
+            if should_stop(
+                start,
+                timeout_sec,
+                count=count,
+                max_count=max_count,
+            ):
                 stopped = True
                 return
 
@@ -770,18 +867,25 @@ class IRCanonicalEngine:
 
             target = self._target_cell(refined)
             ordered_candidates = sorted(
-                target, key=lambda v: self._candidate_order_key(v, refined)
+                target,
+                key=lambda value: self._candidate_order_key(
+                    value,
+                    refined,
+                ),
             )
-            for v in ordered_candidates:
-                child = self._build_child_partition(refined, target, v)
+            for value in ordered_candidates:
+                child = self._build_child_partition(
+                    refined,
+                    target,
+                    value,
+                )
                 dfs(child)
                 if stopped:
                     return
 
         dfs(init)
         assert best_key is not None and best_order is not None
-
-        result = self._assemble_result(
+        return self._assemble_result(
             start=start,
             best_key=best_key,
             best_order=best_order,
@@ -789,9 +893,6 @@ class IRCanonicalEngine:
             count=count,
             stopped=stopped,
         )
-        if timeout_sec is None and not result.stopped_early and not stop_after_two:
-            self._exact_full_cache = result
-        return result
 
     def canonical_result(
         self, *, timeout_sec: Optional[float] = None
@@ -808,6 +909,10 @@ class IRCanonicalEngine:
         :rtype: CanonicalResult
         """
         res = self.run(timeout_sec=timeout_sec)
+        if res.stopped_early:
+            raise CanonicalSearchIncomplete(
+                "CRN canonical identity requires a complete search."
+            )
         return CanonicalResult(
             canonical_order=res.canonical_order,
             canonical_key=res.canonical_key,