bspysmg.utils package#

Module contents#

Package containing a set of general functions to assist plotting, measuring iv curves, generating inputs for the sampler, and checking the consistency of a model.

Subpackages#

bspysmg.utils.iv package

Submodules#

bspysmg.utils.consistency module#

File containing a class for checking a device (or/and a surrogate model) against previously obtained reference measurements.

class bspysmg.utils.consistency.ConsistencyChecker(main_dir: str, repetitions: int = 1, sampler_configs_name: str = 'sampler_configs.json', reference_batch_name: str = 'reference_batch.npz', charging_signal_name: str = 'charging_signal.npz', model: Optional[Module] = None, show_plots: bool = True)[source]#

Bases: Sampler

charge_device(deviation_chargeup, model_deviation_chargeup=None, show_plots=True)[source]#

get_data(charge_device=True) → Tuple[array][source]#

The main function that implements consistency checking routine. It uses the reference data and device’s outputs to check if the outputs of device are consistent with device over several runs. Optionally it can also check consistency of a trained neural network over device measurements.

Returns

tuple with following data:

results: np.array
outputs generated by the device.
deviations: np.array
RMSE between device outputs and refernce data.
correlation: np.array
Value of correlation coefficient between device outputs and refence data.
deviation_chargeup: np.array
RMSE deviation between device output and original device output.

if model is not None:

model_results: np.array
outputs generated by the model.
model_deviations: np.array
RMSE between model outputs and refernce data.
model_correlation: np.array
Value of correlation coefficient between model outputs and refence data.
model_deviation_chargeup: np.array
RMSE deviation between model output and original device output.

Return type

tuple

sample_model_batch(input_batch: Tensor) → Tensor[source]#

Ramp the input batch (0.5 sec up and down) and format it to Tensor. Ramping is required to avoid abrupt changes in the voltage. The input is masked from 0v to first value and then final value back to 0v.

Returns: Input tensor ramped and allocated to tensor.
Return type: torch.Tensor

bspysmg.utils.consistency.consistency_check(main_dir: str, repetitions: int = 1, sampler_configs_name: str = 'sampler_configs.json', reference_batch_name: str = 'reference_batch.npz', charging_signal_name: str = 'charging_signal.npz', charge_device: bool = True, model: Optional[Module] = None, show_plots=True) → None[source]#

This is the driver function used for consistency checking. Consistency checking involves checking how DNPU device is behaving at present moment against how it was before measurement. This check can also be performed against trained neural network model over DNPU measurements. This function initializes a ConsistencyChecker object and performs the consistency check using the get_data function. It also plots and saves various graphs of calculated metrics.

Parameters

main_dir (str) – Path to main directory which contains the configuration files.
repetitions (int [Optional]) – Number of times the experiments should be repeated.
sampler_configs_name (str [Optional]) – Name of the file which contains sampling configuration with keys mentioned in constructor function of ConsistencyChecker class.
reference_batch_name (str [Optional]) – Name of the file which contains the reference dataset. This is the original device measurements. It is a npz file with columns ‘inputs’ and ‘outputs’.
charging_signal_name (str [Optional]) – Name of the file which contains device inputs and outputs. This is the device behaviour at present moment. It is a npz file with columns ‘inputs’ and ‘outputs’.
charge_device (boolean [Optional]) – Whether the consistency check should charge up the device with the charging signal or not.
model (custom model of type torch.nn.Module [Optional]) – Model whose consistency is to be checked. This is a trained neural network model over DNPU measurements and sampled input data.

bspysmg.utils.inputs module#

File containing different methods for generating input waves for sampling purposes.

bspysmg.utils.inputs.generate_sawtooth_multiple(input_range, n_points, up_direction=True) → array[source]#

Generates a simple sawtooth for a single channel (electrode). It goes from zero to a certain point (v_low), from that point to another point (v_max), and from that last point to zero again. The direction can be inverted using up_direction=True so that the sawtooth goes from zero to v_max, from v_max to v_min, and from v_min to zero.

