@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -1,478 +1,477 @@
-import { assert } from "../../../../core/assert.js";
-import { PARTICLE_VM_INSTRUCTION_WORDS, PARTICLE_VM_REGISTER_SLOTS } from "../ParticleConstants.js";
-import { InstructionStream } from "../isa/InstructionStream.js";
-import { ParticleAssembler } from "../isa/ParticleAssembler.js";
-import { ParticleProgram } from "../isa/ParticleProgram.js";
-import { VM_OP, vm_decode_op, vm_decode_width } from "../isa/ParticleVMISA.js";
-import { PARTICLE_PASS_DEAD_CODE, pass_eliminate_dead_code } from "./pass_eliminate_dead_code.js";
-import {
-    PARTICLE_PASS_DEDUP_CONSTANTS,
-    pass_dedup_constants,
-    visit_particle_constant_reads,
-} from "./pass_dedup_constants.js";
-import { PARTICLE_PASS_FOLD_CONSTANTS, pass_fold_constants } from "./pass_fold_constants.js";
-import { PARTICLE_PASS_NARROW_WIDTHS, pass_narrow_widths } from "./pass_narrow_widths.js";
-import { PARTICLE_PASS_PACK_REGISTERS, pass_pack_registers } from "./pass_pack_registers.js";
-import { PARTICLE_PASS_PEEPHOLE, pass_peephole } from "./pass_peephole.js";
-import { PARTICLE_PASS_PROPAGATE_COPIES, pass_propagate_copies } from "./pass_propagate_copies.js";
-import { PARTICLE_PASS_SHARE_SUBEXPRESSIONS, pass_share_subexpressions } from "./pass_share_subexpressions.js";
-
-/**
- * Binary-level optimizer for particle VM programs: instructions in, instructions out.
- *
- * It runs over a compiled {@link InstructionStream} rather than inside any one frontend, because
- * there is more than one frontend — the node-graph compiler, the assembly text pane in the editor,
- * and whatever comes next — and the same waste appears in all of them. The node compiler lowers a
- * value at a time and has no way to know that the broadcast it just emitted will be read one lane
- * wide; a pass over the finished stream can simply look.
- *
- * ## Shape
- *
- * Passes are ordinary functions from an instruction array to a new one, with `null` for "changed
- * nothing". They never reorder: every pass rewrites an instruction in place or drops it, which is
- * what makes the ordering constraints — `RANDOM`'s draw sequence, `STORE_ATTR`/`LOAD_ATTR`
- * aliasing — hold structurally rather than by each pass remembering them.
- *
- * The pipeline sweeps the enabled passes in order until a whole sweep changes nothing or
- * `max_iterations` sweeps have run, then packs the register file once. Passes that pay to repeat on
- * their own take their own `max_iterations`, so effort is the caller's to spend.
- *
- * ## What must not change
- *
- * A program's meaning is the record it leaves, the kill flag it sets, and the RNG state it ends on.
- * Every pass here preserves all three to the bit, with one deliberate exception: folding `x * 0` to
- * `+0` gives up the sign of that zero, and gives up `NaN` where something upstream overflowed. It is
- * on by default — see the argument in `pass_fold_constants.js` — and
- * `{ passes: { fold_constants: { fold_multiply_by_zero: false } } }` takes the optimizer back to
- * bit-identical. `optimize_particle_program.spec.js` and the differential harness beside it hold
- * both settings to their respective promises, over the real distribution compositions, the
- * hand-written spec programs and randomly generated ones.
- */
-
-/**
- * @callback ParticleOptimizerPass
- * @param {number[][]} instructions five-word tuples, in program order
- * @param {ParticleOptimizerContext} context
- * @returns {number[][]|null} the rewritten stream, or `null` when the pass changed nothing
- */
-
-/**
- * @typedef {object} ParticleOptimizerContext
- * @property {ArrayLike<number>} constants the shared constant pool, one float per word
- * @property {((values: number[]) => number)|null} intern_constant interns a run of constants and
- *   returns its first word index — {@link ../isa/ParticleAssembler.js}'s `constant`. Without it a
- *   pass can read the pool but not add to it, which only costs it the folds that need a new literal.
- * @property {number} register_slots size of the register file
- * @property {number} max_iterations how many times this pass may repeat itself
- */
-
-/**
- * The passes, in the order a sweep runs them. `final` passes run once, after the sweeps settle.
- *
- * @type {Array<{name: string, run: ParticleOptimizerPass, max_iterations: number, final?: boolean}>}
- */
-export const PARTICLE_OPTIMIZER_PASSES = [
-    { name: PARTICLE_PASS_DEAD_CODE, run: pass_eliminate_dead_code, max_iterations: 1 },
-    { name: PARTICLE_PASS_NARROW_WIDTHS, run: pass_narrow_widths, max_iterations: 1 },
-    { name: PARTICLE_PASS_FOLD_CONSTANTS, run: pass_fold_constants, max_iterations: 1 },
-    // Before sharing, and after the folds that intern new literals: two loads of one value are the
-    // same subexpression only once they name the same pool word.
-    { name: PARTICLE_PASS_DEDUP_CONSTANTS, run: pass_dedup_constants, max_iterations: 1 },
-    { name: PARTICLE_PASS_SHARE_SUBEXPRESSIONS, run: pass_share_subexpressions, max_iterations: 1 },
-    { name: PARTICLE_PASS_PROPAGATE_COPIES, run: pass_propagate_copies, max_iterations: 3 },
-    { name: PARTICLE_PASS_PEEPHOLE, run: pass_peephole, max_iterations: 1 },
-    { name: PARTICLE_PASS_PACK_REGISTERS, run: pass_pack_registers, max_iterations: 1, final: true },
-];
-
-/**
- * Passes enabled unless the caller says otherwise. The switches are for bisecting and for measuring
- * what each pass is worth; the two rewrites that change the arithmetic rather than the program are
- * options of their passes rather than passes, so that the list stays a list of what to run and not a
- * list of what to trust. `fold_constants.fold_multiply_by_zero` is on, `peephole.fuse_multiply_add`
- * is off, and both are argued where they live.
- *
- * @type {Readonly<Object<string, boolean>>}
- */
-export const PARTICLE_OPTIMIZER_DEFAULT_PASSES = Object.freeze(
-    Object.fromEntries(PARTICLE_OPTIMIZER_PASSES.map(pass => [pass.name, true]))
-);
-
-/**
- * How many times the whole pass list may sweep before the optimizer gives up on reaching a fixed
- * point. Passes feed each other — folding a `SELECT` makes a broadcast dead, deleting it lets the
- * value above narrow — so one sweep is never enough. Two settle every program in this tree and
- * three settle the worst of a hundred generated ones; the budget is well clear of that, because a
- * program that ran out of sweeps would be a program whose optimization depended on the budget.
- *
- * @type {number}
- */
-export const PARTICLE_OPTIMIZER_DEFAULT_ITERATIONS = 8;
-
-/**
- * Optimize one section of a particle program.
- *
- * @param {InstructionStream} stream
- * @param {object} [options]
- * @param {ArrayLike<number>} [options.constants] the shared constant pool; without it the passes
- *   that reason about literal values do nothing
- * @param {function(number[]): number} [options.intern_constant] adds a run to that pool
- * @param {Object<string, boolean|object>} [options.passes] per-pass switches, overriding
- *   {@link PARTICLE_OPTIMIZER_DEFAULT_PASSES}; an object value also carries that pass's options
- * @param {number} [options.max_iterations] sweeps of the whole pass list
- * @param {boolean} [options.speculate] whether to try lane peeling both ways and keep the better
- *   program; on unless told otherwise. Off makes the pipeline a straight run of its passes, which is
- *   what a caller measuring one pass in isolation wants.
- * @param {number} [options.register_slots]
- * @returns {InstructionStream} a fresh stream, whose `register_count` is re-derived from what the
- *   optimized instructions actually touch
- */
-export function optimize_particle_program(stream, options = {}) {
-    assert.ok(stream instanceof InstructionStream, "stream must be an InstructionStream");
-
-    const register_slots = options.register_slots ?? PARTICLE_VM_REGISTER_SLOTS;
-    const max_iterations = options.max_iterations ?? PARTICLE_OPTIMIZER_DEFAULT_ITERATIONS;
-
-    assert.isNonNegativeInteger(max_iterations, "max_iterations");
-
-    /** @type {number[][]} */
-    const instructions = stream.instructions.map(words => words.slice());
-
-    const base_context = {
-        constants: options.constants ?? [],
-        intern_constant: options.intern_constant ?? null,
-        register_slots,
-    };
-
-    const speculative = to_stream(run_pipeline(instructions, base_context, options, max_iterations));
-
-    if (options.speculate === false || !peeling_could_apply(options)) {
-        return speculative;
-    }
-
-    // Peeling a constant tail off an instruction always costs one instruction where it fires, and
-    // pays only through what dies above it — a mask's load, the broadcast feeding it, the arithmetic
-    // that built them. Whether that cascade happens is not a local question, and a heuristic for it
-    // would be wrong on somebody's effect. So the pipeline is run both ways and the better program
-    // kept; these are at most a few hundred instructions and settling one twice costs nothing worth
-    // measuring.
-    const conservative = to_stream(
-        run_pipeline(instructions, base_context, without_peeling(options), max_iterations)
-    );
-
-    return better_of(conservative, speculative);
-}
-
-/**
- * Sweep the enabled passes to a fixed point, then run the closing ones once.
- *
- * @param {number[][]} instructions
- * @param {object} base_context
- * @param {object} options
- * @param {number} max_iterations
- * @returns {number[][]}
- */
-function run_pipeline(instructions, base_context, options, max_iterations) {
-    const sweep = PARTICLE_OPTIMIZER_PASSES.filter(pass => pass.final !== true);
-    const closing = PARTICLE_OPTIMIZER_PASSES.filter(pass => pass.final === true);
-
-    let current = instructions;
-
-    for (let iteration = 0; iteration < max_iterations; iteration++) {
-        let changed = false;
-
-        for (const pass of sweep) {
-            const result = run_pass(pass, current, base_context, options);
-
-            if (result !== null) {
-                current = result;
-                changed = true;
-            }
-        }
-
-        if (!changed) {
-            break;
-        }
-    }
-
-    for (const pass of closing) {
-        const result = run_pass(pass, current, base_context, options);
-
-        if (result !== null) {
-            current = result;
-        }
-    }
-
-    return current;
-}
-
-/**
- * Fewer instructions wins; a tie goes to the smaller register file, and a tie there to the
- * speculative one, whose instructions are the narrower of the two.
- *
- * @param {InstructionStream} conservative
- * @param {InstructionStream} speculative
- * @returns {InstructionStream}
- */
-function better_of(conservative, speculative) {
-    if (conservative.instruction_count !== speculative.instruction_count) {
-        return conservative.instruction_count < speculative.instruction_count ? conservative : speculative;
-    }
-
-    return conservative.register_count < speculative.register_count ? conservative : speculative;
-}
-
-/** @returns {boolean} whether the run just made could have peeled anything */
-function peeling_could_apply(options) {
-    const setting = options.passes?.[PARTICLE_PASS_FOLD_CONSTANTS];
-
-    if (setting === false) {
-        return false;
-    }
-
-    return !(typeof setting === "object" && setting !== null && setting.peel_constant_lanes === false);
-}
-
-/** @returns {object} the same options with lane peeling turned off */
-function without_peeling(options) {
-    const setting = options.passes?.[PARTICLE_PASS_FOLD_CONSTANTS];
-    const fold = typeof setting === "object" && setting !== null ? setting : {};
-
-    return {
-        ...options,
-        passes: {
-            ...options.passes,
-            [PARTICLE_PASS_FOLD_CONSTANTS]: { ...fold, peel_constant_lanes: false },
-        },
-    };
-}
-
-/**
- * @param {{name: string, run: ParticleOptimizerPass, max_iterations: number}} pass
- * @param {number[][]} instructions
- * @param {object} base_context
- * @param {object} options
- * @returns {number[][]|null}
- */
-function run_pass(pass, instructions, base_context, options) {
-    const setting = options.passes?.[pass.name];
-
-    if (setting === false) {
-        return null;
-    }
-
-    const overrides = typeof setting === "object" && setting !== null ? setting : {};
-
-    return pass.run(instructions, {
-        ...base_context,
-        max_iterations: pass.max_iterations,
-        ...overrides,
-    });
-}
-
-/**
- * A `passes` setting enabling only the named passes.
- *
- * The plain object form is additive — anything it does not mention keeps its default — which is what
- * a caller turning one pass off wants and the opposite of what a caller measuring one pass wants.
- *
- * @param {...string} names
- * @returns {Object<string, boolean>}
- */
-export function only_particle_passes(...names) {
-    const switches = {};
-
-    for (const pass of PARTICLE_OPTIMIZER_PASSES) {
-        switches[pass.name] = names.includes(pass.name);
-    }
-
-    return switches;
-}
-
-/**
- * Optimize both sections of a compiled program against their shared constant pool.
- *
- * The pool is shared and may grow — a folded expression needs somewhere to put its literal — so it
- * is interned through a {@link ParticleAssembler}, which is the code that already knows how to reuse
- * a run that is anywhere in the pool rather than only one on a boundary.
- *
- * @param {ParticleProgram} program
- * @param {object} [options] as {@link optimize_particle_program}, minus the pool it supplies itself
- * @returns {ParticleProgram}
- */
-export function optimize_compiled_particle_program(program, options = {}) {
-    const assembler = new ParticleAssembler();
-
-    assembler.constants = Array.from(program.constants);
-
-    const shared = {
-        ...options,
-        constants: assembler.constants,
-        intern_constant: (values) => assembler.constant(...values),
-    };
-
-    const init = optimize_particle_program(stream_from_words(program.init), shared);
-    const update = optimize_particle_program(stream_from_words(program.update), shared);
-
-    const init_words = init.toWords();
-    const update_words = update.toWords();
-
-    // Last, and here rather than in a pass: which pool words are dead is a question about the whole
-    // program, and a pass sees one section. Running it before the sections settled would be wrong
-    // twice over — the folds are still interning, and the speculation below has not yet thrown away
-    // the run whose literals are the dead ones.
-    const constants = sweep_particle_constants(
-        [init_words, update_words],
-        assembler.constants,
-        sweeping_is_enabled(options)
-    );
-
-    return new ParticleProgram({
-        init: init_words,
-        update: update_words,
-        constants,
-        register_count: Math.max(init.register_count, update.register_count),
-    });
-}
-
-/**
- * Whether the caller left the constant-pool passes on. See the note in
- * {@link ./pass_dedup_constants.js} on why the compaction follows the rewrite's switch.
- *
- * @param {object} options
- * @returns {boolean}
- */
-function sweeping_is_enabled(options) {
-    const setting = options.passes?.[PARTICLE_PASS_DEDUP_CONSTANTS];
-
-    if (setting === false) {
-        return false;
-    }
-
-    return !(typeof setting === "object" && setting !== null && setting.sweep === false);
-}
-
-/**
- * Drop the pool words no section loads any more, and move the loads onto what is left.
- *
- * Marking is per word rather than per run, and that is what makes compaction safe for runs that
- * overlap — a scalar sharing the leading word of a `vec4` is something the assembler deliberately
- * produces. Every word of a live run is marked, and compaction keeps marked words in order, so a run
- * whose words were consecutive still is; only its base moves.
- *
- * @param {Uint32Array[]} sections instruction words, rewritten in place
- * @param {ArrayLike<number>} constants the shared pool
- * @param {boolean} enabled
- * @returns {Float32Array} the pool the sections now address
- */
-function sweep_particle_constants(sections, constants, enabled) {
-    if (!enabled) {
-        return new Float32Array(constants);
-    }
-
-    const live = new Uint8Array(constants.length);
-
-    let well_formed = true;
-
-    for (const words of sections) {
-        visit_particle_constant_reads(instruction_tuples(words), (index, base, span) => {
-            if (base < 0 || base + span > constants.length) {
-                // Out of the pool already. Compacting under it would turn a program that fails
-                // validation into one that fails it somewhere else, so nothing is touched.
-                well_formed = false;
-                return;
-            }
-
-            for (let i = 0; i < span; i++) {
-                live[base + i] = 1;
-            }
-        });
-    }
-
-    if (!well_formed) {
-        return new Float32Array(constants);
-    }
-
-    /** @type {number[]} */
-    const kept = [];
-
-    /** @type {Int32Array} old word index -> new one; only meaningful where `live` */
-    const remap = new Int32Array(constants.length);
-
-    for (let i = 0; i < constants.length; i++) {
-        remap[i] = kept.length;
-
-        if (live[i] === 1) {
-            kept.push(constants[i]);
-        }
-    }
-
-    if (kept.length !== constants.length) {
-        for (const words of sections) {
-            for (let base = 0; base < words.length; base += PARTICLE_VM_INSTRUCTION_WORDS) {
-                if (vm_decode_op(words[base]) !== VM_OP.LOAD_CONST) {
-                    continue;
-                }
-
-                words[base + 2] = remap[words[base + 2]];
-            }
-        }
-    }
-
-    return new Float32Array(kept);
-}
-
-/**
- * A packed section as the five-word tuples the pass helpers read.
- *
- * @param {Uint32Array} words
- * @returns {Uint32Array[]} views, so nothing is copied
- */
-function instruction_tuples(words) {
-    const out = [];
-
-    for (let base = 0; base < words.length; base += PARTICLE_VM_INSTRUCTION_WORDS) {
-        out.push(words.subarray(base, base + PARTICLE_VM_INSTRUCTION_WORDS));
-    }
-
-    return out;
-}
-
-/**
- * @param {Uint32Array} words a packed instruction section
- * @returns {InstructionStream}
- */
-export function stream_from_words(words) {
-    const out = new InstructionStream();
-
-    for (let base = 0; base < words.length; base += PARTICLE_VM_INSTRUCTION_WORDS) {
-        out.emit(
-            vm_decode_op(words[base]),
-            words[base + 1],
-            words[base + 2],
-            words[base + 3],
-            words[base + 4],
-            vm_decode_width(words[base])
-        );
-    }
-
-    return out;
-}
-
-/**
- * Re-emit into a fresh stream, so the register high-water mark is the optimized program's rather
- * than the one it was built from. A file that shrank is itself part of the win — it is the
- * interpreter's dominant register cost (see the occupancy note in `vm/chunk_particle_vm.js`) — and
- * carrying the old count forward would hide it.
- *
- * @param {number[][]} instructions
- * @returns {InstructionStream}
- */
-function to_stream(instructions) {
-    const out = new InstructionStream();
-
-    for (const words of instructions) {
-        out.emit(vm_decode_op(words[0]), words[1], words[2], words[3], words[4], vm_decode_width(words[0]));
-    }
-
-    return out;
-}
+import { assert } from "../../../../core/assert.js";
+import { PARTICLE_VM_INSTRUCTION_WORDS, PARTICLE_VM_REGISTER_SLOTS } from "../ParticleConstants.js";
+import { InstructionStream } from "../isa/InstructionStream.js";
+import { ParticleAssembler } from "../isa/ParticleAssembler.js";
+import { ParticleProgram } from "../isa/ParticleProgram.js";
+import { VM_OP, vm_decode_op } from "../isa/ParticleVMISA.js";
+import { PARTICLE_PASS_ALLOCATE_REGISTERS, pass_allocate_registers } from "./pass_allocate_registers.js";
+import { PARTICLE_PASS_DEAD_CODE, pass_eliminate_dead_code } from "./pass_eliminate_dead_code.js";
+import {
+    PARTICLE_PASS_DEDUP_CONSTANTS,
+    pass_dedup_constants,
+    visit_particle_constant_reads,
+} from "./pass_dedup_constants.js";
+import { PARTICLE_PASS_FOLD_CONSTANTS, pass_fold_constants } from "./pass_fold_constants.js";
+import { PARTICLE_PASS_INLINE_CONSTANTS, pass_inline_constants } from "./pass_inline_constants.js";
+import { PARTICLE_PASS_NARROW_WIDTHS, pass_narrow_widths } from "./pass_narrow_widths.js";
+import { PARTICLE_PASS_PACK_REGISTERS, pass_pack_registers } from "./pass_pack_registers.js";
+import { PARTICLE_PASS_PEEPHOLE, pass_peephole } from "./pass_peephole.js";
+import { PARTICLE_PASS_PROPAGATE_COPIES, pass_propagate_copies } from "./pass_propagate_copies.js";
+import { PARTICLE_PASS_SHARE_SUBEXPRESSIONS, pass_share_subexpressions } from "./pass_share_subexpressions.js";
+import { PARTICLE_PASS_SCHEDULE, pass_schedule } from "./pass_schedule.js";
+
+/**
+ * Binary-level optimizer for particle VM programs: a {@link ParticleProgram} in, one out.
+ *
+ * {@link optimize_particle_program} is the entry point and its options are FLAT — the passes to run
+ * as a list of names, and every rewrite a caller might want to name as an option of its own. Which
+ * pass implements a rewrite is this file's business and not the caller's, so
+ * `{ fold_multiply_by_zero: false }` asks for exact arithmetic without naming the pass that would
+ * otherwise round. {@link ./dag/optimize_particle_program_vector.js the graph optimizer} has the
+ * same shape, so a caller can hold both and choose between them.
+ *
+ * It runs over a compiled {@link InstructionStream} rather than inside any one frontend, because
+ * there is more than one frontend — the node-graph compiler, the assembly text pane in the editor,
+ * and whatever comes next — and the same waste appears in all of them. The node compiler lowers a
+ * value at a time and has no way to know that the broadcast it just emitted will be read one lane
+ * wide; a pass over the finished stream can simply look.
+ *
+ * ## Shape
+ *
+ * Passes are ordinary functions from an instruction array to a new one, with `null` for "changed
+ * nothing". All but one never reorder: every pass rewrites an instruction in place or drops it,
+ * which is what makes the ordering constraints — `RANDOM`'s draw sequence, `STORE_ATTR`/`LOAD_ATTR`
+ * aliasing — hold structurally rather than by each pass remembering them. The one that does,
+ * `pass_schedule`, moves nothing across an instruction with side effects, which keeps the same
+ * constraints structural for it.
+ *
+ * The pipeline sweeps the enabled passes in order until a whole sweep changes nothing or
+ * `max_iterations` sweeps have run, then schedules, allocates and packs the register file — and
+ * sweeps again if that changed anything, since a reordered program is one the passes have not seen.
+ * Passes that pay to repeat on their own take their own `max_iterations`, so effort is the
+ * caller's to spend.
+ *
+ * ## What must not change
+ *
+ * A program's meaning is the record it leaves, the kill flag it sets, and the RNG state it ends on.
+ * Every pass here preserves all three to the bit, with one deliberate exception: folding `x * 0` to
+ * `+0` gives up the sign of that zero, and gives up `NaN` where something upstream overflowed. That
+ * substitution is made in a register, so what it does to the record is whatever the instructions
+ * below it do with a zero — which is not bounded, and is why the harness holds the fold to the
+ * record words a multiply can REACH rather than to a shape. It is on by default — see the argument
+ * in `pass_fold_constants.js` — and `{ fold_multiply_by_zero: false }`
+ * takes the optimizer back to bit-identical. `optimize_particle_program.spec.js` and the
+ * differential harness beside it hold both settings to their respective promises, over the real
+ * distribution compositions, the hand-written spec programs and randomly generated ones.
+ *
+ * Two further rewrites change the arithmetic and are off unless a caller names them:
+ * `fuse_multiply_add`, which is a rounding the reference can see, and `fold_inexact`, which is a
+ * rounding only a GPU can see — the fast-math fold of the transcendentals and `rsqrt`. Each is
+ * argued where it lives.
+ */
+
+/**
+ * @callback ParticleOptimizerPass
+ * @param {number[][]} instructions five-word tuples, in program order
+ * @param {ParticleOptimizerContext} context
+ * @returns {number[][]|null} the rewritten stream, or `null` when the pass changed nothing
+ */
+
+/**
+ * @typedef {object} ParticleOptimizerContext
+ * @property {ArrayLike<number>} constants the shared constant pool, one float per word
+ * @property {((values: number[]) => number)|null} intern_constant interns a run of constants and
+ *   returns its first word index — {@link ../isa/ParticleAssembler.js}'s `constant`. Without it a
+ *   pass can read the pool but not add to it, which only costs it the folds that need a new literal.
+ * @property {number} register_slots size of the register file
+ * @property {number} max_iterations how many times this pass may repeat itself
+ */
+
+/**
+ * The passes, in the order a sweep runs them. `final` passes run once, after the sweeps settle.
+ * A pass marked `enabled: false` runs only when a caller switches it on by name.
+ *
+ * @type {Array<{name: string, run: ParticleOptimizerPass, max_iterations: number, final?: boolean, enabled?: boolean}>}
+ */
+export const PARTICLE_OPTIMIZER_PASSES = [
+    { name: PARTICLE_PASS_DEAD_CODE, run: pass_eliminate_dead_code, max_iterations: 1 },
+    { name: PARTICLE_PASS_NARROW_WIDTHS, run: pass_narrow_widths, max_iterations: 1 },
+    { name: PARTICLE_PASS_FOLD_CONSTANTS, run: pass_fold_constants, max_iterations: 1 },
+    // Before sharing, and after the folds that intern new literals: two loads of one value are the
+    // same subexpression only once they name the same pool word.
+    { name: PARTICLE_PASS_DEDUP_CONSTANTS, run: pass_dedup_constants, max_iterations: 1 },
+    { name: PARTICLE_PASS_SHARE_SUBEXPRESSIONS, run: pass_share_subexpressions, max_iterations: 1 },
+    { name: PARTICLE_PASS_PROPAGATE_COPIES, run: pass_propagate_copies, max_iterations: 3 },
+    { name: PARTICLE_PASS_PEEPHOLE, run: pass_peephole, max_iterations: 1 },
+    // Last in the sweep: every pass above reasons about constants as loads into registers, and
+    // once a constant is an operand of its consumer there is nothing left for them to see. This is
+    // where the literal kind pays — a third of the simulate pass on a constant-heavy effect, see
+    // ../vm/chunk_particle_vm.js — so it is on like the rest.
+    { name: PARTICLE_PASS_INLINE_CONSTANTS, run: pass_inline_constants, max_iterations: 1 },
+    // Once the instructions have settled, their order: a value that lives no longer than it must
+    // is a slot the allocator below can give back.
+    { name: PARTICLE_PASS_SCHEDULE, run: pass_schedule, max_iterations: 1, final: true },
+    // Allocation packs after every placement itself, so packing on its own is what runs when the
+    // allocator is switched off — and a no-op after it.
+    { name: PARTICLE_PASS_ALLOCATE_REGISTERS, run: pass_allocate_registers, max_iterations: 1, final: true },
+    { name: PARTICLE_PASS_PACK_REGISTERS, run: pass_pack_registers, max_iterations: 1, final: true },
+];
+
+/**
+ * The passes that run unless the caller names a different set. For bisecting, and for measuring what
+ * each pass is worth; the rewrites that change the ARITHMETIC rather than the program are flat
+ * options instead of passes, so that this stays a list of what to run and not a list of what to
+ * trust. `fold_multiply_by_zero` is on, `fuse_multiply_add` and `fold_inexact` are off, and each is
+ * argued where it lives.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const PARTICLE_OPTIMIZER_DEFAULT_PASSES = Object.freeze(
+    PARTICLE_OPTIMIZER_PASSES.filter(pass => pass.enabled !== false).map(pass => pass.name)
+);
+
+/**
+ * How many times the whole pass list may sweep before the optimizer gives up on reaching a fixed
+ * point. Passes feed each other — folding a `SELECT` makes a broadcast dead, deleting it lets the
+ * value above narrow — so one sweep is never enough. Two settle every program in this tree and
+ * three settle the worst of a hundred generated ones; the budget is well clear of that, because a
+ * program that ran out of sweeps would be a program whose optimization depended on the budget.
+ *
+ * @type {number}
+ */
+export const PARTICLE_OPTIMIZER_DEFAULT_ITERATIONS = 8;
+
+/**
+ * Optimize one section of a particle program.
+ *
+ * The options are flat, and the ones that are not about the pipeline itself are handed to every pass
+ * — each takes the ones it knows and ignores the rest, which is why a rewrite like
+ * `fold_multiply_by_zero` is named here rather than buried under the pass that happens to implement
+ * it. A caller asking for exact arithmetic should not have to know which pass would otherwise round.
+ *
+ * @param {InstructionStream} stream
+ * @param {object} [options]
+ * @param {ArrayLike<number>} [options.constants] the shared constant pool; without it the passes
+ *   that reason about literal values do nothing
+ * @param {function(number[]): number} [options.intern_constant] adds a run to that pool
+ * @param {ReadonlyArray<string>} [options.passes] the passes to run, defaulting to
+ *   {@link PARTICLE_OPTIMIZER_DEFAULT_PASSES}; see {@link particle_passes_except}
+ * @param {number} [options.max_iterations] sweeps of the whole pass list
+ * @param {boolean} [options.speculate] whether to try lane peeling both ways and keep the better
+ *   program; on unless told otherwise. Off makes the pipeline a straight run of its passes, which is
+ *   what a caller measuring one pass in isolation wants.
+ * @param {number} [options.register_slots]
+ * @param {boolean} [options.fold_multiply_by_zero] a known zero absorbs a multiply
+ * @param {boolean} [options.fold_inexact] fold what the two executors may round apart
+ * @param {boolean} [options.peel_constant_lanes] split a lane whose value is known off its
+ *   instruction
+ * @param {number} [options.max_select_moves] how many copies folding a `SELECT` may cost
+ * @param {boolean} [options.fuse_multiply_add] fuse where the rounding may differ
+ * @param {boolean} [options.fuse_exact_multiply_add] fuse where it cannot
+ * @param {boolean} [options.merge_constant_loads] join adjacent pool loads into one run
+ * @param {boolean} [options.merge_moves] join adjacent copies into one
+ * @returns {InstructionStream} a fresh stream, whose `register_count` is re-derived from what the
+ *   optimized instructions actually touch
+ */
+export function optimize_particle_section(stream, {
+    constants = [],
+    intern_constant = null,
+    register_slots = PARTICLE_VM_REGISTER_SLOTS,
+    passes = PARTICLE_OPTIMIZER_DEFAULT_PASSES,
+    max_iterations = PARTICLE_OPTIMIZER_DEFAULT_ITERATIONS,
+    speculate = true,
+    ...settings
+} = {}) {
+    assert.ok(stream instanceof InstructionStream, "stream must be an InstructionStream");
+    assert.isNonNegativeInteger(max_iterations, "max_iterations");
+
+    /** @type {number[][]} */
+    const instructions = stream.instructions.map(words => words.slice());
+    const enabled = new Set(passes);
+    const base_context = { ...settings, constants, intern_constant, register_slots };
+
+    const speculative = to_stream(run_pipeline(instructions, base_context, enabled, max_iterations));
+
+    if (speculate === false || !enabled.has(PARTICLE_PASS_FOLD_CONSTANTS) || settings.peel_constant_lanes === false) {
+        return speculative;
+    }
+
+    // Peeling a constant tail off an instruction always costs one instruction where it fires, and
+    // pays only through what dies above it — a mask's load, the broadcast feeding it, the arithmetic
+    // that built them. Whether that cascade happens is not a local question, and a heuristic for it
+    // would be wrong on somebody's effect. So the pipeline is run both ways and the better program
+    // kept; these are at most a few hundred instructions and settling one twice costs nothing worth
+    // measuring.
+    const conservative = to_stream(
+        run_pipeline(instructions, { ...base_context, peel_constant_lanes: false }, enabled, max_iterations)
+    );
+
+    return better_of(conservative, speculative);
+}
+
+/**
+ * Sweep the enabled passes to a fixed point, then the closing ones to theirs — and round again
+ * while the closing passes keep finding something.
+ *
+ * The two halves feed each other. A schedule frees slots the allocator then reuses, and an
+ * allocated file constrains the next schedule; and a program in a new order is a program the sweep
+ * passes have not seen — a copy whose original is now intact until the read, two loads that are now
+ * adjacent. Each closing acceptance shrinks the file or its peak, so the rounds are bounded by the
+ * file's size, and a program that comes back unchanged from a round is one a second run of the
+ * optimizer would also leave alone.
+ *
+ * @param {number[][]} instructions
+ * @param {object} base_context
+ * @param {Set<string>} enabled
+ * @param {number} max_iterations sweeps of the pass list per round
+ * @returns {number[][]}
+ */
+function run_pipeline(instructions, base_context, enabled, max_iterations) {
+    const running = PARTICLE_OPTIMIZER_PASSES.filter(pass => enabled.has(pass.name));
+    const sweep = running.filter(pass => pass.final !== true);
+    const closing = running.filter(pass => pass.final === true);
+
+    let current = instructions;
+
+    for (let round = 0; round < 2 * base_context.register_slots; round++) {
+        current = run_to_fixed_point(sweep, current, base_context, max_iterations);
+
+        const closed = run_to_fixed_point(closing, current, base_context, 2 * base_context.register_slots);
+
+        if (closed === current) {
+            break;
+        }
+
+        current = closed;
+    }
+
+    return current;
+}
+
+/**
+ * @param {Array<{name: string, run: ParticleOptimizerPass, max_iterations: number}>} passes
+ * @param {number[][]} instructions
+ * @param {object} base_context
+ * @param {number} max_iterations
+ * @returns {number[][]} the settled stream — `instructions` itself when nothing changed
+ */
+function run_to_fixed_point(passes, instructions, base_context, max_iterations) {
+    let current = instructions;
+
+    for (let iteration = 0; iteration < max_iterations; iteration++) {
+        let changed = false;
+
+        for (const pass of passes) {
+            const result = pass.run(current, { ...base_context, max_iterations: pass.max_iterations });
+
+            if (result !== null) {
+                current = result;
+                changed = true;
+            }
+        }
+
+        if (!changed) {
+            break;
+        }
+    }
+
+    return current;
+}
+
+/**
+ * Fewer instructions wins; a tie goes to the smaller register file, and a tie there to the
+ * speculative one, whose instructions are the narrower of the two.
+ *
+ * @param {InstructionStream} conservative
+ * @param {InstructionStream} speculative
+ * @returns {InstructionStream}
+ */
+function better_of(conservative, speculative) {
+    if (conservative.instruction_count !== speculative.instruction_count) {
+        return conservative.instruction_count < speculative.instruction_count ? conservative : speculative;
+    }
+
+    return conservative.register_count < speculative.register_count ? conservative : speculative;
+}
+
+/**
+ * The default passes with these ones left out — what a caller turning ONE pass off wants, without
+ * having to write down the ten it is keeping.
+ *
+ * @param {...string} names
+ * @returns {string[]}
+ */
+export function particle_passes_except(...names) {
+    return PARTICLE_OPTIMIZER_DEFAULT_PASSES.filter(name => !names.includes(name));
+}
+
+/**
+ * Optimize a compiled program: `ParticleProgram` in, `ParticleProgram` out.
+ *
+ * The entry point, and the same shape
+ * {@link ./dag/optimize_particle_program_vector.js the graph optimizer} has — one program in, one
+ * out, flat options — so that a caller can hold both and choose.
+ *
+ * Both sections are optimized against one constant pool, which is shared and may grow: a folded
+ * expression needs somewhere to put its literal. It is interned through a
+ * {@link ParticleAssembler}, which is the code that already knows how to reuse a run anywhere in the
+ * pool rather than only one on a boundary.
+ *
+ * @param {ParticleProgram} program
+ * @param {object} [options] as {@link optimize_particle_section}, minus the pool it supplies itself
+ * @returns {ParticleProgram}
+ */
+export function optimize_particle_program(program, options = {}) {
+    assert.ok(program instanceof ParticleProgram, "program must be a ParticleProgram");
+
+    const assembler = new ParticleAssembler();
+
+    assembler.constants = Array.from(program.constants);
+
+    const shared = {
+        ...options,
+        constants: assembler.constants,
+        intern_constant: (values) => assembler.constant(...values),
+    };
+
+    const init = optimize_particle_section(stream_from_words(program.init), shared);
+    const update = optimize_particle_section(stream_from_words(program.update), shared);
+
+    const init_words = init.toWords();
+    const update_words = update.toWords();
+
+    // Last, and here rather than in a pass: which pool words are dead is a question about the whole
+    // program, and a pass sees one section. Running it before the sections settled would be wrong
+    // twice over — the folds are still interning, and the speculation below has not yet thrown away
+    // the run whose literals are the dead ones.
+    const constants = sweep_particle_constants(
+        [init_words, update_words],
+        assembler.constants,
+        (options.passes ?? PARTICLE_OPTIMIZER_DEFAULT_PASSES).includes(PARTICLE_PASS_DEDUP_CONSTANTS)
+            && options.sweep !== false
+    );
+
+    return new ParticleProgram({
+        init: init_words,
+        update: update_words,
+        constants,
+        register_count: Math.max(init.register_count, update.register_count),
+    });
+}
+
+/**
+ * Drop the pool words no section loads any more, and move the loads onto what is left.
+ *
+ * Marking is per word rather than per run, and that is what makes compaction safe for runs that
+ * overlap — a scalar sharing the leading word of a `vec4` is something the assembler deliberately
+ * produces. Every word of a live run is marked, and compaction keeps marked words in order, so a run
+ * whose words were consecutive still is; only its base moves.
+ *
+ * @param {Uint32Array[]} sections instruction words, rewritten in place
+ * @param {ArrayLike<number>} constants the shared pool
+ * @param {boolean} enabled
+ * @returns {Float32Array} the pool the sections now address
+ */
+function sweep_particle_constants(sections, constants, enabled) {
+    if (!enabled) {
+        return new Float32Array(constants);
+    }
+
+    const live = new Uint8Array(constants.length);
+
+    let well_formed = true;
+
+    for (const words of sections) {
+        visit_particle_constant_reads(instruction_tuples(words), (index, base, span) => {
+            if (base < 0 || base + span > constants.length) {
+                // Out of the pool already. Compacting under it would turn a program that fails
+                // validation into one that fails it somewhere else, so nothing is touched.
+                well_formed = false;
+                return;
+            }
+
+            for (let i = 0; i < span; i++) {
+                live[base + i] = 1;
+            }
+        });
+    }
+
+    if (!well_formed) {
+        return new Float32Array(constants);
+    }
+
+    /** @type {number[]} */
+    const kept = [];
+
+    /** @type {Int32Array} old word index -> new one; only meaningful where `live` */
+    const remap = new Int32Array(constants.length);
+
+    for (let i = 0; i < constants.length; i++) {
+        remap[i] = kept.length;
+
+        if (live[i] === 1) {
+            kept.push(constants[i]);
+        }
+    }
+
+    if (kept.length !== constants.length) {
+        for (const words of sections) {
+            for (let base = 0; base < words.length; base += PARTICLE_VM_INSTRUCTION_WORDS) {
+                if (vm_decode_op(words[base]) === VM_OP.LOAD_CONST) {
+                    words[base + 1] = remap[words[base + 1]];
+                }
+            }
+        }
+    }
+
+    return new Float32Array(kept);
+}
+
+/**
+ * A packed section as the four-word tuples the pass helpers read.
+ *
+ * @param {Uint32Array} words
+ * @returns {Uint32Array[]} views, so nothing is copied
+ */
+function instruction_tuples(words) {
+    const out = [];
+
+    for (let base = 0; base < words.length; base += PARTICLE_VM_INSTRUCTION_WORDS) {
+        out.push(words.subarray(base, base + PARTICLE_VM_INSTRUCTION_WORDS));
+    }
+
+    return out;
+}
+
+/**
+ * @param {Uint32Array} words a packed instruction section
+ * @returns {InstructionStream}
+ */
+export function stream_from_words(words) {
+    const out = new InstructionStream();
+
+    for (let base = 0; base < words.length; base += PARTICLE_VM_INSTRUCTION_WORDS) {
+        out.emitWords(words.subarray(base, base + PARTICLE_VM_INSTRUCTION_WORDS));
+    }
+
+    return out;
+}
+
+/**
+ * Re-emit into a fresh stream, so the register high-water mark is the optimized program's rather
+ * than the one it was built from. A file that shrank is itself part of the win — it is the
+ * interpreter's dominant register cost (see the occupancy note in `vm/chunk_particle_vm.js`) — and
+ * carrying the old count forward would hide it.
+ *
+ * @param {number[][]} instructions
+ * @returns {InstructionStream}
+ */
+function to_stream(instructions) {
+    const out = new InstructionStream();
+
+    for (const words of instructions) {
+        out.emitWords(words);
+    }
+
+    return out;
+}