API Reference Overview

BitLogic's public API is small by design. Everything the typical user needs is re-exported from the top-level bitlogic module:

from bitlogic import (
    DistributiveThermometer,   # encoder (thermometer)
    Thermometer,               # encoder (thermometer)
    UniformFixedPoint,         # encoder (uniform fixed-point quantizer)
    LogicDense,                # fully-connected LUT layer
    GroupSum,                  # popcount classification head
    GroupedDSP,                # GroupSum + quantized k×k matmul
    FeedForward,               # reference encoder → LogicDense × N → head stack
)

Advanced use-cases can reach into the submodules directly:

• bitlogic.parametrizations — the eight LUT shapes plus the setup_parametrization factory.
• bitlogic.connections — input-routing strategies plus the setup_connections factory.
• bitlogic.layers — layer implementations (LogicDense).
• bitlogic.encoders — thermometer and uniform fixed-point bit encoders.
• bitlogic.heads — output heads (GroupSum plus the quantized-weight variant GroupedDSP).
• bitlogic.models — reference architectures (FeedForward) built on the primitives above.

Data-flow contract

graph LR
    A[Input<br/>continuous] --> B[Encoder<br/>bits]
    B --> C[LogicDense 1]
    C --> D[LogicDense 2]
    D --> E[Head]
    E --> F[Task output]

Each LogicDense layer internally looks like this:

graph LR
    X[x: B×in_dim] --> G[Connections<br/>gather lut_rank inputs]
    G --> P[Parametrization<br/>evaluate LUTs]
    P --> Y[y: B×out_dim]

• Connections owns routing indices (fixed) or a learnable selector.
• Parametrization owns the per-neuron weight tensor and the forward basis that turns those weights into LUT values.

For a given layer, both modules share the same lut_rank; LogicDense forwards the single lut_rank keyword argument to both subsystems.

Minimal end-to-end example

import torch
from bitlogic import DistributiveThermometer, LogicDense, GroupSum

enc = DistributiveThermometer(num_bits=8).fit(train_samples)

model = torch.nn.Sequential(
    enc,
    torch.nn.Flatten(),
    LogicDense(6272, 2000, parametrization="light", lut_rank=4),
    LogicDense(2000, 2000, parametrization="light", lut_rank=4),
    GroupSum(k=10, tau=30.0),
)

Hardware export

Every LogicDense exposes a get_luts_and_ids() method that returns discretized truth tables and input-id routing, suitable as input to an HDL backend:

luts, ids = layer.get_luts_and_ids()
# luts: (out_dim, 2 ** lut_rank) of {0, 1}
# ids:  (lut_rank, out_dim)  — which input feeds each slot of each neuron

The bitlogic.hdl submodule builds on this handoff: it emits a flat combinational SystemVerilog module and (optionally) drives Yosys + the Nangate 45 nm Open Cell Library to extract a NAND2-equivalent gate count.