CultLib/packages/cultmath/tools/cycles-oracle/README.md

70 lines
4.7 KiB
Markdown
Raw Normal View History

# Cycles oracle
`oracle.py` produces the fixtures that `CyclesOracleTests` holds `math.cycles_*` to: for each Cycles node
CultMath ports, the node's results as Blender's own Cycles computes them.
## Run
```
CYCLES_CPU_NO_AVX2=1 blender --background --factory-startup --python oracle.py -- <fixture directory> [<family> ...]
```
The fixture directory is `tests/CultMath.Tests/fixtures/cycles-oracle`. Families are `math`, `map-range`,
`clamp`, `mix`, `rgb-to-bw` and `ramp`; with none named, all are written. The tool is a Blender Python
script and runs only under Blender, never under a plain Python.
## The pin
It refuses to run under any Blender but **5.2.2 LTS, build hash `d13f752e3b9c`**, exits nonzero and names
the version and build it found beside the ones it needs. Blender 5.2.2 is
<https://download.blender.org/release/Blender5.2/> (`blender-5.2.2-linux-x64.tar.xz`). The platform is Linux x64: the fixtures reproduce
byte for byte only there, and the Steam/Windows build is another build (see below). The fixtures record the
version, the hash and the platform they were written on, as provenance.
## The reference and other builds
Ruling `cultmath-tapes:ruling:cycles-kernel-reference-ruled`: CultMath's Cycles converters mean Cycles' formulas
evaluated with IEEE single rounding per operation, and the Linux SSE4.2 oracle stays their bit-exact witness.
Every other Cycles build (AVX2 FMA-contracted, MSVC /fp:fast, GPU backends) and CultMath's own HLSL lowering are
held to a stated per-function tolerance class measured on that build; cancellation-prone functions (floored
modulo, wrap) get an error bound relative to |b| and a documented divergence note.
Cycles' AVX2 CPU kernel is compiled with fused multiply-add, so `a - floor(a / b) b` is one fused operation
there, and CultMath's C# (which fuses nothing) computes the unfused one. The fixtures pin the SSE4.2 kernel,
which has no FMA, by `CYCLES_CPU_NO_AVX2=1`; the tool bakes `10000 mod 0.1` before anything else and exits 4 if
the result is the fused one, so a run on the wrong kernel writes nothing. Other kernels are other builds:
measured under the table below, never written to these fixtures.
| build | how it was measured | fixture | per-function ulp or bound |
| --- | --- | --- | --- |
| Blender 5.2.2 Linux x64, SSE4.2 kernel (the reference) | `oracle.py` with `CYCLES_CPU_NO_AVX2=1`; `CyclesOracleTests` holds every function to the fixtures | `tests/CultMath.Tests/fixtures/cycles-oracle/*.json` | 0 ulp, every function |
| Blender 5.2.2 Linux x64, AVX2 kernel | the same oracle without the pin, 1024 rows per function, against the single-rounding model `fma(-floor(a / b), b, a)` (wrap: `fma(-range, floor((value - min) / range), value)`) | none committed | floored modulo: at most 2^-23 (\|a / b\| + 1) \|b\|, measured 0.91 of 2^-24 (\|a\| + \|b\|) on 151 rows; wrap: at most 2^-23 (\|value\| + \|min\| + \|range\|), measured 0.77 of 2^-24 on 30 rows; other functions unmeasured |
The divergence note: a build compiled with fast-math may also move `floor(a / b)` by one near an integer
quotient, so the result differs by a whole \|b\| (wrap: a whole range). Further rows come from follow-up
`cultmath-tapes:follow_up:cycles-tolerance-classes`; its per-build fixtures go under
`fixtures/cycles-oracle/<build>/` with their tolerances beside `Tolerances` in `CyclesOracleTests`.
## Method
Operands go into float, Non-Color input images (channel packed, read with Closest interpolation), three
operands per image. The node under test reads them. One Emit bake per output channel (Cycles on the CPU, 1
sample, margin 0, no denoising) writes the result to a float image; each pixel is one case. The tool first
checks that a bake returns an operand image bit for bit, and stops if it does not. The fixtures hold the
operands and the results as float32 bit patterns, so a test reads exactly what Cycles computed.
A Map Range node's Clamp option is baked as the node with Clamp on, which Cycles expands into a Clamp node
of type Range on the result. The ramp family bakes a Color Ramp whose table entries are each read at a `t`
whose product with 255 is the entry's index, so the first 256 cases are the ramp's own table.
## Fixtures
Written by this tool and never edited by hand. Rerunning it under the same Blender build on the same
platform rewrites them byte for byte; `CyclesOracleTests` holds every function to them at 0 ulp. Run the
oracle on Yggdrasil-class Linux, never on the workstation.
## Licence
`oracle.py` is GPL-3.0-or-later, as a script that runs inside Blender (`bpy`). It ships in no package: the
`GameCult.Math` NuGet package and the Unity package do not contain `tools/`. The fixtures are data it
produced. The Cycles functions they test are Apache-2.0 (`math.Cycles.cs`, `CultMath.Cycles.hlsl`).