Parameters

input_range (linst) – Minimum and maximum voltages that the sawtooth will achieve.
n_points (int) – Number of points that the sawtooth will have.
up_direction (bool, optional) – Direction of the sawtooth. If true, the sawtooth will go first up and then down. If False, the sawtooth will go first down and then up. By default False.

Returns

An array containing the two pointed sawtooth in a single dimension.

Return type

np.array

bspysmg.utils.inputs.generate_sawtooth_simple(v_low: float, v_high: float, point_no: int, up_direction: bool = False) → array[source]#

Parameters

v_low (float) – Minimum voltage that the sawtooth will achieve.
v_high (float) – Maximum voltage that the sawtooth will achieve.
point_no (int) – Number of points that the sawtooth will have.
up_direction (bool, optional) – Direction of the sawtooth. If true, the sawtooth will go first up and then down. If False, the sawtooth will go first down and then up. By default False.

Returns

An array containing the two pointed sawtooth in a single dimension.

Return type

np.array

bspysmg.utils.inputs.generate_sinewave(n: int, fs: float, amplitude: float, phase: float = 0) → array[source]#

Generates a sine wave that can be used for the input data.

Parameters

n (int) – The number of points to generate in the sine wave.
fs (float) – Frequency of the sine wave.
amplitude (float) – Amplitude of the sine wave.
phase (Optional[float]) – Phase offset of sinewave at t=0.

Returns

Generated sine wave.

Return type

np.array

bspysmg.utils.inputs.get_frequency(configs: dict) → array[source]#

Generate input frequency for each electrode.

Parameters: configs (dict) – Sampling configurations, the dictionary has the following keys: 1. input_frequency: list Base frequencies of the input waves that will be created. In order to optimise coverage, irrational numbers are recommended. The list should have the same length as the activation electrode number. The input frequency list will be square rooted. E.g., for 7 activation electrodes: input_frequency = [2, 3, 5, 7, 13, 17, 19]
Returns: List of input frequencies for each eletrode.
Return type: np.array

bspysmg.utils.inputs.get_input_generator(configs: dict) → Tuple[dict, Callable][source]#

Returns the configurations dictionary for generating input signal wave and also returns the function that will be used for generating the signal.

Parameters

configs (dict) –

Sampling configurations, the dictionary has the following keys: 1. input_data : dict Dictionary containing the information necessary to create the input sampling data.

1.1 input_distribution: str It determines the wave shape of the input. Two main options availeble ‘sawtooth’ and ‘sine’. The first option will create saw-like signals, and the second sine-wave signals. Sawtooth signals have more coverage on the edges of the input range.

1.2 activation_electrode_no: int Number of activation electrodes in the device that wants to be sampled.

1.3 readout_electrode_no : int Number of readout electrodes in the device that wants to be sampled.

1.4 input_frequency: list Base frequencies of the input waves that will be created. In order to optimise coverage, irrational numbers are recommended. The list should have the same length as the activation electrode number. The input frequency list will be square rooted. E.g., for 7 activation electrodes: input_frequency = [2, 3, 5, 7, 13, 17, 19]

1.5 phase : float Horizontal shift of the input signals. It is recommended to have random numbers which are different for the training, validation and test datasets. These numbers will be square rooted and multiplied by a given factor.

1.6 factor : float Given factor by which the input frequencies will be multiplied after square rooting them.

1.7 amplitude : Optional[list[float]] Amplitude of the generated input wave signal. It is calculated according to the minimum and maximum ranges of each electrode. Where the amplitude value should correspond with (max_range_value - min_range_value) / 2. If no amplitude is given it will be automatically calculated from the driver configurations for activation electrode ranges. If it wants to be manually set, the offset variable should also be included in the dictionary.

1.8 offset: Optional[list[float]] Vertical offset of the generated input wave signal. It is calculated according to the minimum and maximum ranges of each electrode. Where the offset value should correspond with (max_range_value + min_range_value) / 2. If no offset is given it will be automatically calculated from the driver configurations for activation electrode ranges. If it wants to be manually set, the offset variable should also be included in the dictionary.

