@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -18,6 +18,33 @@ export function run_particle_section({ words, constants, register_count, environ
     killed: boolean;
     rng_state: number;
 };
+/**
+ * Which record words — and whether the kill flag — the result of a zero-absorbing opcode can reach.
+ *
+ * This is the bound on `fold_constants.fold_multiply_by_zero`, and it is deliberately blunt in the
+ * one direction that keeps it sound: every instruction in
+ * {@link PARTICLE_ZERO_ABSORBING_OPS} is treated as though its result had been substituted, because
+ * which of them had a compile-time zero operand is a fact about the optimizer's analysis and not
+ * about the program. The set comes from the pass rather than being restated here, so an opcode added
+ * to the rewrite is an opcode this follows. Everything the marked slots flow into is marked too, and a
+ * store carries the mark into the record word it writes.
+ *
+ * A `LOAD_ATTR` of a marked record word marks its destination back, so a value that went out through
+ * the record and came back in is still followed. Slots are cleared by a write whose sources are all
+ * unmarked — the value there is then the same in both programs — while record words are only ever
+ * added to, because a store cannot un-write what an earlier one already made unequal.
+ *
+ * Static, so it over-approximates the runs: a lane that never actually held a substituted zero is
+ * marked anyway. That is the right direction to be wrong in, and it is not blunt in practice — see
+ * the 94% in the module comment.
+ *
+ * @param {Uint32Array} words a packed instruction section
+ * @returns {{record: Uint8Array, killed: boolean}}
+ */
+export function particle_multiply_reach(words: Uint32Array): {
+    record: Uint8Array;
+    killed: boolean;
+};
 /**
  * Compare two runs. Record words are compared as raw bits first — which is the strict answer,
  * including the sign of a zero — and only a pair that differs is re-read as floats, so a `NaN` on
@@ -27,9 +54,10 @@ export function run_particle_section({ words, constants, register_count, environ
  * @param {{record: Uint32Array, killed: boolean, rng_state: number}} after
  * @param {object} [comparison]
  * @param {number} [comparison.tolerance] relative slack on record words; zero means the bits match
- * @param {boolean} [comparison.absorbed_zero] accept the two things `x * 0 -> +0` gives up: a `-0`
- *   that became a `+0`, and a `NaN` that became a zero. Nothing else — a number that moved is still
- *   a failure, and a zero that became a `NaN` is a failure in the direction that cannot happen.
+ * @param {{record: Uint8Array, killed: boolean}|null} [comparison.reach] what the zero fold is
+ *   allowed to have changed, from {@link particle_multiply_reach}. A marked word is not compared at
+ *   all — there is no shape left to hold it to, which is the whole of the argument in the module
+ *   comment — and every other one is held to the bit.
  * @returns {string|null} what differs, or `null` when nothing does
  */
 export function diff_particle_section_result(before: {
@@ -40,9 +68,12 @@ export function diff_particle_section_result(before: {
     record: Uint32Array;
     killed: boolean;
     rng_state: number;
-}, { tolerance, absorbed_zero }?: {
+}, { tolerance, reach }?: {
     tolerance?: number;
-    absorbed_zero?: boolean;
+    reach?: {
+        record: Uint8Array;
+        killed: boolean;
+    } | null;
 }): string | null;
 /**
  * Compare an optimized section against the original across every environment.
@@ -54,7 +85,9 @@ export function diff_particle_section_result(before: {
  * @param {{words: Uint32Array, constants: Float32Array|number[], register_count: number}} params.before
  * @param {{words: Uint32Array, constants: Float32Array|number[], register_count: number}} params.after
  * @param {Array<object>} [params.environments]
- * @param {object} [params.comparison] see {@link diff_particle_section_result}
+ * @param {object} [params.comparison] see {@link diff_particle_section_result}, plus
+ *   `reached_by_zero_fold` — the reach is a property of the two SECTIONS rather than of a run, so it
+ *   is worked out once here and handed down as `reach`
  * @returns {string|null} a description of the first divergence, or `null`
  */
 export function diff_particle_sections({ before, after, environments, comparison }: {
@@ -76,7 +109,7 @@ export function diff_particle_sections({ before, after, environments, comparison
  *
  * @param {ParticleProgram} before
  * @param {ParticleProgram} after
- * @param {object} [comparison] see {@link diff_particle_section_result}, plus `environments`
+ * @param {object} [comparison] see {@link diff_particle_sections}, plus `environments`
  * @returns {string|null}
  */
 export function diff_particle_programs(before: ParticleProgram, after: ParticleProgram, comparison?: object): string | null;

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

@@ -1 +1 @@
-{"version":3,"file":"particle_program_equivalence.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/particle_program_equivalence.js"],"names":[],"mappings":"AAiFA;;;;;;;;;GASG;AACH;IAN+B,KAAK,EAAzB,WAAW;IACmB,SAAS,EAAvC,YAAY,GAAC,MAAM,EAAE;IACN,cAAc,EAA7B,MAAM;IACS,WAAW,EAA1B,MAAM;;YACM,WAAW;YAAU,OAAO;eAAa,MAAM;EAgBrE;AAED;;;;;;;;;;;;;GAaG;AACH,qDATW;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,SACzD;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC;IAErC,SAAS,GAA7B,MAAM;IACe,aAAa,GAAlC,OAAO;IAGL,MAAM,GAAC,IAAI,CAqCvB;AAED;;;;;;;;;;;;GAYG;AACH;IANkG,MAAM,EAA7F;QAAC,KAAK,EAAE,WAAW,CAAC;QAAC,SAAS,EAAE,YAAY,GAAC,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAC;IACS,KAAK,EAA5F;QAAC,KAAK,EAAE,WAAW,CAAC;QAAC,SAAS,EAAE,YAAY,GAAC,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAC;IACvD,YAAY,GAAnC,MAAM,MAAM,CAAC;IACG,UAAU,GAA1B,MAAM;IACJ,MAAM,GAAC,IAAI,CAgBvB;AAED;;;;;;;GAOG;AACH,qGAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAmBvB;AAhJD;;;;;GAKG;AACH,oCAFU,MAAM;IAAC,MAAM,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,WAAW,CAAA;CAAC,CAAC,CAOjG"}
+{"version":3,"file":"particle_program_equivalence.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/particle_program_equivalence.js"],"names":[],"mappings":"AA8GA;;;;;;;;;GASG;AACH;IAN+B,KAAK,EAAzB,WAAW;IACmB,SAAS,EAAvC,YAAY,GAAC,MAAM,EAAE;IACN,cAAc,EAA7B,MAAM;IACS,WAAW,EAA1B,MAAM;;YACM,WAAW;YAAU,OAAO;eAAa,MAAM;EAgBrE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,+CAHW,WAAW;YACA,UAAU;YAAU,OAAO;EAkEhD;AAqCD;;;;;;;;;;;;;;GAcG;AACH,qDAVW;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,SACzD;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC;IAErC,SAAS,GAA7B,MAAM;IACkD,KAAK,GAA7D;QAAC,MAAM,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAC,GAAC,IAAI;IAIxC,MAAM,GAAC,IAAI,CAuCvB;AAED;;;;;;;;;;;;;;GAcG;AACH;IARkG,MAAM,EAA7F;QAAC,KAAK,EAAE,WAAW,CAAC;QAAC,SAAS,EAAE,YAAY,GAAC,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAC;IACS,KAAK,EAA5F;QAAC,KAAK,EAAE,WAAW,CAAC;QAAC,SAAS,EAAE,YAAY,GAAC,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAC;IACvD,YAAY,GAAnC,MAAM,MAAM,CAAC;IACG,UAAU,GAA1B,MAAM;IAGJ,MAAM,GAAC,IAAI,CAqBvB;AAED;;;;;;;GAOG;AACH,qGAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAmBvB;AAtRD;;;;;GAKG;AACH,oCAFU,MAAM;IAAC,MAAM,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,WAAW,CAAA;CAAC,CAAC,CAOjG"}