Box
Where a patch lives in the level's integer index space.
[lower, upper]AMReX alignment / design proposal / 26 September 2026
From one grid
to a hierarchy.
Give today's solver a clearer structure. Then teach it to connect patches. Then add resolution where the physics needs it.
Three separate gates. The first changes the representation of existing simulations. Multiblock and refinement are later numerical features. Nothing on this page is evidence that those features already work.
01 / Vocabulary
A domain is a place.
A patch is a piece of storage.
The domain is the physical region being simulated. A level gives it a particular grid spacing. A patch stores a rectangular part of that level.
One coarse patch can cover the entire domain. Fine levels can use several smaller patches. Splitting a level into patches does not change its resolution.
AMReX uses boxes and field collections to express this separation. Official data-model reference.
Physical domainbounds · coordinates · periodicity
Level 0 · spacing h
Patch Aindex box + fields
Patch Bindex box + fields
Placement
Where the quantity is sampled relative to a cell.
cell · x/y/z faceField view
How a kernel reaches values without owning their memory.
bounds + strides + dataLevel layout
Which boxes share a resolution and cover which region.
spacing + patch boxes02 / Follow the same physical domain
The representation changes first.
The mesh changes later.
Choose a stage to inspect the difference. These are schematic 2D grids, not simulation results.
AMR-02 / same capability
One patch, expressed clearly.
The solver still advances the same grid. Domain coordinates, patch bounds, field placement and memory ownership become explicit and consistently used.
- What changes
- Data contracts and their consumers.
- What must be proved
- Existing scientific results, selective capture and performance are preserved.
160 active cells · 1 physical level · 1 patch
Why does keeping one coarse grid not solve all the interface work?
It guarantees base coverage. Fine patches still need values from their neighbors, and the coarse and fine regions must agree on normal volume flux and pressure coupling. The coarse solution must respond to the fine region as part of one physical solution.
Why are allocated and active cells different in the refined illustration?
The fine patch covers 48 of the 160 coarse cells and contains 192 fine cells. We retain 160 + 192 = 352 cell slots, but the physical composite uses 160 − 48 + 192 = 304 active cells. A uniformly fine 2D grid would contain 640 cells. These counts exclude face arrays, ghosts, geometry and solver buffers; they are not a GPU memory or speed prediction. In 3D, a 2:1 refinement divides a coarse cell into eight fine cells.
03 / What already fits
Our MAC fields have a natural home.
Pressure and velocity should not be forced into one identically shaped array. A patch with Nx × Ny × Nz cells has different valid extents for each field.
- Pressure
- Nx × Ny × Nz
- U velocity
- (Nx + 1) × Ny × Nz
- V velocity
- Nx × (Ny + 1) × Nz
- W velocity
- Nx × Ny × (Nz + 1)
We keep device-resident arrays, float fields, Half geometry and double weighted reductions. Alignment makes their meaning and ownership explicit.
04 / Where the hard work lives
Three boundaries.
Three different responsibilities.
The physical boundary
A wall, inlet, outlet or periodic domain edge. Apply the problem's physical conditions here.
A same-resolution patch edge
An internal storage split. Obtain neighboring samples and agree on the shared face value; this edge is not a wall.
A coarse/fine interface
Different resolutions describe the same fluid. Couple pressure, transfer fields and make weighted fluxes consistent.
Current advection clamps or wraps at the current grid's edges. S2 must replace that domain-wide assumption with a policy for sampling across patches, including departure points and corner data.
See AMReX boundary filling and AMReX-Hydro projection methods.
05 / Our current code
Adaptable foundations.
Specific assumptions to untangle.
| Area | AMR-02: representation | S2 / S3: behavior |
|---|---|---|
| Grid & coordinates | Separate domain geometry, global boxes and local strides. | Support several patches and new refinement layouts. |
| Session & fields | One level with one patch; explicit owners and borrowed views. | Coordinate operators and reductions across patches. |
| Boundary sampling | Name and guard the current patch-equals-domain restriction. | Exchange same-level data, then fill coarse/fine data. |
| Solid geometry | Separate coordinates from cut-cell metrics; preserve sampling. | Establish consistent geometry and fluxes across interfaces. |
| Results & viewers | Derive current metadata from the canonical layout. Preserve wire meanings. | Carry native patch/level coverage or label resampled previews. |
Physical refinement levels
Where the solution lives
Coarse background plus finer local regions. These levels carry physical simulation state and affect resolution.
Coarse domain → fine region
Multigrid solver levels
How an equation is solved
Auxiliary coarse problems accelerate pressure convergence. They do not add locally refined simulation state.
Pressure problem → coarser corrections
Both can use box descriptors. They need separate identities and ownership. Existing GpuMgHierarchy is the second kind.
06 / Delivery gates
Prove each step before adding the next.
- AMR-02
Align today's structures
Inventory consumers, introduce canonical descriptors, migrate ownership and callers, then remove superseded representations.
Gate: existing inputs, fields, measurements, outputs and scientific acceptance remain valid. No new mesh capability and no abstraction-driven performance regression.
- S2
Connect patches at one resolution
Begin with the same problem split in two. Add same-level sampling, shared-face consistency, coupled pressure/diffusion, geometry, measurements and output.
Gate: partitioned and monolithic solutions agree within declared tolerances, including periodic and cut interfaces. A simple two-patch test alone does not finish S2.
- S3 / fixed
Add resolution in one region
Start with one coarse base, one aligned 2:1 fine patch and synchronized timesteps. Add coverage masks, transfers and composite equations.
Gate: accuracy and conservation pass against uniform-fine references, with less measured memory or time at comparable measurement accuracy.
- S3 / adaptive
Let refined regions change
Extend fixed refinement to multiple patches/levels. Then add tagging, regridding, safe state transfer, layout revisions and geometry/solver rebuilding.
Gate: refine/derefine cycles preserve the required budgets and constraints. Thermal and moving-geometry combinations need their own evidence. Time subcycling is a later decision.
Continue reading
The design behind the diagrams.
The Markdown plans define scope and acceptance. The work board owns current status. Proposed type names and diagrams are explanatory; they are not executable API or file-format specifications.