@woosh/meep-engine 3.47.0 → 3.50.0

package/src/shade/renderer/fluid/mac/shader_fluid_mac_divergence.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The right-hand side of the pressure solve over one cascade window
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8, pass 4): `f = div/dt` at every cell, `div` the MAC
+ * divergence over h, and 0 in a solid cell. Pinned faces are read at their value, the wall's
+ * velocity.
+ *
+ * One invocation a cell, in 8 × 8 × 4 workgroups over the window, dispatched `(nx / 8, ny / 8, nz / 4)`.
+ * Each reads its cell's six faces straight from the textures and its solid flag: 6 texels and 1 flag a
+ * cell. Every face a window cell reads lies inside the window.
+ *
+ * Direct reads, not a tile in workgroup memory: an LDS tile with a one-cell halo (3 × 600 texels a
+ * workgroup, 7.0 a cell) measured 2× slower on an RTX 4090 (D3D12, paired, 200 dispatches an arm, the
+ * same RHS bit for bit): 4.1 µs against 2.0 at 64×32×64, 9.2 against 5.1 at 128×32×128 (medians).
+ *
+ * Bindings:
+ * - `step`: {@link FLUID_MAC_STEP_STRUCT};
+ * - `velocity_u`, `velocity_v`, `velocity_w`: the advected velocity, `r32float` 3-D textures,
+ *   window-local; beyond the window the far field;
+ * - `solid`: the window-local solid flags, `array<u32>`, bit 0;
+ * - `rhs`: written, `array<f32>`, window-local, x fastest.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_mac_divergence: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_fluid_mac_divergence.d.ts.map

package/src/shade/renderer/fluid/mac/shader_fluid_mac_divergence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_fluid_mac_divergence.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/mac/shader_fluid_mac_divergence.js"],"names":[],"mappings":"AAgEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,0CAFU,aAAa,CAMpB;8BAxF2B,+BAA+B"}

package/src/shade/renderer/fluid/mac/shader_fluid_mac_divergence.js

