canns-lib: Rust Acceleration for CANNs

• canns-lib is a Rust acceleration backend that enhances performance-critical components in continuous attractor neural network research.
• It uses a thin PyO3 FFI layer to provide a drop-in replacement for Python code, accelerating persistent homology and spatial navigation tasks.
• Benchmark results show up to 700x speedup over pure-Python implementations, significantly reducing interpreter overhead in key workflows.

canns-lib is the Rust acceleration backend of the CANNs toolkit for research on continuous attractor neural networks. Within that ecosystem, it is defined as a companion Rust crate that exposes a performance-critical subset of toolkit functionality to Python through a thin PyO3 FFI layer, with the explicit role of accelerating workloads that are dominated by Python interpreter overhead rather than by JAX kernels. It is presented together with canns, the main Python library on BrainPy/JAX, and ASA, the Attractor Structure Analyzer, as one of three tightly integrated components of the broader toolkit (He et al., 26 Jun 2026).

1. Definition and system placement

In the toolkit architecture, canns-lib occupies the acceleration layer beneath the user-facing Python API. The paper describes it as “the acceleration backend” and as a standalone Rust crate that provides a drop-in performance-critical subset of the toolkit, specifically for Ripser-based persistent homology, long spatial navigation trajectories, and bulk task generation (He et al., 26 Jun 2026). This positioning is significant because the toolkit does not treat Rust as a separate end-user environment; the main modeling, training, and analysis abstractions remain in canns, while canns-lib is invoked opportunistically when a native implementation is advantageous.

The architectural division is deliberate. BrainPy/JAX underpins the main simulation and modeling stack, especially where GPU/TPU portability is relevant, whereas canns-lib addresses CPU-side kernels whose arithmetic intensity per Python object is low and whose runtime is dominated by interpreter overhead. The paper therefore frames canns-lib not as a reimplementation of the full CANNs stack, but as a targeted systems layer that preserves a Pythonic workflow while removing specific bottlenecks (He et al., 26 Jun 2026).

This separation also defines the toolkit’s internal dependency structure. canns declares canns-lib as a hard dependency, so the accelerated Ripser and spatial-navigation paths are part of the default installation path for the main library. At the same time, the paper preserves a distinction between transparent backend selection and module scope: the backend is always available through the Python API when installed, but only a subset of the total toolkit is actually accelerated (He et al., 26 Jun 2026).

2. Software architecture and interface model

canns-lib is implemented as a standalone Rust crate, released and versioned independently from the Python package, with Python bindings provided through PyO3. The paper identifies the currently shipped module coverage as canns_lib.ripser and canns_lib.spatial, and gives the PyPI package requirement as canns-lib >= 0.6.2 (He et al., 26 Jun 2026). The design principle is narrow native specialization rather than wholesale migration of the Python library into Rust.

The interface contract is intentionally conservative. The Python module API is described as a superset-compatible drop-in: code that works with the pure-Python implementation also works with the Rust implementation when the wheel is installed, without conditional logic at the call site. For persistent homology, the semantic interface is explicitly stated to remain identical to the pure-Python reference, including Betti numbers, barcodes, and persistence diagrams. For spatial navigation, the Rust implementation is a PyO3-accelerated re-implementation of RatInABox that retains the same Environment / Agent API, so migration can occur by changing only the import statement (He et al., 26 Jun 2026).

This interface strategy has two consequences. First, canns-lib is largely invisible in ordinary use: many workflows interact only with canns and never call Rust directly. Second, the backend serves interoperability goals as much as raw performance goals. ASA, for example, consumes the same Rust-accelerated Ripser module through the analyzer stack, so downstream tools such as CohoMap, CohoSpace, PathCompare, and CohoScore remain backend-agnostic (He et al., 26 Jun 2026).

The implementation is CPU-only at present. GPU/TPU acceleration remains in the JAX layer, and the Rust backend is used only where CPU-side native execution is the intended optimization target. This clarifies a common misconception: canns-lib is not the toolkit’s universal compute engine, nor is it a GPU backend for continuous attractor simulation (He et al., 26 Jun 2026).

3. Accelerated computational domains

The paper assigns canns-lib three target domains: Ripser-based persistent homology, long spatial-navigation trajectories, and bulk task generation. Of these, the first two receive detailed technical and empirical treatment (He et al., 26 Jun 2026).

For persistent homology, canns-lib.ripser accelerates the computation of Vietoris–Rips persistent barcodes used by ASA and related analyzer workflows. The mathematical objects are the standard ones of topological data analysis:

