Spatial Gradient Implementation for Firing Thresholds

Overview

This document describes the implementation of spatial gradients for neuron firing thresholds in FEAGI 2.0. This feature allows firing thresholds to vary across the spatial dimensions of a cortical area, enabling more sophisticated neural processing patterns.

Feature Description

What is a Spatial Gradient?

A spatial gradient allows the firing threshold of neurons to vary based on their 3D position (x, y, z) within a cortical area. The threshold for a neuron at position (x, y, z) is calculated as:

threshold(x, y, z) = base_threshold + (x × increment_x) + (y × increment_y) + (z × increment_z)

Where:

base_threshold: The firing threshold at position (0, 0, 0)
increment_x: Change in threshold per unit X position
increment_y: Change in threshold per unit Y position
increment_z: Change in threshold per unit Z position

Use Cases

Sensory Processing: Create receptive fields with varying sensitivity
Spatial Attention: Implement position-dependent activation patterns
Hierarchical Processing: Model cortical layers with different excitability
Retinotopic Mapping: Simulate center-surround receptive fields
Somatotopic Maps: Model body position-dependent sensitivity

Examples

Example 1: Uniform Thresholds (No Gradient)

base_threshold = 10.0
increment_x = 0.0
increment_y = 0.0
increment_z = 0.0

Result: All neurons have threshold = 10.0

Example 2: Linear X-Axis Gradient

base_threshold = 10.0
increment_x = 2.0
increment_y = 0.0
increment_z = 0.0

For a 5×1×1 area:
- Neuron at (0,0,0): threshold = 10.0
- Neuron at (1,0,0): threshold = 12.0
- Neuron at (2,0,0): threshold = 14.0
- Neuron at (3,0,0): threshold = 16.0
- Neuron at (4,0,0): threshold = 18.0

Example 3: 3D Gradient

base_threshold = 100.0
increment_x = 1.0
increment_y = 5.0
increment_z = 10.0

For a 2×2×2 area:
- (0,0,0): 100.0
- (1,0,0): 101.0
- (0,1,0): 105.0
- (1,1,0): 106.0
- (0,0,1): 110.0
- (1,0,1): 111.0
- (0,1,1): 115.0
- (1,1,1): 116.0

Example 4: Negative Gradient (Decreasing Sensitivity)

base_threshold = 50.0
increment_x = -5.0
increment_y = 0.0
increment_z = 0.0

For a 3×1×1 area:
- Neuron at (0,0,0): threshold = 50.0
- Neuron at (1,0,0): threshold = 45.0
- Neuron at (2,0,0): threshold = 40.0

Implementation Details

Modified Components

1. Neuron Storage (`feagi-npu/runtime`)

Files Modified:

src/traits/runtime.rs: Added threshold_limits() accessors to NeuronStorage trait
src/std_impl/neuron_array.rs: Added threshold_limits vector to StdNeuronArray
src/embedded_impl/neuron_array.rs: Added threshold_limits array to embedded NeuronArray

Changes:

add_neuron() and add_neurons_batch() signatures now accept threshold_limit parameter
Storage structures now maintain per-neuron threshold limits alongside thresholds

2. NPU Core (`feagi-npu/burst-engine`)

Files Modified:

src/npu.rs: Updated create_cortical_area_neurons() to accept spatial gradient parameters
src/dynamic_npu.rs: Updated wrapper methods to pass gradient parameters
src/neural_dynamics.rs: Already implemented firing window logic (from previous feature)

Key Changes in npu.rs:

pub fn create_cortical_area_neurons(
    &mut self,
    cortical_idx: u32,
    width: u32,
    height: u32,
    depth: u32,
    neurons_per_voxel: u32,
    default_threshold: f32,  // Base threshold at (0,0,0)
    threshold_increment_x: f32,  // ✨ NEW
    threshold_increment_y: f32,  // ✨ NEW
    threshold_increment_z: f32,  // ✨ NEW
    default_threshold_limit: f32,
    // ... other parameters
) -> Result<u32>

Threshold Calculation Logic:

// Optimized: Check if we have any gradients
let has_x_gradient = threshold_increment_x.abs() > f32::EPSILON;
let has_y_gradient = threshold_increment_y.abs() > f32::EPSILON;
let has_z_gradient = threshold_increment_z.abs() > f32::EPSILON;
let has_any_gradient = has_x_gradient || has_y_gradient || has_z_gradient;

if has_any_gradient {
    // Calculate position-based thresholds (spatial gradient)
    for x in 0..width {
        for y in 0..height {
            for z in 0..depth {
                let threshold_at_pos = default_threshold
                    + (x as f32 * threshold_increment_x)
                    + (y as f32 * threshold_increment_y)
                    + (z as f32 * threshold_increment_z);
                
                for _ in 0..neurons_per_voxel {
                    thresholds.push(T::from_f32(threshold_at_pos));
                }
            }
        }
    }
} else {
    // Fast path: uniform thresholds
    thresholds.resize(total_neurons, T::from_f32(default_threshold));
}

3. Brain Development (`feagi-brain-development`)

Files Modified:

src/models/cortical_area.rs: Added accessor methods to CorticalAreaExt trait
src/connectome_manager.rs: Updated to extract and pass gradient parameters

New Trait Methods:

pub trait CorticalAreaExt {
    fn firing_threshold_increment_x(&self) -> f32;
    fn firing_threshold_increment_y(&self) -> f32;
    fn firing_threshold_increment_z(&self) -> f32;
}

Implementation:

