Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 36 additions & 11 deletions clean/fg/FORMATS.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,12 +63,37 @@ delivered by the spec side; the code never guesses it (it raises, or takes the c
from blobs (`params_from_blobs`: stored weights gathered with the map's offsets) or from the converter's `--raw`
output of the preset-FG map (`params_from_raw`, stages `dl1.lNN` / `dl2.lNN`, tensors `W` and `b`; every value
checked to be exact in float16).
- `run_layer`: one convolution with `ops.conv2d`. `run_graph`: a network as a list of steps (`conv` with its layer and
ReLU flag, `pool` with its kind, `upscale`, `add`, `concat`, `slice`), checked before it runs (known steps, exact
fields, buffers written once before they are read, each layer used at most once). `net1_forward` adds the 2 x 2
fold before and the unfold (16 values per cell to 4 per pixel) after; `net2_forward` returns the named buffers.
- Required arguments (OPEN): `wiring` (the steps), `pad`, `fold_order`. The weight order and net1's blob 2 are settled
by map v1.1 and are no longer arguments. The real wiring plugs in as data; the layers do not change.
- Also from the converter's model file (`params_from_model_file`, container version 1, checksum checked).
- `net1_forward(values, params)`: net1 with its delivered wiring and arithmetic (next section); no other arguments.
- net2 (wiring not delivered): `run_layer` (one convolution with `ops.conv2d`), `run_graph` (a list of steps: `conv`
with its layer and ReLU flag, `pool` with its kind, `upscale`, `add`, `concat`, `slice`; checked before it runs)
and `net2_forward`. Required arguments (OPEN): `wiring`, `pad`.

## net1 (`reference/net1.py`)

- Input: 10 float16 values per pixel of the input grid, folded 2 x 2 into cells of 48 channels: channel 4 v + q with
q = 2 dy + dx; channels 40..47 and pixels outside the input area are zero. Output: 16 channels per cell, unfolded the
same way to 4 values per pixel.
- 32 steps (`NET1_WIRING`, data): five levels down (convolution, then 2 x 2 max-pool), the two bottom 1 x 1
convolutions, five levels up (upscale to the skip's size, float16 add of the skip, two 1 x 1 convolutions). Level
sizes halve with floor; the skips are the encoder outputs after the activation.
- Convolution: stride 1, zero border, cross-correlation over the natural weights. Float16 accumulator started at the
bias; 16-term chunks (k = (3 ky + kx) in + c, or c for 1 x 1) each summed exactly and added with one float16
rounding (`fp16acc.acc_dot16`, integer arithmetic). Chunk orders: 1 x 1 ascending; blobs 1, 3, 4 channel block outer,
then the taps with kx outer and ky inner; blob 5 kx outer, then channel block, then ky.
- Activation: leaky ReLU y = max(x, h(s x)) after every convolution but the last (blob 17, linear), with the delivered
slope s = 0.0099945068359375 (float16 0x211E). Nearest-even rounding of 0.01 would give 0x211F; the delivered value
is used as given.
- Max-pool: 2 x 2, stride 2, floor sizes, m <- (x > m) x + (x <= m) m in float16 (inf and NaN give the same result in
any tap order; two +inf give NaN, as the formula does).
- Upscale: bilinear, align corners, from the coarser level to the skip's size: single-precision positions
s = ((n_in - 1) / (n_out - 1)) i, x0 = trunc(s), x1 = trunc(s + 1) (both n_in - 1 at the edge), float16 weights,
every product and sum rounded to float16. The original's ratio is an approximate division; here it is the correctly
rounded single-precision quotient.
- Add: h(a + b).
- `tools/net1_digest.py`: net1 on a converter model file with a fixed synthetic input; records digests only.
- Not part of net1 and still open: what the 10 input values are made of (images A-D, the warps) and the input grid
size relative to the output.

## Configuration (`reference/config.py`)

Expand All @@ -85,14 +110,14 @@ delivered by the spec side; the code never guesses it (it raises, or takes the c

1. (closed: map v1.1, natural order, is `data/fg.v1.map.json`.)
2. (closed: the in-blob axis order is the map's offsets.)
3. Which launch reads which blob (upload order is known; launch order is not).
3. net2's fused kernels: stride inside a kernel, the residual add, the three-way splits, the upsample and merges.
(net1's launch order is delivered.)
4. (closed: net1's blob 2 is a 1 x 1 convolution.)
5. Both networks' grid sizes relative to the output size.
6. What the UI-recomposition preset changes in the stage order.
7. Launch order, the motion-field scatter, the pull pyramid and the UI handling (part 3).
7. The motion-field scatter, the pull pyramid and the UI handling; net1's input images A-D and the warps.
8. Whether the networks run once per real frame or once per generated frame.
9. The float16 accumulation order of the matrix unit; the convolution border rule; which net2 layers end in ReLU;
the pooling kind; net1's feature channel order, the fold order and what the cell padding holds; how the warp for
the warp errors samples.
9. For net2: the border rule and the accumulation order. (For net1 both are delivered, with the activation, the
pooling kind, the fold order and the cell padding.)
10. The cap on the multi-frame count; the further mode that accepts index N + 1 and what it does; which maximum the
"last index" flag compares with; the private override that can turn UI recomposition off.
6 changes: 5 additions & 1 deletion clean/fg/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,12 @@ front end or the launcher yet. Status, open items and formats: [FORMATS.md](FORM
| `tests/test_fg_layout.py` | the table against the totals the spec side gives |
| `reference/ops.py` | NumPy CPU reference of the networks' building blocks: float16 convolution (3 x 3, 1 x 1) with bias and ReLU, 2x pooling, bilinear 2x upscale (align corners), element-wise combines, net1's input features and 2 x 2 fold; each open behaviour is a required argument or raises `OpenItem` |
| `tests/test_fg_reference.py` | the building blocks against plain loop versions, on synthetic data |
| `reference/forward.py` | both networks' forward pass: each layer from its stage's natural parameters (from blobs or the converter's raw output), and a network run from a wiring the caller supplies (conv / pool / upscale / add / concat / slice steps); the wiring, the border rule and the fold order are required arguments |
| `reference/forward.py` | both networks' forward pass: parameters (from blobs, the converter's raw output or its model file); `net1_forward` with net1's delivered wiring; net2 from a wiring the caller supplies (conv / pool / upscale / add / concat / slice steps), the wiring and the border rule required |
| `tests/test_fg_forward.py` | every layer of both networks against a direct NumPy convolution on synthetic weights; each step kind; wiring checks; stand-in wirings against layers composed by hand; parameters from blobs and from raw files |
| `reference/net1.py` | net1 complete: the fold, the 32 steps as data, float16 chunk accumulation from the bias in each layer's chunk order, zero border, leaky ReLU, max-pool, the align-corners upscale with float16 steps, float16 adds, the unfold |
| `reference/fp16acc.py` | exact float16 chunk accumulation: RN16(acc + 16 products) with integer arithmetic |
| `tests/test_fg_net1.py`, `tests/test_fg_fp16acc.py` | net1 end to end against a hand-composed version; one convolution per chunk order against exact rationals; the upscale against the scalar rule; pooling with inf / NaN; the accumulation against exact rationals |
| `tools/net1_digest.py` | net1 on a converter model file with a fixed synthetic input; records digests of the output only |
| `../converter` (preset FG) | the converter reads a version-1 map with `"preset": "FG"`: one block source per weight blob; see the converter's README, "Preset FG" |
| `../../data/fg.v1.map.json` | the spec side's converter map, revision v1.1 (weights in natural order); `tests/test_fg_map.py` pins its digest and checks it against `layout.py` |
| `reference/natural.py` | the natural weight order from the map itself: its offsets as gather indices (stored blob weights to natural), natural to canonical `[out, k, k, in]` |
Expand Down
93 changes: 72 additions & 21 deletions clean/fg/reference/forward.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,21 @@
"""Frame generation (issue #96): CPU reference of both networks' forward pass, as far as it is delivered.

Written for this project. The layers are settled: their shapes (clean/fg/layout.py), the weights in natural order and
the biases the converter map gives per stage (data/fg.v1.map.json, revision v1.1; clean/fg/reference/natural.py),
float16 convolutions with bias, ReLU, 2x pooling, bilinear 2x upscale, element-wise combines, and net1's 2 x 2 fold
(clean/fg/reference/ops.py). net1's blob 2 is a 1 x 1 convolution. How the layers are connected is not delivered, so a
network is run from a wiring the caller supplies. When the real wiring arrives it is passed in as data; the layers do
not change.
the biases the converter map gives per stage (data/fg.v1.map.json, revision v1.1; clean/fg/reference/natural.py).

Required arguments for what is OPEN (clean/fg/FORMATS.md):
net1 is complete: net1_forward runs its delivered wiring and arithmetic (clean/fg/reference/net1.py: the fold, 32
steps, leaky ReLU, zero border, float16 chunk accumulation, the unfold); it takes no other arguments.

net2's wiring is not delivered, so net2 is run from a wiring the caller supplies (run_graph, net2_forward). Required
arguments for what is OPEN there (clean/fg/FORMATS.md):
- `wiring`: the list of steps (which layer reads which buffers, where the pooling, upscales, combines and channel
splits sit, ReLU after each convolution, the pooling kind). Format: see run_graph.
splits sit, the activation after each convolution, the pooling kind). Format: see run_graph.
- `pad`: the border rule of the 3 x 3 convolutions (ops.PAD_MODES).
- `fold_order`: the order of the values inside net1's 48-value cells.

Parameters are {layer name: (weights [out, k, k, in] float16, bias [out] float16)} with the layout's layer names
(net1_01 .. net1_17, net2_01 .. net2_25): from blobs (params_from_blobs: stored weights put in natural order by the
map's own offsets) or from the converter's raw output (params_from_raw: stages dl1.lNN / dl2.lNN, tensors W and b).
map's own offsets), from the converter's raw output (params_from_raw) or from its model file (params_from_model_file);
stages dl1.lNN / dl2.lNN, tensors W and b.
"""
import os

Expand Down Expand Up @@ -62,6 +62,64 @@ def params_from_raw(raw_dir, m=None):
return out


def read_model_file(path):
"""{stage: {tensor: float32 array}} from a converter output file model.wgcm (container version 1, float32 tensors;
clean/converter/OUTPUT-FORMAT.md). The trailing SHA-256 is checked."""
import hashlib
import struct
with open(path, "rb") as f:
data = f.read()
if data[:8] != b"WGCMODEL":
raise ValueError("not a WrongGPU model file")
if hashlib.sha256(data[:-32]).digest() != data[-32:]:
raise ValueError("model file checksum does not match")
version, nstages = struct.unpack_from("<II", data, 8)
if version != 1:
raise ValueError("container version %d (preset FG uses 1)" % version)
pos = 88
out = {}
for _ in range(nstages):
(n,) = struct.unpack_from("<H", data, pos)
stage = data[pos + 2:pos + 2 + n].decode()
pos += 2 + n + 32
(nt,) = struct.unpack_from("<I", data, pos)
pos += 4
tensors = {}
for _ in range(nt):
(n,) = struct.unpack_from("<H", data, pos)
name = data[pos + 2:pos + 2 + n].decode()
pos += 2 + n
dtype, rank = data[pos], data[pos + 1]
pos += 2
shape = struct.unpack_from("<%dI" % rank, data, pos)
pos += 4 * rank
off, size = struct.unpack_from("<QQ", data, pos)
pos += 16
if dtype != 0:
raise ValueError("%s/%s: dtype %d, preset FG writes float32" % (stage, name, dtype))
tensors[name] = np.frombuffer(data, dtype="<f4", count=size // 4, offset=off).reshape(shape)
out[stage] = tensors
return out


def params_from_model_file(path, m=None):
"""{layer name: (canonical weights, bias)} from a converter output file of the preset-FG map (stages dl1.lNN /
dl2.lNN with W in the map's natural shape and b). Every value must be exact in float16."""
m = m if m is not None else _natural.load_map()
stages = read_model_file(path)
out = {}
for name, l in LAYERS.items():
st = stages[map_stage_name(l)]
w, b = st["W"], st["b"]
if tuple(w.shape) != _natural.weight_shape(l, m) or b.shape != (l.out,):
raise ValueError("%s: shapes %s / %s do not fit the map" % (name, w.shape, b.shape))
w16, b16 = w.astype("<f2"), b.astype("<f2")
if not (np.array_equal(w16.astype("<f4"), w) and np.array_equal(b16.astype("<f4"), b)):
raise ValueError("%s: a value is not exact in float16" % name)
out[name] = (_natural.to_canonical(w16), b16)
return out


# ---- one layer ----------------------------------------------------------------------------------------------------

def layer_weights(name, params):
Expand Down Expand Up @@ -165,18 +223,11 @@ def run_graph(wiring, inputs, params, *, pad):
return buf


def net1_forward(features, params, *, wiring, pad, fold_order, output):
"""net1 on its per-pixel features [10, H, W] (ops.net1_features): fold 2 x 2 into 48-value cells (fold_order:
OPEN, required), run the wiring on the input buffer "cells", and unfold the buffer named `output` (16 values per
cell) back to 4 values per pixel -> [4, H, W]."""
if features.shape[0] != ops.NET1_FEATURES:
raise ValueError("net1 takes %d features per pixel" % ops.NET1_FEATURES)
cells = ops.fold2x2(features, order=fold_order)
buf = run_graph(wiring, {"cells": cells}, params, pad=pad)
out = buf[output]
if out.shape[0] != 16:
raise ValueError("net1's output has 16 values per cell, got %d" % out.shape[0])
return ops.unfold2x2(out, 4, order=fold_order)
def net1_forward(values, params):
"""net1 on its per-pixel values [10, G1h, G1w] -> [4, G1h, G1w], with the delivered wiring and arithmetic
(clean/fg/reference/net1.py: fold, 32 steps, leaky ReLU, zero border, float16 chunk accumulation, unfold)."""
from clean.fg.reference import net1 as _net1
return _net1.forward(values, params)


def net2_forward(inputs, params, *, wiring, pad, outputs):
Expand Down
95 changes: 95 additions & 0 deletions clean/fg/reference/fp16acc.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# SPDX-License-Identifier: MIT
"""Frame generation (issue #96): exact float16 chunk accumulation, as a CPU reference.

Written for this project. net1's convolutions accumulate in float16, starting at the bias: each chunk of 16 products
is summed exactly and added to the accumulator, which is rounded to float16 once per chunk (round to nearest, ties to
even). This module computes acc' = RN16(acc + sum of 16 products a_i * b_i) exactly, for arrays of accumulators.

How: every finite float16 value is an integer multiple of 2^-24, |m| < 2^40. Each m is split into a high and a low
20-bit part, so the three partial dot products (high*high, high*low + low*high, low*low) are exact in int64. The
exact total, in units of 2^-48, is reduced to units of 2^-25 (half the smallest subnormal) with a sticky bit, and
rounded to float16 with integer arithmetic. No floating-point rounding happens before the single float16 rounding.

Non-finite operands (an accumulator or factor that is inf or NaN) follow IEEE arithmetic: those elements are computed
in float64 and rounded to float16 (inf - inf and 0 * inf give NaN). What the original's matrix unit does with them is
not specified; finite inputs are exact.
"""
import numpy as np

_S24 = float(1 << 24)
_LOW = (1 << 20) - 1


def h(x):
"""Round to float16 (nearest, ties to even) and return float64."""
return np.asarray(x, dtype=np.float64).astype(np.float16).astype(np.float64)


def _ints(x):
"""Finite float16 values (as float64) -> exact integers m with x = m * 2^-24."""
return np.round(np.asarray(x, dtype=np.float64) * _S24).astype(np.int64)


def _split(m):
return m >> 20, m & _LOW


def round16_parts(hh, mid, ll):
"""RN16 of the exact value (hh * 2^40 + mid * 2^20 + ll) * 2^-48, with ll >= 0. Returns float64 float16 values."""
hh = np.asarray(hh, dtype=np.int64)
mid = np.asarray(mid, dtype=np.int64)
ll = np.asarray(ll, dtype=np.int64)
big = np.abs(hh) > (1 << 30) # |value| >= 2^22: infinite whatever the rest adds
hhc = np.clip(hh, -(1 << 30), 1 << 30)
# value * 2^25 = hh * 2^17 + mid2 / 8 + llr / 2^23, with mid2 = mid + (ll >> 20) and 0 <= llr < 2^20
l1 = ll >> 20
llr = ll & _LOW
mid2 = mid + l1
m1 = mid2 >> 3
midr = mid2 & 7
q = (hhc << 17) + m1 # floor of the value in units of 2^-25
sticky = (midr != 0) | (llr != 0) # the fraction (midr * 2^20 + llr) / 2^23 is not zero
neg = q < 0
mag = np.where(neg, np.where(sticky, -q - 1, -q), q)
# quantum in units of 2^-25: 2 for subnormals (value < 2^-14 = 2^11 units), else 2^(e - 10) in binade 2^e units
_, ex = np.frexp(np.maximum(mag, 1).astype(np.float64))
e = ex.astype(np.int64) - 1
qexp = np.where(mag < (1 << 11), 1, np.maximum(e - 10, 1))
quantum = np.left_shift(np.int64(1), qexp)
r = mag % quantum
down = mag - r
half = quantum >> 1
odd = ((down // quantum) & 1) == 1
up = (r > half) | ((r == half) & (sticky | odd))
res = down + np.where(up, quantum, 0)
val = res.astype(np.float64) * 2.0 ** -25
val = np.where((val >= 65536.0) | big, np.inf, val)
sign_neg = np.where(big, hh < 0, neg)
return np.where(sign_neg, -val, val)


def acc_dot16(acc, a, b, axis=-1):
"""RN16(acc + sum over `axis` of a * b), exact for finite float16 inputs. a and b broadcast against each other;
the reduced axis must have length <= 16; acc broadcasts against the result."""
a = np.asarray(a, dtype=np.float64)
b = np.asarray(b, dtype=np.float64)
acc = np.asarray(acc, dtype=np.float64)
a, b = np.broadcast_arrays(a, b)
if a.shape[axis] > 16:
raise ValueError("a chunk has at most 16 products")
fin_a, fin_b = np.isfinite(a), np.isfinite(b)
ah, al = _split(_ints(np.where(fin_a, a, 0.0)))
bh, bl = _split(_ints(np.where(fin_b, b, 0.0)))
hh = np.sum(ah * bh, axis=axis)
mid = np.sum(ah * bl + al * bh, axis=axis)
ll = np.sum(al * bl, axis=axis)
fin_acc = np.isfinite(acc)
m_acc = _ints(np.where(fin_acc, acc, 0.0))
hh, mid, ll, m_acc = np.broadcast_arrays(hh, mid, ll, m_acc)
out = round16_parts(hh, mid + (m_acc << 4), ll)
bad = ~(np.all(fin_a & fin_b, axis=axis) & fin_acc)
if np.any(bad):
with np.errstate(invalid="ignore", over="ignore"):
slow = h(acc + np.sum(a * b, axis=axis))
out = np.where(bad, slow, out)
return out
Loading
Loading