Follow what the solver must preserve, how each algorithm updates it, and what evidence would establish that the implementation is correct.
A review path, not a certificate. Current equations describe implemented behavior. Proposed equations and illustrative examples explain work still to be designed and tested. This documentation adds no numerical capability or new validation result.
Current implementationProposed designUnresolved derivation
Read the idea. Open the equations. Follow the evidence.
Each topic starts with its physical purpose. Expand the derivation, then follow links to the full specification, current implementation or validation protocol. Open decisions remain visible.
PolyCFD advances constant-density, incompressible flow. Pressure enforces continuity; viscosity diffuses momentum; applied forces and boundaries can change total momentum and energy. Pressure is stored at cell centers, and U, V and W at the corresponding faces of a staggered MAC grid.
Equations, units and the conservative form
∂u/∂t + (u · ∇)u = −∇p + ν∇²u + f
∇ · u = 0
p = physical pressure / ρ
Here u is velocity [m/s], ρ is constant density [kg/m³], p is kinematic pressure [m²/s²], ν is kinematic viscosity [m²/s], and f is acceleration [m/s²]. Every term in the momentum equation has acceleration units.
∇ · (u ⊗ u) = (u · ∇)u + u(∇ · u)
The two transport forms agree for a continuously divergence-free field. Discrete interpolation, divergence and flux operators need their own compatibility argument; the continuum identity does not prove that the implemented updates agree.
A cell-centered scalar uses a cell control volume. U momentum uses a control volume around an X face, shifted by half a cell; V and W have their own volumes. On a uniform periodic grid their regular volumes equal the cell volume, but their locations differ. Boundary and cut volumes need explicit definitions.
Boundary conditions are applied between stages. A small pressure residual or final divergence answers a different question from whether advection transported momentum accurately.
Pressure signs, backward-Euler diffusion and the divergence cancellation
D is the implemented divergence, G the effective correction gradient including solid-face masks and correction boundary treatment, L the viscous operator, and φ the pressure increment. These equations abbreviate boundary forcing and imposed face constraints. The pressure operator must match the correction actually applied, including skipped solid-adjacent faces.
D(uⁿ⁺¹) = D(u*) − Δt DGφ
= D(u*) + Δt Aφ ≈ 0
This cancellation requires the same compatible D and G in the solve and correction. Remaining divergence depends on solver error, boundary treatment and geometry. Closed/periodic connected components need a compatible right-hand side and a pressure gauge; a gauge fixes pressure's arbitrary constant, not velocity error.
Backward-Euler diffusion is first order in time. A higher-order transport step alone does not make this complete split method second order. Optional residual projection has its own restricted scope. Moving geometry uses a separate full-pressure formulation and a geometry-dependent continuity target.
Drill further: pressure solvers, diffusion iterations and boundary stencils
The pressure equation uses one shared preconditioned conjugate-gradient loop with Jacobi or geometric multigrid preconditioning. It handles the weighted compatibility and gauge of each unanchored pressure region, including static disconnected domains. Multigrid's coarse correction grids accelerate the linear solve; they are separate from physical AMR levels.
Diffusion solves the backward-Euler equations with Chebyshev semi-iteration on undamped Jacobi and a bounded colored Gauss–Seidel fallback. Their stopping criteria assess the discrete equation residual, including boundary forcing. A converged algebraic solve does not establish that the spatial or temporal discretization is accurate.
Semi-Lagrangian transport finds a departure point and interpolates the old field there. Limited MacCormack adds forward/backward error correction. Both operate on the same MAC velocity state, and both are currently supported.
Follow the RK2 and MacCormack equations into the kernel
x_mid = x − (Δt/2) I[uⁿ](x)
x_dep = x − Δt I[uⁿ](x_mid)
F = S_Δt[uⁿ](qⁿ) = I[qⁿ](x_dep)
B = S_−Δt[uⁿ](F)
q_adv = clamp(F + ½(qⁿ − B), q_min, q_max)
q is one face-velocity component; I interpolates its staggered samples, and S is the backtrace/interpolation operation. Semi-Lagrangian returns F. MacCormack uses the final expression. Both passes use the original carrying velocity uⁿ, including the reverse pass; the reverse transported field is F.
The bounds are the forward interpolation stencil's valid minimum and maximum. Geometry-aware sampling adjusts midpoint and departure locations out of solids and excludes blocked samples. Those modifications and limiting affect accuracy; the regular-grid formula alone does not qualify cut cells.
There is no shared momentum flux subtracted from one volume and added to the next. For an interpolation matrix W, preserving a constant means W1 = 1; preserving a weighted total would also need vᵀW = vᵀ, where v contains control-volume weights. The first condition alone does not imply the second. Limiting makes the overall operation nonlinear as well.
A conservative update evolves an amount inside a control volume. Neighboring volumes use the same interface transfer with opposite signs. This algebra establishes cancellation of internal transfers; it does not establish that their magnitudes are accurate.
Volume A10 → 8
2 units →one shared transfer
Volume B4 → 6
Arithmetic illustration with no external flux or source. These are amounts, not velocities and not simulation results. Total: 14 before and after.
Control-volume balance, flux orientation and dimensions
For this fixed-volume balance, q̄ is a volume average, Q an amount, and S the integrated source. Choose one orientation n_f for each shared face. The incidence sign s is +1 when it points outward from K, and −1 when inward. T includes area and time exactly once.
For scalar advection, F = q u. In three dimensions, T has units [q] m³, matching Vq. For density-normalized momentum q = u_i, Q has units m⁴/s; multiply by constant density for physical momentum [kg m/s]. Pressure and viscous stress are additional transfers, not included in this advective flux.
ΔQ_A = −T_f, ΔQ_B = +T_f
Δ(Q_A + Q_B) = 0
Floating-point accumulation still needs a declared, scale-aware tolerance. At physical boundaries only the interior contribution exists, so the domain total changes by boundary exchange and sources.
An illustrative second-order scalar building block
Example only: a fixed 1D regular grid, constant speed a, periodic boundaries, cell-average scalar q, spacing h. This is not the selected 3D momentum algorithm.
Minmod returns the smaller magnitude with the common sign, or zero when signs differ. Reconstruct fluxes again at q¹. The two-stage SSP Runge–Kutta update uses the average of both stage fluxes for its integrated transfer. A cautious sufficient bound for this specific constant-speed, minmod example is |a|Δt/h ≤ 1/2.
Second-order behavior concerns smooth resolved regions; limiting reduces order near extrema and sharp profiles. Neither this bound nor this reconstruction can be copied unchanged into multidimensional cut-cell MAC momentum. Derive and test that method's own conditions.
The scalar example proves neither MAC momentum conservation nor coupled-flow accuracy. U, V and W each require a staggered control-volume balance and compatible carrying velocities at their transport faces.
What must be specified before implementation
Derive each component's volume, face area and location, including physical boundaries.
Define reconstruction of momentum and normal carrying velocity at every transport face and time stage.
Show that the carrying fluxes obey the required continuity relation on those volumes; a small primal-cell divergence alone does not prove this.
Specify any predicted velocity or additional projection, and how it couples to diffusion, pressure history and sources.
Derive momentum and kinetic-energy balances separately. Conservative momentum can still have excessive energy dissipation or energy growth.
Only then choose the limiter, temporal scheme, ghost width and stable timestep. The existing outer workflow can be shared where mathematically valid; extra numerical stages must be explicit.
Solid surfaces leave fractional fluid volumes and open face areas. The same flux can cause a much larger change inside a tiny volume. Stabilization must preserve the intended balance and respect solid walls.
Stationary cuts, small-cell stability and moving control volumes
κ and α are dimensionless fractions. Small V_fluid can impose a restrictive explicit timestep. Redistribution or merging is a candidate treatment, but its conservation, boundedness and wall behavior need derivation and tests. Current geometry weights and volume floors cannot automatically become the new physical momentum measure.
d/dt ∫[Ω(t)] q dV
+ ∫[∂Ω(t)] q (u − w) · n dA = ∫[Ω(t)] s dV
This moving-volume scalar identity uses boundary velocity w and source density s. For momentum, pressure and viscous tractions must also be included. Fluid volume change, swept transfers, newly exposed samples and wall work must agree. Treat current and previous geometry distinctly; a static derivation does not qualify motion.
S2 splits storage at one resolution. S3 introduces different resolutions. Both require coherent transport and coupled pressure; copying neighboring values alone does not establish either.
Same-level cancellation, average-down and the reflux sign
S2: fill the chosen method's stencil at every needed stage, then use one agreed transfer on the shared interface with opposite signs. Interpolation methods instead need valid departure-point sampling across patch boundaries. Demonstrate partition equivalence for each enabled method.
q̄_C = (Σ_fine V_f q̄_f) / V_C
V_C = Σ_fine V_f
This average-down equation applies to compatible nested scalar volumes. Staggered fields need placement-aware restriction. Covered coarse cells are excluded from composite physical totals. Inconsistent cut volumes invalidate the simple identity.
Orientation: uncovered coarse volume → fine region
coarse update used: −T_C
fine update received: +T_F
coarse correction: +(T_C − T_F)
T_F sums fine transfers over the same physical face and time interval. After correction the coarse update is −T_F, so the interface contributions cancel. Averaging covered coarse values and refluxing the adjacent uncovered coarse volume do different jobs.
Synchronized timesteps do not remove the spatial mismatch. Refluxing also does not enforce the incompressibility constraint: compatible transfers, composite projection, diffusion and geometry remain separate S3 work. The equations above illustrate the accounting; MAC momentum interfaces still need their specific construction.
All simulation processing must execute on the GPU. This includes completing reductions and using their results to calculate coefficients, enforce convergence and select timesteps. GPU kernels followed by CPU numerical completion do not satisfy the requirement.
Follow a reduction through its final consumer
GPU fields → GPU partial reduction → GPU final result
→ GPU coefficient / decision → GPU update
Requested output: GPU final product → external I/O
A PCG dot product must remain on-device through its final double-precision sum and coefficient calculation. A CFL reduction must feed a device-computed admissible timestep. Component labeling, pressure gauges, geometry rebuilding, diagnostics and future regridding follow the same rule. No scalar or setup-only readback exemption is implied.
Host code may schedule launches using configuration metadata. GPU-resident flags govern numerical convergence and dependent work. A completed-operation status may be published, but polling numerical partials on the host to decide further iterations is prohibited. Explicit final measurements and captures never feed CPU-computed values back into the solver.
Acceptance measures zero computational D2H calls and bytes, including indirect reduction APIs and mapped host access. Count explicit final output separately. Keep double weighted reductions and all scientific gates: moving a sum onto the GPU changes accumulation order and requires numerical evidence.
One choice per run. Explicit support and requirements.
TRN-01 design
Retain scientifically useful current methods and introduce one qualified conservative candidate. Select the method when creating the session, record it with the scientific settings, and apply it to every patch and physical level in that run.
Small shared contract
Device field views, geometry and stage inputs; method-owned kernels and scratch; explicit stencil reach, timestep limits and capability checks. Host dispatch selects the configured implementation; all numerical processing and field-derived decisions stay on the GPU.
Explicit integration decisions
A predicted carrying velocity or extra pressure solve changes the numerical method. Document those stages and their budgets instead of treating every candidate as an identical update.
Validate geometry, motion and layout support before execution. Reject unsupported combinations and unknown method names; never silently switch methods. Adaptive steps must honor the selected stability limit. For fixed stepping, reject a step that exceeds the current hard limit before transport changes fields; do not silently shrink it. Recheck limits as the state or geometry evolves.
Initially S3 can enable only the conservative method qualified for coarse/fine coupling. Single-level choices do not promise multilevel support. Each retained method carries its own regression and cost obligations; initial scope excludes mid-run switching and per-patch mixtures.
Maintain the equations and their status in the numerical reference. Its source map links the current implementation and distinguishes existing tests from future evidence. Method selection remains a proposal until its implementation and stated acceptance pass.