@woosh/meep-engine 3.16.0 → 3.17.0

package/src/shade/renderer/particles/optimizer/particle_integer_bounds.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The bound on one lane of an operation's result, from the bounds on that lane of its sources.
+ *
+ * The rules are magnitudes and nothing else — `|a * b| <= |a| * |b|` — so they say the same thing
+ * about a lane of an instruction and about a node of a value graph, and both callers read them from
+ * here rather than each keeping a copy of the table.
+ *
+ * @param {number} op
+ * @param {number} a bound on source 0, `Infinity` when it is unknown or absent
+ * @param {number} b bound on source 1
+ * @param {number} c bound on source 2
+ * @param {number} [width] lanes the operation spans — read only by the reductions
+ * @param {function(): number[]} [whole_operands] bounds over EVERY lane of sources 0 and 1, which is
+ *   what a reduction sums over; never called for a lanewise operation
+ * @returns {number}
+ */
+export function particle_integer_bound_of_operation(op: number, a: number, b: number, c: number, width?: number, whole_operands?: () => number[]): number;
+/**
+ * @param {number} value
+ * @returns {number} the value's magnitude when it is an integer, `Infinity` otherwise
+ */
+export function particle_integer_bound_of_value(value: number): number;
+/**
+ * Which register slots hold an integer, and how big it can be — the one fact that makes a float
+ * rewrite exact.
+ *
+ * `a * b + c` as `MAD` is a different number from `MUL` then `ADD` because the pair rounds the
+ * product before adding it and the fused form does not. When the product is an integer below 2^24
+ * it needs no rounding, and the two forms are then the same number on every executor — whether the
+ * hardware contracts the `MAD` into an FMA or not. So the peephole can fuse those pairs without
+ * giving anything up, provided it can PROVE the product is that small, and this is the analysis
+ * that proves it.
+ *
+ * The facts come from the shapes effects are actually made of. A comparison or a `step` is 0 or 1;
+ * a mask built from one, `cmp * 2 - 1`, is -1 or 1; a literal is whatever it is. Those flow through
+ * copies, negation, `abs`, `floor`, `min`, `max`, `clamp` and `select` unchanged in kind, and
+ * through the arithmetic with their bounds combined. Everything else — a draw, an attribute, a
+ * builtin, `fract`, a division, a transcendental — is unknown. So is any value whose bound would
+ * pass 2^24: above it an integer may no longer be representable, and once a rounding could have
+ * happened nothing downstream is exact any more.
+ *
+ * ## Why the bound is a magnitude and not an interval
+ *
+ * Exactness of a product is a question about magnitudes, and `|a * b| <= |a| * |b|` is all it
+ * needs. An interval would prove more — that `x - floor(x / 289) * 289` is small, say, which is
+ * the other shape the noise library is made of — but only from a bound on `x`, which is a
+ * position, and there is none. That rewrite stays behind the `fuse_multiply_add` switch.
+ *
+ * The file starts zeroed on both executors, so every slot begins as the integer 0.
+ */
+export class ParticleIntegerBounds {
+    /**
+     * @param {ArrayLike<number>} constants the shared constant pool, which `LOAD_CONST` reads
+     * @param {number} [slots]
+     */
+    constructor(constants: ArrayLike<number>, slots?: number);
+    /** @type {ArrayLike<number>} */
+    constants: ArrayLike<number>;
+    /** @type {Float64Array} per slot, the largest magnitude the integer it holds can have; `Infinity` when it is not known to hold one */
+    bound: Float64Array;
+    /**
+     * @param {import("./particle_program_analysis.js").ParticleOperandRun} read a `REG` run
+     * @param {number} [lanes] how many lanes are read; the operand's own count when left out
+     * @returns {number} the largest bound among the lanes read, or `Infinity`
+     */
+    bound_of_read(read: import("./particle_program_analysis.js").ParticleOperandRun, lanes?: number): number;
+    /**
+     * @param {import("./particle_program_analysis.js").ParticleOperandRun} source any operand
+     * @param {number} [lanes] how many lanes are read; the operand's own count when left out
+     * @returns {number} the bound on what it reads: a literal's own magnitude, or a run's
+     */
+    bound_of_source(source: import("./particle_program_analysis.js").ParticleOperandRun, lanes?: number): number;
+    /**
+     * Record what an instruction leaves in its destination.
+     *
+     * @param {ArrayLike<number>} words the four words of a single instruction, as they will run
+     */
+    publish(words: ArrayLike<number>): void;
+    /**
+     * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+     * @param {number} span lanes the instruction writes
+     * @returns {number[]} the bound each written lane will hold — gathered before anything is
+     *   written, since a source may alias the destination
+     */
+    lanes_written(instruction: import("./particle_program_analysis.js").ParticleDecodedInstruction, span: number): number[];
+    /**
+     * @param {import("./particle_program_analysis.js").ParticleOperandRun} read a `REG` run
+     * @param {number} lane
+     * @returns {number} the bound of the slot that lane reads
+     */
+    bound_of_slot(read: import("./particle_program_analysis.js").ParticleOperandRun, lane: number): number;
+}
+/**
+ * Integers up to here are exactly representable as `f32`, and so are all their sums and products
+ * that stay under it. Above it, integers thin out and a rounding could have happened.
+ *
+ * @type {number}
+ */
+export const PARTICLE_EXACT_INTEGER_LIMIT: number;
+//# sourceMappingURL=particle_integer_bounds.d.ts.map

