memtorch.bh¶
Submodule containing various memristive device behavioral models and methods to simualte non-ideal device and circuit behavior.
memtorch.bh.memristor¶
All memristor models and window functions are encapsulated and documented in memtorch.bh.memristor.
memtorch.bh.nonideality¶
All non-idealities modelled by MemTorch are encapsulated and documented in memtorch.bh.nonideality.
memtorch.bh.crossbar.Crossbar¶
Class used to model memristor crossbars and to manage modular crossbar tiles.
import torch
import memtorch
crossbar = memtorch.bh.crossbar.Crossbar(memtorch.bh.memristor.VTEAM,
{"r_on": 1e2, "r_off": 1e4},
shape=(100, 100),
tile_shape=(64, 64))
crossbar.write_conductance_matrix(torch.zeros(100, 100).uniform_(1e-2, 1e-4), transistor=True)
crossbar.devices[0][0][0].set_conductance(1e-4)
crossbar.update(from_devices=True, parallelize=True)
Note
use_bindings is enabled by default, to accelerate operation using C++/CUDA (if supported) bindings.
Warning
As of version 1.1.6, the write_conductance_matrix method exhibits different behavior when self.use_bindings is True, CUDA operation is enabled, and the Data_Driven2021 memristor model is used.
When self.use_bindings is True, CUDA operation is enabled, and the Data_Driven2021 memristor model is used, the programming voltage is force adjusted by force_adjustment_voltage when a device becomes stuck. For all others models, or when CUDA operation is not enabled or self.use_bindings is false, the conductance state of the device being modelled is adjusted using force_adjustment when it becomes stuck.
This behavior will made consistent across Python, C++, and CUDA bindings, in a future release.
-
class
memtorch.bh.crossbar.Crossbar.
Crossbar
(memristor_model, memristor_model_params, shape, tile_shape=None, use_bindings=True, cuda_malloc_heap_size=50, random_crossbar_init=False)[source]¶ Bases:
object
Class used to model memristor crossbars.
Parameters: - memristor_model (memtorch.bh.memristor.Memristor.Memristor) – Memristor model.
- memristor_model_params (**kwargs) – **kwargs to instantiate the memristor model with.
- shape (int, int) – Shape of the crossbar.
- tile_shape (int, int) – Tile shape to use to store weights. If None, modular tiles are not used.
- use_bindings (bool) – Used to determine if C++/CUDA bindings are used (True) or not (False).
- random_crossbar_init (bool) – Determines if the crossbar is to be initialized at random values in between Ron and Roff
-
update
(from_devices=True, parallelize=False)[source]¶ Method to update either the layers conductance_matrix or each devices conductance state.
Parameters:
-
write_conductance_matrix
(conductance_matrix, transistor=True, programming_routine=None, programming_routine_params={})[source]¶ Method to directly program (alter) the conductance of all devices within the crossbar.
Parameters: - conductance_matrix (torch.FloatTensor) – Conductance matrix to write.
- transistor (bool) – Used to determine if a 1T1R (True) or 0T1R arrangement (False) is simulated.
- programming_routine – Programming routine (method) to use.
- programming_routine_params (**kwargs) – Programming routine keyword arguments.
-
class
memtorch.bh.crossbar.Crossbar.
Scheme
[source]¶ Bases:
enum.Enum
Scheme enumeration.
-
DoubleColumn
= 2¶
-
SingleColumn
= 1¶
-
-
memtorch.bh.crossbar.Crossbar.
init_crossbar
(weights, memristor_model, memristor_model_params, transistor, mapping_routine, programming_routine, programming_routine_params={}, p_l=None, scheme=<Scheme.DoubleColumn: 2>, tile_shape=(128, 128), use_bindings=True, cuda_malloc_heap_size=50, random_crossbar_init=False)[source]¶ Method to initialise and construct memristive crossbars.
Parameters: - weights (torch.Tensor) – Weights to map.
- memristor_model (memtorch.bh.memristor.Memristor.Memristor) – Memristor model.
- memristor_model_params (**kwargs) – **kwargs to instantiate the memristor model with.
- transistor (bool) – Used to determine if a 1T1R (True) or 1R arrangement (False) is simulated.
- mapping_routine (function) – Mapping routine to use.
- programming_routine (function) – Programming routine to use.
- programming_routine_params (**kwargs) – Programming routine keyword arguments.
- p_l (float) – If not None, the proportion of weights to retain.
- scheme (memtorch.bh.Scheme) – Scheme enum.
- tile_shape (int, int) – Tile shape to use to store weights. If None, modular tiles are not used.
- use_bindings (bool) – Used to determine if C++/CUDA bindings are used (True) or not (False).
- random_crossbar_init (boolean) – Determines if the crossbar is to be initialized at random values in between Ron and Roff
Returns: The constructed crossbars and forward() function.
Return type:
-
memtorch.bh.crossbar.Crossbar.
simulate_matmul
(input, crossbar, nl=True, tiles_map=None, crossbar_shape=None, max_input_voltage=None, ADC_resolution=None, ADC_overflow_rate=0.0, quant_method=None, use_bindings=True)[source]¶ Method to simulate non-linear IV device characterisitcs for a 2-D crossbar architecture given scaled inputs.
Parameters: - input (torch.Tensor) – Scaled input tensor.
- crossbar (memtorch.bh.Crossbar) – Crossbar containing devices to simulate.
- nl (bool) – Use lookup tables rather than simulating each device (True).
- tiles_map (torch.Tensor) – Tiles map for devices if tile_shape is not None.
- crossbar_shape (int, int) – Crossbar shape if tile_shape is not None.
- max_input_voltage (float) – Maximum input voltage used to encode inputs. If None, inputs are unbounded.
- ADC_resolution (int) – ADC resolution (bit width). If None, quantization noise is not accounted for.
- ADC_overflow_rate (float) – Overflow rate threshold for linear quanitzation (if ADC_resolution is not None).
- quant_method – Quantization method. Must be in memtorch.bh.Quantize.quant_methods.
- use_bindings (bool) – Used to determine if C++/CUDA bindings are used (True) or not (False).
Returns: Output tensor.
Return type:
memtorch.bh.crossbar.Program¶
Methods to program (alter) the conductance devices within a crossbar or modular crossbar tiles.
-
memtorch.bh.crossbar.Program.
gen_programming_signal
(number_of_pulses, pulse_duration, refactory_period, voltage_level, time_series_resolution)[source]¶ Method to generate a programming signal using a sequence of pulses.
Parameters: Returns: Tuple containing the generated time and voltage signals.
Return type:
-
memtorch.bh.crossbar.Program.
naive_program
(crossbar, point, conductance, rel_tol=0.01, pulse_duration=0.001, refactory_period=0, pos_voltage_level=1.0, neg_voltage_level=-1.0, timeout=5, force_adjustment=0.001, force_adjustment_rel_tol=0.1, force_adjustment_pos_voltage_threshold=0, force_adjustment_neg_voltage_threshold=0, failure_iteration_threshold=1000, simulate_neighbours=True)[source]¶ Method to program (alter) the conductance of a given device within a crossbar.
Parameters: - crossbar (memtorch.bh.crossbar.Crossbar) – Crossbar containing the device to program.
- point (tuple) – Point to program (row, column).
- conductance (float) – Conductance to program.
- rel_tol (float) – Relative tolerance between the desired conductance and the device’s conductance.
- pulse_duration (float) – Duration of the programming pulse (s).
- refactory_period (float) – Duration of the refactory period (s).
- pos_voltage_level (float) – Positive voltage level (V).
- neg_voltage_level (float) – Negative voltage level (V).
- timeout (int) – Timeout (seconds) until stuck devices are unstuck.
- force_adjustment (float) – Adjustment (resistance) to unstick stuck devices.
- force_adjustment_rel_tol (float) – Relative tolerance threshold between a stuck device’s conductance and high and low conductance states to force adjust.
- force_adjustment_pos_voltage_threshold (float) – Positive voltage level threshold (V) to enable force adjustment.
- force_adjustment_neg_voltage_threshold (float) – Negative voltage level threshold (V) to enable force adjustment.
- failure_iteration_threshold (int) – Failure iteration threshold.
- simulate_neighbours (bool) – Simulate neighbours (True).
Returns: Programmed device.
Return type:
memtorch.bh.crossbar.Tile¶
-
class
memtorch.bh.crossbar.Tile.
Tile
(tile_shape, patch_num=None)[source]¶ Bases:
object
Class used to create modular crossbar tiles to represent 2D matrices.
Parameters: -
update_array
(new_array)[source]¶ Method to update the tile’s weights.
Parameters: new_array (torch.Tensor) – New array to construct the tile with.
-
-
memtorch.bh.crossbar.Tile.
gen_tiles
(tensor, tile_shape, input=False, use_bindings=True)[source]¶ Method to generate a set of modular tiles representative of a tensor.
Parameters: - tensor (torch.Tensor) – Tensor to represent using modular crossbar tiles.
- tile_shape (int, int) – Tile shape to use to store weights.
- input (bool) – Used to determine if a tensor is an input (True).
Returns: Tiles and tile_map.
Return type:
-
memtorch.bh.crossbar.Tile.
tile_matmul
(mat_a_tiles, mat_a_tiles_map, mat_a_shape, mat_b_tiles, mat_b_tiles_map, mat_b_shape, source_resistance=None, line_resistance=None, ADC_resolution=None, ADC_overflow_rate=0.0, quant_method=None, transistor=True, use_bindings=True, cuda_malloc_heap_size=50)[source]¶ Method to perform 2D matrix multiplication, given two sets of tiles.
Parameters: - mat_a_tiles (torch.Tensor) – Tiles representing matrix A.
- mat_a_tiles_map (torch.Tensor) – Tiles map for matrix A.
- mat_a_shape (int, int) – Shape of matrix A.
- mat_b_tiles (torch.Tensor) – Tiles representing matrix B.
- mat_b_tiles_map (torch.Tensor) – Tiles map for matrix B.
- mat_b_shape (int, int) – Shape of matrix B.
- source_resistance (float) – The resistance between word/bit line voltage sources and crossbar(s).
- line_resistance (float) – The interconnect line resistance between adjacent cells.
- ADC_resolution (int) – ADC resolution (bit width). If None, quantization noise is not accounted for.
- ADC_overflow_rate (float) – Overflow rate threshold for linear quanitzation (if ADC_resolution is not None).
- quant_method (str) – Quantization method. Must be in memtorch.bh.Quantize.quant_methods.
- transistor (bool) – TBD.
- use_bindings (bool) – Use C++/CUDA bindings to parallelize tile_matmul operations (True).
- cuda_malloc_heap_size (int) – cudaLimitMallocHeapSize (in MB) to determine allocatable kernel heap memory if CUDA is used.
Returns: Output tensor.
Return type:
-
memtorch.bh.crossbar.Tile.
tile_matmul_row
(mat_a_row_tiles, mat_a_tiles_map, mat_b_tiles, mat_b_tiles_map, mat_b_shape, source_resistance=None, line_resistance=None, ADC_resolution=None, ADC_overflow_rate=0.0, quant_method=None, transistor=True)[source]¶ Method to perform row-wise tile matrix multiplication, given two sets of tiles, using a pythonic approach.
Parameters: - mat_a_row_tiles (torch.Tensor) – Tiles representing a row of matrix A.
- mat_a_tiles_map (torch.Tensor) – Tiles map for matrix A.
- mat_b_tiles (torch.Tensor) – Tiles representing matrix B.
- mat_b_tiles_map (torch.Tensor) – Tiles map for matrix B.
- mat_b_shape (int, int) – Shape of matrix B.
- source_resistance (float) – The resistance between word/bit line voltage sources and crossbar(s).
- line_resistance (float) – The interconnect line resistance between adjacent cells.
- ADC_resolution (int) – ADC resolution (bit width). If None, quantization noise is not accounted for.
- ADC_overflow_rate (float) – Overflow rate threshold for linear quanitzation (if ADC_resolution is not None).
- quant_method (str) – Quantization method. Must be in memtorch.bh.Quantize.quant_methods.
- transistor (bool) – TBD.
Returns: Output tensor.
Return type:
-
memtorch.bh.crossbar.Tile.
tiled_inference
(input, m, transistor)[source]¶ Method to perform tiled inference.
Parameters: - input (torch.Tensor) – Input tensor (2-D).
- m (memtorch.mn) – Memristive MemTorch layer.
Returns: Output tensor.
Return type:
memtorch.bh.Quantize¶
Wrapper for C++ quantization bindings.
-
memtorch.bh.Quantize.
quantize
(tensor, quant, overflow_rate=0.0, quant_method=None, min=nan, max=nan, override_original=False)[source]¶ Method to quantize a tensor.
Parameters: - tensor (torch.Tensor) – Input tensor.
- quant (int) – Bit width (if quant_method is not None) or the number of discrete quantization levels (if quant_method is None).
- overflow_rate (float, optional) – Overflow rate threshold for linear quantization.
- quant_method (str, optional) – Quantization method. Must be in quant_methods.
- min (float or tensor, optional) – Minimum value(s) to clip numbers to.
- max (float or tensor, optional) – Maximum value(s) to clip numbers to.
- override_original (bool, optional) – Whether to override the original tensor (True) or not (False).
Returns: Quantized tensor.
Return type:
memtorch.bh.StochasticParameter¶
Methods to model stochastic parameters.
memtorch.bh.StochasticParameter is most commonly used to define stochastic parameters when defining behavioural memristor models, as follows:
import torch
import memtorch
crossbar = memtorch.bh.crossbar.Crossbar(memtorch.bh.memristor.VTEAM,
{"r_on": memtorch.bh.StochasticParameter(min=1e3, max=1e2), "r_off": 1e4},
shape=(100, 100),
tile_shape=(64, 64))
-
class
memtorch.bh.StochasticParameter.
Dict2Obj
(dictionary)[source]¶ Bases:
object
Class used to instantiate a object given a dictionary.
-
memtorch.bh.StochasticParameter.
StochasticParameter
(distribution=<class 'torch.distributions.normal.Normal'>, min=0, max=inf, function=True, **kwargs)[source]¶ Method to model a stochastic parameter.
Parameters: Returns: A sampled value of the stochatic parameter, or a sample-value generator.
Return type: float or function
-
memtorch.bh.StochasticParameter.
unpack_parameters
(local_args, r_rel_tol=None, r_abs_tol=None, resample_threshold=5)[source]¶ Method to sample from stochastic sample-value generators
Parameters: - local_args (locals()) – Local arguments with stochastic sample-value generators from which to sample from.
- r_rel_tol (float) – Relative threshold tolerance.
- r_abs_tol (float) – Absolute threshold tolerance.
- resample_threshold (int) – Number of times to resample r_off and r_on when their proximity is within the threshold tolerance before raising an exception.
Returns: locals() with sampled stochastic parameters.
Return type: **