embedl_deploy.lattice.modules package#

Module contents:

Public re-exports of Lattice fused nn.Module classes.

Users import from here:

from embedl_deploy.lattice.modules import LatticeConv2d
class embedl_deploy.lattice.modules.LatticeAdaptiveAvgPool2d[source]#

Bases: AdaptiveAvgPool2d

Canonical Lattice global average pool.

The only supported form of average pooling for Lattice hardware is AdaptiveAvgPool2d with output_size == (1, 1). The constructor takes no arguments — every instance has the canonical configuration declared by OUTPUT_SIZE.

OUTPUT_SIZE: tuple[int, int] = (1, 1)#

The single permitted output size.

classmethod is_compatible(pool: AdaptiveAvgPool2d) → bool[source]#

Return True when pool already matches Lattice’s supported set.

Parameters:

pool – Pool to check.

Returns:

True when the output size of pool equals (1, 1); False otherwise.

class embedl_deploy.lattice.modules.LatticeCBSR(conv: LatticeConv2d, bn: BatchNorm2d | None = None, act: ReLU | LatticeLeakyReLU | None = None, *, output_precision: Precision = Precision.INT8, output_fixed_calibration: tuple[float, int] | None = None)[source]#

Bases: FusedModule

Fused Conv2d -> [BatchNorm2d] -> [Activation] for Lattice hardware.

The Lattice accelerator implements convolution, optional batch normalization, and optional activation as a single fused CBSR block. When an activation is present it must be ReLU or LatticeLeakyReLU (negative slope fixed at 1/16). This module validates that the convolution parameters are within the hardware’s supported set and raises ValueError otherwise.

Supported convolution parameters:

  • Kernel sizes: 1×1, 3×3

  • Strides: 1, 2 (stride > 1 requires 3×3 kernel)

  • Dilation: 1 only

Parameters:

  • conv – The convolution layer to fuse.

  • bn – Optional batch normalization layer.

  • act – Optional ReLU or LatticeLeakyReLU activation.

  • output_precision – Precision for the output quantizer.

  • output_fixed_calibration – Optional fixed (scale, zero_point) pair for the output quantizer.

Raises:

ValueError – If conv has unsupported kernel size, stride, or dilation.

forward(x: Tensor) → Tensor[source]#

Apply conv -> [bn] -> [act].

inputs_to_quantize: set[int] = {}#

Positional argument indices that should receive a QuantStub. The Q/DQ insertion pass uses this to decide which inputs of the fused node to quantize. Every subclass must set this explicitly.

property quantized_weight: Tensor | None#

Return the weight tensor covered by weight_fake_quant.

Subclasses that attach a WeightFakeQuantize must override this to return the corresponding weight tensor.

class embedl_deploy.lattice.modules.LatticeCBSRAdvanced(conv: LatticeConv2d, bn: BatchNorm2d | None = None, act: ReLU | LatticeLeakyReLU | None = None, *, output_precision: Precision = Precision.INT8, output_fixed_calibration: tuple[float, int] | None = None)[source]#

Bases: LatticeCBSR

Fused Conv2d -> [BatchNorm2d] -> [Activation] for advanced CNN IP.

Like LatticeCBSR but accepts the broader kernel set supported by advanced Lattice accelerators: 1×1, 3×3, 5×5, and 7×7. Only 3×3 allows stride 2; all other kernel sizes require stride 1. Dilation must be 1.

Parameters:

  • conv – The convolution layer to fuse.

  • bn – Optional batch normalization layer.

  • act – Optional ReLU or LatticeLeakyReLU activation.

  • output_precision – Precision for the output quantizer.

  • output_fixed_calibration – Optional fixed (scale, zero_point) pair for the output quantizer.

Raises:

ValueError – If conv has unsupported kernel size, stride, or dilation.

class embedl_deploy.lattice.modules.LatticeConv2d(conv: Conv2d)[source]#

Bases: Conv2d

Conv2d snapped to Lattice’s supported set.

Lattice hardware accepts only 1×1 and 3×3 convolutions with stride 1 or 2 (and stride 1 is mandatory for the 1×1 kernel). The constructor takes an arbitrary source Conv2d and forwards its in_channels, out_channels, dilation, groups, and bias presence; kernel size and stride are snapped to the nearest support values.

A 1×1 kernel is promoted to 3×3 whenever its stride exceeds 1. Padding is set to kernel_size // 2 on each spatial axis to preserve the output shape under the common "same"-style convention used by ResNet-family stems and downsamples.

