Replace the cyclic graph hash #34

Author: LouieSlocombe

README.md

@@ -87,7 +87,7 @@ the same argument using `=`. Boolean values must be exactly `0` (disabled) or
 | `--remove-hydrogens=<0\|1>` | Boolean | `1` | Remove explicit hydrogen atoms from molfile inputs before calculation. This has no effect on native graph inputs. |
 | `--compensate-disjoint=<0\|1>` | Boolean | `0` | Subtract one from final and intermediate assembly indices for every component after the first in the processed graph. For molfiles, components are counted after optional hydrogen removal. Empty graphs receive no adjustment. |
 | `--memory-report=<0\|1>` | Boolean | `0` | After the other calculation outputs are written successfully on Linux, write `/proc/self/status`'s peak virtual-memory value (`VmPeak`, in kB) to `memUsage` in the current working directory. The option has no output on other platforms. |
-| `--telemetry=<0\|1>` | Boolean | `0` | In a telemetry-enabled build, write retained-mask and matching counts, canonicalisation/VF2 activity, cache rates, and phase-specific memory to `INPUTTelemetry.json`. |
+| `--telemetry=<0\|1>` | Boolean | `0` | In a telemetry-enabled build, write retained-mask and matching counts, canonicalisation activity, legacy VF2 counters, cache rates, and phase-specific memory to `INPUTTelemetry.json`. The current exact cyclic canonicaliser does not invoke VF2, so those compatibility counters remain zero. |
 | `--write-intermediate-mas=<0\|1>` | Boolean | `0` | Write each newly found best assembly index and its elapsed `std::clock` tick to `INPUTIntermediateMAs`. |
 
 The runtime and enumeration limits can stop an exhaustive search. `INPUTOut`

benchmarks/README.md

@@ -89,16 +89,17 @@ cautiously when a suite contains millisecond-scale cases.
 JSON schema version 2 retains every timed sample, case metadata, aggregate
 summaries, the deterministic schedule, platform information, executable
 fingerprints, and optional candidate telemetry. Telemetry includes the raw
-processed graph size, retained masks, matching visits, canonicalisation and VF2
-calls, canonical/residual/assembly/pair-bound cache rates, and absolute resident
-peak memory for setup, initial enumeration, DAG conversion, assembly search,
-and output. A cache rate is `null` when no lookup occurred.
+processed graph size, retained masks, matching visits, canonicalisation activity,
+legacy VF2 counters, canonical/residual/assembly/pair-bound cache rates, and
+absolute resident peak memory for setup, initial enumeration, DAG conversion,
+assembly search, and output. A cache rate is `null` when no lookup occurred.
 
 `retained_masks` counts unique initial-DAG masks accepted within the enumeration
 limit, including one-edge roots. `matching_visits` counts valid materialised
 duplicate pairs delivered to the search visitor. `canonicalisation_calls`
-includes canonical-mask cache hits, while `vf2_calls` counts actual exact graph
-isomorphism invocations. The residual lookup hit rate excludes first-occurrence,
+includes canonical-mask cache hits. `vf2_calls` and `vf2_matches` are retained for
+schema compatibility and remain zero now that exact cyclic canonical codes replace
+VF2. The residual lookup hit rate excludes first-occurrence,
 small-residual, and disabled-cache bypasses; the request hit rate includes them.
 Wide caches sample up to 6,144 residuals and return to direct decomposition when
 no hit demonstrates reuse, so unique workloads do not keep paying lookup cost.

unitTests/README.md

@@ -30,10 +30,14 @@ the ordinary CLI and regression checks; telemetry-only checks are detected and
 skipped. Use a separately compiled portable executable on older x86-64 or
 non-x86 systems.
 
-The build path also runs focused active-word mask and iterative tree-
-canonicalisation tests. On Linux the tree tests use a 64 KiB stack and include
-32,766- and 32,767-node labelled paths, preventing recursive traversal from
-returning unnoticed for either centroid shape.
+The build path also runs focused active-word mask, iterative tree-
+canonicalisation, and cyclic-canonicalisation tests. The cyclic tests compare
+the exact coloured-2-core form with VF2 across vertex permutations, atom and
+bond labels, pendant trees, disconnected fallbacks, multiedges, and regular
+graphs that colour refinement alone cannot distinguish. On Linux the tree
+tests use a 64 KiB stack and include 32,766- and 32,767-node labelled paths,
+preventing recursive traversal from returning unnoticed for either centroid
+shape.
 
 Run the manifest and fixture integrity audit with: