diff --git a/clean/fg/FORMATS.md b/clean/fg/FORMATS.md index 859722e8..be2f243c 100644 --- a/clean/fg/FORMATS.md +++ b/clean/fg/FORMATS.md @@ -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. @@ -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. diff --git a/clean/fg/README.md b/clean/fg/README.md index 72965024..87340ffd 100644 --- a/clean/fg/README.md +++ b/clean/fg/README.md @@ -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 . diff --git a/clean/fg/reference/config.py b/clean/fg/reference/config.py new file mode 100644 index 00000000..db84cd47 --- /dev/null +++ b/clean/fg/reference/config.py @@ -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 diff --git a/clean/fg/tests/test_fg_config.py b/clean/fg/tests/test_fg_config.py new file mode 100644 index 00000000..c1d13dff --- /dev/null +++ b/clean/fg/tests/test_fg_config.py @@ -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("