xbtorch.deployment.base

Hardware accelerator simulation module.

Defines the abstract base class GenericAccelerator and several concrete accelerator models (SimpleFixedPoint, Daffodil) for simulating memristive crossbar arrays in XBTorch.

Features include:

  • DAC and ADC quantization (fixed-point or board-specific)

  • Noise modeling (read/write)

  • Stuck-at defect simulation

  • Weight encoding and mapping schemes

  • Array visualization and utility functions

This module provides a unified interface for simulating hardware effects on neural network training and inference.

Functions

register_accelerator(name)

Decorator to register a custom layer under a string name.

Classes

Daffodil([g_min, g_max, v_read, read_noise, ...])

Experimental Daffodil accelerator model.

GenericAccelerator(g_min, g_max, v_read, ...)

Abstract base class for hardware accelerator models in XBTorch.

SimpleFixedPoint([adc_bits, dac_bits, ...])

Simple fixed-point accelerator model.
class xbtorch.deployment.base.Daffodil(g_min=50, g_max=100, v_read=0.3, read_noise=10, write_noise=10, stuck_percentage=0.0, stuck_mode='real', input_encoding_scheme='instant', xb_mapping_scheme=<function map_random>, device='cpu')[source]

Bases: GenericAccelerator

Experimental Daffodil accelerator model.

This accelerator simulates the Daffodil prototyping system developed by NIST/GW/WD, with detailed modeling of the on-board DAC/ADC behavior based on datasheets and experimental calibration.

Parameters:

**kwargs – See GenericAccelerator for supported parameters.

Notes

  • Models a 12-bit DAC (AD5391BSTZ-5) and an ADC with calibration.

  • Includes board-level parameters such as reference voltages, gains, and transimpedance amplifier settings.

  • Provides helper functions for DAC/ADC conversions.

References

ADC_quantize(current)[source]

Quantize output current via the ADC model.

This method simulates the full signal chain:

  • Converts crossbar current to voltage using a transimpedance amplifier model.

  • Clips voltages to the ADC’s operating range.

  • Maps voltages to ADC register values.

  • Converts registers back to voltages.

  • Reconstructs quantized currents.

Parameters:

current (torch.Tensor) – Full-precision current vector (from crossbar readout).

Returns:

Quantized current vector, reconstructed from ADC output.

Return type:

torch.Tensor

Notes

  • Transimpedance conversion uses board parameters (board_vref, board_vmax, board_vground, dpot_r, currentscale).

  • Simulated read noise can be optionally added for realism, but is currently disabled in this implementation.

DAC_quantize(voltage)[source]

Quantize input voltage via the DAC model.

Parameters:

voltage (torch.Tensor) – Full-precision voltage input.

Returns:

Quantized DAC output voltage.

Return type:

torch.Tensor

adc_invert_voltage(value)[source]

Invert analog voltage to nearest ADC register value.

Parameters:

value (torch.Tensor) – Input voltage.

Returns:

ADC register value.

Return type:

torch.Tensor

Raises:

ValueError – If input voltage exceeds ADC register range.

adc_predict_voltage(registervalue)[source]

Predict analog voltage from ADC register value.

Parameters:

registervalue (torch.Tensor) – ADC register value.

Returns:

Predicted analog voltage.

Return type:

torch.Tensor

dac_calcvout(x1)[source]

Compute DAC analog output voltage for a digital register input.

Parameters:

x1 (torch.Tensor) – Register values (0 <= x1 <= 2^12).

Returns:

Corresponding DAC output voltages.

Return type:

torch.Tensor

dac_invertvout(v)[source]

Compute nearest DAC register value for a given output voltage.

Parameters:

v (torch.Tensor) – Desired DAC output voltage.

Returns:

Nearest integer DAC register value.

Return type:

torch.Tensor

