devices.xylo.syns61201.DivisiveNormalisation

class devices.xylo.syns61201.DivisiveNormalisation(*args, **kwargs)

Bases: Module

A digital divisive normalization block

Attributes overview

class_name	Class name of self
full_name	The full name of this module (class plus module name)
name	The name of this module, or an empty string if None
shape	The shape of this module
size	(DEPRECATED) The output size of this module
size_in	The input size of this module
size_out	The output size of this module
spiking_input	If True, this module receives spiking input.
spiking_output	If True, this module sends spiking output.
E_frame_counter	Spike rate per frame (N,)
bits_counter	Number of bits of spike rate counter E
IAF_counter	IAF state (N,)
bits_lowpass	Number of bits in low-pass filter state M
bits_shift_lowpass	Dash decay parameter for low-pass filter M
M_lowpass_state	Low-pass filter state M (N,)
dt	Global clock step in seconds
frame_dt	Frame clock step in seconds
bits_lfsr	Number of LFSR bits
code_lfsr	LFSR sequence to use for pRNG
lfsr_index	Current index into LFSR sequence
p_local	Factor to scale up internal spike generation.
low_pass_mode	Specifies which mode to use for low-pass filtering

Methods overview

__init__([shape, bits_counter, ...])	param shape: The number of channels N for this Module
as_graph()	Convert this module to a computational graph
attributes_named(name)	Search for attributes of this or submodules by time
evolve(input_spike[, record])	This class simulates divisive normalization for an input spike signal with one or several channels.
modules()	Return a dictionary of all sub-modules of this module
parameters([family])	Return a nested dictionary of module and submodule Parameters
reset_parameters()	Reset all parameters in this module
reset_state()	Reset the state of this module
set_attributes(new_attributes)	Set the attributes and sub-module attributes from a dictionary
simulation_parameters([family])	Return a nested dictionary of module and submodule SimulationParameters
state([family])	Return a nested dictionary of module and submodule States
timed([output_num, dt, add_events])	Convert this module to a TimedModule

E_frame_counter: P_ndarray

Spike rate per frame (N,)

Type:

np.ndarray

IAF_counter: P_ndarray

IAF state (N,)

Type:

np.ndarray

M_lowpass_state: P_ndarray

Low-pass filter state M (N,)

Type:

np.ndarray

__init__(shape: int | Tuple[int] = 1, *args, bits_counter: int = 10, E_frame_counter: ndarray | None = None, IAF_counter: ndarray | None = None, bits_lowpass: int = 16, bits_shift_lowpass: int = 5, M_lowpass_state: int | None = None, dt: float | ParameterBase = 0.0001, frame_dt: float = 0.05, bits_lfsr: int = 10, code_lfsr: ndarray | None = None, p_local: int = 12, low_pass_mode: LowPassMode = LowPassMode.UNDERFLOW_PROTECT, **kwargs)

Parameters:

• shape (tuple) – The number of channels N for this Module

• bits_counter (int) – Bit-width of frame counter E. Defualt: 10

• E_frame_counter (np.ndarray) – Initialisation for frame counter E (N,). Default: None, initialise to zero.

• IAF_counter (np.ndarray) – Initialisation for IAF state (N,). Defualt: None, initialise to zero.

• bits_lowpass (int) – Number of bits used by the low-pass filter M. Default: 16

• bits_shift_lowpass (int) – Dash bitshift averaging parameter to use in low-pass filter. Default: 5

• M_lowpass_state (np.ndarray) – Initialisation for low-pass state (N,). Default: None, initialise to zero.

• dt (float) – Global clock step in seconds. Default: 0.1ms

• frame_dt (float) – Frame clock step in seconds. Default: 50ms

• bits_lfsr (int) – Bit-width of LFSR. Default: 10

• code_lfsr (np.ndarray) – LFSR sequence to use. Default: Load a pre-defined LFSR sequence.

• p_local (int) – Factor to multiply spike rate E. Factor p is given by p_local / 2.

• low_pass_mode (LowPassMode) – Specify how to compute the low-pass filter M. Possible values are LowPassMode.UNDERFLOW_PROTECT and LowPassMode.OVERFLOW_PROTECT. Default: LowPassMode.UNDERFLOW_PROTECT, optimised for low input event frequencies. LowPassMode.OVERFLOW_PROTECT is optimal for high input frequencies.

_abc_impl = <_abc._abc_data object>

_auto_batch(data: ndarray, states: Tuple = (), target_shapes: Tuple | None = None) → Tuple[ndarray, Tuple[ndarray]]

Automatically replicate states over batches and verify input dimensions

Examples

>>> data, (state0, state1, state2) = self._auto_batch(data, (self.state0, self.state1, self.state2))

This will verify that data has the correct final dimension (i.e. self.size_in).

If data has only two dimensions (T, Nin), then it will be augmented to (1, T, Nin). The individual states will be replicated out from shape (a, b, c, ...) to (n_batches, a, b, c, ...) and returned.

