nervos.utils package

Submodules

nervos.utils.common module

This common module provides helper functions and tools for various tasks such as logging, file and directory operations, time handling, and model saving/loading using pickle. It serves as a general-purpose utility module for the Nervos project.

nervos.utils.common.get_cwd() → str

Get the current working directory.

Returns:

The path of the current working directory.

Return type:

str

nervos.utils.common.load_model(path: str) → tuple[ndarray, ndarray, dict]

Load model data (labels and synapses) from a file.

Parameters:

path (str) – The file path of the saved model.

Returns:

A tuple containing:

• synapses (np.ndarray): Array representing the synapses of the model.

• labels (np.ndarray): Array of labels associated with the model.

• parameters (dict): Dictionary of parameters used.

Return type:

tuple

Example

synapses, labels, parameters = load_model(“model.red”)

nervos.utils.common.mkdir(f: str) → None

Create a directory if it doesn’t already exist. Supports nested directories.

Parameters:

f (str) – The path of the directory to create.

Returns:

None

nervos.utils.common.plot_spike_train(spike_train: ndarray, ylim: tuple = None) → None

Plot spike trains

Parameters:

• spike_train (np.ndarray) – Spike trains to plot.

• ylim (tuple, optional) – y limit of the graph.

nervos.utils.common.save_model(labels: ndarray, synapses: ndarray, parameters: dict, path: str) → None

Save model data (labels and synapses) to a file.

Parameters:

• labels (np.ndarray) – Array of labels associated with the model.

• synapses (np.ndarray) – Array representing the synapses of the model.

• parameters (dict) – Dictionary of parameters used.

• path (str) – The file path to save the model.

Returns:

None

Example

save_model(labels, synapses, “model.red”)

nervos.utils.common.strftime(t: str) → str

Format the given time string.

Parameters:

t (str) – A time format string (e.g., “%Y-%m-%d %H:%M:%S”).

Returns:

The formatted time string.

Return type:

str

nervos.utils.common.timenow() → float

Get the current time as a Unix timestamp.

Returns:

The current time in seconds since the epoch.

Return type:

float

nervos.utils.layer module

This module defines the Layer class, which represents a single layer of neurons in a neural network. It uses the LIFNeuron class to model neurons and provides methods for initializing and managing synaptic weights. The layer is designed to be flexible and configurable through the Parameters object.

class nervos.utils.layer.Layer(parameters: Parameters, num_input_neurons: int, num_output_neurons: int)

Bases: object

Represents a single layer of neurons in a neural network.

Each layer consists of LIFNeuron instances and synaptic connections that define the interactions between input and output neurons.

parameters

Configuration parameters for the layer.

Type:

Parameters

layer

List of neurons in the layer.

Type:

list[LIFNeuron]

synapses

Synaptic weight matrix (output neurons x input neurons).

Type:

np.ndarray

num_input_neurons

Number of input neurons to the layer.

Type:

int

num_output_neurons

Number of output neurons in the layer.

Type:

int

neuron_potential_memories

List containing potentials of all neurons in the layer.

Type:

list

initial() → None

Initialize all neurons in the layer.

Calls the initial method of each LIFNeuron in the layer to reset their internal states.

set_synapses(synapses: ndarray) → None

Set the synaptic weights for the layer.

Parameters:

synapses (np.ndarray) – A weight matrix of shape (num_output_neurons, num_input_neurons).

update_neuron_potential_memories() → None

Update the layer’s neurons’ potential memory list.

nervos.utils.module module

Provides the implementation of the Module class for managing and training spiking neural networks (SNNs). Includes methods for STDP learning, feed-forward processing, training, testing, and model persistence.

class nervos.utils.module.Module(parameters: Parameters, identifier: str = None)

Bases: object

Represents a module for a spiking neural network.

This class serves as the main structure to initialize, train, and evaluate a spiking neural network using parameters and layer configurations. User must set the necessary data and call methods like initialise_layers and train to fully utilize the module.

parameters

Configuration parameters for the spiking neural network, including learning rates and thresholds.

Type:

Parameters