class xbtorch.deployment.base.GenericAccelerator(g_min, g_max, v_read, read_noise, write_noise, stateful=True, xb_size=(2500, 2500), stuck_percentage=0.0, stuck_mode='real', input_encoding_scheme='instant', weight_encoding_scheme=<function encode_simple_binary>, xb_mapping_scheme=<function map_random>, device='cpu')[source]

Bases: object

Abstract base class for hardware accelerator models in XBTorch.

This class simulates memristive crossbar arrays, incorporating hardware non-idealities such as stuck devices, read/write noise, limited precision DAC/ADC, and weight encoding/mapping schemes. Subclasses implement specific quantization methods for DAC and ADC.

Parameters:

  • g_min (float) – Minimum device conductance (Siemens).

  • g_max (float) – Maximum device conductance (Siemens).

  • v_read (float) – Voltage used for read operations.

  • read_noise (float) – Amplitude of uniform read noise applied during chip readout.

  • write_noise (float) – Standard deviation of Gaussian noise applied during weight writes.

  • stateful (bool, optional) – In stateful mode, a physical representation of the entire crossbar is maintained, and weights are mapped to these limited devices. In stateless mode, weights are mapped and VMM is performed on the fly. This is more memory-efficient. Essentially behaves like an infinite size stateful crossbar.

  • xb_size (tuple of int, optional) – Dimensions of the crossbar array (columns, rows). Default: (2500, 2500). Utilized only when stateful is True.

  • stuck_percentage (float, optional) – Fraction of devices randomly stuck at high or low values. Default: 0.0.

  • stuck_mode ({"ideal", "real"}, optional) – Mode for stuck-at defect modeling: - “ideal”: stuck devices are fixed at g_min or g_max. - “real”: stuck devices are fixed at predefined realistic values.

  • input_encoding_scheme ({"instant", "linear"}, optional) – Mode for stuck-at defect modeling: - “instant”: Instantaneous voltage-amplitude encoding of inputs. - “linear”: Linear, bit-sliced encoding of inputs.

  • weight_encoding_scheme (callable, optional) – Function used to encode weights into conductance matrices. Default: encode_simple_binary().

  • xb_mapping_scheme (callable, optional) – Function for mapping weights to crossbar positions. Default: map_random().

  • device (str, optional) – PyTorch device for simulation (e.g., “cpu” or “cuda”).

_chip

Simulated crossbar array storing device conductances.

Type:

torch.Tensor

defect_map

A tuple of (indices, values) representing defective devices.

Type:

tuple

name

Descriptive string identifying array dimensions and defect rate.

Type:

str

Notes

  • Weight mapping uses both encoding (binary, LEA1, LEA2, etc.) and placement (e.g., random mapping).

  • Noise models include Gaussian for write noise and uniform for read noise.

abstract ADC_quantize(vector)[source]

Abstract method to quantize output currents via ADC.

Parameters:

vector (torch.Tensor) – Full-precision current vector.

Returns:

Quantized current vector.

Return type:

torch.Tensor

abstract DAC_quantize(vector)[source]

Abstract method to quantize input voltages via DAC.

Parameters:

vector (torch.Tensor) – Full-precision input voltage vector.

Returns:

Quantized voltage vector.

Return type:

torch.Tensor

gen_defect_map(stuck_percentage)[source]

Generate a defect map for the chip.

Parameters:

stuck_percentage (float) – Fraction of devices that are stuck.

Returns:

(indices, values) where: - indices are tensor indices of defective devices, - values are their fixed conductances (stuck_high or stuck_low).

Return type:

tuple

get_xb_size()[source]

Retrieve the size (rows, columns) of the simulated crossbar.

initialize_chip()[source]

Initialize the simulated chip state, assuming stateful mode. If stateless, defect maps will be patched on dynamically during operation.

  • Fills the array with uninitialized values (-1).

  • Generates a defect map based on the specified stuck percentage.

map_weights_to_array(sw_weight, pos_idxs=[], neg_idxs=[], additional_args={})[source]

Map software weights onto the hardware array.

