ngclearn.components.synapses package

Subpackages

Submodules

ngclearn.components.synapses.STPDenseSynapse module

class ngclearn.components.synapses.STPDenseSynapse.STPDenseSynapse(*args, **kwargs)[source]

Bases: DenseSynapse

A dynamic dense synaptic cable; this synapse evolves according to short-term plasticity (STP) dynamics.

— Synapse Compartments: —
inputs - input (takes in external signals)
outputs - output signals
weights - current value matrix of synaptic efficacies
biases - current value vector of synaptic bias values
— Short-Term Plasticity Compartments: —
resources - fixed value matrix of synaptic resources (U)
u - release probability; fraction of resources ready for use
x - fraction of resources available after neurotransmitter depletion
Dynamics note:
If tau_d >> tau_f and resources U are large, then synapse is STD-dominated
If tau_d << tau_f and resources U are small, then synases is STF-dominated
Parameters:
  • name – the string name of this cell

  • shape – tuple specifying shape of this synaptic cable (usually a 2-tuple with number of inputs by number of outputs)

  • weight_init – a kernel to drive initialization of this synaptic cable’s values; typically a tuple with 1st element as a string calling the name of initialization to use

  • bias_init – a kernel to drive initialization of biases for this synaptic cable (Default: None, which turns off/disables biases)

  • g_conduct_factor – a fixed (resistance) scaling factor to apply to synaptic transform (Default: 1.), i.e., yields: out = ((W * g_conduct_factor) * in)

  • p_conn – probability of a connection existing (default: 1.); setting this to < 1 and > 0. will result in a sparser synaptic structure (lower values yield sparse structure)

  • tau_f – short-term facilitation (STF) time constant (default: 750 ms); note that setting this to 0 ms will disable STF

  • tau_d – shoft-term depression time constant (default: 50 ms); note that setting this to 0 ms will disable STD

  • resources_int – initialization kernel for synaptic resources matrix

advance_state(t, dt)[source]
classmethod help()[source]
reset()[source]

ngclearn.components.synapses.alphaSynapse module

class ngclearn.components.synapses.alphaSynapse.AlphaSynapse(*args, **kwargs)[source]

Bases: DenseSynapse

A dynamic alpha synaptic cable; this synapse evolves according to alpha synaptic conductance dynamics. Specifically, the conductance dynamics are as follows:

dh/dt = -h/tau_decay + gBar sum_k (t - t_k) // h is an intermediate variable
dg/dt = -g/tau_decay + h/tau_decay
i_syn = g * (syn_rest - v) // g is g_syn and h is h_syn in this synapse implementation
where: syn_rest is the post-synaptic reverse potential for this synapse
t_k marks time of -pre-synaptic k-th pulse received by post-synaptic unit
— Synapse Compartments: —
inputs - input (takes in external signals, e.g., pre-synaptic pulses/spikes)
outputs - output signals (also equal to i_syn, total electrical current)
v - coupled voltages from post-synaptic neurons this synaptic cable connects to
weights - current value matrix of synaptic efficacies
biases - current value vector of synaptic bias values
— Dynamic / Short-term Plasticity Compartments: —
g_syn - fixed value matrix of synaptic resources (U)
i_syn - derived total electrical current variable
Parameters:
  • name – the string name of this synapse

  • shape – tuple specifying shape of this synaptic cable (usually a 2-tuple with number of inputs by number of outputs)

  • tau_decay – synaptic decay time constant (ms)

  • g_syn_bar – maximum conductance elicited by each incoming spike (“synaptic weight”)

  • syn_rest – synaptic reversal potential; note, if this is set to None, then this synaptic conductance model will no longer be voltage-dependent (and will ignore the voltage compartment provided by an external spiking cell)

  • weight_init – a kernel to drive initialization of this synaptic cable’s values; typically a tuple with 1st element as a string calling the name of initialization to use

  • bias_init – a kernel to drive initialization of biases for this synaptic cable (Default: None, which turns off/disables biases) <unused>

  • g_conduct_factor – a fixed (resistance) scaling factor to apply to synaptic transform (Default: 1.), i.e., yields: out = ((W * Rscale) * in)

  • p_conn – probability of a connection existing (default: 1.); setting this to < 1 and > 0. will result in a sparser synaptic structure (lower values yield sparse structure)

  • is_nonplastic – boolean indicating if this synapse permits plasticity adjustments (Default: True)

