# Transport method selection and conservative accuracy on existing grids

**Design proposal, 2026-09-26.** Effort: TRN-01. Current status and owner are on the
[work board](/docs/WORKBOARD). This plan changes no runtime behavior and establishes
no accuracy improvement. Method-selection design updated 2026-09-26. It is a separate numerical effort from
[AMR-02 data alignment](/docs/amrex-alignment/DATA_MODEL_ALIGNMENT), preceding the transport acceptance
of [S2 and S3](/docs/amrex-alignment/S2_S3_PLAN).

## Outcome and sequencing

Establish conservative transport on one physical level and one patch, with explicit
momentum budgets and demonstrated accuracy benefit on preselected current workloads.
Make the resulting flux accounting usable by S2 and later coarse/fine synchronization.
Conservation, solution accuracy, stability and computational cost are separate claims;
all must be evaluated before choosing a production method.

Retain the useful `SemiLagrangian` and limited `MacCormack` choices and add one
qualified conservative method. The current defaults and recorded selections remain
unchanged by this plan. Supporting several algorithms does not mean maintaining
duplicate runtimes: they share state, geometry, pressure/diffusion infrastructure,
results and the accepted-step loop. See the [algorithm review guide](/docs/amrex-alignment/ALGORITHMS)
and [progressive numerical explainer](/algorithms.html) for equations,
implementation links and the evidence needed to assess each claim.

Preferred integration sequence: **AMR-02 -> TRN-01 -> S2 interface validation -> S3**.
Current-method budget measurements and small numerical experiments can begin before
alignment completes. Production integration uses the accepted aligned representation.
S2's layout/ownership work can overlap, but its advection interface design must use
TRN-01's established stencil, flux and timestep requirements. S2 acceptance requires
validated transport for its declared geometry/BC scope; S3 requires that single-level
and partitioned foundation before adding coarse/fine coupling.

