devices.xylo.syns65302.AFESimPDM
- class devices.xylo.syns65302.AFESimPDM(*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 transformAttributes overview
Class name of
self
(float) Time-step length in seconds dependent on the
down_sampling_factor
parameterThe full name of this module (class plus module name)
(float) Averaging window length in seconds dependent on the
dn_low_pass_bitshift
parameter.The name of this module, or an empty string if
None
(int) Rate scaling factor dependent on the
dn_rate_scale_bitshift
parameter.The shape of this module
(DEPRECATED) The output size of this module
The input size of this module
The output size of this module
If
True
, this module receives spiking input.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 stackas_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 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 all parameters in this module
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, andfixed_threshold_vec
parameter is used. For detailed information, please checkDivisiveNormalization
moduledn_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 isb1
and the second isb2
. 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. Usefrom_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 sizeb
implies an averaging window of2^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. Usefrom_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 sizesize_out
, in case of a singular value, broadcasted. These thresholds are used only when thespike_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 as50 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 ofParameterBase
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
andfamily
- 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 attributename
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
orState
.
- _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
representationThis method is optional, and is provided to make the
timed()
conversion to aTimedModule
work better. You should override this method in your customModule
, to wrap each element of your recorded state dictionary as aTimeSeries
- 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
- as_graph()
Convert this module to a computational graph
- Returns:
The computational graph corresponding to this module
- Return type:
- 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 withrecord (bool) – If
True
, the module should record internal state during evolution and return the record. IfFalse
, 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 therecord
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.
- classmethod from_specification(select_filters: Tuple[int] | None = None, spike_gen_mode: str = 'divisive_norm', rate_scale_factor: int | None = 63, low_pass_averaging_window: float | None = 0.084, dn_EPS: int | Tuple[int] | None = 1, fixed_threshold_vec: int | Tuple[int] | None = None, dt: float | None = 0.001024) __AFESimCommon
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 theDivisiveNormalization
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 ofrate_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 theDivisiveNormalization
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 oflow_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 ofdt
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:
- 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 infrom_specification()
method. Raises an error if the targetlow_pass_averaging_window
cannot be obtained within the specified decimal precision. Can be independently used to obtain the bitshift value given the targetlow_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 theDivisiveNormalization
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 infrom_specification()
method. Raises an error if the targetrate_scale_factor
cannot be obtained within the specified decimal precision. Can be independently used to obtain the bitshift values given the targetrate_scale_factor
.- Parameters:
rate_scale_factor (int) – Target
rate_scale_factor
for theDivisiveNormalization
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 isb2
. audio_sampling_rate’ = audio_sampling_rate/(2^b1 - 2^b2) where audio_sampling_rate is the sampling rate of the input audio.
- 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
- 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 targetdt
cannot be obtained within the specified decimal precision. Can be independently used to obtain the down_sampling_factor given the targetdt
.- Parameters:
- 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:
- reset_state() ModuleBase
Reset the state of this module
- Returns:
The updated module is returned for compatibility with the functional API
- Return type:
- 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. IfFalse
, this module expects continuous input.- Type:
bool
- property spiking_output
If
True
, this module sends spiking output. IfFalse
, 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, thenself.dt
will be used. Default:None
add_events (bool) – Iff
True
, theTimedModule
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