advance_state(t, dt)[source]
classmethod help()[source]
reset()[source]

ngclearn.components.synapses.denseSynapse module

class ngclearn.components.synapses.denseSynapse.DenseSynapse(*args, **kwargs)[source]

Bases: JaxComponent

A dense synaptic cable; no form of synaptic evolution/adaptation is in-built to this component.

— Synapse Input Compartments: —
inputs - input (takes in external signals)
— Synapse State Compartments: —
weights - current value matrix of synaptic efficacies (strength values)
biases - current value vector of synaptic bias values
gate - current values of multiplicative (output) gate/modulator (Default: 1)
— Synapse Output Compartments: —
outputs - output signals
Parameters:
  • name – the string name of this cell

  • shape – tuple specifying shape of this synaptic cable (usually a 2-tuple with number of inputs by number of outputs)

  • weight_init – a kernel to drive initialization of this synaptic cable’s values; typically a tuple with 1st element as a string calling the name of initialization to use

  • bias_init – a kernel to drive initialization of biases for this synaptic cable (Default: None, which turns off/disables biases)

  • g_conduct_factor – a fixed (resistance) scaling factor to apply to synaptic transform (Default: 1.), i.e., yields: out = ((W * in) * g_conduct_factor) + bias

  • p_release_mean – probability of pre-synaptic transmission; only if this value is > 0 and < 1, this synapse will enforce stochastic synaptic tranmission on pre-synaptic signals, meaning that each pre-synaptic signal will make it across the synaptic cable with a probability of p(transmit) = p_release_mean +/- 0.1 (Default: 1)

  • p_conn – probability of a connection existing (default: 1.); setting this to < 1 and > 0. will result in a sparser synaptic structure (lower values yield sparse structure)

  • max_delay_steps – maximum delay length (in terms of discrete simulation time-steps) to delay transmission of pre-synaptic signals across this synaptic cable; note that setting this to 0 disables the use of synaptic delay (Default: 0)

  • mask – if non-None, a (multiplicative) mask is applied to this synaptic weight matrix

advance_state()[source]
classmethod help()[source]
reset()[source]

ngclearn.components.synapses.doubleExpSynapse module

class ngclearn.components.synapses.doubleExpSynapse.DoubleExpSynapse(*args, **kwargs)[source]

Bases: DenseSynapse

A dynamic double-exponential synaptic cable; this synapse evolves according to difference of two exponentials synaptic conductance dynamics. Specifically, the conductance dynamics are as follows:

dh/dt = -h/tau_rise + gBar sum_k (t - t_k) * (1/tau_rise - 1/tau_decay) // h is an intermediate variable
dg/dt = -g/tau_decay + h
i_syn = g * (syn_rest - v) // g is g_syn and h is h_syn in this synapse implementation
where: syn_rest is the post-synaptic reverse potential for this synapse
t_k marks time of -pre-synaptic k-th pulse received by post-synaptic unit
— Synapse Compartments: —
inputs - input (takes in external signals, e.g., pre-synaptic pulses/spikes)
outputs - output signals (also equal to i_syn, total electrical current)
v - coupled voltages from post-synaptic neurons this synaptic cable connects to
weights - current value matrix of synaptic efficacies
biases - current value vector of synaptic bias values
— Dynamic / Short-term Plasticity Compartments: —
g_syn - fixed value matrix of synaptic resources (U)
i_syn - derived total electrical current variable
Parameters:
  • name – the string name of this synapse

  • shape – tuple specifying shape of this synaptic cable (usually a 2-tuple with number of inputs by number of outputs)

  • tau_decay – synaptic decay time constant (ms)

  • tau_rise – synaptic increase/rise time constant (ms)

  • g_syn_bar – maximum conductance elicited by each incoming spike (“synaptic weight”)

  • syn_rest – synaptic reversal potential; note, if this is set to None, then this synaptic conductance model will no longer be voltage-dependent (and will ignore the voltage compartment provided by an external spiking cell)

  • weight_init – a kernel to drive initialization of this synaptic cable’s values; typically a tuple with 1st element as a string calling the name of initialization to use

  • bias_init – a kernel to drive initialization of biases for this synaptic cable (Default: None, which turns off/disables biases) <unused>

  • g_conduct_factor – a fixed (resistance) scaling factor to apply to synaptic transform (Default: 1.), i.e., yields: out = ((W * g_conduct_factor) * in)

  • p_conn – probability of a connection existing (default: 1.); setting this to < 1 and > 0. will result in a sparser synaptic structure (lower values yield sparse structure)

  • is_nonplastic – boolean indicating if this synapse permits plasticity adjustments (Default: True)