t0

Timestamp at the initialization of the module, used for tracking execution time.

Type:

float

str_t0

String representation of the initialization timestamp in the format ‘YYYY_MM_DD-HH_MM_SS’.

Type:

str

dataloader

Placeholder for the data loader object to manage training and testing datasets.

Type:

Dataloader

X_train

Training input spike trains (initialized as None).

Type:

np.ndarray

Y_train

Training labels corresponding to X_train (initialized as None).

Type:

np.ndarray

X_test

Testing input spike trains (initialized as None).

Type:

np.ndarray

Y_test

Testing labels corresponding to X_test (initialized as None).

Type:

np.ndarray

identifier

Unique identifier for the module, defaulting to the timestamp str_t0 if not provided.

Type:

str

logger

Logger object for tracking and debugging operations within the module.

Type:

Logger

wta

Used to use Winner-Take-All or update all synapses while doing STDP.

Type:

bool, optional

synapse_update_counts

Tracks the number of STDP updates for each synapse to support cycle-dependent weighting.

Type:

list

cycle_dependent_weight_lookup

Lookup table for weight values based on update cycle counts.

Type:

list, optional

enable_cycle_dependent_weights

Flag to enable weight updates based on cycle count lookup.

Type:

bool

enable_synaptic_noise

Flag to enable truncated normal noise on synapse values during read.

Type:

bool

noise_magnitude_half_range

The half-range magnitude for the synaptic noise distribution.

Type:

float

STDP(delta_t: int) → float

Calculate the spike-timing-dependent plasticity (STDP) adjustment for synapse weights.

Parameters:

delta_t (float) – The time difference between post-synaptic and pre-synaptic spikes.

Returns:

The weight adjustment based on the STDP rule.

Return type:

float

feed_forward(spike_train: ndarray, neuron_label_map: ndarray, training_duration: int, do_stdp: bool = False, label: int = None, spikeplots_for_one_spike_train: list = None, layer_potentials_for_one_spike_train: list = None, weight_evolution_for_one_spike_train: list = None, plotting=False) → tuple[ndarray, int]

Perform feed-forward processing for the Module, with optional STDP learning.

Parameters:

• spike_train (np.ndarray) – Input spike train.

• neuron_label_map (np.ndarray) – Map of neuron indices to labels.

• training_duration (int) – Time duration for the feed-forward process.

• do_stdp (bool, optional) – If True, apply STDP learning. Defaults to False.

• label (int, optional) – Label of the current input. Defaults to None.

• spikeplots_for_one_spike_train (list, optional) – Used to store spikeplots for the current input. Defaults to None.

• layer_potentials_for_one_spike_train (list, optional) – Used to store potentials of all layers’ neurons. Defaults to None.

• plotting (bool, optional) – Used to differentiate between testing and training while storing spikeplots.

Returns:

Spike counts for the output layer and the index of the neuron with the highest potential.

Return type:

tuple

get_all_synapses() → ndarray

Retrieve all synapse weights from the network.

Returns:

A list of all synapse weights for each layer in the network.

Return type:

np.ndarray

get_prediction(spike_train: ndarray, all_synapses: ndarray = None, neuron_label_map: ndarray = None) → int

Predict the label of a given input spike train.

Parameters:

• spike_train (np.ndarray) – Input spike train.

• all_synapses (np.ndarray, optional) – Synapse weights. Defaults to learned synapses.

• neuron_label_map (np.ndarray, optional) – Neuron-to-label mapping. Defaults to learned mapping.

Returns:

Predicted label.

Return type:

int

initialise_layers(layer_sizes: list) → None

Initialize the layers of the network based on the specified layer sizes.

Parameters:

layer_sizes (list) – A list of integers specifying the number of neurons in each layer.

load_model(model_location: str) → None

Load a saved SNN model from the specified location.

Parameters:

model_location (str) – Path to the saved model.

predict(X: ndarray, model_location: str) → int

Predict labels for a batch of inputs. User has to implement this on their own.

Parameters:

• X (np.ndarray) – Batch of input spike trains.

