devices.xylo.syns65302.AFESimExternal

class devices.xylo.syns65302.AFESimExternal(*args, **kwargs)[source]

Bases: __AFESimCommon

AFESim module that simulates audio signal preprocessing on XyloAudio 3 chip. This module requires as input a 14-bit QUANTIZED signal.

See also

For example usage of the AFESimExternal Module, see Using AFESim as an audio transform

Attributes overview

`class_name`	Class name of `self`
`dt`	(float) Time-step length in seconds dependent on the `down_sampling_factor` parameter
`full_name`	The full name of this module (class plus module name)
`low_pass_averaging_window`	(float) Averaging window length in seconds dependent on the `dn_low_pass_bitshift` parameter.
`name`	The name of this module, or an empty string if `None`
`rate_scale_factor`	(int) Rate scaling factor dependent on the `dn_rate_scale_bitshift` parameter.
`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.

Methods overview

`__init__`(**kwargs)	param select_filters: The indices of the filters to be used in the filter bank. Defaults to None: use all filters.
`append`(mod[, name])	Append a module to the `Sequential` network stack
`as_graph`()	Convert this module to a computational graph
`attributes_named`(name)	Search for attributes of this or submodules by time
`evolve`(input_data[, record])	Evolve the state of this module over input data
`export_config`()	Export a hardware configuration matching this AFE simulation
`from_config`(config)	Construct a :py:`.AFESim` module from a hardware configuration. Not yet supported.
`from_specification`([select_filters, ...])	Create an instance of AFESim by specifying higher level parameters for AFESim.
`get_dn_low_pass_bitshift`(...[, decimal])	Get the bitshift value `dn_low_pass_bitshift` which determines the averaging window length of the low-pass filter.
`get_dn_rate_scale_bitshift`(rate_scale_factor)	Get the bitshift values `dn_rate_scale_bitshift` which determine how much the spike rate should be scaled compared with the sampling rate of the input audio.
`get_down_sampling_factor`(audio_sampling_rate, dt)	Get the down_sampling_factor which determines how many time-steps will be accumulated into a single time-step before feeding the data to the SNN core.
`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__(**kwargs)[source]

Parameters:

select_filters (Optional[Tuple[int]], optional) – The indices of the filters to be used in the filter bank. Defaults to None: use all filters. i.e. select_filters = (0,2,4,8,15) will use Filter 0, Filter 2, Filter 4, Filter 8, and Filter 15.
spike_gen_mode (str, optional) – The spike generation mode of the AFE. There are two ways to generate spikes, “divisive_norm” and “threshold”. Defaults to “divisive_norm”. When “divisive_norm” is selected, adaptive thresholds apply, and dn_rate_scale_bitshift, dn_low_pass_bitshift, dn_EPS parameters are used. When “threshold” is selected, fixed thresholds apply, and fixed_threshold_vec parameter is used. For detailed information, please check DivisiveNormalization module
dn_rate_scale_bitshift (Optional[Tuple[int]], optional) – Used only when spike_gen_mode = "divisive_norm". A tuple containing two bitshift values that determine how much the spike rate should be scaled compared with the sampling rate of the input audio. The first value is b1 and the second is b2. Defaults to (6, 0). A bitshift of size specified by the tuple as (b1, b2) yields a spike rate scaling of audio_sampling_rate/(2^b1 - 2^b2) where audio_sampling_rate is the sampling rate of the input audio. A default value of (6, 0) yields an average of 1 (slightly larger than 1) spike per 2^6 - 1 (=63) clock periods. With a clock rate of around 50K -> around 800 ~ 1K spikes/sec per channel. Use from_specification() method to perform a parameter search for (b1,b2) values given the target scaling ratio.
dn_low_pass_bitshift (Optional[int]) – Used only when spike_gen_mode = "divisive_norm". Number of bitshifts used in low-pass filter implementation. A bitshift of size b implies an averaging window of 2^b clock periods. Defaults to 12. The default value of 12, implies an averaging window of size 4096 clock periods. For an audio of clock rate 50K, this yields an averaging window of size 80 ms. Use from_specification() method to perform a parameter search for b values given the target averaging window size.
dn_EPS (Optional[Union[int, Tuple[int]]]) – Used only when spike_gen_mode = "divisive_norm". Lower bound on spike generation threshold. Defaults to 1. Using this parameter we can control the noise level in the sense that if average power in a channel is less than EPS, the spike rate of that channel is somehow diminished during spike generation.
fixed_threshold_vec (Optional[Union[int, Tuple[int]]]) –
Used only when spike_gen_mode = "threshold". A tuple containing threshold values per channel which determine the spike generation threshold. Defaults to 2 ** (27) = 2 ** (14 - 1 + 8 + 6). Thresholds of size size_out, in case of a singular value, broadcasted. These thresholds are used only when the spike_gen_mode = "threshold". The default value 2**27 ensures a spike rate of around 1K for an input sinusoid signal quantized to 14 bits.

