Module codec 

The bit-accounted QTT codec.

Encoder

One pass at absolute quantization step Δ runs TT-SVD left to right with error feedback: core k is computed from the remainder that is least-squares optimal given the already-quantized prefix, quantized, and only then is the remainder refit against it.

Let P_{k−1} be the quantized prefix (rows = prefix indices, cols = r_{k−1}), H = P_{k−1}ᵀP_{k−1} its Gram, and C the LS remainder (X = (P_{k−1}⊗I)·C + E, E ⊥ range). In the metric H̃ = H ⊗ I_{n_k}:

1. eigendecompose the whitened Gram of C → singular values σ_j and an H̃-orthonormal core G (the canonical left-orthogonal gauge, now w.r.t. the true prefix);
2. quantize column j of G with step Δ / σ̂_j, σ̂_j = 2^{e_j/4}, e_j = round(4 log₂ σ_j) — the equal-slope rule: perturbing column j costs σ_j²·step²/12 per entry, so every entry ends up with the same distortion Δ²/12 as an entry of the last core. Columns that round to all zeros are dropped, so ranks are chosen by rate–distortion, not by a separate tolerance;
3. refit C ← (QᵀH̃Q)⁻¹ QᵀH̃ C, H ← QᵀH̃Q, and add the exact discarded energy ‖C‖²_H̃ − ‖proj‖² to the running SSE.

The last core (the LS remainder, carrying the norm) is quantized with step Δ; its error eᵀH̃e is added too. The SSE is therefore known exactly at encode time without reconstructing the tensor (the error pieces are mutually orthogonal). Δ is then found by a bracketed log–log secant search on that SSE.

Error modes

• ErrorBound::Rmse / ErrorBound::Psnr (range-normalised): the searched SSE is followed by an actual decode; if the true RMSE on the original (unpadded) cells exceeds the target the search is redone.
• ErrorBound::MaxAbs (SZ-style pointwise bound b): the TT is coded at an RMSE target f·b for a few f, the encoder decodes its own stream, and every cell with |x − x̂| > b gets a correction k = round((x−x̂)/2b) (then |x − (x̂+2bk)| ≤ b), stored as entropy-coded position gaps + values (a raw-value escape covers float-cast edge cases). The f giving the smallest total stream wins.

Bit account

The stream is self-describing: magic, dtype, digit order, padding policy, shape, Δ, all ranks, all per-column step exponents, every frequency table, all payloads, the residual stream. bytes.len() is the size.

Structs

Config

Encoder configuration.

EncodeStats

What the encoder did, for benchmarking.

Enums

Decoded

A decoded array.

Dtype

Sample type of the original array (decoded output has the same type).

ErrorBound

Error target.

Functions

decode

Decode a stream produced by encode_f32 / encode_f64.

encode_f32

Encode an f32 array of shape dims (row-major).

encode_f64

Encode an f64 array of shape dims (row-major).