DeepGate Logic Layers¶

Quantize and export PyTorch models for DeepGate edge deployment.

Classes:

Name	Description
`ThermometerEncode`	Spatial thermometer encoder, the uint8-image entry point of a logic model.
`ThermometerEncode1d`	Flat thermometer encoder for uint8 vectors.
`RGB4bitTo32bitLUT`	Learnable RGB LUT encoder, the uint8-image entry point of RGB logic models.
`BlockShuffle`	Fixed, seeded block permutation of a flat `[B, N]` bit tensor.
`LUTLinear`	Logic lookup-table linear layer, traceable via `torch.export`.
`LUTConv2d`	Logic lookup-table 2-D convolution (DLGv3), traceable via `torch.export`.
`GroupSum`	Readout that sums input bits within `nb_out` equal-sized groups.
`BitShift`	Multiply-by-power-of-two with int truncation (compiler bit shift).

dg.ThermometerEncode ¶

ThermometerEncode(
    scalar_bitlen: int, pad: int = 0, dup: bool = False
)

Spatial thermometer encoder, the uint8-image entry point of a logic model.

Encodes each uint8 scalar of a [B, C, H, W] image as scalar_bitlen threshold bits (thresholds evenly spaced over [0, 255]), producing a [B, C * scalar_bitlen (+ pad), H, W] float32 tensor of zeros and ones.

Parameters:

Name	Type	Description	Default
`scalar_bitlen`	`int`	Number of threshold bits per input scalar.	required
`pad`	`int`	Extra channels prepended as zeros (or appended as duplicates when `dup` is True).	`0`
`dup`	`bool`	Pad with duplicated leading channels instead of zeros.	`False`

dg.ThermometerEncode1d ¶

ThermometerEncode1d(
    scalar_bitlen: int, pad: int = 0, dup: bool = False
)

Flat thermometer encoder for uint8 vectors.

Encodes each scalar of a [B, N] uint8 vector as scalar_bitlen threshold bits kept adjacent per scalar, producing [B, N * scalar_bitlen (+ pad)] float32 bits.

Parameters:

Name	Type	Description	Default
`scalar_bitlen`	`int`	Number of threshold bits per input scalar.	required
`pad`	`int`	Extra bits (zeros prepended, or leading duplicates appended when `dup` is True).	`0`
`dup`	`bool`	Pad with duplicated leading bits instead of zeros.	`False`

dg.RGB4bitTo32bitLUT ¶

RGB4bitTo32bitLUT(
    init_scale: float = 0.01,
    sg_name: str = "fast_sigmoid",
    sg_kwargs: dict | None = None,
)

Learnable RGB LUT encoder, the uint8-image entry point of RGB logic models.

Each pixel's top 4 bits per channel form a 12-bit index into a learnable [4096, 32] LUT whose binarized entry becomes 32 bit channels: [B, 3, H, W] uint8 to [B, 32, H, W] float32 bits.

Parameters:

Name	Type	Description	Default
`init_scale`	`float`	Stddev of the normal initializer for the LUT weights.	`0.01`
`sg_name`	`str`	Surrogate gradient, `"fast_sigmoid"` or `"identity"`.	`'fast_sigmoid'`
`sg_kwargs`	`dict \| None`	Fast-sigmoid settings (`scale`, `asymptotic`).	`None`

dg.BlockShuffle ¶

BlockShuffle(nb_in: int, block_size: int, seed: int = 42)

Fixed, seeded block permutation of a flat [B, N] bit tensor.

Splits the last dimension into contiguous blocks of block_size and reorders them by a permutation drawn from seed.

Parameters:

Name	Type	Description	Default
`nb_in`	`int`	Flat input width (must be divisible by `block_size`).	required
`block_size`	`int`	Size of each block along the last dimension.	required
`seed`	`int`	Seed for the permutation; the same seed regenerates it identically.	`42`

dg.LUTLinear ¶

