# AMReX alignment

Design and planning, prepared 2026-09-26. **These documents add no runtime capability.**
Current task status and ownership live on the [work board](/docs/WORKBOARD).

The proposed direction is to adopt AMReX's separation of domain, index boxes,
field placement, patch storage and refinement levels within the existing C#/ILGPU
implementation. This is semantic alignment, not an AMReX binding, file-format
compatibility promise or commitment to reproduce its full API.

## Read in this order

| Document | Purpose |
| --- | --- |
| [Visual explainer](/) | Illustrated introduction to the concepts, current gaps and delivery sequence. Opens directly in a browser; no server, dependencies or build. |
| [Data-structure alignment](/docs/amrex-alignment/DATA_MODEL_ALIGNMENT) | AMR-02: change the representation of today's supported simulations without adding multiblock or refinement features. Defines proposed contracts, migration steps and acceptance. |
| [Single-level conservative transport](/docs/amrex-alignment/SINGLE_LEVEL_TRANSPORT) | TRN-01: separate numerical effort for momentum budgets, conservative MAC transport and demonstrated accuracy benefit on current grids before S2/S3 transport acceptance. |
| [S2 and S3 implementation](/docs/amrex-alignment/S2_S3_PLAN) | Subsequent numerical and workflow work: same-resolution patches, fixed refinement, then adaptation. |

The plans are co-located here at the project owner's request and indexed from
[implementation plans](https://github.com/hankbeasley/polycfd/blob/main/docs/plans/README.md). Their task status is not duplicated here.
The HTML explains the plans; the Markdown documents define their scope and acceptance.

`python3 tools/publish_explainer.py` stages the explainer and the Markdown documents it
links (rendered as HTML) under ignored `output/explainer-site/`; `--deploy` uploads that
site publicly to the Cloudflare Pages project `polycfd-amrex-explainer` with wrangler, using
`CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`. The explainer is the site root
(https://polycfd-amrex-explainer.pages.dev/); other repository links point to GitHub.

## Four separate claims

1. **Alignment:** a supported simulation is represented as one level with one patch.
   Existing physics, supported inputs and numerical checks remain unchanged.
2. **Transport:** TRN-01 establishes conservative single-level momentum transport and
   demonstrates accuracy benefit on preselected current workloads. Conservation alone
   does not prove greater accuracy; this numerical change is outside AMR-02.
3. **S2:** one level can be split into communicating patches on one GPU while preserving
   the physical problem and its accepted solution.
4. **S3:** fine regions are coupled to the coarse solution; later regridding changes those
   regions safely. Accuracy, conservation and cost must be established independently.

Preferred integration sequence: **AMR-02 -> TRN-01 -> S2 interface validation -> S3**.
Budget experiments can begin earlier and S2 layout work can overlap, but its transport
interfaces must follow the validated method. Scalar work can support T1 without
claiming temperature functionality from a test harness.

One coarse patch covering the whole physical domain is a reasonable initial S3
constraint. It does not remove the need for same-level fine-patch interfaces or
coarse/fine coupling. An AMR level and a multigrid solver level are different objects.

## Scope of this documentation task

AMR-01 established this folder and AMR-01a adds the transport recommendation across
the plans, roadmap, physics guide, indexes and offline explainer. Documentation
acceptance is repository static verification plus visual/link checks of the explainer.
Completing either documentation task does not complete AMR-02, TRN-01, S2 or S3.
No W4 decision, schema identity, scientific reference or performance allowance changes here.

## Reference map

- [AMReX basics](https://amrex-codes.github.io/amrex/docs_html/Basics.html): box and field concepts.
- [AMReX AmrCore](https://amrex-codes.github.io/amrex/docs_html/AmrCore.html): hierarchy lifecycle, filling and synchronization.
- [AMReX linear solvers](https://amrex-codes.github.io/amrex/docs_html/LinearSolvers.html): multilevel elliptic operators and multigrid.
- [AMReX-Hydro projections](https://amrex-fluids.github.io/amrex-hydro/docs_html/Projections.html): incompressibility and projection.
- [AMReX-Hydro methods](https://amrex-fluids.github.io/amrex-hydro/docs_html/) and [IAMR algorithm options](https://amrex-fluids.github.io/IAMR/docs_html/AlgorithmOptions.html): candidate transport references and formulation choices.
- [AMReX embedded boundaries](https://amrex-codes.github.io/amrex/docs_html/EB.html): geometric database and cut-cell data.

Official references were consulted on 2026-09-26. Their development documentation
can change; before implementation, record the AMReX release/commit used for any
algorithm or interoperability comparison. PolyCFD-specific contracts below are
design proposals, not claims that AMReX prescribes our implementation.