@woosh/meep-engine 3.15.0 → 3.17.0

package/src/shade/renderer/particles/optimizer/dag/particle_vector_extract.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Choose one node per class — the instruction-count half of the optimizer.
+ *
+ * Most classes hold one node and there is nothing to choose. The ones that hold two are where a
+ * rewrite's worth was not local: `a * b + c` as a `MAD` costs one instruction and as `MUL` then
+ * `ADD` costs two, but the `MAD` only SAVES one if nothing else reads the product. So the cost that
+ * matters is the DAG cost — every distinct node counted once, which is exactly the instruction count
+ * — and not the tree cost, which would count a shared subexpression once per reader and talk itself
+ * into duplicating work.
+ *
+ * ## Why this is a greedy and not an exact solver
+ *
+ * DAG-cost extraction is NP-hard in general (reduction from minimum set cover), and the literature's
+ * answer at this scale is an ILP. That would mean a solver, and there is no solver in this tree and
+ * no appetite for vendoring one. What is here instead is the standard two-step: a bottom-up
+ * relaxation to a consistent choice, then hill-climbing on the classes that actually have a choice,
+ * each flip scored by re-measuring the whole reachable set.
+ *
+ * ## The climb does nothing today, and that is worth saying
+ *
+ * With the one alternative there is — `MAD` beside `MUL` then `ADD` — the seed is already optimal,
+ * and it was measured to be: over the whole effect corpus, switching the climb off changes neither an
+ * instruction nor a slot. The reason is that a `MAD` is never WORSE than the pair. Choosing it costs
+ * one instruction and leaves the product to be counted only if something else still reads it, so its
+ * DAG cost is at most the pair's, and the bottom-up relaxation — which prefers it on tree cost, where
+ * it is strictly cheaper — lands on the answer without help.
+ *
+ * The climb stays because the seed's agreement is a property of THAT rule and not of the pipeline. A
+ * rule whose alternative is dearer where it is shared — a fused operation that costs more than one
+ * instruction, an operation with a wider destination — has a tree cost that says the wrong thing, and
+ * the climb is what corrects it. `./particle_vector_extract.spec.js` exercises exactly that, through the
+ * `node_cost` the caller may pass, so the machinery is held to its purpose rather than to the one
+ * rule that happens not to need it.
+ *
+ * The relaxation is also what keeps extraction honest about cycles. A class can only be given a cost
+ * through nodes whose children already have one, so a node that could only be reached through its own
+ * class never gets a finite cost and is never chosen, whatever the rules did.
+ */
+/**
+ * What a node costs. Everything is one instruction except a literal, which is usually an operand
+ * rather than an instruction — priced below one so that folding is preferred, and above zero so that
+ * a fold is not preferred over a value that was already going to be computed anyway.
+ *
+ * @param {import("./particle_vector_graph.js").ParticleVectorNode} node
+ * @returns {number}
+ */
+export function particle_vector_node_cost(node: import("./particle_vector_graph.js").ParticleVectorNode): number;
+/**
+ * @typedef {object} ParticleValueExtraction
+ * @property {Map<number, number>} choice per class, the node chosen for it
+ * @property {number[]} order the demanded classes, every class after the ones it reads
+ * @property {number} cost the DAG cost of that choice
+ */
+/**
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {number[]} roots classes the program has to compute
+ * @param {object} [options]
+ * @param {function(import("./particle_vector_graph.js").ParticleVectorNode): number} [options.node_cost]
+ * @param {number} [options.max_rounds] hill-climbing sweeps over the classes that have a choice
+ * @param {number} [options.max_evaluations] flips to score before settling for what is in hand; a
+ *   guard so a pathological program cannot make extraction the slow part of a build
+ * @returns {ParticleValueExtraction}
+ */
+export function extract_particle_values(graph: import("./particle_vector_graph.js").ParticleVectorGraph, roots: number[], { node_cost, max_rounds, max_evaluations, }?: {
+    node_cost?: (arg0: import("./particle_vector_graph.js").ParticleVectorNode) => number;
+    max_rounds?: number;
+    max_evaluations?: number;
+}): ParticleValueExtraction;
+export type ParticleValueExtraction = {
+    /**
+     * per class, the node chosen for it
+     */
+    choice: Map<number, number>;
+    /**
+     * the demanded classes, every class after the ones it reads
+     */
+    order: number[];
+    /**
+     * the DAG cost of that choice
+     */
+    cost: number;
+};
+//# sourceMappingURL=particle_vector_extract.d.ts.map