• model_location (str) – Path to the model for inference.

Returns:

Predicted labels for the input batch.

Return type:

int

reweigh_synapses_for_between_input_and_output_neuron(current_neuron_idx: int, spike_train_for_current_layer: ndarray, synapses: ndarray, time_step: float, next_neuron_idx: int, synapse_memory: ndarray) → None

Apply STDP learning to reweigh synapses connecting input neurons and the output neuron.

Parameters:

• current_neuron_idx (int) – Index of the input neuron.

• spike_train_for_current_layer (np.ndarray) – Spike train for the current layer.

• synapses (np.ndarray) – Synapse weights for the layer.

• time_step (float) – Current time step in the simulation.

• next_neuron_idx (int) – Index of the target output neuron.

• synapse_memory (np.ndarray) – Memory to track updated synapses.

save_epoch(epoch: int, synapses: ndarray, neuron_label_map: ndarray, accuracy: float) → None

Save the model after a training epoch.

Parameters:

• epoch (int) – Current epoch number.

• synapses (np.ndarray) – Synapse weights after the epoch.

• neuron_label_map (np.ndarray) – Neuron-to-label mapping.

• accuracy (float) – Accuracy on the test set after the epoch.

test() → float

Test the Module on the provided test dataset.

Returns:

The accuracy of the Module on the test dataset.

Return type:

float

train() → float

Train the Module using the provided dataset.

Returns:

The accuracy on the test set after training.

Return type:

float

update_current_potentials_and_adaptive_thresholds(current_potentials: ndarray, neuron: LIFNeuron, neuron_index: int, spike_train_at_timestep: ndarray, synapses_for_neuron_index: ndarray, time_step: float, in_training: bool = False) → None

Update the membrane potential and adaptive thresholds of a neuron during feed-forward processing.

Parameters:

• current_potentials (np.ndarray) – Current potentials for all neurons in the layer.

• neuron (LIFNeuron) – The neuron to update.

• neuron_index (int) – Index of the neuron in the layer.

• spike_train_at_timestep (np.ndarray) – Spike train data at the current time step.

• synapses_for_neuron_index (np.ndarray) – Synapse weights for the neuron.

• time_step (float) – Current time step in the simulation.

• in_training (bool) – Is the model in train mode (do_stdp is True).

update_synapse(synapse_weight: float, weight_factor: float, next_neuron_idx: int, current_neuron_idx: int) → float

Adjust the synapse weight using the specified weight factor.

Parameters:

• synapse_weight (float) – The current weight of the synapse.

• weight_factor (float) – The adjustment factor based on STDP.

• next_neuron_idx (int) – Index of the post-synaptic neuron.

• current_neuron_idx (int) – Index of the pre-synaptic neuron.

Returns:

The updated synapse weight.

Return type:

float

nervos.utils.module.apply_truncated_noise_to_value(value: float, half_range: float) → float

Applies truncated normal noise to a single floating-point value.

Parameters:

• value (float) – The input value between 0 and 1.

• half_range (float) – The half-range for the noise distribution.

Returns:

The value with noise applied, clipped to [0, 1].

Return type:

float

nervos.utils.module.apply_truncated_noise_vectorized(input_array: ndarray, half_range: float) → ndarray

Applies truncated normal noise to an array of values.

Parameters:

• input_array (np.ndarray) – The input array of values between 0 and 1.

• half_range (float) – The half-range for the noise distribution.

Returns:

The array with noise applied, clipped to [0, 1].

Return type:

np.ndarray

nervos.utils.neuron module

This module defines the LIFNeuron class, which models a Leaky Integrate-and-Fire (LIF) neuron. The neuron is characterized by its potential dynamics, refractory period, and adaptive threshold. It provides methods for updating the neuron’s state after firing or being inhibited, as well as resetting its initial state.

class nervos.utils.neuron.LIFNeuron(parameters: Parameters)

Bases: object

A Leaky Integrate-and-Fire (LIF) neuron model.

This class models the dynamics of a LIF neuron, including its potential updates, refractory behavior, and adaptive threshold.

parameters