@@ -0,0 +1,92 @@
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
+import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.js";
+import { chunk_grid_tile_window, GRID_TILE_SIZE } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_fluid_mac_seam_solid } from "./chunk_fluid_mac_seams.js";
+import { chunk_v3_mac_compute_divergence } from "./chunk_v3_mac_compute_divergence.js";
+import { FLUID_MAC_STEP_STRUCT } from "./FLUID_MAC_STEP_STRUCT.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("step", FLUID_MAC_STEP_STRUCT)
+    .addTexture("velocity_u", "unfilterable-float", "3d")
+    .addTexture("velocity_v", "unfilterable-float", "3d")
+    .addTexture("velocity_w", "unfilterable-float", "3d")
+    .addStorageBuffer("solid", WebGPUArray.from(u32), false)
+    .addStorageBuffer("rhs", WebGPUArray.from(f32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+// the velocity is a transient set, stored window-local; beyond the window, the far field
+fn mac_velocity_u(face: vec3<i32>) -> f32 {
+    if (grid_tile_window_contains(face, step.faces_u.size)) {
+        return textureLoad(velocity_u, vec3<u32>(face), 0).r;
+    }
+
+    return step.far_velocity.x;
+}
+
+fn mac_velocity_v(face: vec3<i32>) -> f32 {
+    if (grid_tile_window_contains(face, step.faces_v.size)) {
+        return textureLoad(velocity_v, vec3<u32>(face), 0).r;
+    }
+
+    return step.far_velocity.y;
+}
+
+fn mac_velocity_w(face: vec3<i32>) -> f32 {
+    if (grid_tile_window_contains(face, step.faces_w.size)) {
+        return textureLoad(velocity_w, vec3<u32>(face), 0).r;
+    }
+
+    return step.far_velocity.z;
+}
+
+@compute @workgroup_size(${GRID_TILE_SIZE.join(', ')})
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    rhs[grid3d_to_index(id, step.cells.size.xy)] = v3_mac_compute_divergence(vec3<i32>(id), step.rhs_scale);
+}
+`, [
+        chunk_grid_tile_window,
+        chunk_grid3d_to_index,
+        chunk_fluid_mac_seam_solid,
+        chunk_v3_mac_compute_divergence,
+    ]
+);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * The right-hand side of the pressure solve over one cascade window
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8, pass 4): `f = div/dt` at every cell, `div` the MAC
+ * divergence over h, and 0 in a solid cell. Pinned faces are read at their value, the wall's
+ * velocity.
+ *
+ * One invocation a cell, in 8 × 8 × 4 workgroups over the window, dispatched `(nx / 8, ny / 8, nz / 4)`.
+ * Each reads its cell's six faces straight from the textures and its solid flag: 6 texels and 1 flag a
+ * cell. Every face a window cell reads lies inside the window.
+ *
+ * Direct reads, not a tile in workgroup memory: an LDS tile with a one-cell halo (3 × 600 texels a
+ * workgroup, 7.0 a cell) measured 2× slower on an RTX 4090 (D3D12, paired, 200 dispatches an arm, the
+ * same RHS bit for bit): 4.1 µs against 2.0 at 64×32×64, 9.2 against 5.1 at 128×32×128 (medians).
+ *
+ * Bindings:
+ * - `step`: {@link FLUID_MAC_STEP_STRUCT};
+ * - `velocity_u`, `velocity_v`, `velocity_w`: the advected velocity, `r32float` 3-D textures,
+ *   window-local; beyond the window the far field;
+ * - `solid`: the window-local solid flags, `array<u32>`, bit 0;
+ * - `rhs`: written, `array<f32>`, window-local, x fastest.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_mac_divergence = ComputeShader.from({
+    label: "Fluid / MAC divergence",
+    body,
+    resources,
+});

package/src/shade/renderer/fluid/mac/shader_fluid_mac_gradient.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The projection's last pass over one cascade window (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8,
+ * pass 6, without the publish): every face of the advected velocity has the pressure gradient taken
+ * from it, `u − (dt/h)·(p_R − p_L)`, a pinned face passes through, and the result is written into
+ * the persistent velocity.
+ *
+ * A tile pass: 8 × 8 × 4 cells a workgroup, dispatched `(nx / 8, ny / 8, nz / 4)`. The workgroup loads
+ * the pressure and the solid flags as f32 tiles with a one-cell halo into workgroup memory
+ * (`chunk_grid_tile_halo_f32`, one barrier; 2 × 2,400 bytes); beyond the window the halo holds the
+ * Dirichlet ghost pressure, the parent's at the ghost cell's centre (`chunk_fluid_pressure_ghost`), and
+ * fluid. Each invocation writes its cell's −x, −y and −z faces, and the
+ * last tile along an axis the window's +boundary face plane, whose outer cells are in the halo.
+ *
+ * Bindings:
+ * - `step`: {@link FLUID_MAC_STEP_STRUCT};
+ * - `ghost_pressure`: the step's pressure ghosts, the parent's pressure one cell past the window;
+ * - `velocity_u`, `velocity_v`, `velocity_w`: the advected velocity, `r32float` 3-D textures,
+ *   window-local;
+ * - `pressure`: kinematic pressure, m²/s², `array<f32>`, toroidal through `step.cells`;
+ * - `solid`: the window-local solid flags, `array<u32>`, bit 0;
+ * - `out_u`, `out_v`, `out_w`: written, the persistent velocity, `r32float` 3-D storage textures,
+ *   toroidal through `step.faces_*`.
+ *
+ * Reads: 2 × 600 halo words a workgroup, 4.7 a cell, where reading each face's two cells' pressure
+ * and flags straight from the buffers would take 12; then 12 workgroup-memory reads and 3 texels a
+ * cell (each face's own).
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_mac_gradient: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_fluid_mac_gradient.d.ts.map

package/src/shade/renderer/fluid/mac/shader_fluid_mac_gradient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_fluid_mac_gradient.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/mac/shader_fluid_mac_gradient.js"],"names":[],"mappings":"AAmJA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wCAFU,aAAa,CAMpB;8BA/K2B,+BAA+B"}

package/src/shade/renderer/fluid/mac/shader_fluid_mac_gradient.js

@@ -0,0 +1,181 @@
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
+import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.js";
+import { chunk_grid_tile_halo_f32 } from "../../shader/chunk/grid/chunk_grid_tile_halo_f32.js";
+import { GRID_TILE_SIZE } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
+import { GRID_TILE_WINDOW_STRUCT } from "../../shader/chunk/grid/GRID_TILE_WINDOW_STRUCT.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_fluid_pressure_ghost } from "../pressure/chunk_fluid_pressure_ghost.js";
+import { chunk_v3_mac_subtract_pressure_gradient } from "./chunk_v3_mac_subtract_pressure_gradient.js";
+import { FLUID_MAC_STEP_STRUCT } from "./FLUID_MAC_STEP_STRUCT.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("step", FLUID_MAC_STEP_STRUCT)
+    .addTexture("velocity_u", "unfilterable-float", "3d")
+    .addTexture("velocity_v", "unfilterable-float", "3d")
+    .addTexture("velocity_w", "unfilterable-float", "3d")
+    .addStorageBuffer("pressure", WebGPUArray.from(f32), false)
+    .addStorageBuffer("ghost_pressure", WebGPUArray.from(f32), false)
+    .addStorageBuffer("solid", WebGPUArray.from(u32), false)
+    .addStorageTexture("out_u", "r32float", "3d", "write-only")
+    .addStorageTexture("out_v", "r32float", "3d", "write-only")
+    .addStorageTexture("out_w", "r32float", "3d", "write-only");
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const FLUID_MAC_TILE_PRESSURE = 0u;
+const FLUID_MAC_TILE_SOLID = 1u;
+
+var<workgroup> fluid_mac_tile_pressure: array<f32, GRID_TILE_HALO_CELLS>;
+// 1.0 where a cell is solid
+var<workgroup> fluid_mac_tile_solid: array<f32, GRID_TILE_HALO_CELLS>;
+
+// the window-local cell of this workgroup's first interior cell
+var<private> fluid_mac_tile_origin: vec3<i32>;
+
+fn grid_tile_f32_fetch_inside(source: u32, storage_cell: vec3<u32>) -> f32 {
+    if (source == FLUID_MAC_TILE_PRESSURE) {
+        return pressure[grid3d_to_index(storage_cell, step.cells.period.xy)];
+    }
+
+    // the solid flags are window-local, and their tile loads through a window that does not wrap
+    return select(0.0, 1.0, (solid[grid3d_to_index(storage_cell, step.cells.size.xy)] & 1u) != 0u);
+}
+
+fn fluid_pressure_ghost_corner() -> vec3<i32> {
+    return step.cells.corner;
+}
+
+fn fluid_pressure_ghost_size() -> vec3<u32> {
+    return step.cells.size;
+}
+
+// beyond the window: pressure is the Dirichlet ghost at the ghost cell's centre, the parent's, and cells are fluid
+fn grid_tile_f32_fetch_outside(source: u32, world_cell: vec3<i32>) -> f32 {
+    if (source == FLUID_MAC_TILE_PRESSURE) {
+        return fluid_pressure_ghost(world_cell);
+    }
+
+    return 0.0;
+}
+
+fn mac_pressure(cell: vec3<i32>) -> f32 {
+    return grid_tile_f32_read(&fluid_mac_tile_pressure, cell - fluid_mac_tile_origin);
+}
+
+fn mac_cell_solid(cell: vec3<i32>) -> bool {
+    return grid_tile_f32_read(&fluid_mac_tile_solid, cell - fluid_mac_tile_origin) != 0.0;
+}
+
+// the advected velocity is a transient set, stored window-local; only faces inside the window are read
+fn mac_velocity_u(face: vec3<i32>) -> f32 {
+    return textureLoad(velocity_u, vec3<u32>(face), 0).r;
+}
+
+fn mac_velocity_v(face: vec3<i32>) -> f32 {
+    return textureLoad(velocity_v, vec3<u32>(face), 0).r;
+}
+
+fn mac_velocity_w(face: vec3<i32>) -> f32 {
+    return textureLoad(velocity_w, vec3<u32>(face), 0).r;
+}
+
+// the projected velocity is the persistent set, stored through its toroidal windows
+fn fluid_mac_gradient_store_u(face: vec3<i32>) {
+    let storage = grid_tile_window_storage(face, step.faces_u.corner_storage, step.faces_u.period);
+    textureStore(out_u, storage, vec4<f32>(v3_mac_subtract_pressure_gradient_u(face, step.dt_over_h), 0.0, 0.0, 0.0));
+}
+
+fn fluid_mac_gradient_store_v(face: vec3<i32>) {
+    let storage = grid_tile_window_storage(face, step.faces_v.corner_storage, step.faces_v.period);
+    textureStore(out_v, storage, vec4<f32>(v3_mac_subtract_pressure_gradient_v(face, step.dt_over_h), 0.0, 0.0, 0.0));
+}
+
+fn fluid_mac_gradient_store_w(face: vec3<i32>) {
+    let storage = grid_tile_window_storage(face, step.faces_w.corner_storage, step.faces_w.period);
+    textureStore(out_w, storage, vec4<f32>(v3_mac_subtract_pressure_gradient_w(face, step.dt_over_h), 0.0, 0.0, 0.0));
+}
+
+@compute @workgroup_size(${GRID_TILE_SIZE.join(', ')})
+fn main(
+    @builtin(workgroup_id) group: vec3<u32>,
+    @builtin(local_invocation_id) local: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    fluid_mac_tile_origin = vec3<i32>(group) * GRID_TILE_SIZE;
+
+    let cells_local = ${GRID_TILE_WINDOW_STRUCT.wgsl_ref}(step.cells.corner, vec3<u32>(0u), step.cells.size, step.cells.size);
+
+    grid_tile_f32_load(&fluid_mac_tile_pressure, step.cells, FLUID_MAC_TILE_PRESSURE, fluid_mac_tile_origin, lane);
+    grid_tile_f32_load(&fluid_mac_tile_solid, cells_local, FLUID_MAC_TILE_SOLID, fluid_mac_tile_origin, lane);
+
+    let cell = fluid_mac_tile_origin + vec3<i32>(local);
+    let last = vec3<i32>(step.cells.size) - vec3<i32>(1);
+
+    // each cell's -x, -y and -z faces
+    fluid_mac_gradient_store_u(cell);
+    fluid_mac_gradient_store_v(cell);
+    fluid_mac_gradient_store_w(cell);
+
+    // the +boundary face planes, owned by the last tile along each axis; their outer cell is in the halo
+    if (cell.x == last.x) {
+        fluid_mac_gradient_store_u(cell + vec3<i32>(1, 0, 0));
+    }
+    if (cell.y == last.y) {
+        fluid_mac_gradient_store_v(cell + vec3<i32>(0, 1, 0));
+    }
+    if (cell.z == last.z) {
+        fluid_mac_gradient_store_w(cell + vec3<i32>(0, 0, 1));
+    }
+}
+`, [
+        GRID_TILE_WINDOW_STRUCT.declaration_chunk,
+        chunk_grid_tile_halo_f32,
+        chunk_grid3d_to_index,
+        chunk_v3_mac_subtract_pressure_gradient,
+        chunk_fluid_pressure_ghost,
+    ]
+);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * The projection's last pass over one cascade window (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8,
+ * pass 6, without the publish): every face of the advected velocity has the pressure gradient taken
+ * from it, `u − (dt/h)·(p_R − p_L)`, a pinned face passes through, and the result is written into
+ * the persistent velocity.
+ *
+ * A tile pass: 8 × 8 × 4 cells a workgroup, dispatched `(nx / 8, ny / 8, nz / 4)`. The workgroup loads
+ * the pressure and the solid flags as f32 tiles with a one-cell halo into workgroup memory
+ * (`chunk_grid_tile_halo_f32`, one barrier; 2 × 2,400 bytes); beyond the window the halo holds the
+ * Dirichlet ghost pressure, the parent's at the ghost cell's centre (`chunk_fluid_pressure_ghost`), and
+ * fluid. Each invocation writes its cell's −x, −y and −z faces, and the
+ * last tile along an axis the window's +boundary face plane, whose outer cells are in the halo.
+ *
+ * Bindings:
+ * - `step`: {@link FLUID_MAC_STEP_STRUCT};
+ * - `ghost_pressure`: the step's pressure ghosts, the parent's pressure one cell past the window;
+ * - `velocity_u`, `velocity_v`, `velocity_w`: the advected velocity, `r32float` 3-D textures,
+ *   window-local;
+ * - `pressure`: kinematic pressure, m²/s², `array<f32>`, toroidal through `step.cells`;
+ * - `solid`: the window-local solid flags, `array<u32>`, bit 0;
+ * - `out_u`, `out_v`, `out_w`: written, the persistent velocity, `r32float` 3-D storage textures,
+ *   toroidal through `step.faces_*`.
+ *
+ * Reads: 2 × 600 halo words a workgroup, 4.7 a cell, where reading each face's two cells' pressure
+ * and flags straight from the buffers would take 12; then 12 workgroup-memory reads and 3 texels a
+ * cell (each face's own).
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_mac_gradient = ComputeShader.from({
+    label: "Fluid / MAC gradient",
+    body,
+    resources,
+});

package/src/shade/renderer/fluid/pressure/FLUID_MG.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The cells of every level, finest first: each halves the one above on every axis, down to the
+ * first level of at most {@link FLUID_MG_COARSEST_CELL_LIMIT} cells.
+ *
+ * @param {number} nx power of two
+ * @param {number} ny power of two
+ * @param {number} nz power of two
+ * @returns {number[][]} `[nx, ny, nz]` a level
+ */
+export function fluid_mg_level_sizes(nx: number, ny: number, nz: number): number[][];
+/**
+ * The weight of a window-edge face on a level, before its open fraction: `2 / (1 + h/H)` with
+ * `H = h·2^level`, which keeps the Dirichlet point at the finest level's ghost-cell centre.
+ * 1 on the finest level.
+ *
+ * @param {number} level
+ * @returns {number}
+ */
+export function fluid_mg_edge_weight(level: number): number;
+/**
+ * The GPU fluid's pressure solve, a geometric-multigrid V-cycle over cell-centred levels
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8). The numbers its kernels, its host and its CPU model
+ * share.
+ *
+ * ## The operator
+ *
+ * Level `l` halves every axis of the level above it, so a cell of it is `H = h·2^l` on a side. Its
+ * operator is the 7-point Laplacian over `H²` with a weight per face:
+ *
+ *     Σ_f w_f·(p_nb − p) / H² = f
+ *
+ * - A face is **open** in the fraction of its area that is open on the finest level, where a face
+ *   is open when the cells on both sides of it are fluid, and the cells beyond the window are.
+ * - A face on the window's edge has the finite-volume weight `2 / (1 + h/H)` times that fraction: the
+ *   Dirichlet point stays at the centre of the finest level's ghost cell on every level. The weight-1
+ *   rule of the CPU solver on every level stalls the V-cycle (0.661 with a global smoother, 0.750 with
+ *   the block smoother, measured).
+ * - A cell whose faces are all closed has no degree of freedom and is never updated: a solid cell,
+ *   or fluid sealed on every side, the CPU's `diag == 0`.
+ *
+ * ## Weight words
+ *
+ * A cell's six faces are packed into one `u32`, {@link FLUID_MG_FACE_BITS} bits a face, face `f` at
+ * bit `f·5`, in the CPU neighbour mask's order: −x, +x, −y, +y, −z, +z. Each field is the face's open
+ * area in sixteenths, so {@link FLUID_MG_FACE_OPEN} is a face open all over. A coarse face is the mean
+ * of its four child faces, rounded up: exact on the first two coarse levels, whose fractions are
+ * quarters and sixteenths, and never closing a face that is open somewhere below.
+ *
+ * ## Storage
+ *
+ * The finest level's pressure is the cascade's persistent toroidal field, addressed through its
+ * window. Everything else is window-local and linear, `x + nx·(y + ny·z)`.
+ */
+/**
+ * Most cells the coarsest level holds: one per invocation of the single workgroup that solves it.
+ * The levels stop at the first one at or below this.
+ * @type {number}
+ */
+export const FLUID_MG_COARSEST_CELL_LIMIT: number;
+/**
+ * Red-black sweeps of the coarsest solve: the fewest that keep the V-cycle's factor on the CPU model.
+ * With three levels or more (every window of 32 to 256 cells an axis, and 16³), 8, 32, 64 and 400
+ * measured the same factor to three digits, open and with obstacles, at 64×32×64, 128×32×128, 32³,
+ * 32×256×32 and 256×32×32; even 2 held there. A two-level window, whose coarsest level carries the
+ * whole coarse correction, sets the count: at 16×8×16, 8 reads 0.178 after 10 cycles against 32's
+ * 0.174, and 4 drifts to 0.345.
+ *
+ * On an RTX 4090 the coarsest pass at 8 sweeps took 7.2 µs against 22.5 at 32 (64×32×64; 8.2 against
+ * 26.6 at 128×32×128), and a cold solve of two V-cycles left the same residual on the device.
+ * @type {number}
+ */
+export const FLUID_MG_COARSEST_SWEEPS: number;
+/**
+ * Smoother sweeps on each leg of a V-cycle, ν: two down and two up.
+ * @type {number}
+ */
+export const FLUID_MG_SMOOTH_SWEEPS: number;
+/**
+ * Most sweeps one smoother dispatch runs: the budget of the loop each invocation runs, every sweep
+ * two passes over its cell with a barrier after each.
+ * @type {number}
+ */
+export const FLUID_MG_SMOOTH_SWEEP_LIMIT: number;
+/**
+ * Bits a face takes in a weight word.
+ * @type {number}
+ */
+export const FLUID_MG_FACE_BITS: number;
+/**
+ * A face's field in a weight word when all of its area is open: fields count sixteenths.
+ * @type {number}
+ */
+export const FLUID_MG_FACE_OPEN: number;
+/**
+ * Which cells a smoother dispatch updates, by colour: red cells have an even `x + y + z`. Both
+ * colours in one dispatch are updated against a halo frozen at its start, which is only stable at
+ * ω = 1; the SOR arm runs one colour a dispatch.
+ */
+export type FluidMGColour = number;
+/**
+ * Which cells a smoother dispatch updates, by colour: red cells have an even `x + y + z`. Both
+ * colours in one dispatch are updated against a halo frozen at its start, which is only stable at
+ * ω = 1; the SOR arm runs one colour a dispatch.
+ * @readonly
+ * @enum {number}
+ */
+export const FluidMGColour: Readonly<{
+    Red: 1;
+    Black: 2;
+    Both: 3;
+}>;
+//# sourceMappingURL=FLUID_MG.d.ts.map

package/src/shade/renderer/fluid/pressure/FLUID_MG.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FLUID_MG.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/pressure/FLUID_MG.js"],"names":[],"mappings":"AAgGA;;;;;;;;GAQG;AACH,yCALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,EAAE,EAAE,CAsBtB;AAED;;;;;;;GAOG;AACH,4CAHW,MAAM,GACJ,MAAM,CAMlB;AAzID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;GAIG;AACH,2CAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;;GAWG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;;GAGG;AACH,qCAFU,MAAM,CAEwB;AAExC;;;;GAIG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,iCAFU,MAAM,CAEoB;AAEpC;;;GAGG;AACH,iCAFU,MAAM,CAEqB;;;;;;4BAO3B,MAAM;AALhB;;;;;;GAMG;AACH;;;;GAIG"}

package/src/shade/renderer/fluid/pressure/FLUID_MG.js

@@ -0,0 +1,140 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * The GPU fluid's pressure solve, a geometric-multigrid V-cycle over cell-centred levels
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8). The numbers its kernels, its host and its CPU model
+ * share.
+ *
+ * ## The operator
+ *
+ * Level `l` halves every axis of the level above it, so a cell of it is `H = h·2^l` on a side. Its
+ * operator is the 7-point Laplacian over `H²` with a weight per face:
+ *
+ *     Σ_f w_f·(p_nb − p) / H² = f
+ *
+ * - A face is **open** in the fraction of its area that is open on the finest level, where a face
+ *   is open when the cells on both sides of it are fluid, and the cells beyond the window are.
+ * - A face on the window's edge has the finite-volume weight `2 / (1 + h/H)` times that fraction: the
+ *   Dirichlet point stays at the centre of the finest level's ghost cell on every level. The weight-1
+ *   rule of the CPU solver on every level stalls the V-cycle (0.661 with a global smoother, 0.750 with
+ *   the block smoother, measured).
+ * - A cell whose faces are all closed has no degree of freedom and is never updated: a solid cell,
+ *   or fluid sealed on every side, the CPU's `diag == 0`.
+ *
+ * ## Weight words
+ *
+ * A cell's six faces are packed into one `u32`, {@link FLUID_MG_FACE_BITS} bits a face, face `f` at
+ * bit `f·5`, in the CPU neighbour mask's order: −x, +x, −y, +y, −z, +z. Each field is the face's open
+ * area in sixteenths, so {@link FLUID_MG_FACE_OPEN} is a face open all over. A coarse face is the mean
+ * of its four child faces, rounded up: exact on the first two coarse levels, whose fractions are
+ * quarters and sixteenths, and never closing a face that is open somewhere below.
+ *
+ * ## Storage
+ *
+ * The finest level's pressure is the cascade's persistent toroidal field, addressed through its
+ * window. Everything else is window-local and linear, `x + nx·(y + ny·z)`.
+ */
+
+/**
+ * Most cells the coarsest level holds: one per invocation of the single workgroup that solves it.
+ * The levels stop at the first one at or below this.
+ * @type {number}
+ */
+export const FLUID_MG_COARSEST_CELL_LIMIT = 256;
+
+/**
+ * Red-black sweeps of the coarsest solve: the fewest that keep the V-cycle's factor on the CPU model.
+ * With three levels or more (every window of 32 to 256 cells an axis, and 16³), 8, 32, 64 and 400
+ * measured the same factor to three digits, open and with obstacles, at 64×32×64, 128×32×128, 32³,
+ * 32×256×32 and 256×32×32; even 2 held there. A two-level window, whose coarsest level carries the
+ * whole coarse correction, sets the count: at 16×8×16, 8 reads 0.178 after 10 cycles against 32's
+ * 0.174, and 4 drifts to 0.345.
+ *
+ * On an RTX 4090 the coarsest pass at 8 sweeps took 7.2 µs against 22.5 at 32 (64×32×64; 8.2 against
+ * 26.6 at 128×32×128), and a cold solve of two V-cycles left the same residual on the device.
+ * @type {number}
+ */
+export const FLUID_MG_COARSEST_SWEEPS = 8;
+
+/**
+ * Smoother sweeps on each leg of a V-cycle, ν: two down and two up.
+ * @type {number}
+ */
+export const FLUID_MG_SMOOTH_SWEEPS = 2;
+
+/**
+ * Most sweeps one smoother dispatch runs: the budget of the loop each invocation runs, every sweep
+ * two passes over its cell with a barrier after each.
+ * @type {number}
+ */
+export const FLUID_MG_SMOOTH_SWEEP_LIMIT = 8;
+
+/**
+ * Bits a face takes in a weight word.
+ * @type {number}
+ */
+export const FLUID_MG_FACE_BITS = 5;
+
+/**
+ * A face's field in a weight word when all of its area is open: fields count sixteenths.
+ * @type {number}
+ */
+export const FLUID_MG_FACE_OPEN = 16;
+
+/**
+ * Which cells a smoother dispatch updates, by colour: red cells have an even `x + y + z`. Both
+ * colours in one dispatch are updated against a halo frozen at its start, which is only stable at
+ * ω = 1; the SOR arm runs one colour a dispatch.
+ * @readonly
+ * @enum {number}
+ */
+export const FluidMGColour = Object.freeze({
+    Red: 1,
+    Black: 2,
+    Both: 3,
+});
+
+/**
+ * The cells of every level, finest first: each halves the one above on every axis, down to the
+ * first level of at most {@link FLUID_MG_COARSEST_CELL_LIMIT} cells.
+ *
+ * @param {number} nx power of two
+ * @param {number} ny power of two
+ * @param {number} nz power of two
+ * @returns {number[][]} `[nx, ny, nz]` a level
+ */
+export function fluid_mg_level_sizes(nx, ny, nz) {
+    assert.isPositiveInteger(nx, 'nx');
+    assert.isPositiveInteger(ny, 'ny');
+    assert.isPositiveInteger(nz, 'nz');
+
+    const sizes = [[nx, ny, nz]];
+
+    let x = nx, y = ny, z = nz;
+
+    while (x * y * z > FLUID_MG_COARSEST_CELL_LIMIT) {
+        assert.ok(x % 2 === 0 && y % 2 === 0 && z % 2 === 0, `a level of ${x}x${y}x${z} cells above the coarsest must halve on every axis`);
+
+        x /= 2;
+        y /= 2;
+        z /= 2;
+
+        sizes.push([x, y, z]);
+    }
+
+    return sizes;
+}
+
+/**
+ * The weight of a window-edge face on a level, before its open fraction: `2 / (1 + h/H)` with
+ * `H = h·2^level`, which keeps the Dirichlet point at the finest level's ghost-cell centre.
+ * 1 on the finest level.
+ *
+ * @param {number} level
+ * @returns {number}
+ */
+export function fluid_mg_edge_weight(level) {
+    assert.isNonNegativeInteger(level, 'level');
+
+    return 2 / (1 + 2 ** -level);
+}

