@woosh/meep-engine 3.69.0 → 3.70.0

package/src/shade/renderer/fluid/GPUFluidCascade.js

@@ -16,6 +16,7 @@ import { FluidMacPasses } from "./mac/FluidMacPasses.js";
 import { FluidMacVelocitySet } from "./mac/FluidMacVelocitySet.js";
 import { GPUFluidPressureSolve } from "./pressure/GPUFluidPressureSolve.js";
 import { FLUID_FORCING_BRICK_CELLS } from "./forcing/FLUID_FORCING.js";
+import { fluid_far_field_place, fluid_far_field_value, fluid_far_record, fluid_far_record_copy, fluid_far_record_read } from "./FLUID_FAR_FIELD_STRUCT.js";
 
 /**
  * @typedef {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
@@ -83,27 +84,22 @@ export function gpu_fluid_cascade_frame_keep(from, to) {
 }
 
 /**
- * The far field's velocity and `Λ` from a {@link FluidAtmosphere} record, checking that it carries
- * no body force: `force` is a CPU-field term and not part of the far field (§6), so the GPU fluid
- * drops it, and says so in development.
+ * The far field and `Λ` from a {@link FluidAtmosphere} record, checking that it carries no body
+ * force: `force` is a CPU-field term and not part of the far field (§6), so the GPU fluid drops it,
+ * and says so in development.
  *
  * @param {Float64Array|number[]} atmosphere
  * @param {number} offset
- * @param {Float32Array} out_far_velocity receives `v_far`, rounded to f32
+ * @param {{mean: Float32Array, sigma: number, offset: Float64Array, length: number}} out_far receives
+ *   the far field (`fluid_far_record`), its mean rounded to f32
  * @returns {number} `Λ`
  */