1.9 ramp_time: float Time that will be taken before sending each batch to go from zero to the first point of the batch and to zero from the last point of the batch.

1.10 batch_time: Time that the sampling of each batch will take.

1.11 number_batches: int Number of batches that will be sampled. A default value of 3880 is reccommended.

Returns

Sampling configuration dictionary and signal generating function.

Return type

tuple

bspysmg.utils.inputs.get_random_phase(activation_electrode_no=7)[source]#

Generates a list containing different random phases for each activation electrodes. It can be used before gathering the data, in order to randomize the phase of the input during the data acquisition after one or few sampling batches.

Parameters: activation_electrode_no (int) – The number of activation electrodes for which the phase will be generated.
Returns: Generated phases for activation electrodes.
Return type: list

bspysmg.utils.inputs.load_configs(config_dict: dict) → dict[source]#

Creates a dictionary with sampling configurations.

Parameters

configs (dict) –

Sampling configurations, the dictionary has the following keys: 1. driver: dict Dictionary containing the driver configurations. For more information check the documentation about this configuration file, check the documentation of brainspy.processors.hardware.drivers.ni.setup.NationalInstrumentsSetup 2. input_data : dict Dictionary containing the information necessary to create the input sampling data.

2.1 input_distribution: str It determines the wave shape of the input. Two main options availeble ‘sawtooth’ and ‘sine’. The first option will create saw-like signals, and the second sine-wave signals. Sawtooth signals have more coverage on the edges of the input range.

2.2 activation_electrode_no: int Number of activation electrodes in the device that wants to be sampled.

2.3 readout_electrode_no : int Number of readout electrodes in the device that wants to be sampled.

2.4 input_frequency: list Base frequencies of the input waves that will be created. In order to optimise coverage, irrational numbers are recommended. The list should have the same length as the activation electrode number. The input frequency list will be square rooted. E.g., for 7 activation electrodes: input_frequency = [2, 3, 5, 7, 13, 17, 19]

2.5 phase : float Horizontal shift of the input signals. It is recommended to have random numbers which are different for the training, validation and test datasets. These numbers will be square rooted and multiplied by a given factor.

2.6 factor : float Given factor by which the input frequencies will be multiplied after square rooting them.

2.7 amplitude : Optional[list[float]] Amplitude of the generated input wave signal. It is calculated according to the minimum and maximum ranges of each electrode. Where the amplitude value should correspond with (max_range_value - min_range_value) / 2. If no amplitude is given it will be automatically calculated from the driver configurations for activation electrode ranges. If it wants to be manually set, the offset variable should also be included in the dictionary.

2.8 offset: Optional[list[float]] Vertical offset of the generated input wave signal. It is calculated according to the minimum and maximum ranges of each electrode. Where the offset value should correspond with (max_range_value + min_range_value) / 2. If no offset is given it will be automatically calculated from the driver configurations for activation electrode ranges. If it wants to be manually set, the offset variable should also be included in the dictionary.

2.9 ramp_time: float Time that will be taken before sending each batch to go from zero to the first point of the batch and to zero from the last point of the batch.

2.10 batch_time: Time that the sampling of each batch will take.

2.11 number_batches: int Number of batches that will be sampled. A default value of 3880 is reccommended.

Returns

Sampling configuration dictionary with additional keys as follows:

1. batch_points: int Number of data points in the signal of a single batch

2. ramp_points: int Number of data points in the waiting signal between each batch.

Return type

dict

bspysmg.utils.inputs.sawtooth_wave(time_points: array, frequency: float, phase: float, amplitude: float, offset: float) → array[source]#

Generates a sawtooth wave.

Parameters

time_points (np.array) – Time points to evaluate the function.
frequency (float) – Frequencies of the inputs.
phase (float) – Phase offset of wave.
amplitude (float) – Amplitude of the wave.
offset (float) – Offset of the input.

Returns

Sawtooth wave.