Coordinate the scalar experiment with [T1](/docs/ROADMAP#t1--temperature-transport-and-prescribed-thermal-conditions).
Reuse appropriate flux/field infrastructure and budget checks. The experiment is a
numerical test harness, not a delivered temperature feature; T1's materials, thermal
BCs, sources, heat budgets and complete user workflow retain their own acceptance.
T1 scalar work need not wait for all MAC momentum work to finish.

Keep C#/.NET, ILGPU, one GPU, MAC staggering, float fields, Half geometry, double
weighted reductions and device residency. Multiblock, refinement, adaptation, new
thermal physics and a wholesale pressure/diffusion redesign are outside this effort.
Any required change to time integration or cut-cell stabilization must be an explicit
numerical decision with evidence, not an incidental part of data alignment.

## The current limitation

[AdvectionGpu](https://github.com/hankbeasley/polycfd/blob/main/src/PolyCfd.Gpu/Advection/AdvectionGpu.cs) backtraces sample
locations and interpolates the previous velocity field. Its limited MacCormack
variant applies a forward/backward correction and limits overshoot. It does not
form the shared momentum transfers of a conservative finite-volume update.

For a transported quantity, a conservative update uses the same face transfer as
an outgoing contribution to one control volume and an incoming contribution to its
neighbor. Internal contributions cancel. Boundary transfers and sources still change
the total. On a MAC grid, momentum is associated with staggered control volumes;
cell-centered scalar conservation cannot simply be relabeled as momentum conservation.

Constant-density mass balance is constrained by pressure projection. A small velocity
divergence does not establish momentum-transport conservation. Kinetic energy is a
different diagnostic: viscosity, boundaries, forces and numerical dissipation affect
it, so the target is the appropriate physical evolution, not constant energy in every case.

The current method may be accurate for supported cases. No blanket accuracy ranking
is assumed: a conservative scheme can be more diffusive than the current MacCormack
scheme. Timestep splitting, backward-Euler diffusion, resolution and cut-boundary
approximations remain other error sources. See the [physics guide](/docs/PHYSICS_GUIDE).

## Candidate method and flux contract

Use a limited, second-order finite-volume formulation compatible with our MAC grid as
the starting candidate. Record spatial reconstruction, limiting, transport velocity,
temporal centering, projection coupling and timestep restrictions before implementation.
A nominally second-order advection method does not make the complete split integrator
second order. Compare alternatives, including a conservative remap if justified,
against the same conservation, accuracy and cost gates; the precise algorithm is open.

[AMReX-Hydro](https://amrex-fluids.github.io/amrex-hydro/docs_html/) provides Godunov
and method-of-lines references. Its projection/velocity arrangements are not a direct
replacement for PolyCFD's current MAC state and cut-cell equations. AMReX-based IAMR
also exposes conservative and nonconservative formulations: choosing conservative
transport is our numerical direction, not a requirement of AMReX's data model.
[IAMR algorithm options](https://amrex-fluids.github.io/IAMR/docs_html/AlgorithmOptions.html)

The design must specify:

- What each transported quantity integrates over, including the momentum control-volume
  weights and geometry for each staggered component. Do not substitute arbitrary
  cell-to-face averaging for a derived cut-cell momentum balance.
- Flux sign, orientation, location, units and whether values already include open area
  or timestep. Apply each geometric/time weight exactly once.
- A single shared transfer per internal interface, with equal/opposite contributions
  to adjacent control volumes. Later partitioning must preserve this identity.
- How advecting velocities satisfy the required discrete continuity constraint at the
  transport time, and how pressure, diffusion and source stages preserve the budget.
- Stencil/ghost reach, limiter bounds and explicit stability limits, including small
  cut cells. Define boundary and wall momentum exchange consistently.
- Device ownership and lifetime of flux data. Retain only the data needed by the
  update, diagnostics or future interface accumulation; avoid speculative full-field
  downloads or permanent duplicate buffers for an unimplemented AMR scheme.

## Bounded method selection

Extend the existing scenario/runtime advection choice rather than introducing a
general plugin framework. The conservative candidate has no public name or serialized
value yet; choose those after its equations and supported scope are settled. These
are planned contracts, not capabilities of the current mutable operator API.

### One resolved choice per run

Resolve and validate the method when creating the session, then keep it immutable
for that run. All patches and physical levels use the same momentum-transport method.
No per-patch, per-level or per-stage switching, automatic fallback, runtime hot swap,
or independently selectable limiter/reconstruction combinations are in scope. A
method's own predictor/corrector stages are part of that method, not separate choices.
Future temperature transport retains its own equation and qualification requirements.

Keep typed inputs, scenario JSON, resolved settings, saved-run identity and replay
consistent. Record the selected method and its resolved numerical settings alongside
the existing build identity; comparisons must identify differences in method and
timestep policy. Reject unknown strings, unknown enum values and unsupported
combinations through exhaustive dispatch. Do not reinterpret a saved method as a new
algorithm or silently change the default when adding a choice. Update maintained
callers, generated contracts, fixtures and examples together during implementation.

### Small host-side contract

Bind one implementation during setup and dispatch between methods on the host,
outside per-cell GPU kernels. Reuse aligned field/geometry views with explicit
borrowing and stream completion; each implementation owns only its required scratch.
Allocate no conservative flux arrays for a semi-Lagrangian run and no MacCormack
correction buffers for a run that does not use them. Include retained buffers and
peak initialization/geometry-change storage in resource estimates before admission.

The contract must expose the following small set of numerical requirements:

| Requirement | Design obligation |
| --- | --- |
| Supported cases | Declare layout, dimension/minimum extents, boundary conditions, stationary cuts and motion support. Reject unsupported known configurations before device allocation; check evolving geometry against the same contract. |
| Sampling and stages | Declare valid/ghost reach, edge/corner requirements and when data is required. A departure-point sampler may have timestep-dependent reach; do not pretend every method has one fixed stencil. |
| Time limit | Supply the method's actual stability restrictions and distinguish them from recommended accuracy controls. Combine them with motion, user and final-time controls; account for cut-cell stabilization and later all active levels. |
| Integration coupling | Specify advecting-velocity prediction, pressure constraints, temporal centering and any extra projection/source stages. Make necessary integrator changes explicit; a generic `Advect()` call does not establish numerical compatibility. |
| Conservation evidence | For a conservative method, expose consistently oriented, area/time-weighted interface transfers needed for budgets and later synchronization. Do not manufacture fluxes for interpolation methods or make them allocate unused flux storage. |

For adaptive stepping, enforce the selected method's admissible timestep on every
attempt, including after geometry changes. For fixed stepping, validate the configured
step initially and reject an attempted step that exceeds a newly computed hard limit
before transport modifies fields; do not silently shrink it or bypass the check because
adaptive stepping is disabled. Preserve the separately declared final-time clipping
policy. Report the applicable limit and the actual accepted timestep. A large-step
semi-Lagrangian stability property is not a guarantee of accurate transport.

### Qualification grows by method and topology

| Method | One patch / one physical level | S2 uniform patches | Initial S3 refinement |
| --- | --- | --- | --- |
| `SemiLagrangian` | Preserve current supported cases and scientific gates | Enable only after its own interpatch sampling and partition-equivalence checks | Unsupported initially |
| Limited `MacCormack` | Preserve current supported cases and scientific gates | Enable only after its forward/reverse/limiter stages pass partition-equivalence checks | Unsupported initially |
| Conservative candidate | Enable only for the TRN-01-qualified boundary/geometry/motion subset | Require shared-flux cancellation and partition equivalence for that subset | Sole initial candidate; still requires S3 coarse/fine, projection and geometry qualification |

All S2/S3 entries are future scope. No method is required to support every topology.
Stationary regular, stationary cut and moving-geometry qualifications remain separate
within each entry. Keep useful choices because of demonstrated capabilities or
speed/accuracy tradeoffs; remove abandoned experiments and superseded internals.
Retaining current methods is not a compatibility requirement to extend them to S3.

## Implementation steps

These are ordered work packages within TRN-01. Status lives on the work board.

1. **Establish current budgets and references.** Define component momentum and energy
   diagnostics, using derived geometry weights and double reductions. Separate the
   observed increments from advection, pressure, viscosity, sources, physical boundary
   exchange and moving-boundary contributions. Measure the existing methods before
   changing them. Freeze target cases, observation windows, error measures, conservation
   limits and reference/build identities before candidate evaluation.
2. **Prove a scalar transport building block.** Use prescribed divergence-free velocity
   on one regular periodic grid. Check shared-flux cancellation, constant preservation,
   total transported amount, smooth-profile convergence and boundedness of sharp
   profiles. Include nonuniform prescribed velocity so constant-translation special
   cases do not hide a defect. Extend to inlet/outlet budget accounting. A scalar pass
   is evidence for this building block only.
3. **Implement MAC momentum transport.** Construct the staggered momentum control-volume
   fluxes and couple the update to the current pressure/time integration. Check uniform
   velocity preservation, periodic momentum budgets, temporal/spatial convergence and
   the existing exact-flow controls. Diagnose projection and splitting effects separately.
4. **Qualify physical boundaries and cut geometry.** Add wall/inlet/outlet momentum
   accounting, stationary cut cells and a justified small-cell stability treatment.
   Any redistribution or merging must itself preserve the intended balance and respect
   the physical solid. Qualify moving geometry as a separate increment with consistent
   previous/current volumes and wall exchange before enabling the new method there.
5. **Integrate bounded selection and qualify the candidate.** Compare full single-grid
   workflows, including required output, against the preserved build. Keep the useful
   current methods and add the candidate only for its accepted subset. Bind one immutable
   selection per run, implement capability/timestep checks and selected-method resource
   estimates, and review predictor/projection coupling against the algorithm derivation.
   Update maintained typed/serialized settings, examples, fixtures, tests and guides
   together if the public method selection changes. Remove temporary experimental
   paths; preserve useful capabilities and historical reference evidence. Hand the
   accepted flux/stencil contract and verification cases to S2.

Current supported cases, including motion, remain usable while a candidate is
restricted to its validated subset. Do not silently route an unsupported candidate
case through another method or remove a capability to simplify acceptance. The
supported subset and outstanding qualification work must be explicit.

**Context:** `src/PolyCfd.Gpu/Advection`, `src/PolyCfd.Gpu/Integration`,
`src/PolyCfd.Gpu/Geometry`, `docs/PHYSICS_GUIDE.md`,
`docs/PERIODIC_EXACT_VALIDATION.md`, `docs/TAYLOR_GREEN_VALIDATION.md`,
`docs/BACKWARD_STEP_VALIDATION.md`, `docs/CYLINDER_FORCES.md`.

## Single-grid acceptance matrix

| Evidence | What must be demonstrated |
| --- | --- |
| Prescribed scalar transport | Closed periodic/source-free budget within the declared roundoff-aware bound; constant preservation; convergence and appropriate limiter behavior. This is not momentum or thermal acceptance. |
| Traveling shear / transported profiles | Measured phase and amplitude error, spreading and grid/timestep convergence. |
| Planar Taylor-Green, Beltrami and nonlinear Taylor-Green | Field errors and their convergence, component momentum budgets and correct physical energy evolution. Nonlinear flow uses the qualified numerical reference, not an assumed exponential decay. |
| Backward step and cylinder | Recirculation/separation, field or measurement accuracy and forces within their applicable accepted protocols. |
| Static cut-cell and moving cases | Geometry-weighted balances, boundary consistency, small-cell stability and each declared supported motion regime. A regular-grid result does not qualify them. |

Method selection also requires implementation acceptance; these checks do not replace
the numerical evidence above:

| Contract evidence | What must be demonstrated |
| --- | --- |
| Identity and reproducibility | Typed and serialized choices resolve identically, survive saved-run/replay paths and fresh-integrator experiments, and remain immutable during a run. Comparisons retain method, actual timestep policy and build identity. |
| Exhaustive rejection | Unknown names/enum values and unsupported method/layout/BC/geometry/motion combinations fail with actionable errors. No branch silently selects another algorithm. |
| Timestep enforcement | Fixed and adaptive paths enforce each hard limit, including changed geometry, final-time clipping and rejected steps. Accuracy recommendations are not mislabeled as proven stability bounds. |
| Coupling and stage identity | The selected algorithm's predictors, pressure constraints and source ordering match its derivation. Diagnostic stage meanings and completed-frame identities remain truthful when methods have different internal stages. |
| Resources and lifetime | Measured retained/peak memory agrees with selected-method estimates; unused methods allocate no field-sized scratch. Disposal, failed setup and geometry rebinding preserve borrowed lifetimes and device residency. |
| Preserved choices | Current methods retain their accepted scientific behavior and supported workflows. Candidate comparisons use frozen cases and limits; neither a default change nor a new option rewrites reference expectations. |

Compare the preserved and candidate methods at the same grid, timestep, physical
time/window and scientifically equivalent settings. Also compare cost to meet a
predeclared measurement-error target: tighter advective CFL limits can require more
steps even when each step is fast. Measure initialization, stepping, geometry and
required outputs; record allocations, retained memory and transfers on an idle GPU.

Acceptance requires **a demonstrated single-grid accuracy benefit on the preselected
target workload(s)** as well as validated conservation, stability and cost within
the agreed limits. Quantify the benefit beyond reference uncertainty and numerical
noise; do not select a favorable case or metric after seeing the results. Preserve
existing scientific gates on the regression workload set and explicitly retain any
previously unresolved qualification failures. Do not claim every flow improves.

Set conservation/error bounds and the target workload before evaluation. Use existing
reference protocols where they apply; explain and review any new references separately.
Do not refresh baselines, relax windows/tolerances or change performance allowances to
make the method pass. Failure to show the intended benefit calls for revision or
deferral, not automatic adoption because the method is conservative. Follow
[performance acceptance](https://github.com/hankbeasley/polycfd/blob/main/docs/PERFORMANCE_VALIDATION.md#architecture-change-acceptance).

Run `python3 tools/verify static fast gpu` for runtime implementation, focused CUDA
tests while iterating, and the appropriate CUDA `verify-all` suite with full coverage
before broad numerical acceptance. Follow [suite selection](/docs/COMPLETE_VALIDATION#choose-coverage-for-the-change)
and [verification instructions](https://github.com/hankbeasley/polycfd/blob/main/test/README.md), including isolated artifacts
when another campaign owns binaries. Report receipt paths, counts, `notRun` entries,
hardware/reference limitations and actual timing conditions. CPU backend not run
(user directive). Existing supported APIs, selective capture and completed-frame
ownership remain subject to [runtime contracts](/docs/RUNTIME_CONTRACTS).

## What remains for S2 and S3

S2 must preserve the accepted shared flux across same-resolution patch boundaries,
including periodic and cut interfaces, and demonstrate equivalence to the single-patch
method. Its data exchange policy follows each enabled method's reach and temporal
stages. Enabling an interpolation method on S2 needs separate partition equivalence;
it does not acquire a conservative-flux guarantee by sharing the same data model.

S3 still needs coarse/fine transfers, compatible geometry/coverage, time/area-integrated
flux mismatch correction, composite pressure and diffusion, and later regridding.
Refluxing can correct a mismatch between conservative level updates; it does not fix
an arbitrary interpolation update. [AMReX flux registers](https://amrex-codes.github.io/amrex/docs_html/AmrCore.html#fluxregisters)
Shared timesteps do not eliminate spatial flux mismatch. TRN-01 does not claim to
solve these multilevel problems in advance. Initially S3 accepts only the conservative
method qualified for that case; reject interpolation-method refinement requests.

When the effort is accepted, move lasting equations, budgets and method-selection
contracts into current runtime/physics guides and retire this implementation plan.