devices.xylo.syns61201.AFESamnaο
- class devices.xylo.syns61201.AFESamna(*args, **kwargs)[source]ο
Bases:
rockpool.nn.modules.module.Module
Interface to the Audio Front-End module on a Xylo-A2 HDK
This module uses
samna
to interface to the AFE hardware on a Xylo-A2 HDK. It permits recording from the AFE hardware.To record from the module, use the
evolve()
method. You need to pass this method an empty matrix, with the desired number of time-steps. The time-stepdt
is specified at module instantiation.A simulation of the module is available in
AFESim
.Warning
This module does not currently support manual configuration. A fixed configuration is provided which uses auto-calibration, applied when the module is instantiated. This takes approximately 50 seconds to configure, leading to slow instantiation.
See also
For information about the Audio Front-End design, and examples of using
AFESim
for a simulation of the AFE, see Using the analog frontend model.Examples
Instantiate an AFE module, connected to a Xylo-A2 HDK
>>> from rockpool.devices.xylo import AFESamna >>> import rockpool.devices.xylo.syns61201.xa2_devkit_utils as xdu >>> afe_hdks = xdu.find_xylo_a2_boards() >>> afe = AFESamna(afe_hdks[0], dt = 10e-3)
Use the module to record some audio events
>>> import numpy as np >>> audio_events = afe(np.zeros([0, 100, 0]))
Attributes overview
Class name of
self
The full name of this module (class plus module name)
The name of this module, or an empty string if
None
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__
(device[,Β config,Β dt,Β ...])Instantiate an AFE module, via a samna backend
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])Use the AFE HW module to record live audio and return as encoded events
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
save_config
(filename)Save an AFE configuration to disk in JSON format
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: Optional[samna.afe2.configuration.AfeConfiguration] = None, dt: float = 0.001, auto_calibrate: bool = False, amplify_level: str = 'low', change_count: Optional[int] = None, hibernation_mode: bool = False, divisive_norm: bool = False, divisive_norm_params: Optional[dict] = {}, calibration_params: Optional[dict] = {}, read_register: bool = False, *args, **kwargs)[source]ο
Instantiate an AFE module, via a samna backend
- Parameters
device (AFE2HDK) β A connected AFE2 HDK device.
config (AFE2Configuration) β A samna AFE2 configuration object.
dt (float) β The desired spike time resolution in seconds.
auto_calibrate (bool) β If True, will apply auto-calibration.
amplify_level (str) β The level of volume gain. Defaul βlowβ is the one without gain.
change_count (int) β If is not None, AFE event counter will change from outputting 1 spike out of 4 into outputting 1 out of change_count.
hibernation_mode (bool) β If True, hibernation mode will be switched on, which only outputs events if it receives inputs above a threshold.
divisive_norm (bool) β If True, divisive normalization will be switched on.
divisive_norm_params (Dict) β Specify the divisive normalization parameters, should be structured as {βsβ: , βpβ: , βiaf_biasβ: }.
calibration_params (Dict) β Specify the calibration parameters.
read_register (bool) β If True, will print all register values of AFE after initialization.
- _abc_impl = <_abc_data object>ο
- _auto_batch(data: numpy.ndarray, states: Tuple = (), target_shapes: Optional[Tuple] = None) Tuple[numpy.ndarray, Tuple[numpy.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
- _auto_calibration(device: Any, config: samna.afe2.configuration.AfeConfiguration, calibration_params: dict, apply_config: bool = True) None [source]ο
Perform AFE auto-calibration.
- Parameters
device (XyloA2HDK) β A connected AFE2 HDK device
config (AFE2Configuration) β A configuration for AFE
calibration_params (Dict) β Specify the calibration parameters
apply_config (bool) β If True, will apply configuration to AFE
- _force_set_attributesο
(bool) If
True
, do not sanity-check attributes when setting.
- _get_attribute_family(type_name: str, family: Optional[Union[Tuple, List, str]] = 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)
- _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: Optional[str]ο
Name of this module, if assigned
- _register_attribute(name: str, val: rockpool.parameters.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: rockpool.nn.modules.module.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) rockpool.nn.modules.module.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
- property _version: Tuple[int, int]ο
Return the version and revision numbers of the connected Xylo-AFE2 chip
- Returns
version, revision
- Return type
(int, int)
- _wrap_recorded_state(recorded_dict: dict, t_start: float) Dict[str, rockpool.timeseries.TimeSeries] ο
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]
- as_graph() rockpool.graph.graph_base.GraphModuleBase ο
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: Union[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
- evolve(input_data, record: bool = False) Tuple[Any, Any, Any] [source]ο
Use the AFE HW module to record live audio and return as encoded events
- Parameters
input_data (np.ndarray) β An array
[0, T, 0]
, specifying the number of time-steps to record.- Returns
(np.ndarray, dict, dict) output_events, {}, {}
- 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: Optional[Union[Tuple, List, str]] = 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
- reset_state() rockpool.nn.modules.module.ModuleBase ο
Reset the state of this module
- Returns
The updated module is returned for compatibility with the functional API
- Return type
- save_config(filename)[source]ο
Save an AFE configuration to disk in JSON format
- Parameters
filename (str) β The filename to write to
- set_attributes(new_attributes: dict) rockpool.nn.modules.module.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: Optional[Union[Tuple, List, str]] = 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: Optional[Union[Tuple, List, str]] = 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: Optional[float] = 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