advance_state(t, dt)[source]
classmethod help()[source]
reset()[source]

ngclearn.components.synapses.exponentialSynapse module

class ngclearn.components.synapses.exponentialSynapse.ExponentialSynapse(*args, **kwargs)[source]

Bases: DenseSynapse

A dynamic exponential synaptic cable; this synapse evolves according to exponential synaptic conductance dynamics. Specifically, the conductance dynamics are as follows:

dg/dt = -g/tau_decay + gBar sum_k (t - t_k)
i_syn = g * (syn_rest - v) // g is g_syn in this synapse implementation
where: syn_rest is the post-synaptic reverse potential for this synapse
t_k marks time of -pre-synaptic k-th pulse received by post-synaptic unit
— Synapse Compartments: —
inputs - input (takes in external signals, e.g., pre-synaptic pulses/spikes)
outputs - output signals (also equal to i_syn, total electrical current)
v - coupled voltages from post-synaptic neurons this synaptic cable connects to
weights - current value matrix of synaptic efficacies
biases - current value vector of synaptic bias values
— Dynamic / Short-term Plasticity Compartments: —
g_syn - fixed value matrix of synaptic resources (U)
i_syn - derived total electrical current variable
Parameters:
  • name – the string name of this synapse

  • shape – tuple specifying shape of this synaptic cable (usually a 2-tuple with number of inputs by number of outputs)

  • tau_decay – synaptic decay time constant (ms)

  • g_syn_bar – maximum conductance elicited by each incoming spike (“synaptic weight”)

  • syn_rest – synaptic reversal potential; note, if this is set to None, then this synaptic conductance model will no longer be voltage-dependent (and will ignore the voltage compartment provided by an external spiking cell)

  • weight_init – a kernel to drive initialization of this synaptic cable’s values; typically a tuple with 1st element as a string calling the name of initialization to use

  • bias_init – a kernel to drive initialization of biases for this synaptic cable (Default: None, which turns off/disables biases) <unused>

  • g_conduct_factor – a fixed (resistance) scaling factor to apply to synaptic transform (Default: 1.), i.e., yields: out = ((W * g_conduct_factor) * in)

  • p_conn – probability of a connection existing (default: 1.); setting this to < 1 and > 0. will result in a sparser synaptic structure (lower values yield sparse structure)

  • is_nonplastic – boolean indicating if this synapse permits plasticity adjustments (Default: True)

advance_state(t, dt)[source]
classmethod help()[source]
reset()[source]

ngclearn.components.synapses.mpsSynapse module

class ngclearn.components.synapses.mpsSynapse.MPSSynapse(*args, **kwargs)[source]

Bases: JaxComponent

A Matrix Product State (MPS) compressed synaptic cable.

This component represents a synaptic weight matrix decomposed into a contracted chain of low-rank tensor cores (also known as a “tensor train”). This architecture drastically reduces parameter counts for high-dimensional layers – from O(N*M) to O(N*K + M*K) – while maintaining high expressive power and biological plausibility through local error-driven updates.

References:
Stoudenmire, E. Miles, and David J. Schwab. “Supervised learning with
quantum-inspired tensor networks.” Advances in neural information
processing systems 29 (2016).

Novikov, Alexander, et al. “Tensorizing neural networks.” Advances in
neural information processing systems 28 (2015).

Nuijten, W. W. L., et al. “A Message Passing Realization of Expected
Free Energy Minimization.” arXiv preprint arXiv:2501.03154 (2025).

Wilson, P. “Performing Active Inference with Explainable Tensor
Networks.” (2024).