$$\mathrm{VR}_\epsilon(X) = \left\{ \sigma\subseteq X: d(x_a,x_b)\leq \epsilon \;\; \textrm{for all } x_a,x_b\in\sigma \right\}$$

and

$$H_k(K;F)=\ker\partial_k/\operatorname{im}\partial_{k+1}.$$

The paper ties this implementation to the attractor signatures of principal interest in CANN research, including the ideal Betti-number patterns

$S^1:\qquad (\beta_0,\beta_1,\beta_2)=(1,1,0)$

and

$T^2:\qquad (\beta_0,\beta_1,\beta_2)=(1,2,1).$

Within this domain, the Rust module supports coefficient rings, homology dimensions 0, 1, and 2, reduction-order statistics, multiple distance metrics including Euclidean, Manhattan, cosine, and custom metrics, sparse distance matrices, and optional representative-cocycle output (He et al., 26 Jun 2026).

For spatial navigation, canns-lib.spatial is the Rust port of a RatInABox-style environment and agent simulator used in navigation tasks and path-integration workflows. The paper attributes to it support for solid boundaries, periodic boundaries, arbitrary polygons, holes, and thigmotaxis wall-following (He et al., 26 Jun 2026). The performance rationale is that long-horizon environment stepping involves collision checking, boundary handling, and sensory sampling, which scale poorly in pure Python.

The two accelerated domains also differ in baseline difficulty. Persistent homology is compared against ripser.py, which already wraps a highly optimized C++ implementation, so only modest gains are plausible. Spatial navigation is compared against pure-Python RatInABox, where interpreter overhead dominates and native acceleration changes the effective scaling regime (He et al., 26 Jun 2026).

4. Performance profile and empirical validation

The benchmark evidence presented for canns-lib is sharply workload-dependent. The representative table in the paper reports results on an Apple M2 Pro with 16 GB RAM, in a CPU-only, single-thread configuration, using 54 datasets for Ripser and step sweeps from $10^2$ to $10^6$ for spatial navigation (He et al., 26 Jun 2026).

Workload	Baseline	Reported result
Ripser-based persistent homology	ripser.py	$1.13\times$ average, $1.82\times$ peak
Spatial navigation	pure-Python RatInABox	$\sim 700\times$ geometric-mean speedup
Spatial navigation at $10^6$ steps	pure-Python RatInABox	$$H_k(K;F)=\ker\partial_k/\operatorname{im}\partial_{k+1}.$$0 s vs. $$H_k(K;F)=\ker\partial_k/\operatorname{im}\partial_{k+1}.$$1 s, $$H_k(K;F)=\ker\partial_k/\operatorname{im}\partial_{k+1}.$$2

For the Ripser path, the paper is careful to characterize the gain as modest. The $$H_k(K;F)=\ker\partial_k/\operatorname{im}\partial_{k+1}.$$3 geometric-mean speedup is explicitly attributed to the strength of the comparison baseline, since ripser.py already uses a tight C++ implementation. The Rust gains are associated with reduced Python overhead in filtration bookkeeping and parallelized dense column reductions (He et al., 26 Jun 2026). The implementation details named in the paper are row-by-row edge generation, binary search on sparse columns, structure-of-arrays memory layout, and Rayon-based multi-threading.

Accuracy and compatibility claims for the Ripser path are correspondingly strict. The paper states that results are bit-exact with the baseline, that the bottleneck distance between matched persistence pairs stays well below the 0.02 tolerance, and that the $$H_k(K;F)=\ker\partial_k/\operatorname{im}\partial_{k+1}.$$4 match rate is 100% across all 54 datasets. Memory usage is reported as essentially identical, with a $$H_k(K;F)=\ker\partial_k/\operatorname{im}\partial_{k+1}.$$5 ratio relative to ripser.py (He et al., 26 Jun 2026). These claims position canns-lib.ripser as a semantics-preserving acceleration rather than an approximate substitute.

The spatial benchmark is qualitatively different. The paper states that pure-Python RatInABox scales unfavourably past $$H_k(K;F)=\ker\partial_k/\operatorname{im}\partial_{k+1}.$$6 steps, whereas the Rust backend scales linearly to $$H_k(K;F)=\ker\partial_k/\operatorname{im}\partial_{k+1}.$$7 steps in under a second on a laptop. Under the benchmark configuration generated by canns-lib/benchmarks/spatial/step_scaling_benchmark.py, with dt=0.02, a unit-square environment, four solid walls, and agent start [0.5, 0.5], the reported runtime at $$H_k(K;F)=\ker\partial_k/\operatorname{im}\partial_{k+1}.$$8 steps is $$H_k(K;F)=\ker\partial_k/\operatorname{im}\partial_{k+1}.$$9 s for canns-lib and $S^1:\qquad (\beta_0,\beta_1,\beta_2)=(1,1,0)$0 s for pure-Python RatInABox, corresponding to a $S^1:\qquad (\beta_0,\beta_1,\beta_2)=(1,1,0)$1 speedup (He et al., 26 Jun 2026). The abstract’s phrase “hundreds-of-times speedups for spatial-navigation workloads” refers to this regime.