package/src/shade/renderer/particles/optimizer/dag/particle_vector_extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_vector_extract.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/optimizer/dag/particle_vector_extract.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;;;;;;GAOG;AACH,gDAHW,OAAO,4BAA4B,EAAE,kBAAkB,GACrD,MAAM,CAIlB;AAED;;;;;GAKG;AAEH;;;;;;;;;GASG;AACH,+CATW,OAAO,4BAA4B,EAAE,mBAAmB,SACxD,MAAM,EAAE;IAE4E,SAAS,UAApF,OAAO,4BAA4B,EAAE,kBAAkB,KAAG,MAAM;IACxD,UAAU,GAA3B,MAAM;IACW,eAAe,GAAhC,MAAM;IAEJ,uBAAuB,CA0DnC;;;;;YAvEa,IAAI,MAAM,EAAE,MAAM,CAAC;;;;WACnB,MAAM,EAAE;;;;UACR,MAAM"}

package/src/shade/renderer/particles/optimizer/dag/particle_vector_extract.js

@@ -0,0 +1,283 @@
+import { assert } from "../../../../../core/assert.js";
+import { PV } from "./particle_vector_graph.js";
+
+/**
+ * Choose one node per class — the instruction-count half of the optimizer.
+ *
+ * Most classes hold one node and there is nothing to choose. The ones that hold two are where a
+ * rewrite's worth was not local: `a * b + c` as a `MAD` costs one instruction and as `MUL` then
+ * `ADD` costs two, but the `MAD` only SAVES one if nothing else reads the product. So the cost that
+ * matters is the DAG cost — every distinct node counted once, which is exactly the instruction count
+ * — and not the tree cost, which would count a shared subexpression once per reader and talk itself
+ * into duplicating work.
+ *
+ * ## Why this is a greedy and not an exact solver
+ *
+ * DAG-cost extraction is NP-hard in general (reduction from minimum set cover), and the literature's
+ * answer at this scale is an ILP. That would mean a solver, and there is no solver in this tree and
+ * no appetite for vendoring one. What is here instead is the standard two-step: a bottom-up
+ * relaxation to a consistent choice, then hill-climbing on the classes that actually have a choice,
+ * each flip scored by re-measuring the whole reachable set.
+ *
+ * ## The climb does nothing today, and that is worth saying
+ *
+ * With the one alternative there is — `MAD` beside `MUL` then `ADD` — the seed is already optimal,
+ * and it was measured to be: over the whole effect corpus, switching the climb off changes neither an
+ * instruction nor a slot. The reason is that a `MAD` is never WORSE than the pair. Choosing it costs
+ * one instruction and leaves the product to be counted only if something else still reads it, so its
+ * DAG cost is at most the pair's, and the bottom-up relaxation — which prefers it on tree cost, where
+ * it is strictly cheaper — lands on the answer without help.
+ *
+ * The climb stays because the seed's agreement is a property of THAT rule and not of the pipeline. A
+ * rule whose alternative is dearer where it is shared — a fused operation that costs more than one
+ * instruction, an operation with a wider destination — has a tree cost that says the wrong thing, and
+ * the climb is what corrects it. `./particle_vector_extract.spec.js` exercises exactly that, through the
+ * `node_cost` the caller may pass, so the machinery is held to its purpose rather than to the one
+ * rule that happens not to need it.
+ *
+ * The relaxation is also what keeps extraction honest about cycles. A class can only be given a cost
+ * through nodes whose children already have one, so a node that could only be reached through its own
+ * class never gets a finite cost and is never chosen, whatever the rules did.
+ */
+
+/**
+ * What a node costs. Everything is one instruction except a literal, which is usually an operand
+ * rather than an instruction — priced below one so that folding is preferred, and above zero so that
+ * a fold is not preferred over a value that was already going to be computed anyway.
+ *
+ * @param {import("./particle_vector_graph.js").ParticleVectorNode} node
+ * @returns {number}
+ */
+export function particle_vector_node_cost(node) {
+    return node.op === PV.CONST ? 0.5 : 1;
+}
+
+/**
+ * @typedef {object} ParticleValueExtraction
+ * @property {Map<number, number>} choice per class, the node chosen for it
+ * @property {number[]} order the demanded classes, every class after the ones it reads
+ * @property {number} cost the DAG cost of that choice
+ */
+
+/**
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {number[]} roots classes the program has to compute
+ * @param {object} [options]
+ * @param {function(import("./particle_vector_graph.js").ParticleVectorNode): number} [options.node_cost]
+ * @param {number} [options.max_rounds] hill-climbing sweeps over the classes that have a choice
+ * @param {number} [options.max_evaluations] flips to score before settling for what is in hand; a
+ *   guard so a pathological program cannot make extraction the slow part of a build
+ * @returns {ParticleValueExtraction}
+ */
+export function extract_particle_values(graph, roots, {
+    node_cost = particle_vector_node_cost,
+    max_rounds = 8,
+    max_evaluations = 4096,
+} = {}) {
+    const choice = seed_choice(graph, node_cost);
+    const canonical = [...new Set(roots.map(root => graph.find(root)))];
+
+    let reached = reachable(graph, canonical, choice);
+    let cost = dag_cost(graph, reached, choice, node_cost);
+    let evaluations = 0;
+
+    for (let round = 0; round < max_rounds && evaluations < max_evaluations; round++) {
+        let improved = false;
+
+        // Only the classes that are both reachable and hold more than one node are a decision; with
+        // one alternative-generating rule that is a handful of products per program.
+        for (const id of [...reached].sort((a, b) => a - b)) {
+            const members = graph.members(id);
+
+            if (members.length < 2 || evaluations >= max_evaluations) {
+                continue;
+            }
+
+            const before = choice.get(id);
+
+            for (const member of members) {
+                if (member === before) {
+                    continue;
+                }
+
+                evaluations++;
+                choice.set(id, member);
+
+                const trial_reached = reachable(graph, canonical, choice);
+                const trial_cost = dag_cost(graph, trial_reached, choice, node_cost);
+
+                // Strictly better only, so the climb cannot walk in a circle over spellings that cost
+                // the same — and so a class it settles on is a class it had a reason to move.
+                if (trial_cost < cost) {
+                    improved = true;
+                    reached = trial_reached;
+                    cost = trial_cost;
+                    break;
+                }
+
+                choice.set(id, before);
+            }
+        }
+
+        if (!improved) {
+            break;
+        }
+    }
+
+    return { choice, order: topological(graph, reached, choice), cost };
+}
+
+/**
+ * A consistent choice to start from: per class, the node whose own cost plus its children's is least,
+ * relaxed until nothing moves.
+ *
+ * This is the TREE cost, which over-counts sharing — but it is only a starting point, and it is the
+ * one starting point guaranteed to be well-founded, since a class only gets a cost once some node in
+ * it has children that all have one.
+ *
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {function(import("./particle_vector_graph.js").ParticleVectorNode): number} node_cost
+ * @returns {Map<number, number>} per class, the node chosen
+ */
+function seed_choice(graph, node_cost) {
+    /** @type {Map<number, number>} */
+    const choice = new Map();
+    /** @type {Map<number, number>} */
+    const cost = new Map();
+
+    // Classes are visited oldest first and a node's children are almost always older than it, so this
+    // settles in two sweeps for anything the rules build; the loop is what covers the "almost".
+    for (let changed = true; changed;) {
+        changed = false;
+
+        for (const [id, members] of graph.class_nodes) {
+            for (const member of members) {
+                const node = graph.node(member);
+                let total = node_cost(node);
+
+                for (const child of node.children) {
+                    const child_cost = cost.get(graph.find(child));
+
+                    if (child_cost === undefined) {
+                        total = Infinity;
+                        break;
+                    }
+
+                    total += child_cost;
+                }
+
+                if (total < (cost.get(id) ?? Infinity)) {
+                    cost.set(id, total);
+                    choice.set(id, member);
+                    changed = true;
+                }
+            }
+        }
+    }
+
+    return choice;
+}
+
+/**
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {Map<number, number>} choice
+ * @param {number} id a canonical class
+ * @returns {import("./particle_vector_graph.js").ParticleVectorNode}
+ */
+function chosen(graph, choice, id) {
+    const node = choice.get(id);
+
+    assert.defined(node, `particle value extraction: class ${id} has no node whose cost is finite`);
+
+    return graph.node(node);
+}
+
+/**
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {number[]} roots canonical class ids
+ * @param {Map<number, number>} choice
+ * @returns {Set<number>} every class the roots reach through the chosen nodes
+ */
+function reachable(graph, roots, choice) {
+    const seen = new Set();
+    const stack = [...roots];
+
+    while (stack.length > 0) {
+        const id = stack.pop();
+
+        if (seen.has(id)) {
+            continue;
+        }
+
+        seen.add(id);
+
+        for (const child of chosen(graph, choice, id).children) {
+            stack.push(graph.find(child));
+        }
+    }
+
+    return seen;
+}
+
+/**
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {Set<number>} reached
+ * @param {Map<number, number>} choice
+ * @param {function(import("./particle_vector_graph.js").ParticleVectorNode): number} node_cost
+ * @returns {number} every distinct chosen node counted once — the instruction count, near enough
+ */
+function dag_cost(graph, reached, choice, node_cost) {
+    let total = 0;
+
+    for (const id of reached) {
+        total += node_cost(chosen(graph, choice, id));
+    }
+
+    return total;
+}
+
+/**
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {Set<number>} reached
+ * @param {Map<number, number>} choice
+ * @returns {number[]} the reached classes, every one after the classes its chosen node reads
+ */
+function topological(graph, reached, choice) {
+    /** @type {number[]} */
+    const order = [];
+    const done = new Set();
+
+    for (const root of [...reached].sort((a, b) => a - b)) {
+        if (done.has(root)) {
+            continue;
+        }
+
+        const stack = [{ id: root, next: 0 }];
+
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            const children = chosen(graph, choice, frame.id).children;
+
+            if (done.has(frame.id)) {
+                stack.pop();
+                continue;
+            }
+
+            if (frame.next < children.length) {
+                const child = graph.find(children[frame.next++]);
+
+                if (!done.has(child)) {
+                    stack.push({ id: child, next: 0 });
+                }
+
+                continue;
+            }
+
+            done.add(frame.id);
+            order.push(frame.id);
+            stack.pop();
+        }
+    }
+
+    return order;
+}

