POLYCFD / Design notebook

Algorithms / review companion / 26 September 2026

From physical laws
to discrete updates.

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

Choose your depth

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.

  1. Physical model and MAC locationsWhat is conserved, and where do values live?
  2. The current time stepTransport, forces, diffusion and pressure correction.
  3. Current transport methodsRK2 backtracing and limited MacCormack.
  4. A conservative updateShared fluxes, signs, units and a scalar example.
  5. From a scalar to MAC momentumWhat the simple example has not established.
  6. Cut cells and moving boundariesSmall volumes, wall exchange and geometric conservation.
  7. S2 and S3 interfacesShared transfers, restriction, refluxing and projection.
  8. Choosing a methodA bounded option with explicit numerical requirements.
  9. Review and validationSeparate mathematical obligations from measured evidence.

01 / Physical model

A velocity field with a continuity constraint.

Current implementation

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.

Drill down: governing equations · control volumes · index conventions.

02 / Current integration

One time step has several distinct balances.

Current static geometry
  1. Advect velocity
  2. Add forces and old pressure
  3. Solve viscous diffusion
  4. Apply face constraints
  5. Project and accumulate pressure

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
u_adv = Advect(uⁿ, Δt)
u_rhs = u_adv + Δt f − Δt G(pⁿ)
(I − Δt ν L)u_diff = u_rhs
u* = ApplyImmersedConstraints(u_diff)
Aφ = −D(u*) / Δt,    A = −DG
uⁿ⁺¹ = u* − Δt Gφ
pⁿ⁺¹ = pⁿ + φ

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 down: stage and moving-geometry equations · physics guide · integrator source · incremental projection tests.

Drill further: pressure solvers, diffusion iterations and boundary stencils

The pressure equation uses preconditioned conjugate gradients with Jacobi or geometric multigrid preconditioning. Cut-cell weights define the relevant inner product and nullspace handling. Multigrid's coarse correction grids accelerate the linear solve; they are separate from physical AMR levels.

Diffusion solves the backward-Euler equations with weighted 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.

Continue into the pressure multigrid design, cut-cell multigrid operators, current diffusion algorithm and residual definition, and boundary stencils. The multigrid documents label their historical sketches; use their current notes and linked source when reviewing implemented behavior.

03 / Existing choices

Follow the fluid backward to an old value.

Current implementation

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.

Drill down: sampling details and limitations · current kernels · uniform and Gaussian transport tests.

04 / Proposed conservative foundation

Count each internal transfer once.

Proposed design

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
Q_K = V_K q̄_K
T_f = ∫[tⁿ,tⁿ⁺¹] ∫[face f] F · n_f dA dt
Q_Kⁿ⁺¹ = Q_Kⁿ − Σ_f s_Kf T_f + S_K

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.

σ_i = minmod(q_i − q_(i−1), q_(i+1) − q_i)
q_L = q_i + σ_i/2
q_R = q_(i+1) − σ_(i+1)/2
F_(i+½) = max(a,0) q_L + min(a,0) q_R
L(q)_i = −(F_(i+½) − F_(i−½)) / h
q¹ = qⁿ + Δt L(qⁿ)
qⁿ⁺¹ = ½qⁿ + ½[q¹ + Δt L(q¹)]

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.

Drill down: balance derivation · scalar assumptions, references and checks · AMReX-Hydro method references.

05 / Required derivation

Momentum lives on three staggered meshes.

Unresolved derivation

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
  1. Derive each component's volume, face area and location, including physical boundaries.
  2. Define reconstruction of momentum and normal carrying velocity at every transport face and time stage.
  3. Show that the carrying fluxes obey the required continuity relation on those volumes; a small primal-cell divergence alone does not prove this.
  4. Specify any predicted velocity or additional projection, and how it couples to diffusion, pressure history and sources.
  5. 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.

Drill down: open MAC derivation · TRN-01 work packages and acceptance.

06 / Geometry matters

A cut volume changes the balance and stability.

New transport not yet qualified

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
V_fluid = κ V_cell
A_open = α A_face
Δq̄ = (−Σ outward transfers + sources) / V_fluid

κ 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.

Drill down: geometry proof obligations · current moving-geometry physics · AMReX small-cell discussion.

07 / Later patch coupling

Make both sides describe the same transfer.

S2 and S3 design

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.

Drill down: interface review · S2/S3 delivery gates · AMReX flux registers.

08 / Bounded method selection

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. Dispatch happens on the host.

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.

Drill down: method contract and support matrix · existing scheme selector · current runtime contract.

09 / Review checklist

An equation, a test and a physical claim
are different kinds of evidence.

Use the question in the first column to choose the next review step
ClaimMathematical or implementation checkMeasured evidence
Consistent physicsUnits, locations, signs, BCs, wall forces and volume measures.Exact flows and independent reference protocols.
Conservative transportInternal flux cancellation and complete boundary/source budget.Stage-resolved momentum budgets, including cuts and motion where enabled.
ContinuityCompatible divergence/gradient and solvable pressure system.Pressure residual and native discrete divergence, per connected component.
Accurate evolutionConsistency and claimed space/time order under stated assumptions.Independent grid/time refinement; phase, amplitude, force and energy error.
Stable and boundedMethod-specific CFL and limiter/stabilization conditions.Sharp profiles, tiny cut cells, boundaries and permitted timestep extremes.
Usable choiceReproducible selection, support rejection and owned storage.Per-method regression, peak memory and total cost to a target accuracy.

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.