Parameters:

  • sw_weight (torch.Tensor) – Software weight matrix to map.

  • pos_idxs (list of tuple, optional) – Starting indices for positive weight encodings.

  • neg_idxs (list of tuple, optional) – Starting indices for negative weight encodings.

  • additional_args (dict, optional) – Additional keyword arguments for the encoding scheme.

Returns:

(masksposs, masksnegs) masks used for layer ensemble averaging schemes. Returns (None, None) otherwise.

Return type:

tuple

Notes

  • Adds Gaussian write noise if configured.

  • Defect map is reapplied to enforce stuck devices.

map_weights_to_array_stateless(sw_weight)[source]
plot_array(x_start=None, x_count=None, y_start=None, y_count=None, title=None, show=False)[source]

Visualize the conductance state of the array.

Parameters:

  • x_start (int, optional) – Starting indices of the subarray to plot.

  • y_start (int, optional) – Starting indices of the subarray to plot.

  • x_count (int, optional) – Dimensions of the subarray to plot.

  • y_count (int, optional) – Dimensions of the subarray to plot.

  • title (str, optional) – Title for the plot.

  • show (bool, optional) – Display the plot at the end.

Returns:

The read subarray.

Return type:

torch.Tensor

read_chip(row, n_rows, col, n_cols, fast_mode=True)[source]

Read a subarray of the chip, optionally with read noise.

This method requires the object to be in a stateful mode. If self.stateful is False, a RuntimeError is raised.

Parameters:

  • row (int) – Starting row index.

  • n_rows (int) – Number of rows to read.

  • col (int) – Starting column index.

  • n_cols (int) – Number of columns to read.

  • fast_mode (bool, optional) – If False, raises NotImplementedError. Default: True.

Returns:

Subarray with applied read noise (if configured).

Return type:

torch.Tensor

Raises:

  • RuntimeError – If self.stateful is False.

  • ValueError – If fast_mode is False (not implemented yet).

read_chip_stateless(subarray)[source]

Read a subarray of the chip, optionally with read noise.

This method requires the object to be in a stateful mode. If self.stateful is False, a RuntimeError is raised.

Parameters:

G

Returns:

Subarray with applied read noise (if configured).

Return type:

torch.Tensor

Raises:

  • RuntimeError – If self.stateful is False.

  • ValueError – If fast_mode is False (not implemented yet).

class xbtorch.deployment.base.SimpleFixedPoint(adc_bits=5, dac_bits=5, g_min=50, g_max=100, v_read=0.3, read_noise=0, stateful=True, xb_size=(2500, 2500), write_noise=0, stuck_percentage=0.0, stuck_mode='real', input_encoding_scheme='instant', xb_mapping_scheme=<function map_random>, weight_encoding_scheme=<function encode_simple_binary>, device='cpu')[source]

Bases: GenericAccelerator

Simple fixed-point accelerator model.

This accelerator simulates fixed-point DAC and ADC quantization using the QTorch library. It models limited precision effects with configurable bitwidths.

Parameters:

  • adc_bits (int, optional (default=5)) – Number of bits for ADC quantization.

  • dac_bits (int, optional (default=5)) – Number of bits for DAC quantization.

  • **kwargs – See GenericAccelerator for supported parameters.

Notes

  • Quantization is symmetric, using QTorch’s fixed_point_quantize().

ADC_quantize(vector)[source]

Quantize output current vector using fixed-point ADC.

Parameters:

vector (torch.Tensor) – Full-precision current vector.

Returns:

Quantized current vector.

Return type:

torch.Tensor

DAC_quantize(vector)[source]

Quantize input voltage vector using fixed-point DAC.

Parameters:

vector (torch.Tensor) – Full-precision input voltage vector.

Returns:

Quantized voltage vector.

Return type:

torch.Tensor

xbtorch.deployment.base.register_accelerator(name: str)[source]

Decorator to register a custom layer under a string name.