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
13 changes: 13 additions & 0 deletions clean/fg/FORMATS.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,17 @@ delivered by the spec side; the code never guesses it (it raises, or takes the c
(`order`), the fold order inside a cell (`order`). What the cell padding holds is OPEN too (zeros here).
- `net1_forward` and `net2_forward` raise `OpenItem`: the wiring of both networks is not delivered.

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

- No configuration value changes the networks or their weights.
- Multi-frame: count N (1 by default, at most a cap), index i in 1..N. Intermediate time t = i / (N + 1) as one
single-precision division (`intermediate_time`, numpy float32). Flags: multi-frame active (N > 1), last index
(i equal to the maximum index).
- UI recomposition: preset A (off) or B (on), set by the application; a profile value of 1 or 0xFFFFFE forces it off,
2 or 0xFFFFFF forces it on, any other value leaves it (`ui_recomposition`).
- Required arguments where the behaviour is OPEN: the cap on N (`n_max`), the further mode that also accepts
i = N + 1 (`extra_index`), the maximum that "last index" compares with (`maximum`).

## OPEN (waiting for the spec side)

1. The converter map file.
Expand All @@ -54,3 +65,5 @@ delivered by the spec side; the code never guesses it (it raises, or takes the c
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.
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.
2 changes: 2 additions & 0 deletions clean/fg/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ front end or the launcher yet. Status, open items and formats: [FORMATS.md](FORM
| `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 |
| `../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" |
| `reference/config.py` | the settled per-call configuration: the multi-frame intermediate time (one single-precision division), the index checks and flags, UI recomposition (FG preset A / B) with the profile values that force it |
| `tests/test_fg_config.py` | the intermediate time against exactly rounded quotients, the index rules, every forcing profile value |

```
python -m unittest discover -s clean/fg/tests -t .
Expand Down
71 changes: 71 additions & 0 deletions clean/fg/reference/config.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# SPDX-License-Identifier: MIT
"""Frame generation (issue #96): the per-call configuration values that are settled, as a CPU reference.

Written for this project. None of these values changes the networks or their weights (one weight set serves every
configuration); they decide the intermediate time and which stages run.

- Multi-frame: N generated frames per real frame (1 by default, at most a cap), index i in 1..N. The intermediate
time is t = i / (N + 1), one single-precision division. "Multi-frame active" is N > 1; "last index" is i equal to
the maximum index.
- UI recomposition (FG preset A = off, B = on): set by the application; a profile value can force it.

OPEN (clean/fg/FORMATS.md): the cap on N; the one further mode that also accepts i = N + 1, and what it does; which
maximum "last index" compares with (N, or the cap); the private override that can turn UI recomposition off. Where
these matter, the caller passes them explicitly; nothing here picks them.
"""
import numpy as np

PRESET_A = "A" # UI recomposition off
PRESET_B = "B" # UI recomposition on

# Profile values that force UI recomposition (True = on, preset B; False = off, preset A). Any other value leaves the
# application's setting as it is.
PROFILE_FORCE = {0x1: False, 0x2: True, 0xFFFFFE: False, 0xFFFFFF: True}


def check_multi_frame(n, i, *, n_max, extra_index=False):
"""Validates a multi-frame count n and index i. n_max: the cap on n (OPEN, so required). extra_index: the caller
states that the one further mode that also accepts i = n + 1 is in use (what that mode is, is OPEN)."""
for name, v in (("n", n), ("i", i), ("n_max", n_max)):
if isinstance(v, bool) or not isinstance(v, (int, np.integer)):
raise TypeError("%s must be an integer" % name)
if n_max < 1:
raise ValueError("n_max must be at least 1")
if not 1 <= n <= n_max:
raise ValueError("multi-frame count %d outside 1..%d" % (n, n_max))
top = n + 1 if extra_index else n
if not 1 <= i <= top:
raise ValueError("multi-frame index %d outside 1..%d" % (i, top))


def intermediate_time(n, i):
"""t = i / (n + 1) as one IEEE single-precision division of the two counts (each exact in float32 here).
Returns a numpy float32."""
if not (0 <= i < 1 << 24 and 0 <= n + 1 < 1 << 24):
raise ValueError("counts must be exact in float32")
return np.float32(i) / np.float32(n + 1)


def multi_frame_active(n):
return n > 1


def last_index(i, maximum):
"""True when i equals the maximum index. Which maximum the original compares with (n or the cap) is OPEN, so the
caller passes it."""
return i == maximum


def ui_recomposition(app_setting, profile_value=None):
"""Whether UI recomposition is on (preset B) or off (preset A): the application's setting, unless a profile value in
PROFILE_FORCE forces it. profile_value None: no profile value. (A private override that can turn it off is OPEN and
not modelled.)"""
if not isinstance(app_setting, bool):
raise TypeError("app_setting must be True or False")
if profile_value is not None and profile_value in PROFILE_FORCE:
return PROFILE_FORCE[profile_value]
return app_setting


def preset(ui_recomp_on):
return PRESET_B if ui_recomp_on else PRESET_A
77 changes: 77 additions & 0 deletions clean/fg/tests/test_fg_config.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# SPDX-License-Identifier: MIT
"""Frame generation (#96): the configuration reference (clean/fg/reference/config.py).

python -m unittest clean.fg.tests.test_fg_config
"""
import struct
import unittest
from fractions import Fraction

import numpy as np

from clean.fg.reference import config as C


def rn32(q):
"""A rational rounded to the nearest binary32 (ties to even), written separately: via struct of a float64 that is
itself correctly rounded from the exact quotient (innocuous double rounding: 53 >= 2 * 24 + 2)."""
return struct.unpack("<f", struct.pack("<f", q.numerator / q.denominator))[0]


class MultiFrame(unittest.TestCase):
def test_times(self):
self.assertEqual(C.intermediate_time(1, 1), np.float32(0.5))
self.assertEqual([float(C.intermediate_time(3, i)) for i in (1, 2, 3)], [0.25, 0.5, 0.75])
t = C.intermediate_time(2, 1)
self.assertEqual(t.dtype, np.float32)
self.assertEqual(float(t), rn32(Fraction(1, 3)))
self.assertNotEqual(float(t), 1.0 / 3.0) # single, not double precision

def test_times_against_exact_rounding(self):
for n in range(1, 64):
for i in range(1, n + 2):
self.assertEqual(float(C.intermediate_time(n, i)), rn32(Fraction(i, n + 1)), (n, i))

def test_flags(self):
self.assertFalse(C.multi_frame_active(1))
self.assertTrue(C.multi_frame_active(2))
self.assertTrue(C.last_index(3, 3))
self.assertFalse(C.last_index(2, 3))

def test_validation(self):
C.check_multi_frame(1, 1, n_max=1)
C.check_multi_frame(3, 3, n_max=4)
C.check_multi_frame(3, 4, n_max=4, extra_index=True)
for n, i, n_max in ((0, 1, 4), (5, 1, 4), (3, 0, 4), (3, 4, 4), (1, 1, 0)):
with self.assertRaises(ValueError, msg=(n, i, n_max)):
C.check_multi_frame(n, i, n_max=n_max)
with self.assertRaises(ValueError):
C.check_multi_frame(3, 5, n_max=4, extra_index=True)
with self.assertRaises(TypeError):
C.check_multi_frame(2, 1) # the cap is OPEN: required
with self.assertRaises(TypeError):
C.check_multi_frame(2.0, 1, n_max=4)
with self.assertRaises(TypeError):
C.check_multi_frame(True, 1, n_max=4)


class UiRecomposition(unittest.TestCase):
def test_profile_values(self):
for app in (False, True):
self.assertFalse(C.ui_recomposition(app, 1))
self.assertTrue(C.ui_recomposition(app, 2))
self.assertFalse(C.ui_recomposition(app, 0xFFFFFE))
self.assertTrue(C.ui_recomposition(app, 0xFFFFFF))
for other in (None, 0, 3, 0xFFFFFD, 0x1000000, -1):
self.assertEqual(C.ui_recomposition(app, other), app, other)

def test_presets(self):
self.assertEqual(C.preset(False), "A")
self.assertEqual(C.preset(True), "B")
self.assertEqual(C.preset(C.ui_recomposition(False, 0xFFFFFF)), "B")
with self.assertRaises(TypeError):
C.ui_recomposition(1)


if __name__ == "__main__":
unittest.main()
Loading