package/src/shade/renderer/particles/optimizer/particle_integer_bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_integer_bounds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/particle_integer_bounds.js"],"names":[],"mappings":"AAmJA;;;;;;;;;;;;;;;GAeG;AACH,wDATW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,UACN,MAAM,yBACM,MAAM,EAAE,GAElB,MAAM,CAkDlB;AAUD;;;GAGG;AACH,uDAHW,MAAM,GACJ,MAAM,CAIlB;AA/ND;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IACI;;;OAGG;IACH,uBAHW,UAAU,MAAM,CAAC,UACjB,MAAM,EAOhB;IAJG,gCAAgC;IAChC,WADW,UAAU,MAAM,CAAC,CACF;IAC1B,sIAAsI;IACtI,OADW,YAAY,CACa;IAGxC;;;;OAIG;IACH,oBAJW,OAAO,gCAAgC,EAAE,kBAAkB,UAC3D,MAAM,GACJ,MAAM,CAclB;IAED;;;;OAIG;IACH,wBAJW,OAAO,gCAAgC,EAAE,kBAAkB,UAC3D,MAAM,GACJ,MAAM,CAMlB;IAED;;;;OAIG;IACH,eAFW,UAAU,MAAM,CAAC,QAiB3B;IAED;;;;;OAKG;IACH,2BALW,OAAO,gCAAgC,EAAE,0BAA0B,QACnE,MAAM,GACJ,MAAM,EAAE,CAkCpB;IAED;;;;OAIG;IACH,oBAJW,OAAO,gCAAgC,EAAE,kBAAkB,QAC3D,MAAM,GACJ,MAAM,CAMlB;CACJ;AAoED;;;;;GAKG;AACH,2CAFU,MAAM,CAEoC"}

package/src/shade/renderer/particles/optimizer/particle_integer_bounds.js