Configuration parameters for the neuron.

Type:

Parameters

adaptive_threshold

The dynamic threshold for the neuron to fire.

Type:

float

refractory_time

The refractory time during which the neuron cannot fire.

Type:

float

potential

The current membrane potential of the neuron.

Type:

float

rest_until

The time step until which the neuron remains at rest.

Type:

int

potential_memory

Stores the potential at any time step of training.

Type:

dict[int, float]

inhibit(time_step: float)

Inhibit the neuron by setting its potential to the inhibitory potential.

Parameters:

time_step (float) – The current time step when the neuron is inhibited.

Returns:

None

initial()

Reset the neuron’s state to its initial configuration.

Initializes the adaptive threshold, refractory time, resting potential, and resets the rest_until attribute.

Parameters:

None

Returns:

None

state_just_after_firing(time_step: float)

Update the neuron’s state immediately after firing.

Sets the potential to the reset potential and schedules the neuron to remain at rest until the end of the refractory period.

Parameters:

time_step (float) – The current time step when the neuron fires.

Returns:

None

nervos.utils.parameters module

This module defines the Parameters class, which serves as a flexible container for various configuration parameters. The class provides methods for loading parameters from a URL, dictionary, or file, listing all parameters, and saving them to a JSON file.

class nervos.utils.parameters.Parameters

Bases: object

A dynamic configuration manager for storing, updating, and persisting parameters.

This class allows parameters to be loaded from different sources (URL, dictionary, file), listed in a readable format, or saved to a JSON file.

from_dict(parameters: dict) → None

Load parameters from a dictionary.

Parameters:

parameters (dict) – A dictionary of parameters to set.

from_file(path: str) → None

Load parameters from a JSON file.

Parameters:

path (str) – The path to the JSON file containing parameters.

from_url(url: str) → None

Load parameters from a JSON response at the specified URL.

Parameters:

url (str) – The URL from which to fetch the JSON parameters.

list_parameters() → None

Print all parameters and their values in a formatted table.

save(identifier: str, directory: str = None) → None

Save the parameters to a JSON file.

Parameters:

• identifier (str) – A unique identifier for the saved file.

• directory (str, optional) – The directory in which to save the file. Defaults to ‘parameters’ in the current working directory.

Module contents

This package implements a spiking neural network (SNN) framework, which includes modules for neurons, layers, parameters, and training.

The package provides a structure for creating and training a spiking neural network using biologically inspired spiking neurons, such as the Leaky Integrate-and-Fire (LIF) neuron model, and implements spike-timing dependent plasticity (STDP) for learning. It is composed of multiple modules and helper functions to support various operations like layer initialization, network training, data handling, and parameter management.

Submodules:

• common.py: Provides utility functions for logging, time tracking, file handling, and model saving/loading.

• layer.py: Contains the Layer class, which represents a layer in the network. It manages the list of neurons and synapses between them.

• module.py: Implements the main Module class, which manages the overall spiking neural network, including training, testing, and synapse updates.

• neuron.py: Defines the LIFNeuron class for the Leaky Integrate-and-Fire neurons, including mechanisms for spiking, threshold adaptation, and potential updates.

• parameters.py: Defines the Parameters class for configuring and storing network parameters, including learning rates, synapse properties, and training settings.

Key Features:

• Spiking Neurons: The LIFNeuron class models a biological spiking neuron, including mechanisms for potential integration, spiking, and adaptation.

• STDP (Spike-Timing Dependent Plasticity): The STDP method in the Module class implements the biological learning rule where synapse weights are adjusted based on spike timing between pre- and post-synaptic neurons.

• Layer and Synapse Management: The Layer class allows for layer-wise organization of neurons and synapses, enabling flexible model architecture.

• Training and Testing: The Module class facilitates network training and testing, managing data, synapse updates, and performance evaluation over multiple epochs.

• Parameter Management: The Parameters class handles network configuration, including saving and loading parameters from various sources (files, URLs, or dictionaries).

This package is designed for research and experimentation with spiking neural networks and is particularly useful for understanding biological learning principles in artificial systems.