package/src/shade/renderer/particles/optimizer/dag/particle_vector_graph.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Node kinds with no opcode of their own. Above every {@link VM_OP } number.
+ */
+export type PV = number;
+export namespace PV {
+    let CONST: number;
+    let ATTR: number;
+    let BUILD: number;
+}
+export class ParticleVectorGraph {
+    /**
+     * @param {object} [params]
+     * @param {ParticleVectorRule[]} [params.rules]
+     */
+    constructor({ rules, share_window }?: {
+        rules?: ParticleVectorRule[];
+    });
+    /** @type {ParticleVectorRule[]} */
+    rules: ParticleVectorRule[];
+    /**
+     * How far back a value may have been computed and still be reused rather than recomputed.
+     *
+     * Sharing is not free on a machine with forty-eight registers. A value computed once and read
+     * a thousand instructions later occupies its run for all of them: `curl3` measures at 57
+     * slots with sharing unbounded and 33 with none — for 1,100 instructions either way. So the
+     * question is never whether to share but WHICH sharings are free, and the pass pipeline
+     * answers it without seeming to think about it: its common-subexpression pass can only reuse
+     * a value still in its register, so it takes the sharing that extends no live range and
+     * recomputes the rest. This is that policy with a number on it, and the number is a rung of
+     * the ladder in `./optimize_particle_program_vector.js` rather than a constant, because how
+     * much sharing a program can afford is a property of the program.
+     *
+     * @type {number}
+     */
+    share_window: number;
+    /** @type {ParticleVectorNode[]} */
+    nodes: ParticleVectorNode[];
+    /** @type {Map<string, number>} */
+    interned: Map<string, number>;
+    /** @type {number[]} per node, the class it was created as */
+    class_of: number[];
+    /** @type {Uint32Array} union-find over class ids */
+    parent: Uint32Array;
+    /** @type {Map<number, number[]>} per class root, the nodes in it */
+    class_nodes: Map<number, number[]>;
+    /** @type {Map<number, number>} per class root, the magnitude bound on the integer it holds */
+    class_bound: Map<number, number>;
+    /** @returns {number} */
+    get size(): number;
+    /**
+     * @param {number} id
+     * @returns {number} the class root
+     */
+    find(id: number): number;
+    /** @param {number} id @returns {ParticleVectorNode} */
+    node(id: number): ParticleVectorNode;
+    /** @param {number} id @returns {number[]} */
+    members(id: number): number[];
+    /** @param {number} id @returns {number} */
+    width_of(id: number): number;
+    /** @param {number} id @returns {number} */
+    bound_of(id: number): number;
+    /**
+     * The literal a value is, lane by lane — `null` where it is not one.
+     *
+     * @param {number} id
+     * @returns {number[]|null}
+     */
+    constants_of(id: number): number[] | null;
+    /**
+     * The literal one lane of a value is.
+     *
+     * @param {number} id
+     * @param {number} lane
+     * @returns {number|null}
+     */
+    constant_at(id: number, lane: number): number | null;
+    /**
+     * A vector of literals.
+     *
+     * @param {...number} values one per lane, at least one
+     * @returns {number} a class
+     */
+    constant(...values: number[]): number;
+    /**
+     * Build a value — or find the one that already means this, or the better one a rule knows.
+     *
+     * @param {Partial<ParticleVectorNode>} shape
+     * @returns {number} a class
+     */
+    make({ op, width, operand_width, children, patterns, imm }: Partial<ParticleVectorNode>): number;
+    /**
+     * Record that a node means the same as an existing class — for a rewrite whose worth is not
+     * local, and which extraction should therefore be the one to take or leave.
+     *
+     * @param {number} id
+     * @param {number} alternative
+     */
+    add_alternative(id: number, alternative: number): void;
+    #private;
+}
+export type ParticleVectorNode = {
+    /**
+     * a {@link VM_OP } or a {@link PV }
+     */
+    op: number;
+    /**
+     * lanes the VALUE has, `1..4`
+     */
+    width: number;
+    /**
+     * lanes each source is read at, which is the instruction's width
+     * field. The same as `width` for anything lanewise; three for a `CROSS`, and the operand's own
+     * width for a reduction, which reads many lanes to write one.
+     */
+    operand_width: number;
+    /**
+     * the values its sources read, one per source
+     */
+    children: number[];
+    /**
+     * per source, the swizzle it reads that value through — or, for
+     * `BUILD`, the single lane it takes
+     */
+    patterns: number[];
+    /**
+     * static fields: literal bits, a record word, a builtin id, a curve handle,
+     * the first draw of a `RANDOM`
+     */
+    imm: number[];
+};
+export type ParticleVectorRule = (graph: ParticleVectorGraph, node: ParticleVectorNode) => number;
+//# sourceMappingURL=particle_vector_graph.d.ts.map