package/src/shade/renderer/fluid/pressure/FLUID_MG_PASS_STRUCT.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One pass of the pressure solve over one level, as its kernel reads it from a uniform.
+ *
+ * A level's values are addressed like a {@link GRID_TILE_WINDOW_STRUCT} window: the finest level's
+ * pressure through the cascade's toroidal window, everything else window-local and linear, which is a
+ * window with its storage corner at 0 and a period of its size.
+ *
+ * - `corner`: the world cell at window-local (0, 0, 0) of the finest level; a Dirichlet ghost outside
+ *   the window is asked for by world cell. Unread below the finest level.
+ * - `size`: the level's cells, the cells the pass covers.
+ * - `input_corner_storage`, `input_period`: where the level's input values are stored.
+ * - `output_corner_storage`, `output_period`: where a smoother writes its output.
+ * - `coarse_size`: the next coarser level's cells: what the smoother prolongs from and the restriction
+ *   writes.
+ * - `level`: 0 on the finest level, whose ghosts are Dirichlet pressure; an error's ghost is 0.
+ * - `colours`: the smoother's colour mask, a {@link FluidMGColour}.
+ * - `sweeps`: the smoother's sweeps.
+ * - `prolong`: 1 when the smoother's load adds the coarser level's error.
+ * - `omega`: the smoother's relaxation factor.
+ * - `h2`: the level's `H²`, metres².
+ * - `edge_weight`: the level's window-edge face weight, `2 / (1 + h/H)`.
+ *
+ * The word builders read `size` only: the level they write.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_MG_PASS_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=FLUID_MG_PASS_STRUCT.d.ts.map

package/src/shade/renderer/fluid/pressure/FLUID_MG_PASS_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FLUID_MG_PASS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/pressure/FLUID_MG_PASS_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,mCAFU,YAAY,CAiBJ;6BA3CW,mCAAmC"}