Weights and bias are copied from the source convolution whenever the snapped weight tensor has the same shape as the source’s (i.e., only stride and/or padding changed). If the kernel size was snapped — and the weight tensor shape therefore changed — the instance keeps freshly initialized weights, since there is no well-defined way to reuse the original kernel values.

KERNEL_SIZES: tuple[int, ...] = (1, 3)#

Permitted spatial kernel sizes.

STRIDES: tuple[int, ...] = (1, 2)#

Permitted spatial strides.

classmethod is_compatible(conv: Conv2d) → bool[source]#

Return True when conv already matches Lattice’s supported set.

A convolution is compatible when its kernel size, stride, and padding equal what snapped_params would return for it.

Parameters:

conv – Convolution to check.

Returns:

True when conv already conforms to Lattice constraints; False otherwise.

classmethod snapped_params(conv: Conv2d) → tuple[tuple[int, int], tuple[int, int], tuple[int, int]][source]#

Return (kernel_size, stride, padding) after Lattice snapping.

Parameters:

conv – Source convolution whose parameters are snapped to the nearest values accepted by Lattice hardware.

Returns:

A three-tuple (kernel_size, stride, padding) of the snapped parameters where each element is itself an (h, w) pair.

class embedl_deploy.lattice.modules.LatticeConv2dAdvanced(conv: Conv2d)[source]#

Bases: LatticeConv2d

Conv2d snapped to Lattice’s advanced-kernel set.

Lattice advanced hardware supports 1×1, 3×3, 5×5, and 7×7 convolutions. 3×3 allows stride 1 or 2; all other kernel sizes require stride 1. Padding is always kernel_size // 2.

Like LatticeConv2d, weights and bias are preserved when only stride and/or padding changed, and freshly initialized when the kernel size was snapped.

KERNEL_SIZES: tuple[int, ...] = (1, 3, 5, 7)#

Permitted spatial kernel sizes.

classmethod snapped_params(conv: Conv2d) → tuple[tuple[int, int], tuple[int, int], tuple[int, int]][source]#

Return (kernel_size, stride, padding) after snapping.

Kernel size is snapped to the nearest square kernel from the supported set (1×1, 3×3, 5×5, 7×7) using the larger spatial dimension. Only 3×3 allows stride 2; all other kernel sizes are restricted to stride 1.

class embedl_deploy.lattice.modules.LatticeFusedAddAct(act: ReLU | LatticeLeakyReLU | None = None, *, output_precision: Precision = Precision.INT8, output_fixed_calibration: tuple[float, int] | None = None)[source]#

Bases: FusedModule

Fused add(·, residual) -> [Activation] for Lattice hardware.

Fuses the element-wise addition of two branches with an optional trailing activation (ReLU or LatticeLeakyReLU) into a single block. This captures the residual merge point in ResNet-style architectures where the convolution path has already been fused separately.

Unlike LatticeCBSR there is no convolution, batch normalization, or weight tensor, so no WeightFakeQuantize is attached.

Parameters:

  • act – Optional ReLU or LatticeLeakyReLU activation applied after the element-wise addition.

  • output_precision – Precision for the output quantizer.

  • output_fixed_calibration – Optional fixed (scale, zero_point) pair for the output quantizer.

forward(x: Tensor, residual: Tensor) → Tensor[source]#

Apply add(x, residual) -> [act].

inputs_to_quantize: set[int] = {}#

Positional argument indices that should receive a QuantStub. The Q/DQ insertion pass uses this to decide which inputs of the fused node to quantize. Every subclass must set this explicitly.

class embedl_deploy.lattice.modules.LatticeFusedLinear(linear: Linear, bn: BatchNorm1d | None = None, act: ReLU | LatticeLeakyReLU | None = None, *, output_precision: Precision = Precision.INT8, output_fixed_calibration: tuple[float, int] | None = None)[source]#

Bases: FusedModule

Fused Linear -> [BatchNorm1d] -> [Activation] for Lattice hardware.

The Lattice accelerator implements a linear (GEMM) layer with optional batch normalization and optional activation as a single fused block. When an activation is present it must be ReLU or LatticeLeakyReLU.

