devices.xylo.syns61201.XyloSamna

class devices.xylo.syns61201.XyloSamna(*args, **kwargs)[source]

Bases: Module

A spiking neuron Module backed by the Xylo hardware, via samna.

Use config_from_specification() to build and validate a configuration for Xylo.

See also

See the tutorials 🐝 Overview of the Xylo™ family and Training a spiking network to deploy to the Xylo™ digital SNN for a high-level overview of building and deploying networks for Xylo. See the tutorial 🐝🎵 Introduction to Xylo™Audio for information specific to the Xylo™Audio dev kits, including power measurement.

Note

Evolution of this module support measuring power during evolution. See evolve() for more information.

Attributes overview

`class_name`	Class name of `self`
`config`	The HDK configuration applied to the Xylo module
`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.
`dt`	Simulation time-step of the module, in seconds

Methods overview

`__init__`(device[, config, dt, output_mode, ...])	Instantiate a Module with Xylo dev-kit backend
`as_graph`()	Convert this module to a computational graph
`attributes_named`(name)	Search for attributes of this or submodules by time
`evolve`(input[, record, read_timeout, ...])	Evolve a network on the Xylo HDK in accelerated-time mode
`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`

__init__(device: Any, config: XyloConfiguration | None = None, dt: float = 0.001, output_mode: str = 'Spike', power_frequency: float | None = 5.0, *args, **kwargs)[source]

Instantiate a Module with Xylo dev-kit backend

Parameters:

device (XyloA2HDK) – An opened samna device to a Xylo dev kit
config (XyloConfiguration) – A Xylo configuration from samna
dt (float) – The simulation time-step to use for this Module
output_mode (str) – The readout mode for the Xylo device. This must be one of ["Spike", "Isyn", "Vmem"]. Default: “Spike”, return events from the output layer.
power_frequency (float) – The frequency of power measurement. Default: 5.0

_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

_config_hibernation_mode()[source]: Configure the Xylo HDK to use hibernation mode

_configure_accel_time_mode(Nhidden: int, Nout: int, record: bool = False) → None[source]

Configure the Xylo HDK to use accelerated-time mode, with optional state recording

Parameters:

Nhidden (int) – Number of hidden neurons from which to record state. Default: 0; do not record state from any neurons. If non-zero, state from neurons with ID 0..(Nhidden-1) inclusive will be recorded during evolution.
Nout (int) – Number of output layer neurons from which to record state. Default: 0; do not record state from any output neurons.
record (bool) – Iff True, record state during evolution. Default: False, do not record state.

_device: Any

The Xylo HDK used by this module

Type:: XyloHDK

_evolve_manual(input: ndarray, record: bool = False, read_timeout: float = 5.0, *args, **kwargs) → Tuple[ndarray, dict, dict][source]

Evolve a network on the Xylo HDK in single-step manual mode. For debug purposes only. Uses ‘samna.xyloCore2.OperationMode.Manual’ in samna.

Sends a series of events to the Xylo HDK, evolves the network over the input events, and returns the output events produced during the input period.

Parameters:

input (np.ndarray) – A raster (T, Nin) specifying for each bin the number of input events sent to the corresponding input channel on Xylo, at the corresponding time point. Up to 15 input events can be sent per bin.
record (bool) – Iff True, record and return all internal state of the neurons and synapses on Xylo. Default: False, do not record internal state.
read_timeout (Optional[float]) – Set an explicit read timeout for the entire simulation time. This should be sufficient for the simulation to complete, and for data to be returned. Default: None, set a reasonable default timeout.

Returns:

output, new_state, record_dict. output is a raster (T, Nout), containing events for each channel in each time bin. Time bins in output correspond to the time bins in input. new_state is an empty dictionary. The Xylo HDK does not permit querying or setting state. record_dict is a dictionary containing recorded internal state of Xylo during evolution, if the record argument is True. Otherwise this is an empty dictionary.

Return type:

(np.ndarray, dict, dict)

Raises:

TimeoutError – If reading data times out during the evolution. An explicity timeout can be set using the read_timeout argument.

_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.

_last_record_mode: bool | None

The most recent (and assumed still valid) recording mode

Type:: bool

_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(state_dict: dict, t_start: float = 0.0) → dict[source]

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

property class_name: str

Class name of self

Type:: str

property config

The HDK configuration applied to the Xylo module

Type:: XyloConfiguration

dt: float | SimulationParameter

Simulation time-step of the module, in seconds

Type:: float

evolve(input: ndarray, record: bool = False, read_timeout: float | None = None, record_power: bool = False, *args, **kwargs) → Tuple[ndarray, dict, dict][source]

Evolve a network on the Xylo HDK in accelerated-time mode

Sends a series of events to the Xylo HDK, evolves the network over the input events, and returns the output events produced during the input period. Optionally record internal state of the network, selectable with the record flag.

If measuring power, pass record_power = True to evolve(). In this case, record_dict will contain the keys "io_power", "afe_core_power", "afe_ldo_power" and "snn_core_power". These contain lists of power measurements for the four power nets on Xylo, in Watts, sampled at the power_freq attribute in Hz, supplied when instantiating the module (Default: 5 Hz). 'io_power' is the total I/O power of the device. 'snn_core_power' is the power consumption of the digital SNN core and control logic. 'afe_core_power' is the power of the analog audio front-end core. 'afe_ldo_power' is the power consumption of the internal low-drop-out voltage supply used by the AFE.

Parameters:

input (np.ndarray) – A raster (T, Nin) specifying for each bin the number of input events sent to the corresponding input channel on Xylo, at the corresponding time point. Up to 15 input events can be sent per bin.
record (bool) – Iff True, record and return all internal state of the neurons and synapses on Xylo. Default: False, do not record internal state.
read_timeout (Optional[float]) – Set an explicit read timeout for the entire simulation time. This should be sufficient for the simulation to complete, and for data to be returned. Default: None, set a reasonable default timeout.
record_power (bool) – Iff True, record the power consumption during each evolve.

Returns:

output, new_state, record_dict. output is a raster (T, Nout), containing events for each channel in each time bin. Time bins in output correspond to the time bins in input. new_state is an empty dictiionary. The Xylo HDK does not permit querying or setting state. record_dict is a dictionary containing recorded internal state of Xylo during evolution, if the record argument is True. Otherwise this is an empty dictionary.

Return type:

(np.ndarray, dict, dict)

Raises:

TimeoutError – If reading data times out during the evolution. An explicity timeout can be set using the read_timeout argument.

property full_name: str

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

Type:: str

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

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() → XyloSamna[source]

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