See also

How to set the value of threshold for a target spike rate?

In the current implementation, input audio to filters has 14 bits which is further left-bit-shifted by 8 bits to improve numerical precision, thus, 22 bits. This implies that the output signal may have a maximum amplitude of at most 2^21 - 1 ~ 2^22, for example, when fed by a sinusoid signal within the passband of the filter. For a target rate of around 1K. e.g., 1 spike every 50 clock period for an audio of sampling rate 50K, then we need to choose a threshold as large as 50 x 2^22 ~ 2^27.
down_sampling_factor (int) – Determines how many time-steps will be accumulated into a single time-step before feeding the data to the SNN core. Defaults to 50. Resulting dt = 0.001024 Use from_specification() method to perform a parameter search for down_sampling_factor value given the target dt.

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

static _handle_none_dn_EPS(spike_gen_mode: str, dn_EPS: int | Tuple[int] | None) → int | Tuple[int]: Handle the case when dn_EPS is None.

static _handle_none_dn_low_pass_bitshift(spike_gen_mode: str, dn_low_pass_bitshift: int | None) → int: Handle the case when dn_low_pass_bitshift is None.

static _handle_none_dn_rate_scale_bitshift(spike_gen_mode: str, dn_rate_scale_bitshift: Tuple[int] | None) → Tuple[int]: Handle the case when dn_rate_scale_bitshift is None.

static _handle_none_fixed_threshold_vec(spike_gen_mode: str, fixed_threshold_vec: int | Tuple[int] | None) → int | Tuple[int]: Handle the case when fixed_threshold_vec is None.

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

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

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]

append(mod: ModuleBase, name: str | None = None) → ModuleBase

Append a module to the Sequential network stack

Parameters:

mod (Module) – A rockpool Module to append to this network stack. The input size of mod must match the output size of the existing network.
name (str) – An optional name to assign to the new module. If None, a name will automatically be generated.

as_graph()

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 dt: float: (float) Time-step length in seconds dependent on the down_sampling_factor parameter

evolve(input_data, record: bool = False) → Tuple[Any, Any, Any]

Evolve the state of this module over input data

NOTE: THIS MODULE CLASS DOES NOT PROVIDE DOCUMENTATION FOR ITS EVOLVE METHOD. PLEASE UPDATE THE DOCUMENTATION FOR THIS MODULE.

Parameters:

input_data – The input data with shape (T, size_in) to evolve with
record (bool) – If True, the module should record internal state during evolution and return the record. If False, no recording is required. Default: False.

Returns:

(output, new_state, record): output (np.ndarray): The output response of this module with shape (T, size_out) new_state (dict): A dictionary containing the updated state of this and all submodules after evolution record (dict): A dictionary containing recorded state of this and all submodules, if requested using the record argument

Return type:

tuple

export_config() → Any: Export a hardware configuration matching this AFE simulation

classmethod from_config(config: Any) → AFESim: Construct a :py:`.AFESim` module from a hardware configuration. Not yet supported.

Create an instance of AFESim by specifying higher level parameters for AFESim.

Parameters:

