4.3 SparseSynapticMap CSR

SparseSynapticMap (CSR)

Relevant source files

The following files were used as context for generating this wiki page:

• src/sparse.rs
• src/tests.rs

Purpose and Scope

The SparseSynapticMap module, implemented in src/sparse.rs, provides a Compressed Sparse Row (CSR) storage engine designed to replace dense $N \times N$ synaptic weight matrices with adjacency lists src/sparse.rs:3-18. This representation optimizes memory footprint and enables GPU-accelerated execution patterns by reducing VRAM bandwidth requirements and facilitating warp-optimized memory accesses src/sparse.rs:3-6. This page documents the data structures, fallible and panicking constructors, dense-to-sparse migration utilities, weight pruning workflows, and GPU export mechanisms.

---

1. Data Structures and CSR Layout

To represent sparse network connectivities efficiently, the codebase defines the network size limit and core structs in src/sparse.rs src/sparse.rs:23-53.

• MAX_SPARSE_NEURONS: Defines the maximum supported neuron count (65,536, or u16::MAX as usize + 1), enforcing that target indices fit within a u16 word src/sparse.rs:23-24.
• Synapse: A simple record holding a target neuron index (target: u16) and a synaptic weight (weight: f32) src/sparse.rs:26-33.
• SparseSynapticMap<const N: usize>: The generic CSR container holding three vectors src/sparse.rs:44-53.
  • row_ptr: Indices marking the boundary of each neuron's connections in col_indices and values (length N + 1) src/sparse.rs:46-48.
  • col_indices: Target neuron indices for each non-zero entry src/sparse.rs:49-50.
  • values: The non-zero connection weights corresponding to each entry src/sparse.rs:51-52.

graph TD
    subgraph "NaturalLanguageSpace"
        A["DenseMatrix"] -->|Pruning| B["CSRRepresentation"]
        B -->|GPUUpload| C["DeviceBuffers"]
    end

    subgraph "CodeEntitySpace"
        D["SparseSynapticMap<N>"] --> E["row_ptr: Vec<usize>"]
        D --> F["col_indices: Vec<u16>"]
        D --> G["values: Vec<f32>"]
        H["Synapse"] --> I["target: u16"]
        H --> J["weight: f32"]
    end

    B -.-> D
    C -.-> E
    C -.-> F
    C -.-> G

Loading

Sources: src/sparse.rs:3-53

---

2. Constructors and Fallible Builders

SparseSynapticMap provides both panicking convenience methods and fallible variants (try_*) that validate neuron count constraints and index bounds src/sparse.rs:55-162.

Initialization and Validation

• SparseSynapticMap::new() and SparseSynapticMap::try_new(): Initialize an empty sparse structure for $N$ neurons, validating that $N \le \text{}`MAX_SPARSE_NEURONS`` src/sparse.rs:55-81.
• SparseSynapticMap::from_dense() and SparseSynapticMap::try_from_dense(): Convert a dense array [[f32; N]; N] into a CSR structure by filtering out weights whose absolute value falls at or below a sparsity_threshold src/sparse.rs:83-115.
• SparseSynapticMap::from_adjacency() and SparseSynapticMap::try_from_adjacency(): Build the CSR map from an explicit slice of adjacency vectors &[Vec<Synapse>], verifying that the outer slice length matches $N$ and that no target index exceeds the maximum allowed neuron bounds src/sparse.rs:117-162.

sequenceDiagram
    participant Caller
    participant SparseSynapticMap as SparseSynapticMap<N>
    participant MeshError

    Caller->>SparseSynapticMap: try_from_adjacency(adjacency)
    SparseSynapticMap->>SparseSynapticMap: validate_neuron_count()
    alt Invalid Neuron Count
        SparseSynapticMap-->>MeshError: Err(NeuronCountMismatch)
    end
    SparseSynapticMap->>SparseSynapticMap: Check target bounds
    alt Out of Bounds Target
        SparseSynapticMap-->>MeshError: Err(IndexOutOfBounds)
    end
    SparseSynapticMap-->>Caller: Ok(SparseSynapticMap)

Loading

Sources: src/sparse.rs:55-162

---

3. Weight Management and Pruning

Row-level inspection and weight manipulation routines allow dynamic updating of synaptic connectivity during simulation loops src/sparse.rs:164-190.

• get_row(row: usize): Returns an iterator over all connected target indices and their weights for a given neuron row src/sparse.rs:165-169.
• get_weight(row: usize, col: usize): Directly retrieves the weight between row and col, returning 0.0 if no connection exists src/sparse.rs:171-181.
• set_weight(...) / try_set_weight(...): Dynamically updates a single weight. If the updated weight exceeds the sparsity threshold, it inserts or updates the entry; if it drops below the threshold, the connection is pruned from the sparse arrays src/sparse.rs:183-190.

Sources: src/sparse.rs:164-190

---

4. GPU Export and Memory Efficiency

The contiguous layout of row_ptr, col_indices, and values makes SparseSynapticMap suitable for direct serialization and zero-copy or low-overhead transfer to GPU execution environments (such as CUDA or WebGPU buffers) src/sparse.rs:3-18.

By storing only non-zero entries, networks with low connectivity (e.g., ~5% sparsity in a 2048-neuron configuration) achieve substantial memory reductions—shrinking from dense matrix representations (~16 MB) down to compact sparse allocations (~800 KB) src/sparse.rs:16-18.

graph TD
    subgraph "HostMemory"
        A["SparseSynapticMap<N>"] --> B["row_ptr slice"]
        A --> C["col_indices slice"]
        A --> D["values slice"]
    end

    subgraph "DeviceMemory"
        B -->|cudaMemcpy| E["GPU Row Ptr Buffer"]
        C -->|cudaMemcpy| F["GPU Col Indices Buffer"]
        D -->|cudaMemcpy| G["GPU Values Buffer"]
    end

Loading

Sources: src/sparse.rs:3-18

---

5. Routing Policy and Integration

SparseSynapticMap serves as the underlying structural representation for routing policies and synaptic weight matrices where dense allocations would otherwise exhaust memory limits src/sparse.rs:3-6. It pairs with routing configurations to ensure indices remain bounded by u16 constraints, supporting scalable neuromorphic workloads across the crate src/sparse.rs:35-43.

Sources: src/sparse.rs:3-43, src/tests.rs:1-221