Fields, Chris, et al. “Control flow in active inference systems.”
arXiv preprint arXiv:2303.01514 (2023).
— Synapse Compartments: —
inputs - external input signal values (shape: batch_size x in_dim)
outputs - transformed signal values (shape: batch_size x out_dim)
pre - pre-synaptic latent state values for learning (shape: batch_size x in_dim)
post - post-synaptic error signal values for learning (shape: batch_size x out_dim)
core1 - first MPS tensor core (shape: 1 x in_dim x bond_dim)
core2 - second MPS tensor core (shape: bond_dim x out_dim x 1)
key - JAX PRNG key used for stochasticity
Parameters:
  • name – the string name of this component

  • shape – tuple specifying the shape of the latent synaptic weight matrix (number of inputs, number of outputs)

  • bond_dim – the internal rank or “bond dimension” of the MPS compression. Higher values increase expressive power at the cost of more parameters. (Default: 16)

  • batch_size – the number of samples in a concurrent batch (Default: 1)

advance_state()[source]

Performs the forward synaptic transformation using MPS contraction.

The full transformation is equivalent to: outputs = inputs @ (Core1 * Core2), but computed via iterative contraction to maintain memory efficiency: 1. z = inputs contracted with Core1 (Batch x Bond_Dim) 2. outputs = z contracted with Core2 (Batch x Out_Dim)

evolve(eta=0.01)[source]

Updates the MPS tensor cores using local error-driven (Hebbian) gradients.

This utilizes the ‘pre’ and ‘post’ compartments to update core1 and core2. Because the weights are factorized, the update to each core depends on the activity and errors projected through the other core, maintaining global consistency through local message passing.

classmethod help()[source]

Returns an info dictionary describing the component.

project_backward(error_signal)[source]

Projects an error signal backwards through the compressed synaptic cable.

This allows the passing of messages/gradients through the hierarchy without ever reconstructing the full dense weight matrix, ensuring O(N) complexity relative to the input/output dimensions.

reset()[source]

Resets input, output, and activity compartments to zero.

property weights

Reconstructs the full dense matrix from the MPS cores for analysis. Note: This is computationally expensive for high-dimensional layers.

ngclearn.components.synapses.sparseTensorSynapse module

class ngclearn.components.synapses.sparseTensorSynapse.SparseTensorSynapse(*args, **kwargs)[source]

Bases: DenseSynapse

A sparse tensor-synaptic cable. Note this component cable implements a full, locally-connected structure or an unshared convolutional synaptic tensor structural component (cable).

— Synapse Input Compartments: —
inputs - input (takes in external signals)
— Synapse State Compartments: —
weights - current value matrix of synaptic efficacies (strength values)
biases - current value vector of synaptic bias values
— Synapse Output Compartments: —
outputs - output signals
Parameters:
  • name – the string name of this cell

  • n_in_streams – total number of incoming streams

  • K_local – input local block feature size

  • O_local – output local block feature size (note: total number of output streams is computed internally)

  • P_l – local window size (how many input streams to grab), i.e., maximum connection window size (defines tensor shape) (Default: 1)

  • stride – stride factor for locally-connected structure to “skip over” (in terms of incoming streams); stride step between successive output receptive field streams (Default: 1)

  • convergent_factor – if > 0, windows contract symmetrically towards center of layer (simulates foveation or variable resolution) (Default: 0)

  • dilation – dilation factor; gap between input indices inside a block (1 = contiguous) (Default: 1)

  • invert_conn – if True, this tensor shape will internally “transpose” itself to formulate the appropriate locally-connected inverted/transposed structure (note that this means the shape will no longer be what the constructor’s argument dictate - it will be the effective transpose of these arguments) (Default: False)

  • normalize – if True, this synaptic tensor will normalize its internal blocks (Default: False)

  • norm_axis – axis upon which block norms are computed (Default: 1)

  • weight_init – a kernel to drive initialization of this synaptic cable’s values; typically a tuple with 1st element as a string calling the name of initialization to use

  • bias_init – a kernel to drive initialization of biases for this synaptic cable (Default: None, which turns off/disables biases)

  • g_conduct_factor – a fixed (resistance) scaling factor to apply to synaptic transform (Default: 1.), i.e., yields: out = ((W * in) * g_conduct_factor) + bias

  • p_conn – probability of a connection existing (default: 1.); setting this to < 1 and > 0. will result in a sparser synaptic structure (lower values yield sparse structure)

  • use_block_matrix_format – if True, this tensor synapse resorts to a memory-intensive block-matrix computational format (Default: False)