audio_sampling_rate (float) – Check :py:class:`.AFESim.
select_filters (Optional[Tuple[int]], optional) – Check AFESim. Defaults to None.
spike_gen_mode (str, optional) – Check AFESim. Defaults to “divisive_norm”.
input_mode (str, optional) – Check AFESim. Defaults to “external”.
rate_scale_factor (Optional[int], optional) – Target rate_scale_factor for the DivisiveNormalization module. Defaults to 63. Depended upon the dn_rate_scale_bitshift. rate_scale_factor = 2**dn_rate_scale_bitshift[0] - 2**dn_rate_scale_bitshift[1] Not always possible to obtain the exact value of rate_scale_factor due to the hardware constraints. In such cases, the closest possible value is reported with an error message.
low_pass_averaging_window (Optional[float], optional) – Target low_pass_averaging_window for the DivisiveNormalization module. Defaults to 84e-3. Depended upon the dn_low_pass_bitshift. low_pass_averaging_window = 2**dn_low_pass_bitshift / audio_sampling_rate Not always possible to obtain the exact value of low_pass_averaging_window due to the hardware constraints. In such cases, the closest possible value is reported with an error message. Note that a value within 3 decimal precision is accepted as equal.
dn_EPS (Union[int, Tuple[int]], optional) – Check AFESim. Defaults to 1.
fixed_threshold_vec (Union[int, Tuple[int]], optional) – Check AFESim. Defaults to None.
dt (Optional[float], optional) – Target dt value for the SNN core. Defaults to 1024e-6. Depended upon the down_sampling_factor. dt = down_sampling_factor / audio_sampling_rate Not always possible to obtain the exact value of dt due to the hardware constraints. In such cases, the closest possible value is reported with an error message. Note that a value within 6 decimal precision is accepted as equal.

Returns:

A AFESim instance constructed by specifying higher level parameters.

Return type:

AFESim

property full_name: str

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

Type:: str

static get_dn_low_pass_bitshift(audio_sampling_rate: float, low_pass_averaging_window: float, decimal: int = 3) → int

Get the bitshift value dn_low_pass_bitshift which determines the averaging window length of the low-pass filter. Used as a utility function in from_specification() method. Raises an error if the target low_pass_averaging_window cannot be obtained within the specified decimal precision. Can be independently used to obtain the bitshift value given the target low_pass_averaging_window.

Parameters:

audio_sampling_rate (float) – Sampling rate of the input audio.
low_pass_averaging_window (float) – Target low_pass_averaging_window for the DivisiveNormalization module. Depended upon the dn_low_pass_bitshift. low_pass_averaging_window = 2**dn_low_pass_bitshift / audio_sampling_rate
decimal (int, optional) – The number of decimal points to be considered when comparing the target low_pass_averaging_window with the obtained value. Defaults to 3.

Returns:

The bitshift value that determines the averaging window length of the low-pass filter.

Return type:

int

static get_dn_rate_scale_bitshift(rate_scale_factor: int) → Tuple[int]

Get the bitshift values dn_rate_scale_bitshift which determine how much the spike rate should be scaled compared with the sampling rate of the input audio. Used as a utility function in from_specification() method. Raises an error if the target rate_scale_factor cannot be obtained within the specified decimal precision. Can be independently used to obtain the bitshift values given the target rate_scale_factor.

Parameters:

rate_scale_factor (int) – Target rate_scale_factor for the DivisiveNormalization module. Depended upon the dn_rate_scale_bitshift. rate_scale_factor = 2**dn_rate_scale_bitshift[0] - 2**dn_rate_scale_bitshift[1]

Returns:

A tuple containing two bitshift values that determine how much the spike rate should be scaled compared with the sampling rate of the input audio. The first value is b1 and the second is b2.: audio_sampling_rate’ = audio_sampling_rate/(2^b1 - 2^b2) where audio_sampling_rate is the sampling rate of the input audio.

Return type:

Tuple[int]

static get_down_sampling_factor(audio_sampling_rate: float, dt: float, decimal: int = 6) → int

Get the down_sampling_factor which determines how many time-steps will be accumulated into a single time-step before feeding the data to the SNN core. Used as a utility function in from_specification() method. Raises an error if the target dt cannot be obtained within the specified decimal precision. Can be independently used to obtain the down_sampling_factor given the target dt.

Parameters:

audio_sampling_rate (float) – Sampling rate of the input audio.
dt (float) – Target dt value for the SNN core.
decimal (int, optional) – The number of decimal points to be considered when comparing the target dt with the obtained value. Defaults to 6.

Returns:

The down_sampling_factor which determines how many time-steps will be accumulated into a single time-step before feeding the data to the SNN core.

Return type:

int

property low_pass_averaging_window: float: (float) Averaging window length in seconds dependent on the dn_low_pass_bitshift parameter. Defines the averaging window length of the low-pass filter

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

property rate_scale_factor: int: (int) Rate scaling factor dependent on the dn_rate_scale_bitshift parameter. Defines how much the spike rate should be scaled compared with the sampling rate of the input audio

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