If data has only a single dimension (T,), it will be expanded to (1, T, self.size_in).

state0, state1, state2 will be replicated out along the batch dimension.

>>> data, (state0,) = self._auto_batch(data, (self.state0,), ((10, -1, self.size_in),))

Attempt to replicate state0 to a specified size (10, -1, self.size_in).

Parameters:

• data (np.ndarray) – Input data tensor. Either (batches, T, Nin) or (T, Nin)

• states (Tuple) – Tuple of state variables. Each will be replicated out over batches by prepending a batch dimension

• target_shapes (Tuple) – A tuple of target size tuples, each corresponding to each state argument. The individual states will be replicated out to match the corresponding target sizes. If not provided (the default), then states will be only replicated along batches.

Returns:

(np.ndarray, Tuple[np.ndarray]) data, states

_force_set_attributes

(bool) If True, do not sanity-check attributes when setting.

_get_attribute_family(type_name: str, family: Tuple | List | str | None = None) → dict

Search for attributes of this module and submodules that match a given family

This method can be used to conveniently get all weights for a network; or all time constants; or any other family of parameters. Parameter families are defined simply by a string: "weights" for weights; "taus" for time constants, etc. These strings are arbitrary, but if you follow the conventions then future developers will thank you (that includes you in six month’s time).

Parameters:

• type_name (str) – The class of parameters to search for. Must be one of ["Parameter", "SimulationParameter", "State"] or another future subclass of ParameterBase

• family (Union[str, Tuple[str]]) – A string or list or tuple of strings, that define one or more attribute families to search for

Returns:

A nested dictionary of attributes that match the provided type_name and family

Return type:

dict

_get_attribute_registry() → Tuple[Dict, Dict]

Return or initialise the attribute registry for this module

Returns:

registered_attributes, registered_modules

Return type:

(tuple)

_has_registered_attribute(name: str) → bool

Check if the module has a registered attribute

Parameters:

name (str) – The name of the attribute to check

Returns:

True if the attribute name is in the attribute registry, False otherwise.

Return type:

bool

_in_Module_init

(bool) If exists and True, indicates that the module is in the __init__ chain.

_low_pass_overflow_protect(E_t: ndarray, M_t: ndarray) → ndarray

Implement one low-pass filter time-step, with overflow protection

Parameters:

• E_t (np.ndarray) – Input rates for this frame ``(N,)`

• M_t (np.ndarray) – Current low-pass state from previous frame (N,)

Returns:

Low-pass state for the next frame (N,)

Return type:

np.ndarray

_low_pass_underflow_protect(E_t: ndarray, M_t: ndarray) → ndarray

Implement one low-pass filter time-step, with underflow protection

Parameters:

• E_t (np.ndarray) – Input rates for this frame ``(N,)`

• M_t (np.ndarray) – Current low-pass state from previous frame (N,)

Returns:

Low-pass state for the next frame (N,)

Return type:

np.ndarray

_name: str | None

Name of this module, if assigned

_register_attribute(name: str, val: ParameterBase)

Record an attribute in the attribute registry

Parameters:

• name (str) – The name of the attribute to register

• val (ParameterBase) – The ParameterBase subclass object to register. e.g. Parameter, SimulationParameter or State.

_register_module(name: str, mod: ModuleBase)

Register a sub-module in the module registry

Parameters:

• name (str) – The name of the module to register

• mod (ModuleBase) – The ModuleBase object to register

_reset_attribute(name: str) → ModuleBase

Reset an attribute to its initialisation value

Parameters:

name (str) – The name of the attribute to reset

Returns:

For compatibility with the functional API

Return type:

self (Module)

_shape

The shape of this module

_spiking_input: bool

Whether this module receives spiking input

_spiking_output: bool

Whether this module produces spiking output

_submodulenames: List[str]

Registry of sub-module names

_wrap_recorded_state(recorded_dict: dict, t_start: float) → Dict[str, TimeSeries]

Convert a recorded dictionary to a TimeSeries representation

This method is optional, and is provided to make the timed() conversion to a TimedModule work better. You should override this method in your custom Module, to wrap each element of your recorded state dictionary as a TimeSeries

Parameters:

• state_dict (dict) – A recorded state dictionary as returned by evolve()

• t_start (float) – The initial time of the recorded state, to use as the starting point of the time series

Returns:

The mapped recorded state dictionary, wrapped as TimeSeries objects

Return type:

Dict[str, TimeSeries]

as_graph() → GraphModuleBase

Convert this module to a computational graph

Returns:

The computational graph corresponding to this module

Return type:

GraphModuleBase

Raises:

NotImplementedError – If as_graph() is not implemented for this subclass

attributes_named(name: Tuple[str] | List[str] | str) → dict

Search for attributes of this or submodules by time

Parameters:

name (Union[str, Tuple[str]) – The name of the attribute to search for

Returns:

A nested dictionary of attributes that match name

Return type:

dict

bits_counter: P_int

Number of bits of spike rate counter E

Type:

int

bits_lfsr: P_int

Number of LFSR bits

Type:

int

bits_lowpass: P_int

Number of bits in low-pass filter state M

Type:

int

bits_shift_lowpass: P_int

Dash decay parameter for low-pass filter M

Type:

int

property class_name: str

Class name of self

Type:

str

code_lfsr: P_ndarray

LFSR sequence to use for pRNG

Type:

np.ndarray

dt: P_float

Global clock step in seconds

Type:

float

evolve(input_spike: ndarray, record: bool = False) → Tuple[ndarray, dict]

This class simulates divisive normalization for an input spike signal with one or several channels. The output of the simulation is another spike signal with normalized rates.

frame_dt: P_float

Frame clock step in seconds

Type:

float

property full_name: str

The full name of this module (class plus module name)

Type:

str

lfsr_index: P_int

Current index into LFSR sequence

Type:

int

low_pass_mode

Specifies which mode to use for low-pass filtering

Type:

LowPassMode

modules() → Dict

Return a dictionary of all sub-modules of this module

Returns:

A dictionary containing all sub-modules. Each item will be named with the sub-module name.

Return type:

dict

property name: str

The name of this module, or an empty string if None

Type:

str

p_local: P_int

Factor to scale up internal spike generation.

Type:

int

parameters(family: Tuple | List | str | None = None) → Dict

Return a nested dictionary of module and submodule Parameters

Use this method to inspect the Parameters from this and all submodules. The optional argument family allows you to search for Parameters in a particular family — for example "weights" for all weights of this module and nested submodules.

Although the family argument is an arbitrary string, reasonable choises are "weights", "taus" for time constants, "biases" for biases…

Examples

Obtain a dictionary of all Parameters for this module (including submodules):

>>> mod.parameters()
dict{ ... }

Obtain a dictionary of Parameters from a particular family:

>>> mod.parameters("weights")
dict{ ... }

Parameters:

family (str) – The family of Parameters to search for. Default: None; return all parameters.

Returns:

A nested dictionary of Parameters of this module and all submodules

Return type:

dict

reset_parameters()

Reset all parameters in this module

Returns:

The updated module is returned for compatibility with the functional API

Return type:

Module

reset_state() → ModuleBase

Reset the state of this module

Returns:

The updated module is returned for compatibility with the functional API

Return type:

Module

set_attributes(new_attributes: dict) → ModuleBase

Set the attributes and sub-module attributes from a dictionary

This method can be used with the dictionary returned from module evolution to set the new state of the module. It can also be used to set multiple parameters of a module and submodules.

Examples

Use the functional API to evolve, obtain new states, and set those states:

>>> _, new_state, _ = mod(input)
>>> mod = mod.set_attributes(new_state)

Obtain a parameter dictionary, modify it, then set the parameters back:

>>> params = mod.parameters()
>>> params['w_input'] *= 0.
>>> mod.set_attributes(params)

Parameters:

new_attributes (dict) – A nested dictionary containing parameters of this module and sub-modules.

property shape: tuple

The shape of this module

Type:

tuple

simulation_parameters(family: Tuple | List | str | None = None) → Dict

Return a nested dictionary of module and submodule SimulationParameters

Use this method to inspect the SimulationParameters from this and all submodules. The optional argument family allows you to search for SimulationParameters in a particular family.

Examples

Obtain a dictionary of all SimulationParameters for this module (including submodules):

>>> mod.simulation_parameters()
dict{ ... }

Parameters:

family (str) – The family of SimulationParameters to search for. Default: None; return all SimulationParameter attributes.

Returns:

A nested dictionary of SimulationParameters of this module and all submodules

Return type:

dict

property size: int

(DEPRECATED) The output size of this module

Type:

int

property size_in: int

The input size of this module

Type:

int

property size_out: int

The output size of this module

Type:

int

property spiking_input: bool

If True, this module receives spiking input. If False, this module expects continuous input.

Type:

bool

property spiking_output

If True, this module sends spiking output. If False, this module sends continuous output.

Type:

bool

state(family: Tuple | List | str | None = None) → Dict

Return a nested dictionary of module and submodule States

Use this method to inspect the States from this and all submodules. The optional argument family allows you to search for States in a particular family.

Examples

Obtain a dictionary of all States for this module (including submodules):

>>> mod.state()
dict{ ... }

Parameters:

family (str) – The family of States to search for. Default: None; return all State attributes.

Returns:

A nested dictionary of States of this module and all submodules

Return type:

dict

timed(output_num: int = 0, dt: float | None = None, add_events: bool = False)

Convert this module to a TimedModule

Parameters:

• output_num (int) – Specify which output of the module to take, if the module returns multiple output series. Default: 0, take the first (or only) output.

• dt (float) – Used to provide a time-step for this module, if the module does not already have one. If self already defines a time-step, then self.dt will be used. Default: None

• add_events (bool) – Iff True, the TimedModule will add events occurring on a single timestep on input and output. Default: False, don’t add time steps.

Returns: TimedModule: A timed module that wraps this module