LUTLinear(
    nb_in: int,
    nb_out: int,
    nb_input_bits: int = 2,
    version: str = "dlgv3",
    sg_name: str = "fast_sigmoid",
    sg_kwargs: dict | None = None,
    connectivity_name: str = "random",
    connectivity_kwargs: dict | None = None,
)

Logic lookup-table linear layer, traceable via torch.export.

Each of the nb_out units selects nb_input_bits input bits through a fixed named connectivity and evaluates them against a learnable unit. With version="dlgv3" (default) the unit is a full lookup table; with version="dlgv4" it is an XNOR match pattern (the unit fires on an exact match). Forwards are hard evaluations (bits in, bits out); training uses a fast-sigmoid surrogate.

Parameters:

Name	Type	Description	Default
`nb_in`	`int`	Number of input bits.	required
`nb_out`	`int`	Number of output bits (units); must be a multiple of 32.	required
`nb_input_bits`	`int`	Input bits selected per unit (2, 3 or 4).	`2`
`version`	`str`	DLG unit version (`"dlgv3"` or `"dlgv4"`).	`'dlgv3'`
`sg_name`	`str`	Surrogate gradient, `"fast_sigmoid"` or `"identity"`.	`'fast_sigmoid'`
`sg_kwargs`	`dict \| None`	Fast-sigmoid settings (`scale`, `asymptotic`).	`None`
`connectivity_name`	`str`	Name of the dg connectivity variant.	`'random'`
`connectivity_kwargs`	`dict \| None`	Keyword arguments for the connectivity.	`None`

dg.LUTConv2d ¶

LUTConv2d(
    in_channels: int,
    out_channels: int,
    nb_input_bits: int = 2,
    kernel: int | tuple[int, int] = 3,
    stride: int | tuple[int, int] = 1,
    padding: int = 1,
    sg_name: str = "fast_sigmoid",
    sg_kwargs: dict | None = None,
    connectivity_name: str = "random",
    connectivity_kwargs: dict | None = None,
)

Logic lookup-table 2-D convolution (DLGv3), traceable via torch.export.

Unfold-then-LUTLinear: input patches become column vectors of in_channels * kH * kW bits and feed an internal LUTLinear with out_channels units, whose connectivity gets the kernel key injected.

Parameters:

Name	Type	Description	Default
`in_channels`	`int`	Number of input bit channels.	required
`out_channels`	`int`	Number of output bit channels; must be a multiple of 32.	required
`nb_input_bits`	`int`	Input bits selected per unit (2, 3 or 4).	`2`
`kernel`	`int \| tuple[int, int]`	Kernel size.	`3`
`stride`	`int \| tuple[int, int]`	Convolution stride.	`1`
`padding`	`int`	Symmetric zero-padding (as in `F.unfold`).	`1`
`sg_name`	`str`	Surrogate gradient, `"fast_sigmoid"` or `"identity"`.	`'fast_sigmoid'`
`sg_kwargs`	`dict \| None`	Fast-sigmoid settings (`scale`, `asymptotic`).	`None`
`connectivity_name`	`str`	Name of the dg connectivity variant.	`'random'`
`connectivity_kwargs`	`dict \| None`	Keyword arguments for the connectivity (without `kernel`; it is injected automatically).	`None`

dg.GroupSum ¶

GroupSum(nb_in: int, nb_out: int)

Readout that sums input bits within nb_out equal-sized groups.

Written as plain reshape + sum so it traces to recognisable aten ops. The input must already be binary, which every logic layer output guarantees.

Parameters:

Name	Type	Description	Default
`nb_in`	`int`	Number of input bits (must divide into `nb_out` power-of-two groups).	required
`nb_out`	`int`	Number of groups (output units).	required

dg.BitShift ¶

BitShift(nb_shift: int, direction: str = 'right')

Multiply-by-power-of-two with int truncation (compiler bit shift).

Forward emulates the compiler's truncating shift exactly; gradients pass straight through scaled by the multiplier.

Parameters:

Name	Type	Description	Default
`nb_shift`	`int`	Shift amount (positive integer).	required
`direction`	`str`	`"right"` (divide) or `"left"` (multiply).	`'right'`