scirs2_spatial/neuromorphic/core/
events.rs

1//! Neuromorphic Spike Events
2//!
3//! This module defines the fundamental spike event structure used throughout
4//! neuromorphic computing systems. Spike events represent the basic unit of
5//! communication in spiking neural networks.
6
7/// Neuromorphic spike event
8///
9/// Represents a discrete spike occurring in a neuromorphic system. Each spike
10/// carries information about its source, timing, amplitude, and associated
11/// spatial coordinates.
12///
13/// # Fields
14/// - `neuron_id`: Unique identifier for the neuron that generated the spike
15/// - `timestamp`: Time of spike occurrence in simulation time units
16/// - `amplitude`: Strength/amplitude of the spike
17/// - `spatial_coords`: Spatial coordinates associated with the spike
18///
19/// # Example
20/// ```rust
21/// use scirs2_spatial::neuromorphic::core::SpikeEvent;
22///
23/// let spike = SpikeEvent {
24///     neuron_id: 42,
25///     timestamp: 1000.5,
26///     amplitude: 1.0,
27///     spatial_coords: vec![0.5, 0.3, 0.8],
28/// };
29///
30/// println!("Neuron {} spiked at time {}", spike.neuron_id, spike.timestamp);
31/// ```
32#[derive(Debug, Clone)]
33pub struct SpikeEvent {
34    /// Source neuron ID
35    pub neuron_id: usize,
36    /// Spike timestamp (in simulation time units)
37    pub timestamp: f64,
38    /// Spike amplitude
39    pub amplitude: f64,
40    /// Spatial coordinates associated with the spike
41    pub spatial_coords: Vec<f64>,
42}
43
44impl SpikeEvent {
45    /// Create a new spike event
46    ///
47    /// # Arguments
48    /// * `neuron_id` - ID of the neuron generating the spike
49    /// * `timestamp` - Time of spike occurrence
50    /// * `amplitude` - Spike amplitude (typically 1.0)
51    /// * `spatial_coords` - Associated spatial coordinates
52    ///
53    /// # Returns
54    /// A new `SpikeEvent` instance
55    pub fn new(neuron_id: usize, timestamp: f64, amplitude: f64, spatial_coords: Vec<f64>) -> Self {
56        Self {
57            neuron_id,
58            timestamp,
59            amplitude,
60            spatial_coords,
61        }
62    }
63
64    /// Get the neuron ID that generated this spike
65    pub fn neuron_id(&self) -> usize {
66        self.neuron_id
67    }
68
69    /// Get the timestamp of this spike
70    pub fn timestamp(&self) -> f64 {
71        self.timestamp
72    }
73
74    /// Get the amplitude of this spike
75    pub fn amplitude(&self) -> f64 {
76        self.amplitude
77    }
78
79    /// Get the spatial coordinates associated with this spike
80    pub fn spatial_coords(&self) -> &[f64] {
81        &self.spatial_coords
82    }
83
84    /// Get the number of spatial dimensions
85    pub fn spatial_dims(&self) -> usize {
86        self.spatial_coords.len()
87    }
88
89    /// Calculate the temporal distance to another spike
90    ///
91    /// # Arguments
92    /// * `other` - Another spike event
93    ///
94    /// # Returns
95    /// Absolute temporal distance between the two spikes
96    pub fn temporal_distance(&self, other: &SpikeEvent) -> f64 {
97        (self.timestamp - other.timestamp).abs()
98    }
99
100    /// Calculate the spatial distance to another spike
101    ///
102    /// # Arguments
103    /// * `other` - Another spike event
104    ///
105    /// # Returns
106    /// Euclidean distance between spatial coordinates, or None if dimensions don't match
107    pub fn spatial_distance(&self, other: &SpikeEvent) -> Option<f64> {
108        if self.spatial_coords.len() != other.spatial_coords.len() {
109            return None;
110        }
111
112        let distance = self
113            .spatial_coords
114            .iter()
115            .zip(other.spatial_coords.iter())
116            .map(|(a, b)| (a - b).powi(2))
117            .sum::<f64>()
118            .sqrt();
119
120        Some(distance)
121    }
122
123    /// Check if this spike occurs before another spike
124    ///
125    /// # Arguments
126    /// * `other` - Another spike event
127    ///
128    /// # Returns
129    /// True if this spike occurs before the other spike
130    pub fn is_before(&self, other: &SpikeEvent) -> bool {
131        self.timestamp < other.timestamp
132    }
133
134    /// Check if this spike occurs after another spike
135    ///
136    /// # Arguments
137    /// * `other` - Another spike event
138    ///
139    /// # Returns
140    /// True if this spike occurs after the other spike
141    pub fn is_after(&self, other: &SpikeEvent) -> bool {
142        self.timestamp > other.timestamp
143    }
144
145    /// Check if two spikes are from the same neuron
146    ///
147    /// # Arguments
148    /// * `other` - Another spike event
149    ///
150    /// # Returns
151    /// True if both spikes are from the same neuron
152    pub fn same_neuron(&self, other: &SpikeEvent) -> bool {
153        self.neuron_id == other.neuron_id
154    }
155}
156
157impl PartialEq for SpikeEvent {
158    fn eq(&self, other: &Self) -> bool {
159        self.neuron_id == other.neuron_id
160            && (self.timestamp - other.timestamp).abs() < 1e-9
161            && (self.amplitude - other.amplitude).abs() < 1e-9
162            && self.spatial_coords == other.spatial_coords
163    }
164}
165
166impl PartialOrd for SpikeEvent {
167    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
168        self.timestamp.partial_cmp(&other.timestamp)
169    }
170}
171
172/// Collection of spike events with utilities for temporal and spatial analysis
173#[derive(Debug, Clone)]
174pub struct SpikeSequence {
175    /// Vector of spike events
176    events: Vec<SpikeEvent>,
177}
178
179impl SpikeSequence {
180    /// Create a new empty spike sequence
181    pub fn new() -> Self {
182        Self { events: Vec::new() }
183    }
184
185    /// Create a spike sequence from a vector of events
186    ///
187    /// # Arguments
188    /// * `events` - Vector of spike events
189    ///
190    /// # Returns
191    /// A new `SpikeSequence` containing the events
192    pub fn from_events(events: Vec<SpikeEvent>) -> Self {
193        Self { events }
194    }
195
196    /// Add a spike event to the sequence
197    ///
198    /// # Arguments
199    /// * `event` - Spike event to add
200    pub fn add_event(&mut self, event: SpikeEvent) {
201        self.events.push(event);
202    }
203
204    /// Get all spike events
205    pub fn events(&self) -> &[SpikeEvent] {
206        &self.events
207    }
208
209    /// Get the number of spike events
210    pub fn len(&self) -> usize {
211        self.events.len()
212    }
213
214    /// Check if the sequence is empty
215    pub fn is_empty(&self) -> bool {
216        self.events.is_empty()
217    }
218
219    /// Sort events by timestamp
220    pub fn sort_by_time(&mut self) {
221        self.events.sort_by(|a, b| {
222            a.timestamp
223                .partial_cmp(&b.timestamp)
224                .expect("Operation failed")
225        });
226    }
227
228    /// Get events within a time window
229    ///
230    /// # Arguments
231    /// * `start_time` - Start of time window
232    /// * `end_time` - End of time window
233    ///
234    /// # Returns
235    /// Vector of spike events within the time window
236    pub fn events_in_window(&self, start_time: f64, end_time: f64) -> Vec<&SpikeEvent> {
237        self.events
238            .iter()
239            .filter(|event| event.timestamp >= start_time && event.timestamp <= end_time)
240            .collect()
241    }
242
243    /// Get events from a specific neuron
244    ///
245    /// # Arguments
246    /// * `neuron_id` - ID of the neuron
247    ///
248    /// # Returns
249    /// Vector of spike events from the specified neuron
250    pub fn events_from_neuron(&self, neuron_id: usize) -> Vec<&SpikeEvent> {
251        self.events
252            .iter()
253            .filter(|event| event.neuron_id == neuron_id)
254            .collect()
255    }
256
257    /// Calculate average firing rate for a neuron
258    ///
259    /// # Arguments
260    /// * `neuron_id` - ID of the neuron
261    /// * `time_window` - Duration of the time window
262    ///
263    /// # Returns
264    /// Average firing rate in spikes per time unit
265    pub fn firing_rate(&self, neuron_id: usize, time_window: f64) -> f64 {
266        let neuron_events = self.events_from_neuron(neuron_id);
267        if neuron_events.is_empty() || time_window <= 0.0 {
268            return 0.0;
269        }
270
271        neuron_events.len() as f64 / time_window
272    }
273
274    /// Get the time span of the sequence
275    ///
276    /// # Returns
277    /// Tuple of (earliest_time, latest_time), or None if sequence is empty
278    pub fn time_span(&self) -> Option<(f64, f64)> {
279        if self.events.is_empty() {
280            return None;
281        }
282
283        let times: Vec<f64> = self.events.iter().map(|event| event.timestamp).collect();
284        let min_time = times.iter().fold(f64::INFINITY, |a, &b| a.min(b));
285        let max_time = times.iter().fold(f64::NEG_INFINITY, |a, &b| a.max(b));
286
287        Some((min_time, max_time))
288    }
289}
290
291impl Default for SpikeSequence {
292    fn default() -> Self {
293        Self::new()
294    }
295}
296
297#[cfg(test)]
298mod tests {
299    use super::*;
300
301    #[test]
302    fn test_spike_event_creation() {
303        let spike = SpikeEvent::new(42, 1000.5, 1.0, vec![0.5, 0.3, 0.8]);
304
305        assert_eq!(spike.neuron_id(), 42);
306        assert_eq!(spike.timestamp(), 1000.5);
307        assert_eq!(spike.amplitude(), 1.0);
308        assert_eq!(spike.spatial_coords(), &[0.5, 0.3, 0.8]);
309        assert_eq!(spike.spatial_dims(), 3);
310    }
311
312    #[test]
313    fn test_temporal_distance() {
314        let spike1 = SpikeEvent::new(1, 100.0, 1.0, vec![0.0]);
315        let spike2 = SpikeEvent::new(2, 105.0, 1.0, vec![1.0]);
316
317        assert_eq!(spike1.temporal_distance(&spike2), 5.0);
318        assert_eq!(spike2.temporal_distance(&spike1), 5.0);
319    }
320
321    #[test]
322    fn test_spatial_distance() {
323        let spike1 = SpikeEvent::new(1, 100.0, 1.0, vec![0.0, 0.0]);
324        let spike2 = SpikeEvent::new(2, 105.0, 1.0, vec![3.0, 4.0]);
325
326        assert_eq!(spike1.spatial_distance(&spike2), Some(5.0));
327
328        // Test mismatched dimensions
329        let spike3 = SpikeEvent::new(3, 110.0, 1.0, vec![1.0]);
330        assert_eq!(spike1.spatial_distance(&spike3), None);
331    }
332
333    #[test]
334    fn test_spike_ordering() {
335        let spike1 = SpikeEvent::new(1, 100.0, 1.0, vec![0.0]);
336        let spike2 = SpikeEvent::new(2, 105.0, 1.0, vec![1.0]);
337
338        assert!(spike1.is_before(&spike2));
339        assert!(spike2.is_after(&spike1));
340        assert!(!spike1.is_after(&spike2));
341        assert!(!spike2.is_before(&spike1));
342    }
343
344    #[test]
345    fn test_spike_sequence() {
346        let mut sequence = SpikeSequence::new();
347        assert!(sequence.is_empty());
348
349        let spike1 = SpikeEvent::new(1, 100.0, 1.0, vec![0.0]);
350        let spike2 = SpikeEvent::new(2, 105.0, 1.0, vec![1.0]);
351
352        sequence.add_event(spike1);
353        sequence.add_event(spike2);
354
355        assert_eq!(sequence.len(), 2);
356        assert!(!sequence.is_empty());
357
358        let time_span = sequence.time_span().expect("Operation failed");
359        assert_eq!(time_span.0, 100.0);
360        assert_eq!(time_span.1, 105.0);
361    }
362
363    #[test]
364    fn test_events_in_window() {
365        let mut sequence = SpikeSequence::new();
366        sequence.add_event(SpikeEvent::new(1, 95.0, 1.0, vec![0.0]));
367        sequence.add_event(SpikeEvent::new(2, 100.0, 1.0, vec![1.0]));
368        sequence.add_event(SpikeEvent::new(3, 105.0, 1.0, vec![2.0]));
369        sequence.add_event(SpikeEvent::new(4, 110.0, 1.0, vec![3.0]));
370
371        let windowed_events = sequence.events_in_window(100.0, 105.0);
372        assert_eq!(windowed_events.len(), 2);
373        assert_eq!(windowed_events[0].neuron_id, 2);
374        assert_eq!(windowed_events[1].neuron_id, 3);
375    }
376
377    #[test]
378    fn test_firing_rate() {
379        let mut sequence = SpikeSequence::new();
380        sequence.add_event(SpikeEvent::new(1, 100.0, 1.0, vec![0.0]));
381        sequence.add_event(SpikeEvent::new(1, 105.0, 1.0, vec![0.0]));
382        sequence.add_event(SpikeEvent::new(1, 110.0, 1.0, vec![0.0]));
383        sequence.add_event(SpikeEvent::new(2, 107.0, 1.0, vec![1.0]));
384
385        // Neuron 1 has 3 spikes in 10 time units = 0.3 spikes per unit
386        assert_eq!(sequence.firing_rate(1, 10.0), 0.3);
387
388        // Neuron 2 has 1 spike in 10 time units = 0.1 spikes per unit
389        assert_eq!(sequence.firing_rate(2, 10.0), 0.1);
390
391        // Non-existent neuron
392        assert_eq!(sequence.firing_rate(99, 10.0), 0.0);
393    }
394}
scirs2_spatial/neuromorphic/core/events.rs

scirs2_spatial/neuromorphic/core/
events.rs