package/src/shade/renderer/particles/optimizer/dag/particle_vector_graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_vector_graph.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/optimizer/dag/particle_vector_graph.js"],"names":[],"mappings":";;;iBA+CU,MAAM;;;;;;AAmChB;IACI;;;OAGG;IACH;QAFyC,KAAK,GAAnC,kBAAkB,EAAE;OAiC9B;IA9BG,mCAAmC;IACnC,OADW,kBAAkB,EAAE,CACb;IAClB;;;;;;;;;;;;;;OAcG;IACH,cAFU,MAAM,CAEgB;IAChC,mCAAmC;IACnC,OADW,kBAAkB,EAAE,CAChB;IACf,kCAAkC;IAClC,UADW,IAAI,MAAM,EAAE,MAAM,CAAC,CACL;IACzB,6DAA6D;IAC7D,UADW,MAAM,EAAE,CACD;IAClB,oDAAoD;IACpD,QADW,WAAW,CACU;IAChC,oEAAoE;IACpE,aADW,IAAI,MAAM,EAAE,MAAM,EAAE,CAAC,CACJ;IAC5B,8FAA8F;IAC9F,aADW,IAAI,MAAM,EAAE,MAAM,CAAC,CACF;IAGhC,wBAAwB;IACxB,mBAEC;IAED;;;OAGG;IACH,SAHW,MAAM,GACJ,MAAM,CAMlB;IAED,uDAAuD;IACvD,SADY,MAAM,GAAe,kBAAkB,CAGlD;IAED,6CAA6C;IAC7C,YADY,MAAM,GAAe,MAAM,EAAE,CAGxC;IAED,2CAA2C;IAC3C,aADY,MAAM,GAAe,MAAM,CAGtC;IAED,2CAA2C;IAC3C,aADY,MAAM,GAAe,MAAM,CAGtC;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,MAAM,EAAE,GAAC,IAAI,CAUzB;IAED;;;;;;OAMG;IACH,gBAJW,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CAMvB;IAED;;;;;OAKG;IACH,oBAHc,MAAM,KACP,MAAM,CAUlB;IAED;;;;;OAKG;IACH,4DAHW,QAAQ,kBAAkB,CAAC,GACzB,MAAM,CAkDlB;IAED;;;;;;OAMG;IACH,oBAHW,MAAM,eACN,MAAM,QAgChB;;CAwCJ;;;;;QAjRa,MAAM;;;;WACN,MAAM;;;;;;mBACN,MAAM;;;;cAGN,MAAM,EAAE;;;;;cACR,MAAM,EAAE;;;;;SAER,MAAM,EAAE;;yCAMX,mBAAmB,QACnB,kBAAkB,KAChB,MAAM"}