engine.synapse

Synapses connect neurons or ensembles to each other.

class engine.synapse.Synapse(src_ensemble: [<class 'sapicore.engine.neuron.Neuron'>] = None, dst_ensemble: [<class 'sapicore.engine.neuron.Neuron'>] = None, weight_max: float = 1000.0, weight_min: float = -1000.0, delay_ms: float = 0.0, simple_delays: bool = True, weight_init_method: ~typing.Callable = <function xavier_uniform_>, **kwargs)

Static synapse base class.

This class provides basic parameters and logic for connecting ensemble instances. Static synapses keep their initial weights throughout the simulation unless manually adjusted. Synapse instances have 2D weight and connectivity matrices, reflecting their role as layer-to-layer connectors.

Synapses own the following parameters, over and above those inherited from Component:

Parameters:

  • src_ensemble (Neuron) – Reference to the presynaptic (sending) ensemble.

  • dst_ensemble (Neuron) – Reference to postsynaptic ensemble (receiving) ensemble.

  • weight_max (float or Tensor) – Positive weight value limit for any synapse element (applies throughout the simulation).

  • weight_min (float or Tensor) – Negative weight value limit for any synapse element (applies throughout the simulation).

  • delay_ms (float or Tensor) – Generic transmission delay, managed by the synapse object using queues. Transmission delays are useful for some temporal coding schemes.

  • simple_delays (bool) – Whether transmission delay values from one presynaptic element are the same for all postsynaptic targets. Provides a speed-control tradeoff (one matrix multiplication vs. N vector multiplications).

  • weight_init_method (Callable) – Weight initialization method from torch.nn.init.

  • connections (Tensor) – 2D binary integer mask matrix indicating which source unit -> destination unit connections are enabled. Loggable attribute.

  • weights (Tensor) – 2D float matrix storing a weight for each pair of source and destination ensemble units. Loggable attribute.

  • output (Tensor) – 1D tensor storing the result of W*x matrix multiplication in the current simulation step. Loggable attribute.

_config_props_: tuple[str] = ('weight_max', 'weight_min', 'delay_ms', 'simple_delays')

A list of configurable property names of the class that is set/read by the configuration API.

Each sub/super-class can define this and the properties are accumulated across all the sub/super-classes.

connect(mode: str = 'all', prop: float = 1.0)

Applies a predefined connectivity mask strategy.

Parameters:

  • mode (str) – Sapicore provides four built-in connectivity mask initialization options: “all”, “one”, “prop”, “rand”. “all” enables all connections (matrix of 1s) except self-connections (diagonal) if the destination and source ensemble are the same object. “one” connects the i-th source neuron to the i-th destination neuron, zeroing out all matrix elements except the diagonal. “prop” connects each source neuron to prop`*`dst_ensemble.num_units randomly selected destination neurons. “rand” sets a proportion prop of the matrix elements to 1 with no balance constraints (unlike “prop”).

  • prop –

    Desired proportion a neurons in destination receiving a connection from a particular neuron in the source ensemble. Rounded to an integer using np.round.

    E.g., if prop = 0.2 and matrix_shape is (100, 5), 20 random row elements (destination neurons) in the connectivity mask will be set to 1.

Raises:

ValueError – If mode was set to a value other than “all”, “one”, “prop”, or “rand”.

Warning

Attempting to initialize one-to-one connectivity between ensembles of different sizes will necessarily result in some unconnected neurons. The faux-diagonal will be set to 1s but there will be all 0s rows/cols, depending on whether the source or destination ensemble is bigger.

forward(data: Tensor) → dict

Static synapse forward method. Amounts to a simple matrix multiplication.

When called with synapses that have nonzero transmission delays, variably-old data will be used as dictated by the queue maintained by this instance.

Parameters:

data (Tensor) – Output vector from the input layer in the previous iteration (spiked buffer, containing 0s and 1s).

Returns:

Dictionary containing weights, connections, and output for further processing.

Return type:

dict

Note

The simple transmission delay implementation, for runtime efficiency, assumes that recipient synapse elements all have a shared “view” of incoming activity in the presynaptic ensemble. This means a single matrix multiplication (dst x src) by (src x 1) = (dst x 1) is performed. A smaller queue list of length src_ensemble.num_units is maintained, as opposed to src_ensemble.matrix_shape.

If simple_delays is toggled off, each neuron in the recipient ensemble may have a different delayed view of the source ensemble activity. This means that N vector multiplications must be performed: sig(W[k,i]*dd[i]) where N is the number of elements in the source ensemble, k the index of a destination element, i the index of a source element, W a weight, and dd the delayed data transmitted from the presynaptic neuron i to the postsynaptic neuron k.

heterogenize(num_combinations: int, unravel: bool = True)

Diversifies parameters in accordance with this synapse configuration dictionary and recomputes the spike delay queue in case values were altered.

queue_input(current_data: Tensor) → Tensor

Uses a list of queues to implement transmission delays and “release” input appropriately.

Initializes a list whose Nth element is a queue pre-filled with self.delay_ms[N] // DT zeros. On each forward iteration, call this method. It will enqueue the current source input data value and popleft() the head of the queue.

Returns:

1D tensor of input that occurred an appropriate number of steps ago for each unit.

Return type:

Tensor

set_learning(state: bool = False) → None

Switch weight updates on or off, e.g. before a training/testing round commences.

Parameters:

state (bool) – Toggle learning on if True, off if False.

Note

Fine-grained control over which synapse elements are toggled on will be added in the future, to support more sophisticated algorithms. Currently, the global learning switch is meant to be used, e.g., when feeding test buffer to a trained network with STDP synapses.

set_weights(weight_initializer: Callable, *args, **kwargs) → None

Initializes 2D weight matrix for this synapse instance.

Parameters:

weight_initializer (Callable) – Any weight initialization method from torch.nn.init. Args and kwargs are passed along to it.

update_weights() → Tensor

Static weight update rule. Placeholder for plastic synapse derivative classes (e.g., STDP).

Modules

engine.synapse.STDP

Synapses with spike-timing-dependent plasticity (STDP).