-function read_far_field(atmosphere, offset, out_far_velocity) {
+function read_far_field(atmosphere, offset, out_far) {
     assert.equal(atmosphere[offset + FluidAtmosphere.FORCE_X], 0, 'a body force reaches the GPU fluid, which drops it');
     assert.equal(atmosphere[offset + FluidAtmosphere.FORCE_Y], 0, 'a body force reaches the GPU fluid, which drops it');
     assert.equal(atmosphere[offset + FluidAtmosphere.FORCE_Z], 0, 'a body force reaches the GPU fluid, which drops it');
 
-    out_far_velocity[0] = atmosphere[offset + FluidAtmosphere.VELOCITY_X];
-    out_far_velocity[1] = atmosphere[offset + FluidAtmosphere.VELOCITY_Y];
-    out_far_velocity[2] = atmosphere[offset + FluidAtmosphere.VELOCITY_Z];
-
-    for (let axis = 0; axis < 3; axis++) {
-        assert.isFinite(out_far_velocity[axis], 'v_far');
-    }
+    fluid_far_record_read(out_far, atmosphere, offset);
 
     const lambda = atmosphere[offset + FluidAtmosphere.LAMBDA];
 
@@ -146,8 +142,8 @@ function restrict_value() {
         keep: 1,
         box_size: new Uint32Array(3),
         child_offset: new Int32Array(3),
-        child_far_velocity: new Float32Array(3),
-        far_velocity: new Float32Array(3),
+        child_far: fluid_far_field_value(),
+        far: fluid_far_field_value(),
     };
 }
 
@@ -168,11 +164,13 @@ function restrict_value() {
  *   `FLUID_FORCED_FLAG` where the tick's forcing was written for the cell's faces. A step reads these
  *   unless it is handed another buffer. `GPUFluidForcing` writes them before each step of the
  *   cascade, with {@link solid_bricks} saying which bricks it last wrote;
- * - **its read record**: the instant its velocity was last brought to, `t_s`, with `v_far(t_s)`
- *   ({@link read_far_velocity}, rounded to f32 as the device holds it) and `Λ(t_s)`
- *   ({@link read_lambda}), on the CPU. The velocity is a deviation from `v_far(t_s)`, so every read of
- *   it at an instant `t` is `v_far(t) + (v − v_far(t_s))·e^(−(Λ(t) − Λ(t_s)))` (§6); {@link update_read}
- *   computes that factor, {@link read_keep}, on the CPU, and the device never sees `Λ`.
+ * - **its read record**: the instant its velocity was last brought to, `t_s`, with `v_far(t_s)` —
+ *   its mean ({@link read_far_velocity}, rounded to f32 as the device holds it) and its turbulence's
+ *   `σ`, offset and length scale — and `Λ(t_s)` ({@link read_lambda}), on the CPU. The velocity is a
+ *   deviation from `v_far(t_s)`, so every read of it at an instant `t` at a point `x` is
+ *   `v_far(t, x) + (v − v_far(t_s, x))·e^(−(Λ(t) − Λ(t_s)))` (§6); {@link update_read} computes that
+ *   factor, {@link read_keep}, on the CPU, and the device never sees `Λ`. Each pass lays the far field
+ *   over its own lattice (`FLUID_FAR_FIELD_STRUCT`), so the device never sees the offset either.
  *
  * It is created at the far field of a {@link FluidAtmosphere} record: velocity `v_far`, pressure 0,
  * the read record that instant.
@@ -285,13 +283,23 @@ export class GPUFluidCascade {
     /** The read record: `t_s` and `Λ(t_s)`, f64. */
     #read_time = 0;
     #read_lambda = 0;
-    /** `v_far(t_s)`, as the device holds it. */
-    #read_far_velocity = new Float32Array(3);
+    /** `v_far(t_s)`: its mean as the device holds it, its turbulence. */
+    #read_far = fluid_far_record();
     /** `e^(−(Λ(t) − Λ(t_s)))` at the last {@link update_read}. */
     #read_keep = 1;
 
     /** Scratch for an atmosphere's `v_far`. */
-    #far_scratch = new Float32Array(3);
+    #far_scratch = fluid_far_record();
+
+    /**
+     * The turbulence tile a pass binds when it is handed none: one texel, never read, since a far field
+     * with turbulence asserts a tile.
+     * @type {GPUTexture}
+     */
+    #no_turbulence;
+
+    /** @type {GPUTextureView} */
+    #no_turbulence_view;
 
     /** The window as the published field reads it, rewritten on every query. */
     #cells_window = fluid_cascade_window_value();
@@ -311,7 +319,7 @@ export class GPUFluidCascade {
     #advected = { u: null, v: null, w: null };
 
     /** What the step's passes bind of the parent, rebound for every step. */
-    #parent_bindings = { uniform: null, u: null, v: null, w: null, pressure: null };
+    #parent_bindings = { uniform: null, u: null, v: null, w: null, pressure: null, turbulence: null };
 
     /** The step's ghosts' views and buffer, rebound for every step. */
     #ghosts = { u: null, v: null, w: null, pressure: null };
@@ -374,7 +382,7 @@ export class GPUFluidCascade {
         this.#corner.set(corner);
         this.#cell_size = cell_size;
 
-        this.#read_lambda = read_far_field(atmosphere, atmosphere_offset, this.#read_far_velocity);
+        this.#read_lambda = read_far_field(atmosphere, atmosphere_offset, this.#read_far);
         this.#read_time = atmosphere[atmosphere_offset + FluidAtmosphere.TIME];
 
         const [nx, ny, nz] = this.#resolution;
@@ -428,11 +436,22 @@ export class GPUFluidCascade {
             usage: GPUBufferUsage.STORAGE,
         });
 
-        // a new texture is 0, so only a component the far field moves is written
+        this.#no_turbulence = device.createTexture({
+            label: 'Fluid / cascade / no turbulence',
+            size: [1, 1, 1],
+            dimension: '3d',
+            format: 'rgba16float',
+            usage: GPUTextureUsage.TEXTURE_BINDING,
+        });
+
+        this.#no_turbulence_view = this.#no_turbulence.createView();
+
+        // a new texture is 0, so only a component the far field moves is written; with turbulence the
+        // eddies come in through the fills and the atmosphere, as everything else of the fluid warms up
         const textures = this.#velocity.textures;
 
         for (let component = 0; component < 3; component++) {
-            const value = this.#read_far_velocity[component];
+            const value = this.#read_far.mean[component];
 
             if (value === 0) {
                 continue;
@@ -567,7 +586,41 @@ export class GPUFluidCascade {
      * @returns {Readonly<Float32Array>}
      */
     get read_far_velocity() {
-        return this.#read_far_velocity;
+        return this.#read_far.mean;
+    }
+
+    /**
+     * `v_far(t_s)` laid over this cascade's window as a {@link FLUID_FAR_FIELD_STRUCT} value: cell
+     * coordinate 0 at window-local cell 0. What its publish subtracts.
+     *
+     * @param {{mean: Float32Array, sigma: number, origin: Float32Array, scale: Float32Array}} out
+     * @returns {{mean: Float32Array, sigma: number, origin: Float32Array, scale: Float32Array}} `out`
+     */
+    describe_far(out) {
+        const far = this.#read_far;
+        const corner = this.#corner;
+
+        fluid_far_field_place(out, far, far.offset, far.length, corner[0], corner[1], corner[2], this.#cell_size, this.#cell_size);
+
+        return out;
+    }
+
+    /**
+     * The turbulence tile a pass binds: `turbulence`, or this cascade's stand-in when it is `null`, which
+     * only a far field with no turbulence may take.
+     *
+     * @param {GPUTextureView|null} turbulence
+     * @param {number} sigma the larger `σ` the pass reads
+     * @returns {GPUTextureView}
+     */
+    #turbulence_view(turbulence, sigma) {
+        if (turbulence !== null) {
+            return turbulence;
+        }
+
+        assert.equal(sigma, 0, 'a far field with turbulence is handed the turbulence tile');
+
+        return this.#no_turbulence_view;
     }
 
     /**
@@ -651,16 +704,23 @@ export class GPUFluidCascade {
      * @param {GPUFluidCascade|null} parent a cascade of twice the cell and the same resolution, or `null`
      */
     describe_parent(out, out_bindings, parent) {
-        out.read_far_velocity.set(this.#read_far_velocity);
+        const read = this.#read_far;
+        const h = this.#cell_size;
 
         if (parent === null) {
-            out.origin.fill(0);
+            // no window to address: the origin only places the far field, at this window's corner,
+            // which keeps the positions a read takes small
+            out.origin.set(this.#corner);
             out.keep = 1;
             fluid_cascade_window_empty(out.cells);
             fluid_cascade_window_empty(out.faces_u);
             fluid_cascade_window_empty(out.faces_v);
             fluid_cascade_window_empty(out.faces_w);
-            out.far_velocity.set(this.#read_far_velocity);
+
+            const o = out.origin;
+
+            fluid_far_field_place(out.read, read, read.offset, read.length, o[0], o[1], o[2], h, h);
+            fluid_far_field_place(out.far, read, read.offset, read.length, o[0], o[1], o[2], h, h);
 
             out_bindings.u = this.#far_field_views[0];
             out_bindings.v = this.#far_field_views[1];
@@ -687,7 +747,13 @@ export class GPUFluidCascade {
         fluid_cascade_window_place(out.faces_u, parent.#corner, parent.#resolution, 0);
         fluid_cascade_window_place(out.faces_v, parent.#corner, parent.#resolution, 1);
         fluid_cascade_window_place(out.faces_w, parent.#corner, parent.#resolution, 2);
-        out.far_velocity.set(parent.#read_far_velocity);
+
+        const o = out.origin;
+        const far = parent.#read_far;
+
+        // the read is this cascade's far field; the parent's state deviates from the parent's, at its level
+        fluid_far_field_place(out.read, read, read.offset, read.length, o[0], o[1], o[2], h, h);
+        fluid_far_field_place(out.far, far, far.offset, far.length, o[0], o[1], o[2], h, parent.#cell_size);
 
         const velocity = parent.#velocity;
         out_bindings.u = velocity.u;
@@ -719,6 +785,8 @@ export class GPUFluidCascade {
      * @param {GPUFluidCascadePressureArm} [options.arm]
      * @param {number} [options.count] V-cycles under {@link GPUFluidCascadePressureArm.VCycles}, red-black
      *   sweeps under {@link GPUFluidCascadePressureArm.SOR}
+     * @param {GPUTextureView|null} [options.turbulence] the far field's turbulence tile
+     *   (`GPUSceneWind#turbulence`); `null`, the default, only for a far field with none
      */
     record_step({
                     graph,
@@ -732,6 +800,7 @@ export class GPUFluidCascade {
                     vorticity_confinement = 0,
                     arm = GPUFluidCascadePressureArm.VCycles,
                     count = GPU_FLUID_CASCADE_V_CYCLES,
+                    turbulence = null,
                 }) {
         assert.notOk(this.#destroyed, 'the cascade is destroyed');
         assert.defined(graph, 'graph');
@@ -748,8 +817,8 @@ export class GPUFluidCascade {
         assert.ok(arm ===GPUFluidCascadePressureArm.VCycles || arm === GPUFluidCascadePressureArm.SOR, 'arm');
         assert.isNonNegativeInteger(count, 'count');
 
-        const far_end = this.#far_scratch;
-        const lambda_end = read_far_field(atmosphere, atmosphere_offset, far_end);
+        const end = this.#far_scratch;
+        const lambda_end = read_far_field(atmosphere, atmosphere_offset, end);
         const time_end = atmosphere[atmosphere_offset + FluidAtmosphere.TIME];
 
         assert.greaterThanOrEqual(time_end, this.#read_time, 'the step ends at or after the read record');
@@ -763,8 +832,9 @@ export class GPUFluidCascade {
             cascade: this,
             dt: 0,
             corner: new Int32Array(3),
-            far_start: new Float32Array(3),
-            far_end: new Float32Array(3),
+            far_start: fluid_far_field_value(),
+            far_end: fluid_far_field_value(),
+            turbulence: null,
             keep: 1,
             band: false,
             parent: fluid_cascade_parent_value(),
@@ -784,8 +854,17 @@ export class GPUFluidCascade {
 
         record.dt = dt;
         record.corner.set(this.#corner);
-        record.far_start.set(this.#read_far_velocity);
-        record.far_end.set(far_end);
+
+        // the start's mean and σ where the end's offset puts the eddies: what the far field alone
+        // brings to each face by the step's end
+        const start = this.#read_far;
+        const corner = this.#corner;
+        const length = end.sigma !== 0 ? end.length : start.length;
+
+        fluid_far_field_place(record.far_start, start, end.offset, length, corner[0], corner[1], corner[2], this.#cell_size, this.#cell_size);
+        fluid_far_field_place(record.far_end, end, end.offset, length, corner[0], corner[1], corner[2], this.#cell_size, this.#cell_size);
+
+        record.turbulence = this.#turbulence_view(turbulence, Math.max(start.sigma, end.sigma));
         record.keep = Math.exp(Math.min(0, this.#read_lambda - lambda_end));
         record.band = relaxation_band;
         record.solid = solid;
@@ -798,7 +877,7 @@ export class GPUFluidCascade {
         // the step brings the velocity to t₁
         this.#read_time = time_end;
         this.#read_lambda = lambda_end;
-        this.#read_far_velocity.set(far_end);
+        fluid_far_record_copy(this.#read_far, end);
 
         const pass = graph.add('Fluid / cascade step', record, GPUFluidCascade.#execute);
 
@@ -840,8 +919,10 @@ export class GPUFluidCascade {
      *   one inside the window and on the 4-cell lattice
      * @param {number} options.box_count 0 to 3
      * @param {GPUFluidCascade|null} options.parent the parent to fill from, or `null` for the far field
+     * @param {GPUTextureView|null} [options.turbulence] the far field's turbulence tile; `null`, the
+     *   default, only for a far field with none
      */
-    record_fill({ graph, boxes, box_count, parent }) {
+    record_fill({ graph, boxes, box_count, parent, turbulence = null }) {
         assert.notOk(this.#destroyed, 'the cascade is destroyed');
         assert.defined(graph, 'graph');
         assert.isNonNegativeInteger(box_count, 'box_count');
@@ -857,6 +938,7 @@ export class GPUFluidCascade {
             fill: fill_value(),
             parent: fluid_cascade_parent_value(),
             parent_bindings: { u: null, v: null, w: null, pressure: null },
+            turbulence: null,
             group_count_x: 1,
             group_count_y: 1,
         };
@@ -915,6 +997,8 @@ export class GPUFluidCascade {
 
         this.describe_parent(record.parent, record.parent_bindings, parent);
 
+        record.turbulence = this.#turbulence_view(turbulence, Math.max(record.parent.read.sigma, record.parent.far.sigma));
+
         graph.add('Fluid / cascade fill', record, GPUFluidCascade.#execute_fill).make_side_effect();
     }
 
@@ -930,8 +1014,10 @@ export class GPUFluidCascade {
      * @param {object} options
      * @param {FrameGraph} options.graph
      * @param {GPUFluidCascade} options.child a cascade of half the cell and the same resolution
+     * @param {GPUTextureView|null} [options.turbulence] the far field's turbulence tile; `null`, the
+     *   default, only for a far field with none
      */
-    record_restrict({ graph, child }) {
+    record_restrict({ graph, child, turbulence = null }) {
         assert.notOk(this.#destroyed, 'the cascade is destroyed');
         assert.defined(graph, 'graph');
         assert.ok(child instanceof GPUFluidCascade, 'child is a cascade');
@@ -942,6 +1028,7 @@ export class GPUFluidCascade {
             cascade: this,
             child: null,
             value: restrict_value(),
+            turbulence: null,
             group_count_x: 1,
             group_count_y: 1,
             group_count_z: 1,
@@ -978,10 +1065,18 @@ export class GPUFluidCascade {
         fluid_cascade_window_place(value.faces_v, this.#corner, resolution, 1);
         fluid_cascade_window_place(value.faces_w, this.#corner, resolution, 2);
 
-        value.child_far_velocity.set(child.#read_far_velocity);
-        value.far_velocity.set(this.#read_far_velocity);
+        // both far fields over this cascade's cells: the parent faces the restriction writes
+        const corner = this.#corner;
+        const h = this.#cell_size;
+        const child_far = child.#read_far;
+        const far = this.#read_far;
+
+        fluid_far_field_place(value.child_far, child_far, child_far.offset, child_far.length, corner[0], corner[1], corner[2], h, child.#cell_size);
+        fluid_far_field_place(value.far, far, far.offset, far.length, corner[0], corner[1], corner[2], h, h);
         value.keep = gpu_fluid_cascade_frame_keep(child.#read_lambda, this.#read_lambda);
 
+        record.turbulence = this.#turbulence_view(turbulence, Math.max(child_far.sigma, far.sigma));
+
         record.child = child;
         record.group_count_x = Math.ceil(value.box_size[0] / GRID_TILE_SIZE[0]);
         record.group_count_y = Math.ceil(value.box_size[1] / GRID_TILE_SIZE[1]);
@@ -991,7 +1086,7 @@ export class GPUFluidCascade {
     }
 
     /** The restriction's bindings, rebound for every restriction. */
-    #restrict_bindings = { restriction: null, child_u: null, child_v: null, child_w: null, out_u: null, out_v: null, out_w: null };
+    #restrict_bindings = { restriction: null, child_u: null, child_v: null, child_w: null, out_u: null, out_v: null, out_w: null, fluid_turbulence: null };
 
     #restrict_dispatch = { encoder: null, bindings: null, group_count_x: 1, group_count_y: 1, group_count_z: 1 };
 
@@ -1009,6 +1104,7 @@ export class GPUFluidCascade {
             }
         } finally {
             record.child = null;
+            record.turbulence = null;
             cascade.#free_restrictions.push(record);
         }
     }
@@ -1028,6 +1124,7 @@ export class GPUFluidCascade {
         b.out_u = this.#velocity.u;
         b.out_v = this.#velocity.v;
         b.out_w = this.#velocity.w;
+        b.fluid_turbulence = record.turbulence;
 
         const dispatch = this.#restrict_dispatch;
         dispatch.encoder = encoder;
@@ -1040,13 +1137,13 @@ export class GPUFluidCascade {
 
         dispatch.encoder = null;
         dispatch.bindings = null;
-        b.restriction = b.child_u = b.child_v = b.child_w = null;
+        b.restriction = b.child_u = b.child_v = b.child_w = b.fluid_turbulence = null;
     }
 
     /** The fill's bindings, rebound for every fill. */
     #fill_bindings = {
         fill: null, parent: null, parent_u: null, parent_v: null, parent_w: null, parent_pressure: null,
-        velocity_u: null, velocity_v: null, velocity_w: null, pressure: null,
+        velocity_u: null, velocity_v: null, velocity_w: null, pressure: null, fluid_turbulence: null,
     };
 
     #fill_dispatch = { encoder: null, bindings: null, group_count_x: 1, group_count_y: 1, group_count_z: 1 };
@@ -1066,6 +1163,7 @@ export class GPUFluidCascade {
         } finally {
             record.parent_bindings.u = record.parent_bindings.v = record.parent_bindings.w = null;
             record.parent_bindings.pressure = null;
+            record.turbulence = null;
             cascade.#free_fills.push(record);
         }
     }
@@ -1087,6 +1185,7 @@ export class GPUFluidCascade {
         b.velocity_v = this.#velocity.v;
         b.velocity_w = this.#velocity.w;
         b.pressure = this.#pressure;
+        b.fluid_turbulence = record.turbulence;
 
         const dispatch = this.#fill_dispatch;
         dispatch.encoder = encoder;
@@ -1098,7 +1197,7 @@ export class GPUFluidCascade {
 
         dispatch.encoder = null;
         dispatch.bindings = null;
-        b.fill = b.parent = b.parent_u = b.parent_v = b.parent_w = b.parent_pressure = null;
+        b.fill = b.parent = b.parent_u = b.parent_v = b.parent_w = b.parent_pressure = b.fluid_turbulence = null;
     }
 
     /**
@@ -1116,6 +1215,7 @@ export class GPUFluidCascade {
             record.forcing = null;
             record.parent_bindings.u = record.parent_bindings.v = record.parent_bindings.w = null;
             record.parent_bindings.pressure = null;
+            record.turbulence = null;
             cascade.#free_records.push(record);
         }
     }
@@ -1165,6 +1265,7 @@ export class GPUFluidCascade {
         parent.v = record.parent_bindings.v;
         parent.w = record.parent_bindings.w;
         parent.pressure = record.parent_bindings.pressure;
+        parent.turbulence = record.turbulence;
 
         mac.record_ghosts(encoder, parent, ghosts);
 
@@ -1200,7 +1301,7 @@ export class GPUFluidCascade {
 
         mac.record_gradient(encoder, advected, this.#pressure, solid, velocity, ghosts);
 
-        parent.uniform = parent.u = parent.v = parent.w = parent.pressure = null;
+        parent.uniform = parent.u = parent.v = parent.w = parent.pressure = parent.turbulence = null;
         ghosts.u = ghosts.v = ghosts.w = ghosts.pressure = null;
         forward.u = forward.v = forward.w = null;
         advected.u = advected.v = advected.w = null;
@@ -1225,6 +1326,7 @@ export class GPUFluidCascade {
         this.#no_forcing.destroy();
         this.#no_confinement.destroy();
         this.#far_field_pressure.destroy();
+        this.#no_turbulence.destroy();
 
         for (const texture of this.#far_field_faces) {
             texture.destroy();

package/src/shade/renderer/fluid/GPUFluidCascadeStack.d.ts

@@ -48,7 +48,9 @@ export const GPU_FLUID_CASCADE_STACK_LIMIT: number;
  * `read_keep` (`k`). All retained: nothing is allocated to read them.
  *
  * Created placed around `anchor` and filled from the far field of `atmosphere` (velocity `v_far`,
- * pressure 0); after that nothing is allocated per tick.
+ * pressure 0): its mean at creation, and with turbulence, at the first tick that has any, every
+ * cascade's whole window filled from its parent, coarsest first, so the coarsest takes the far field's
+ * eddies exactly and every finer one its parent's. After that nothing is allocated per tick.
  */
 export class GPUFluidCascadeStack {
     /**
@@ -148,8 +150,11 @@ export class GPUFluidCascadeStack {
      * @param {number} [options.vorticity_confinement] its strength ε, per second, ≥ 0, for both of the
      *   tick's steps, each with its own cell and step (`GPUFluidCascade#record_step`); 0, the default,
      *   records no curl pass
+     * @param {GPUTextureView|null} [options.turbulence] the far field's turbulence tile
+     *   (`GPUSceneWind#turbulence`), which every pass that reads the far field binds; `null`, the default,
+     *   only for a far field with none
      */
-    record_tick({ graph, tick, dt, anchor, atmosphere, atmosphere_offset, forcing, vorticity_confinement }: {
+    record_tick({ graph, tick, dt, anchor, atmosphere, atmosphere_offset, forcing, vorticity_confinement, turbulence }: {
         graph: FrameGraph;
         tick: number;
         dt: number;
@@ -158,6 +163,7 @@ export class GPUFluidCascadeStack {
         atmosphere_offset: number;
         forcing?: GPUFluidForcing | null;
         vorticity_confinement?: number;
+        turbulence?: GPUTextureView | null;
     }): void;
     /**
      * Record the frame's publish into `graph`, after its last tick (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md
@@ -167,7 +173,8 @@ export class GPUFluidCascadeStack {
      *     wind.set_cascades(count, resolution)
      *     wind.set_cascade_window(c, corner, cell_size)       every cascade
      *     wind.set_cascade_decay(c, k)                        k = e^(−(Λ(t) − Λ(t_s,c))), read_keep
-     *     wind.set_far_velocity(v_far(t))
+     *     wind.set_far_velocity(u(t))                         the far field's mean
+     *     wind.set_turbulence(σ, offset, L)                   its turbulence
      *
      * A tile holds `v − v_far(t_s,c)` and `k` is taken for `t`, so a cascade that did not step reads
      * from its old tile through its new decay. A cascade that is published takes the field's

package/src/shade/renderer/fluid/GPUFluidCascadeStack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUFluidCascadeStack.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/fluid/GPUFluidCascadeStack.js"],"names":[],"mappings":"AASA;;;;GAIG;AAEH;;;GAGG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IACI;;;;;OAKG;IACH,iCAFW,OAAO,0CAA0C,EAAE,eAAe,QAK5E;IAgWD;;;;OAIG;IACH,uCAJW,MAAM,4BAEN;QAAC,OAAO,EAAE,OAAO,wCAAwC,EAAE,sBAAsB,CAAA;KAAC,QAkC5F;IArVD;;;;;;;;;;OAUG;IACH;QAT8B,MAAM;QACE,UAAU,EAArC,UAAU,MAAM,CAAC;QAED,SAAS,EAAzB,MAAM;QACU,aAAa,EAA7B,MAAM;QACqB,MAAM,EAAjC,UAAU,MAAM,CAAC;QACc,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QACL,iBAAiB,EAAjC,MAAM;OAwChB;IA/DD;;;;OAIG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;;OAIG;IACH,UAFU,OAAO,CAED;IAqDhB,wBAAwB;IACxB,4BAEC;IAED;;;OAGG;IACH,uCAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;;OAIG;IACH,WAHW,MAAM,GACJ,eAAe,CAI3B;IAED;;;;;OAKG;IACH,qBAFW,YAAY,GAAC,MAAM,EAAE,QAY/B;IAED;;;;;;OAMG;IACH,wBAHW,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,QAMhB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAd+B,KAAK,EAAzB,UAAU;QACM,IAAI,EAApB,MAAM;QAEU,EAAE,EAAlB,MAAM;QACqB,MAAM,EAAjC,UAAU,MAAM,CAAC;QACc,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QAEL,iBAAiB,EAAjC,MAAM;QACyB,OAAO,GAAtC,eAAe,GAAC,IAAI;QAEH,qBAAqB,GAAtC,MAAM;aA8FhB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACY,IAAI,EAA1B,YAAY;QACmB,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QAEL,iBAAiB,EAAjC,MAAM;aAyDhB;IA4CD;;OAEG;IACH,gBAUC;;CACJ;yBApdY,OAAO,2DAA2D,EAAE,UAAU;2BAC9E,OAAO,yBAAyB,EAAE,YAAY;8BAC9C,OAAO,8BAA8B,EAAE,eAAe;gCARnC,sBAAsB"}
+{"version":3,"file":"GPUFluidCascadeStack.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/fluid/GPUFluidCascadeStack.js"],"names":[],"mappings":"AAUA;;;;GAIG;AAEH;;;GAGG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IACI;;;;;OAKG;IACH,iCAFW,OAAO,0CAA0C,EAAE,eAAe,QAK5E;IAuZD;;;;OAIG;IACH,uCAJW,MAAM,4BAEN;QAAC,OAAO,EAAE,OAAO,wCAAwC,EAAE,sBAAsB,CAAA;KAAC,QAmC5F;IAvYD;;;;;;;;;;OAUG;IACH;QAT8B,MAAM;QACE,UAAU,EAArC,UAAU,MAAM,CAAC;QAED,SAAS,EAAzB,MAAM;QACU,aAAa,EAA7B,MAAM;QACqB,MAAM,EAAjC,UAAU,MAAM,CAAC;QACc,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QACL,iBAAiB,EAAjC,MAAM;OAwChB;IA/DD;;;;OAIG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;;OAIG;IACH,UAFU,OAAO,CAED;IAqDhB,wBAAwB;IACxB,4BAEC;IAED;;;OAGG;IACH,uCAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;;OAIG;IACH,WAHW,MAAM,GACJ,eAAe,CAI3B;IAED;;;;;OAKG;IACH,qBAFW,YAAY,GAAC,MAAM,EAAE,QAY/B;IAED;;;;;;OAMG;IACH,wBAHW,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,QAMhB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH;QAjB+B,KAAK,EAAzB,UAAU;QACM,IAAI,EAApB,MAAM;QAEU,EAAE,EAAlB,MAAM;QACqB,MAAM,EAAjC,UAAU,MAAM,CAAC;QACc,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QAEL,iBAAiB,EAAjC,MAAM;QACyB,OAAO,GAAtC,eAAe,GAAC,IAAI;QAEH,qBAAqB,GAAtC,MAAM;QAGwB,UAAU,GAAxC,iBAAe,IAAI;aAoH7B;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACY,IAAI,EAA1B,YAAY;QACmB,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QAEL,iBAAiB,EAAjC,MAAM;aA8DhB;IA+DD;;OAEG;IACH,gBAUC;;CACJ;yBA9gBY,OAAO,2DAA2D,EAAE,UAAU;2BAC9E,OAAO,yBAAyB,EAAE,YAAY;8BAC9C,OAAO,8BAA8B,EAAE,eAAe;gCATnC,sBAAsB"}