Return type

np.array

bspysmg.utils.inputs.sine_wave(time_points: array, frequency: float, phase: float, amplitude: float, offset: float) → array[source]#

Generates a sine wave.

Parameters

time_points (np.array) – Time points to evaluate the function.
frequency (float) – Frequencies of the inputs.
phase (float) – Phase offset of sine wave.
amplitude (float) – Amplitude of the sine wave.
offset (float) – Offset of the input.

Returns

Sine wave.

Return type

np.array

bspysmg.utils.plots module#

File containing several methods for plotting purposes.

bspysmg.utils.plots.iv_plot(result: array, inputs: array, input_electrode: int, data_dir: str = '.', save_plot: Optional[bool] = None, show_plot: bool = False) → None[source]#

Plots IV characteristics and optinally saves the graph for a given electrode number.

Parameters

result (np.array) – Output current values of an electrode.
input_electrode (int) – Electrode number.
save_plot (bool [Optional]) – If set to true, it saves the generated plot to current directory.
show_plot (bool [Optional]) – If set to true, it displays the generated plot.

bspysmg.utils.plots.multi_iv_plot(configs, inputs, output, save_plot=None, show_plot=True)[source]#

Plots the IV curve of several devices in one plot. Devices can be the DNPU device or a surrogate model.

Parameters

configs (dict) –
Dictionary containing the configurations for IV measurements with the following keys:

1. devices: list List of devices for which IV response is to be computed. This list contains the names of all the devices (A,B,C,D etc) involved in the experiment.

2. driver: dict It contains the configurations for each device in the experiment which are defined in the devices list.
inputs (dict) – Dictionary containing the list of input signal waves for each device.
outputs (dict) – Dictionary containing the list of output currents for each device.
save_plot (str or None) – If None, the plot will not be saved, if a string provided, the plot will be saved at the specified dir.
show_plot (boolean) – Whether to show the plot or not.

bspysmg.utils.plots.output_hist(outputs: array, data_dir: str, bins: int = 100, show: bool = False) → None[source]#

Saves and optionally plots the histogram of output/predictions of the model.

Parameters

outputs (np.array) – Output generated by model.
data_dir (str) – Name of the path where the graph is to be saved.
bins (int [Optional]) – Number of bins for the histogram.
show (bool [Optional]) – If set to true, it displays the generated histogram.

bspysmg.utils.plots.plot_error_hist(targets: array, prediction: array, error: array, mse: array, save_dir: str, name: str = 'error') → None[source]#

Plots and saves error histogram graph for between given target and predicted.

Parameters

targets (np.array) – Reference data used for training/validation.
prediction (np.array) – Predictions made by model.
error (np.array) – Errors correspoding to each target data point.
mse (np.array) – Mean squared error correspoding to each target data point.
save_dir (str) – Name of the path where the graph is to be saved.
name (str [Optional]) – Name of the file for the graph.

bspysmg.utils.plots.plot_error_vs_output(targets: array, error: array, save_dir: str, name: str = 'error_vs_output') → None[source]#

Plots and saves error vs output graph for given error and their correspoding output.

Parameters

targets (np.array) – Reference data used for training/validation.
error (np.array) – Errors correspoding to each target data point.
save_dir (str) – Name of the path where the graph is to be saved.
name (str [Optional]) – Name of the file for the graph.

bspysmg.utils.plots.plot_waves(inputs: array, outputs: array, input_no: int, output_no: int, batch: int, legend: array, save_directory: str) → None[source]#

Plots and saves input and output waves for the model. Image is overwritten for each batch and it is used to control what is happening to the device input output relationship for each batch.

Parameters

inputs (np.array) – Input data used for training/validation of model.
outputs (np.array) – Output generated by model corresponding the inputs.
input_no (int) – Input activation electrode number.
output_no (int) – Output electrode number.
batch (int) – The current batch number of the data.
legend (np.array) – List of headers of text file which contains data used for training, validation, and testing.
save_directory (str) – Name of the file for the graph.