impl CorticalAreaExt for CorticalArea {
    fn firing_threshold_increment_x(&self) -> f32 {
        self.get_f32_property("firing_threshold_increment_x", 0.0)
    }
    // ... similar for y and z
}

Genome Configuration

To use spatial gradients, add these properties to a cortical area in the genome JSON:

{
    "cortical_areas": {
        "my_cortical_area": {
            "properties": {
                "firing_threshold": 10.0,
                "firing_threshold_increment_x": 1.0,
                "firing_threshold_increment_y": 0.5,
                "firing_threshold_increment_z": 0.0,
                "firing_threshold_limit": 50.0
            }
        }
    }
}

Property Defaults:

firing_threshold_increment_x: 0.0 (no X gradient)
firing_threshold_increment_y: 0.0 (no Y gradient)
firing_threshold_increment_z: 0.0 (no Z gradient)

If all increment values are 0.0 (default), all neurons get the firing_threshold value (backward compatible).

Performance Optimizations

Fast Path for Uniform Thresholds

When all increments are 0.0, the implementation uses a fast path:

thresholds.resize(total_neurons, T::from_f32(default_threshold));

This avoids the nested loop overhead and allows LLVM to vectorize the fill operation (SIMD).

Epsilon Comparison

The implementation uses f32::EPSILON to check for zero increments:

let has_x_gradient = threshold_increment_x.abs() > f32::EPSILON;

This handles floating-point precision issues gracefully.

Neurons Per Voxel

All neurons in the same voxel (same x,y,z position) receive the same threshold, which is correct behavior for spatial organization.

Testing

Unit Tests

A comprehensive test suite was added:

tests/test_spatial_gradient.rs in feagi-npu/burst-engine

Test Cases:

3D Gradient: Verifies correct threshold calculation across all three axes
Uniform Thresholds: Ensures backward compatibility (no gradient)
Single Axis Gradient: Tests X-only gradient
Multiple Neurons Per Voxel: Confirms all neurons in a voxel share the threshold
Negative Gradient: Tests decreasing thresholds

Integration Testing

The feature was tested by:

Successfully compiling the entire codebase
Loading and processing test_genome.json
Creating 104,513 neurons across 28 cortical areas
Verifying no crashes or memory issues

Backward Compatibility

✅ Fully backward compatible

Existing genomes without increment properties work unchanged (defaults to 0.0)
Uniform threshold behavior preserved when increments are 0.0
No changes to genome loading or API contracts

This implementation builds on the firing_threshold_limit feature, which defines the upper bound for firing:

Firing Window:

neuron fires if:  threshold ≤ membrane_potential ≤ threshold_limit (if limit > 0)

Combined with spatial gradients, this creates position-dependent firing windows across a cortical area.

Future Enhancements

Potential extensions to this feature:

Non-linear Gradients: Quadratic, exponential, or Gaussian profiles
Radial Gradients: Distance-based from a center point
Custom Functions: User-defined threshold mapping functions
Dynamic Gradients: Thresholds that change based on learning or plasticity
Randomized Gradients: Stochastic variation around the spatial trend

Architecture Compliance

✅ This implementation follows FEAGI 2.0 architecture principles:

No hardcoded values: All defaults come from genome properties
Cross-platform: Works with both StdRuntime and EmbeddedRuntime
Precision-agnostic: Supports both FP32 and INT8 quantization
SIMD-friendly: Fast path leverages vectorization
Memory efficient: Minimal overhead (3 f32 values per cortical area)
Deterministic: Same genome always produces same thresholds

References

Modified Crates:

feagi-npu-runtime (v0.0.1-beta.1)
feagi-npu-burst-engine (v0.0.1-beta.1)
feagi-brain-development (v0.0.1-beta.1)

Commit Summary:

Added spatial gradient parameters to neuron creation pipeline
Implemented position-based threshold calculation
Added accessor methods to CorticalAreaExt trait
Maintained backward compatibility with existing genomes

Implementation Date: December 26, 2025
Status: ✅ Complete and Tested
Version: FEAGI 2.0.0-beta.1

Overview​

Feature Description​

What is a Spatial Gradient?​

Use Cases​

Examples​

Example 1: Uniform Thresholds (No Gradient)​

Example 2: Linear X-Axis Gradient​

Example 3: 3D Gradient​

Example 4: Negative Gradient (Decreasing Sensitivity)​

Implementation Details​

Modified Components​

1. Neuron Storage (feagi-npu/runtime)​

2. NPU Core (feagi-npu/burst-engine)​

3. Brain Development (feagi-brain-development)​

Genome Configuration​

Performance Optimizations​

Fast Path for Uniform Thresholds​

Epsilon Comparison​

Neurons Per Voxel​

Testing​

Unit Tests​

Integration Testing​

Backward Compatibility​

Related Features​

Future Enhancements​

Architecture Compliance​

References​

Overview

Feature Description

What is a Spatial Gradient?

Use Cases

Examples

Example 1: Uniform Thresholds (No Gradient)

Example 2: Linear X-Axis Gradient

Example 3: 3D Gradient

Example 4: Negative Gradient (Decreasing Sensitivity)

Implementation Details

Modified Components

1. Neuron Storage (`feagi-npu/runtime`)

2. NPU Core (`feagi-npu/burst-engine`)

3. Brain Development (`feagi-brain-development`)

Genome Configuration

Performance Optimizations

Fast Path for Uniform Thresholds

Epsilon Comparison

Neurons Per Voxel

Testing

Unit Tests

Integration Testing

Backward Compatibility

Related Features

Future Enhancements

Architecture Compliance

References