Module learned 

Learned coefficient models: a small MLP predicts each residual’s distribution — a two-component discretized logistic mixture — from the same causal context features the hand model uses (Feat: neighbour and parent magnitudes, neighbour signs, prediction magnitude, band class and orientation).

Bit-exact inference

Everything from features to coded bits is integer arithmetic:

• features are Q8 fixed-point log₂(1+v) computed with integer ops;
• the network runs on i32 weights (Q8) and i64 accumulators, with >> 8 rescaling and integer ReLU;
• the mixture CDF uses integer tables (logistic in Q24, 2^{f/256} in Q16) built once from IEEE + − × / √ only — correctly rounded, so identical on every conforming backend (no exp/pow from libm);
• the residual is binarized (zero, sign, exp-Golomb bucket, mantissa) and each binary probability is an integer ratio of CDF masses, clamped and fed to the range coder (optionally refined by an integer adaptive probability map).

A GPU decoder that reproduces these integer ops reproduces the bits.

Training

Float training minimizes the code length (cross-entropy, in bits) of the actual quantized residuals under the mixture, by minibatch Adam (tang_optim::Adam) with hand-written backprop. tang-ad’s scalar tape records one node per scalar op; at ~10⁹ ops per epoch that is far too slow, so the trainer differentiates the fixed MLP + mixture likelihood directly (checked against finite differences in the tests).

Modes

• Pretrained (LearnedSpec::Pretrained): a network trained offline on other fields; the stream carries its 64-bit fingerprint, and the decoder resolves it from registered networks.
• Overfitted (LearnedSpec::Overfit): trained at encode time on the file’s own residuals and shipped in the stream (entropy-coded Q8 weights, counted in the rate) — Cool-chic style.

Structs

Net

An integer network (Q8 weights, Q16 biases).

NetModel

The coefficient model driven by a network.

Sample

One training sample.

TrainConfig

Trainer settings.

Enums

LearnedSpec

How the learned model is obtained.

Constants

NF

Input features.

NO

Network outputs: π logit, μ₁, μ₂, log₂ s₁, log₂ s₂.

Functions

collect

Collect (features, residual) for every coefficient of q, in coding order (the features the coder will see).

feat_vec

Integer feature vector (Q8).

lg_q8

Integer Q8 log₂(1 + v).

lookup

A registered pretrained network by fingerprint.

mean_bits_float

Mean ideal code length (bits/sample) of samples under the float view of an integer net (for reporting; the coder’s actual bits include binarization and probability rounding).

parse_model_arg

Parse a CLI model argument: hand, overfit[:h1[,h2]], or pretrained:PATH (the network is also registered for decoding).

read_model

Read the model section for tag (after the tag byte).

register

Make a pretrained network available to decoders in this process.

train

Train a network on samples (deterministic for a given seed); returns the quantized integer network.