@@ -0,0 +1,236 @@
+import { PARTICLE_VM_REGISTER_SLOTS } from "../ParticleConstants.js";
+import { VM_KIND, VM_OP, vm_f32_value } from "../isa/ParticleVMISA.js";
+import { decode_particle_instruction, particle_read_slots } from "./particle_program_analysis.js";
+
+/**
+ * Which register slots hold an integer, and how big it can be — the one fact that makes a float
+ * rewrite exact.
+ *
+ * `a * b + c` as `MAD` is a different number from `MUL` then `ADD` because the pair rounds the
+ * product before adding it and the fused form does not. When the product is an integer below 2^24
+ * it needs no rounding, and the two forms are then the same number on every executor — whether the
+ * hardware contracts the `MAD` into an FMA or not. So the peephole can fuse those pairs without
+ * giving anything up, provided it can PROVE the product is that small, and this is the analysis
+ * that proves it.
+ *
+ * The facts come from the shapes effects are actually made of. A comparison or a `step` is 0 or 1;
+ * a mask built from one, `cmp * 2 - 1`, is -1 or 1; a literal is whatever it is. Those flow through
+ * copies, negation, `abs`, `floor`, `min`, `max`, `clamp` and `select` unchanged in kind, and
+ * through the arithmetic with their bounds combined. Everything else — a draw, an attribute, a
+ * builtin, `fract`, a division, a transcendental — is unknown. So is any value whose bound would
+ * pass 2^24: above it an integer may no longer be representable, and once a rounding could have
+ * happened nothing downstream is exact any more.
+ *
+ * ## Why the bound is a magnitude and not an interval
+ *
+ * Exactness of a product is a question about magnitudes, and `|a * b| <= |a| * |b|` is all it
+ * needs. An interval would prove more — that `x - floor(x / 289) * 289` is small, say, which is
+ * the other shape the noise library is made of — but only from a bound on `x`, which is a
+ * position, and there is none. That rewrite stays behind the `fuse_multiply_add` switch.
+ *
+ * The file starts zeroed on both executors, so every slot begins as the integer 0.
+ */
+export class ParticleIntegerBounds {
+    /**
+     * @param {ArrayLike<number>} constants the shared constant pool, which `LOAD_CONST` reads
+     * @param {number} [slots]
+     */
+    constructor(constants, slots = PARTICLE_VM_REGISTER_SLOTS) {
+        /** @type {ArrayLike<number>} */
+        this.constants = constants;
+        /** @type {Float64Array} per slot, the largest magnitude the integer it holds can have; `Infinity` when it is not known to hold one */
+        this.bound = new Float64Array(slots);
+    }
+
+    /**
+     * @param {import("./particle_program_analysis.js").ParticleOperandRun} read a `REG` run
+     * @param {number} [lanes] how many lanes are read; the operand's own count when left out
+     * @returns {number} the largest bound among the lanes read, or `Infinity`
+     */
+    bound_of_read(read, lanes = read.lanes) {
+        let bound = 0;
+
+        for (const slot of particle_read_slots(read, lanes)) {
+            if (slot < 0 || slot >= this.bound.length) {
+                return Infinity;
+            }
+
+            bound = Math.max(bound, this.bound[slot]);
+        }
+
+        return bound;
+    }
+
+    /**
+     * @param {import("./particle_program_analysis.js").ParticleOperandRun} source any operand
+     * @param {number} [lanes] how many lanes are read; the operand's own count when left out
+     * @returns {number} the bound on what it reads: a literal's own magnitude, or a run's
+     */
+    bound_of_source(source, lanes = source.lanes) {
+        return source.kind === VM_KIND.IMM
+            ? particle_integer_bound_of_value(vm_f32_value(source.word))
+            : this.bound_of_read(source, lanes);
+    }
+
+    /**
+     * Record what an instruction leaves in its destination.
+     *
+     * @param {ArrayLike<number>} words the four words of a single instruction, as they will run
+     */
+    publish(words) {
+        const instruction = decode_particle_instruction(words);
+
+        if (instruction.write === null) {
+            return;
+        }
+
+        const { base, span } = instruction.write;
+        const lanes = this.lanes_written(instruction, span);
+
+        for (let lane = 0; lane < span; lane++) {
+            if (base + lane < this.bound.length) {
+                this.bound[base + lane] = lanes[lane];
+            }
+        }
+    }
+
+    /**
+     * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+     * @param {number} span lanes the instruction writes
+     * @returns {number[]} the bound each written lane will hold — gathered before anything is
+     *   written, since a source may alias the destination
+     */
+    lanes_written(instruction, span) {
+        const [a, b, c] = instruction.sources;
+        const per_lane = (combine) => {
+            const out = new Array(span);
+
+            for (let lane = 0; lane < span; lane++) {
+                out[lane] = capped(combine(lane));
+            }
+
+            return out;
+        };
+        const lane_of = (source, lane) => (source.kind === VM_KIND.IMM
+            ? particle_integer_bound_of_value(vm_f32_value(source.word))
+            : this.bound_of_slot(source, lane));
+
+        // `LOAD_CONST` is the one operation whose lanes come from somewhere other than its
+        // operands, so it is answered here; every other one is the scalar rule below.
+        if (instruction.op === VM_OP.LOAD_CONST) {
+            return per_lane(lane => particle_integer_bound_of_value(this.constants[instruction.words[1] + lane]));
+        }
+
+        return per_lane(lane => particle_integer_bound_of_operation(
+            instruction.op,
+            a === undefined ? Infinity : lane_of(a, lane),
+            b === undefined ? Infinity : lane_of(b, lane),
+            c === undefined ? Infinity : lane_of(c, lane),
+            instruction.operation_width,
+            // The reductions read every lane, so their bound is over the whole operand rather than
+            // over one lane of it.
+            () => [this.bound_of_source(a, instruction.operation_width), this.bound_of_source(b, instruction.operation_width)]
+        ));
+    }
+
+    /**
+     * @param {import("./particle_program_analysis.js").ParticleOperandRun} read a `REG` run
+     * @param {number} lane
+     * @returns {number} the bound of the slot that lane reads
+     */
+    bound_of_slot(read, lane) {
+        const slot = particle_read_slots(read, lane + 1)[lane];
+
+        return slot >= 0 && slot < this.bound.length ? this.bound[slot] : Infinity;
+    }
+}
+
+/**
+ * The bound on one lane of an operation's result, from the bounds on that lane of its sources.
+ *
+ * The rules are magnitudes and nothing else — `|a * b| <= |a| * |b|` — so they say the same thing
+ * about a lane of an instruction and about a node of a value graph, and both callers read them from
+ * here rather than each keeping a copy of the table.
+ *
+ * @param {number} op
+ * @param {number} a bound on source 0, `Infinity` when it is unknown or absent
+ * @param {number} b bound on source 1
+ * @param {number} c bound on source 2
+ * @param {number} [width] lanes the operation spans — read only by the reductions
+ * @param {function(): number[]} [whole_operands] bounds over EVERY lane of sources 0 and 1, which is
+ *   what a reduction sums over; never called for a lanewise operation
+ * @returns {number}
+ */
+export function particle_integer_bound_of_operation(op, a, b, c, width = 1, whole_operands = () => [a, b]) {
+    switch (op) {
+        case VM_OP.CMP_LT:
+        case VM_OP.CMP_LE:
+        case VM_OP.CMP_GT:
+        case VM_OP.CMP_GE:
+        case VM_OP.CMP_EQ:
+        case VM_OP.STEP:
+            return 1;
+
+        case VM_OP.MOV:
+        case VM_OP.NEG:
+        case VM_OP.ABS:
+        case VM_OP.FLOOR:
+            return capped(a);
+
+        case VM_OP.MIN:
+        case VM_OP.MAX:
+            return capped(Math.max(a, b));
+
+        case VM_OP.CLAMP:
+            return capped(Math.max(a, b, c));
+
+        // Whichever of the two the condition picks, and the condition itself is not a value.
+        case VM_OP.SELECT:
+            return capped(Math.max(a, b));
+
+        case VM_OP.ADD:
+        case VM_OP.SUB:
+            return capped(a + b);
+
+        case VM_OP.MUL:
+            return capped(a * b);
+
+        case VM_OP.MAD:
+            return capped(a * b + c);
+
+        // Every product exact and every partial sum within the cap is what makes the sum an
+        // integer whatever order the hardware adds it in.
+        case VM_OP.DOT: {
+            const [whole_a, whole_b] = whole_operands();
+
+            return capped(width * whole_a * whole_b);
+        }
+
+        default:
+            return Infinity;
+    }
+}
+
+/**
+ * Integers up to here are exactly representable as `f32`, and so are all their sums and products
+ * that stay under it. Above it, integers thin out and a rounding could have happened.
+ *
+ * @type {number}
+ */
+export const PARTICLE_EXACT_INTEGER_LIMIT = 2 ** 24;
+
+/**
+ * @param {number} value
+ * @returns {number} the value's magnitude when it is an integer, `Infinity` otherwise
+ */
+export function particle_integer_bound_of_value(value) {
+    return Number.isInteger(value) ? capped(Math.abs(value)) : Infinity;
+}
+
+/**
+ * @param {number} bound
+ * @returns {number} the bound, or `Infinity` once it is past what is exact
+ */
+function capped(bound) {
+    return bound <= PARTICLE_EXACT_INTEGER_LIMIT ? bound : Infinity;
+}