advance_state()[source]
static initialize_layer_geometry(nlm1_streams, Nlm1, Nl, P_l, stride_l, auto_pad=False, dilation_l=1, convergent_factor_l=0.0)[source]
reset()[source]
tie_transpose_weights()[source]
ngclearn.components.synapses.sparseTensorSynapse.precompute_transpose_indices(forward_conn_map, backward_conn_map, forward_shape, backward_shape)[source]

Pre-computes a flat index gather array mapping a forward unshared tensor to its exact transposed backward tensor configuration.

Forward Shape: (P_f, S_f, K_f, O_f) Backward Shape: (P_b, S_b, K_b, O_b) -> Typically K_b == O_f and O_b == K_f

ngclearn.components.synapses.staticSparseTensorSynapse module

class ngclearn.components.synapses.staticSparseTensorSynapse.StaticSparseTensorSynapse(*args, **kwargs)[source]

Bases: SparseTensorSynapse

” A static sparse tensor-synaptic cable; no form of synaptic evolution/adaptation is in-built to this component. Note this component cable implements a full, locally-connected structure or an unshared convolutional synaptic tensor structural component (cable).

— Synapse Input Compartments: —
inputs - input (takes in external signals)
— Synapse State Compartments: —
weights - current value matrix of synaptic efficacies (strength values)
biases - current value vector of synaptic bias values
— Synapse Output Compartments: —
outputs - output signals
Parameters:
  • name – the string name of this cell

  • n_in_streams – total number of incoming streams

  • K_local – input local block feature size

  • O_local – output local block feature size (note: total number of output streams is computed internally)

  • P_l – local window size (how many input streams to grab), i.e., maximum connection window size (defines tensor shape) (Default: 1)

  • stride – stride factor for locally-connected structure to “skip over” (in terms of incoming streams); stride step between successive output receptive field streams (Default: 1)

  • convergent_factor – if > 0, windows contract symmetrically towards center of layer (simulates foveation or variable resolution) (Default: 0)

  • dilation – dilation factor; gap between input indices inside a block (1 = contiguous) (Default: 1)

  • invert_conn – if True, this tensor shape will internally “transpose” itself to formulate the appropriate locally-connected inverted/transposed structure (note that this means the shape will no longer be what the constructor’s argument dictate - it will be the effective transpose of these arguments) (Default: False)

  • normalize – if True, this synaptic tensor will normalize its internal blocks (Default: False)

  • norm_axis – axis upon which block norms are computed (Default: 1)

  • weight_init – a kernel to drive initialization of this synaptic cable’s values; typically a tuple with 1st element as a string calling the name of initialization to use

  • bias_init – a kernel to drive initialization of biases for this synaptic cable (Default: None, which turns off/disables biases)

  • g_conduct_factor – a fixed (resistance) scaling factor to apply to synaptic transform (Default: 1.), i.e., yields: out = ((W * in) * g_conduct_factor) + bias

  • p_conn – probability of a connection existing (default: 1.); setting this to < 1 and > 0. will result in a sparser synaptic structure (lower values yield sparse structure)

  • use_block_matrix_format – if True, this tensor synapse resorts to a memory-intensive block-matrix computational format (Default: False)

ngclearn.components.synapses.staticSynapse module

class ngclearn.components.synapses.staticSynapse.StaticSynapse(*args, **kwargs)[source]

Bases: DenseSynapse

A static dense synaptic cable; no form of synaptic evolution/adaptation is in-built to this component.

— Synapse Compartments: —
inputs - input (takes in external signals)
outputs - output
weights - current value matrix of synaptic efficacies
Parameters:
  • name – the string name of this cell

  • shape – tuple specifying shape of this synaptic cable (usually a 2-tuple with number of inputs by number of outputs)

  • weight_init – a kernel to drive initialization of this synaptic cable’s values; typically a tuple with 1st element as a string calling the name of initialization to use

  • g_conduct_factor – a fixed (conductance) scaling factor to apply to synaptic transform (Default: 1.), i.e., yields: out = ((W * g_conduct_factor) * in)

  • p_conn – probability of a connection existing (default: 1.); setting this to < 1 and > 0. will result in a sparser synaptic structure (lower values yield sparse structure)

Module contents