5. Workflow integration, usage, and reproducibility

In ordinary practice, canns-lib is consumed through canns rather than through a separate Rust-first workflow. The paper repeatedly states that the backend is invoked transparently from the Python API. For ASA, this means that a user running the topological-analysis pipeline receives the accelerated Ripser inner loop without changing the semantic outputs. The paper gives the corresponding launch paths as canns-gui for the GUI and python -m canns.pipeline.asa --config config.yaml for headless use (He et al., 26 Jun 2026).

The spatial module supports a second usage pattern: API-level replacement of RatInABox-compatible code. Because the Rust implementation preserves the same Environment / Agent API, existing Python code can switch by changing only the import statement (He et al., 26 Jun 2026). This makes canns-lib.spatial relevant not only inside the integrated CANNs toolkit, but also as a performance-preserving backend for established spatial-navigation code patterns.

The toolkit’s reproducibility infrastructure extends to the backend. The paper notes public repositories for canns, canns-lib, and ASA; public Docker images with pinned environments; example notebooks under examples/; and a single make reproduce command in the repository root (He et al., 26 Jun 2026). For benchmarking specifically, raw outputs are produced by scripts in canns-lib/benchmarks/, including benchmarks/spatial/step_scaling_benchmark.py and benchmarks/ripser/comprehensive_benchmark.py, with per-run JSON and logs shipped with the repository and methodology documented in the canns-lib repository README.

This reproducibility emphasis is consistent with the toolkit’s broader goal of standardizing CANN workflows. canns-lib is not only an optimization layer; it is also part of an attempt to replace lab-specific code paths with a stable, documented, and benchmarked software substrate (He et al., 26 Jun 2026).

6. Scope, limitations, and nomenclature

The scope of canns-lib is explicitly limited. It accelerates only a performance-critical subset of the toolkit, not the full model library, not the full trainer stack, and not general BrainPy/JAX neural update kernels. The currently shipped modules are canns_lib.ripser and canns_lib.spatial; planned but not yet released modules include approximate nearest neighbours, an accelerated CANN dynamics-computation kernel, and a shared-memory parallel batch evaluator (He et al., 26 Jun 2026). This suggests a staged expansion strategy rather than an already complete native backend.

Several limitations are stated directly. The backend is CPU-only at present. Fallback behavior is asymmetric: the Ripser path can gracefully fall back to a pure-Python reference if the wheel is unavailable, whereas the spatial path is not currently available without the wheel. The paper also notes that $S^1:\qquad (\beta_0,\beta_1,\beta_2)=(1,1,0)$2 scalability remains challenging, because second-homology computation over Vietoris–Rips filtrations is more expensive and does not yet benefit from the same parallelisation optimisations as the $S^1:\qquad (\beta_0,\beta_1,\beta_2)=(1,1,0)$3 path; for large point clouds with $S^1:\qquad (\beta_0,\beta_1,\beta_2)=(1,1,0)$4, longer runtimes should be expected (He et al., 26 Jun 2026).

The name itself also benefits from disambiguation. The explicit identifier canns-lib appears in the CANNs toolkit literature as a Rust backend for continuous attractor neural network research (He et al., 26 Jun 2026). Similar-looking arXiv strings denote unrelated systems: CERNLIB, a revived HEP software stack (Schwickerath et al., 2023); CaNS, a canonical-flow Navier–Stokes solver (Costa et al., 2020); CANS methods for industrial surveillance and collaborative edge inference (Tu et al., 2021, Wu et al., 8 Jun 2026); and CANN-EUCLID, a constitutive-model discovery framework (Alheit et al., 12 Jun 2026). This suggests that bibliographic and software curation around the term requires exact name-level disambiguation rather than acronym matching alone.

Taken together, these constraints define the proper interpretation of canns-lib. It is neither the whole CANNs toolkit nor a general-purpose neural simulation engine. It is a transparent native acceleration substrate for selected non-JAX bottlenecks—most importantly persistent homology and long spatial-navigation workloads—designed to preserve API compatibility while making those stages fast enough for routine use in continuous attractor neural network research (He et al., 26 Jun 2026).