2.3 Core Types and Error Model

Core Types and Error Model

Relevant source files

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

• src/error.rs
• src/topology/graph.rs
• src/types.rs

Purpose and Scope

This page documents the fundamental scalar types, synaptic descriptors, configuration structures, and unified error model defined across src/types.rs, src/error.rs, and network topology validation layers within src/topology/graph.rs. These types establish the core contracts for neuron identification, axonal timing, synaptic weights, Dale's law polarity, and failure handling used throughout the synaptic-wiring package.

Sources: [src/types.rs:1-183](), [src/error.rs:1-109](), [src/topology/graph.rs:1-90]()

---

1. Scalar Aliases and Measurement Units

The runtime uses concrete scalar aliases to enforce memory efficiency and clear unit semantics across the mesh:

• NeuronId: Defined as a u32 alias serving as a unique numeric index for each neuron within a mesh instance ([src/types.rs:13-14]()).
• DelayTicks: Defined as a u16 alias representing axonal propagation delay measured in discrete simulation ticks, where 0 denotes instantaneous same-tick delivery ([src/types.rs:16-18]()).

Sources: [src/types.rs:11-19]()

---

2. Synaptic Polarity and Dale's Principle

Synaptic polarity enforces Dale's principle, which dictates that a neuron's outgoing synapses share a uniform polarity (either all excitatory or all inhibitory) ([src/types.rs:22-36]()).

pub enum Polarity {
    Excitatory,
    Inhibitory,
}

The Polarity enum implements a sign() method that maps Polarity::Excitatory to +1.0 and Polarity::Inhibitory to -1.0 for algebraic weight calculations ([src/types.rs:38-46]()).

Sources: [src/types.rs:20-46]()

---

3. Synapse Descriptors and Weight Validation

The SynapseDescriptor struct describes an individual directed synaptic connection prior to its compilation into Compressed Sparse Row (CSR) matrix layouts ([src/types.rs:51-64]()).

pub struct SynapseDescriptor {
    pub source: NeuronId,
    pub target: NeuronId,
    pub weight: f32,
    pub delay: DelayTicks,
    pub polarity: Polarity,
}

Effective Weights and Invariant Verification

The effective_weight() method computes the signed weight by scaling the non-negative magnitude weight with polarity.sign() ([src/types.rs:79-86]()). Deserialization relies on deserialize_nonnegative_weight to reject negative, infinite, or NaN magnitudes ([src/types.rs:133-142]()).

In compiled graphs (SynapticGraph), signed weights are validated against their assigned polarities using signed_weight_agrees_with_polarity ([src/types.rs:105-113]()) during deserialization ([src/topology/graph.rs:65-88]()).

Title: "Synapse Descriptor Validation and Effective Weight Flow"

graph TD
    SD["SynapseDescriptor"] -->|deserialize_nonnegative_weight| WM["weight_magnitude_is_valid"]
    WM -->|Valid Magnitude| EW["SynapseDescriptor::effective_weight"]
    EW -->|Multiply Polarity Sign| SW["Signed Effective Weight"]
    SW -->|SynapticGraph::from_descriptors| CSR["CSR Adjacency Arrays"]
    CSR -->|RawSynapticGraph::into_graph| VSW["signed_weight_agrees_with_polarity"]

Sources: [src/types.rs:51-142], [src/topology/graph.rs:65-161]()

---

4. Topology Configuration Models

Network generation parameters are structured via TopologyConfig ([src/types.rs:147-158]()) and instantiated with default parameters (2048 neurons, 20% inhibitory fraction, max delay of 20 ticks, and a sparsity threshold of 0.01) ([src/types.rs:160-169]()).

Connection probabilities between neuron pairs are governed by the ConnectionModel enum ([src/types.rs:174-183]), supporting uniform Erdős–Rényi graphs, distance-dependent exponential decay models, and Watts–Strogatz small-world lattices.

Sources: [src/types.rs:144-183]()

---

5. Unified Error Model (MeshError)

All failure modes in the package converge into the unified MeshError enum via thiserror-backed implementations ([src/error.rs:10-59]()). The crate defines a convenience Result<T> alias ([src/error.rs:109]()).

Title: "MeshError Classification Hierarchy"

graph TD
    ME["MeshError"] --> IC["InvalidConfig(String)"]
    ME --> IRC["InvalidRouterConfig { field, reason }"]
    ME --> NCM["NeuronCountMismatch { expected, got, context }"]
    ME --> IOB["IndexOutOfBounds { index, max }"]
    ME --> TE["TopologyError(String)"]
    ME --> DE["DelayError(String)"]
    ME --> NFS["NonFiniteSignal { index, context }"]
    ME --> NFM["NonFiniteNeuromodulator { field }"]
    ME --> ORF["OutOfRangeNeuromodulator { field, value }"]

Error Variants and Roles

• InvalidConfig: General configuration parameters out of bounds ([src/error.rs:14]()).
• InvalidRouterConfig: Channel router or state configuration failures categorized by field ([src/error.rs:16-27]()).
• NeuronCountMismatch: Mismatched dimensions between interacting network components ([src/error.rs:29-34]()).
• IndexOutOfBounds: Invalid neuron or synapse index lookups ([src/error.rs:36-37]()).
• TopologyError: Failures during structural graph generation or constraint resolution ([src/error.rs:39-40]()).
• DelayError: Ring buffer overflow or invalid axonal delay configurations ([src/error.rs:42-43]()).
• NonFiniteSignal: Non-finite (NaN or $\pm\infty$) channel routing samples ([src/error.rs:45-49]()).
• NonFiniteNeuromodulator / OutOfRangeNeuromodulator: Neuromodulator state validation errors where values must reside strictly within $[0, 1]$ ([src/error.rs:51-59]()).

Sources: [src/error.rs:1-109]()