# 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. |
| [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.

## Three 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. **S2:** one level can be split into communicating patches on one GPU while preserving
   the physical problem and its accepted solution.
3. **S3:** fine regions are coupled to the coarse solution; later regridding changes those
   regions safely. Accuracy, conservation and cost must be established independently.

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 delivers this folder, both plans, the offline explainer and links from the
roadmap, work board and documentation indexes. Acceptance is repository static
verification plus visual/link checks of the explainer. Completion of AMR-01 does not
complete AMR-02, 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 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.