Parameters:

  • linear – The nn.Linear from the matched chain.

  • bn – Optional batch normalization layer.

  • act – Optional ReLU or LatticeLeakyReLU activation.

  • output_precision – Initial precision for output_quant_stub. STATE_PREP will override this unless output_fixed_calibration is also supplied.

  • output_fixed_calibration – If provided, (scale, zero_point) fixes the output quantizer so that STATE_PREP and calibration leave it unchanged.

forward(x: Tensor) → Tensor[source]#

Apply linear -> [bn] -> [act].

inputs_to_quantize: set[int] = {}#

Positional argument indices that should receive a QuantStub. The Q/DQ insertion pass uses this to decide which inputs of the fused node to quantize. Every subclass must set this explicitly.

property quantized_weight: Tensor | None#

Return the weight tensor covered by weight_fake_quant.

Subclasses that attach a WeightFakeQuantize must override this to return the corresponding weight tensor.

class embedl_deploy.lattice.modules.LatticeLeakyReLU(act: LeakyReLU)[source]#

Bases: ConvertedModule, LeakyReLU

LeakyReLU snapped to Lattice’s supported slope.

Lattice hardware implements leaky ReLU with a fixed negative slope of 1/16 (0.0625). The constructor always sets the slope to the supported value; the conversion pattern logs a warning when the source slope differs.

Subclasses ConvertedModule so that FX tracing keeps this module as a leaf node.

NEGATIVE_SLOPE: float = 0.0625#

The single permitted negative slope.

classmethod is_compatible(act: LeakyReLU) → bool[source]#

Return True when act already uses the supported slope.

Parameters:

act – Activation to check.

Returns:

True when the negative slope of act equals NEGATIVE_SLOPE; False otherwise.

class embedl_deploy.lattice.modules.LatticeMaxPool2d(pool: MaxPool2d)[source]#

Bases: MaxPool2d

MaxPool2d snapped to Lattice’s supported set.

Lattice hardware supports only a single max-pool configuration: a 2×2 kernel with stride 2 and zero padding. The constructor takes an arbitrary source MaxPool2d and emits that canonical configuration, preserving only dilation and ceil_mode.

KERNEL_SIZE: int = 2#

The single permitted kernel size.

PADDING: int = 0#

The single permitted padding.

STRIDE: int = 2#

The single permitted stride.

classmethod is_compatible(pool: MaxPool2d) → bool[source]#

Return True when pool already matches Lattice’s supported set.

Parameters:

pool – Pool to check.

Returns:

True when kernel size, stride, and padding of pool equal the single supported configuration; False otherwise.

class embedl_deploy.lattice.modules.LatticeQuant(consumers: set[Module], precision: Precision = Precision.INT8, symmetric: bool = True, calibration_method: CalibrationMethod = CalibrationMethod.MINMAX, *, channel_axis: int = 1, fixed_calibration: tuple[float, int] | None = None, canonical_name: str | None = None, producer_qualified_name: str | None = None)[source]#

Bases: QuantStub

Quantize activations and keep Lattice export identity metadata.

Extends QuantStub with two Lattice-specific capabilities:

  • Tracks per-channel calibration maxima from observed activations.

  • Stores stable identity strings used when remapping metadata to ONNX node names during export.

Parameters:

  • consumers – Set of modules that consume this quantizer’s output.

  • precision – Quantized format.

  • symmetric – Whether quantization is symmetric.

  • calibration_method – Activation calibration algorithm.

  • channel_axis – Channel axis used when tracking per-channel calibration maxima.

  • fixed_calibration – Optional fixed (scale, zero_point) pair.

  • canonical_name – Optional canonical metadata key for this quantizer.

  • producer_qualified_name – Optional qualified name of the producer module.

property calibration_max: Tensor | None#

Return tracked per-channel calibration maxima, if available.

compute_parameters() → None[source]#

Compute quant parameters and synchronize Lattice export buffers.

Raises:

ValueError – If the computed zero-point is nonzero. Lattice hardware does not support asymmetric quantization with a nonzero zero-point; the eager and ONNX export paths both assume zero-point is zero.

forward(x: Tensor) → Tensor[source]#

Fake-quantize x, updating observer stats if calibrating.

reset_calibration_max() → None[source]#

Reset tracked per-channel calibration maxima.

set_export_identity(canonical_name: str, producer_qualified_name: str | None = None) → None[source]#

Set canonical identity strings used during metadata export.

Parameters:

  • canonical_name – Canonical key used for export metadata maps.

  • producer_qualified_name – Optional fully-qualified producer module name.