haykh · Sep 27, 2026 · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026
diff --git a/.taplo.toml b/.taplo.toml
diff --git a/.tombi.toml b/.tombi.toml
@@ -0,0 +1,22 @@
+toml-version = "v1.0.0"
+
+[format]
+  [format.rules]
+    indent-sub-tables = true
+    indent-table-key-value-pairs = true
+    trailing-comment-alignment = true
+
+[schema]
+  enabled = true
+  strict = true
+
+[[schemas]]
+  path = "entity.schema.json"
+  include = ["**/*.toml"]
+  exclude = [
+    ".tombi.toml",
+    "extern/**",               # submodules: adios2's pyproject/REUSE, entity-pgens' own configs
+    ".venv/**",
+    "build/**",
+    "**/*.ckpt/**",            # checkpoint metadata dumps carry a [metadata] table, not input
+  ]
diff --git a/CITATION b/CITATION
@@ -26,7 +26,7 @@ For the general relativistic module, please cite the following paper:
 ```latex
 @ARTICLE{EntityGR_2025,
        author = {{Galishnikova}, Alisa and {Hakobyan}, Hayk and {Philippov}, Alexander and {Crinquand}, Benjamin},
-        title = "{$\mathtt{Entity}$ -- Hardware-agnostic Particle-in-Cell Code for Plasma Astrophysics. II: General Relativistic Module}",
+        title = "{Entity -- Hardware-agnostic Particle-in-Cell Code for Plasma Astrophysics. II: General Relativistic Module}",
       journal = {arXiv e-prints},
      keywords = {High Energy Astrophysical Phenomena},
          year = 2025,

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,6 +1,6 @@
 # cmake-lint: disable=C0103,C0111,E1120,R0913,R0915
 
-cmake_minimum_required(VERSION 3.16)
+cmake_minimum_required(VERSION 3.22)
 cmake_policy(SET CMP0110 NEW)
 
 set(PROJECT_NAME entity)
@@ -58,27 +58,21 @@ set(gpu_aware_mpi
     ${default_gpu_aware_mpi}
     CACHE BOOL "Enable GPU-aware MPI")
 
-set(team_policy
-    ${default_team_policy}
-    CACHE BOOL "Enable team_policy tile-blocked deposit/pusher kernels")
-set(team_policy_tile_size
-    ${default_team_policy_tile_size}
-    CACHE STRING "team_policy tile edge length in cells")
-set(team_policy_tile_sizes
+set(tiled_deposit
+    ${default_tiled_deposit}
+    CACHE BOOL "Enable tile-blocked deposit/pusher kernels")
+set(tiled_deposit_tile_size
+    ${default_tiled_deposit_tile_size}
+    CACHE STRING "tiled deposit tile edge length in cells")
+set(tiled_deposit_tile_sizes
     "4;6;8;10;12;14;16"
-    CACHE STRING "team_policy tile-size choices")
-set(team_policy_drift
-    ${default_team_policy_drift}
-    CACHE
-      STRING
-      "team_policy tiled-deposit scratch halo drift in cells (max cells a particle may move between two sorts). Sizes the deposit scratch halo only; the sort cadence is set at runtime via spatial_sorting_interval. Default 1."
-)
+    CACHE STRING "tiled deposit tile-size choices")
+set(tiled_deposit_drift
+    ${default_tiled_deposit_drift}
+    CACHE STRING "tiled deposit scratch halo drift in cells")
 set(vendor_sort
     ${default_vendor_sort}
-    CACHE
-      BOOL
-      "Use the vendor sort_by_key (oneDPL/Thrust/rocThrust) for the team_policy spatial sort when available. OFF forces the Kokkos::BinSort fallback, which sorts each SoA member in place (lower peak memory, no maxnpart gather buffer) at the cost of sort speed."
-)
+    CACHE BOOL "Use the vendor sort_by_key")
 
 # -------------------------- Compilation settings -------------------------- #
 set(CMAKE_CXX_STANDARD 20)
@@ -158,9 +152,25 @@ else()
   set(DEVICE_ENABLED OFF)
 endif()
 
-# ------------------------------ team_policy wiring ------------------------ #
-if(${team_policy})
-  include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/team_policy.cmake)
+if(NOT ${DEVICE_ENABLED})
+  set(vendor_sort OFF)
+  set(gpu_aware_mpi OFF)
+endif()
+
+# tiled deposit
+if(${tiled_deposit})
+  include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/tiled_deposit.cmake)
+else()
+  message(
+    STATUS "tiled_deposit=OFF; using global deposit scheme with ScatterViews")
+endif()
+
+# vendor-specific sorting routines
+if(${vendor_sort})
+  include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/vendor_sort.cmake)
+else()
+  message(STATUS "vendor_sort=OFF; forcing Kokkos::BinSort "
+                 "fallback for spatial sort_by_key")
 endif()
 
 # MPI

diff --git a/CODEGUIDE.md b/CODEGUIDE.md
@@ -32,6 +32,11 @@ entity
 ├── pgens                        # problem generators
 ├── examples                     # example problem generators with standard use-cases
 ├── tutorials                    # problem generators from tutorials
+├── scripts                      # user-facing helper scripts
+│   ├── dependencies.py          #   deployment scripts on various machines
+│   ├── generate_template.py     #   renders `input.default.toml` from `entity.schema.json`
+│   ├── ideal_tile_size.py       #   recommends the team tile size for the tiled deposit
+│   └── render.py                #   helper tools for the on-the-fly rendering routine
 ├── src                          # main code containing all separate submodules
 │   ├── archetypes               #   archetypes which can be used by the user in problem generators
 │   ├── engines                  #   simulation engines
@@ -48,15 +53,15 @@ entity
 ├── .gitattributes
 ├── .gitignore
 ├── .gitmodules
-├── .taplo.toml                  # formatting guidelines for toml files
+├── .tombi.toml                  # formatting guidelines for toml files + schema association
 ├── CITATION
 ├── CODEGUIDE.md                 # this file
 ├── CMakeLists.txt               # root cmake file
 ├── CODE_OF_CONDUCT.md
 ├── LICENSE
 ├── README.md
-├── dependencies.py              # deployment scripts on various machines
-└── input.example.toml           # most complete toml file with all possible input options
+├── entity.schema.json           # JSON Schema for the input file: the source of truth
+└── input.default.toml           # generated reference input with every option at its default
 ```
 
 ## Testing
@@ -75,13 +80,75 @@ You can also compile all the problem generators and run the ones from the `examp
 ./dev/scripts/tests.sh --build build_dir --flags "-D mpi=ON" --with_pgens --make_plots
 ```
 
+## Input configuration
+
+`entity.schema.json` is the single source of truth for the input file. It is a [JSON Schema](https://json-schema.org) (draft 2020-12) describing every table and key the code reads, and it serves two purposes at once:
+
+* editors validate and autocomplete input files against it as you type (see [Formatting](#formatting) below);
+* `input.default.toml` -- the annotated reference input listing every option -- is *generated* from it, so the docs cannot drift from what is validated.
+
+Regenerate the reference input after any schema change:
+
+```sh
+python scripts/generate_template.py -d -o input.default.toml
+```
+
+Dropping `-d` renders the same file with every value left as `""`, i.e. a blank form to fill in rather than a list of defaults. Writing to stdout (the default) is handy for reviewing a change: `diff <(python scripts/generate_template.py -d) input.default.toml`.
+
+### The `x-entity` annotations
+
+Standard JSON Schema keywords (`type`, `enum`, `minimum`, `items`, `prefixItems`, `required`, `default`, `deprecated`, ...) carry everything a validator can check. Everything else lives in an `x-entity` object on the node, and is what the generator turns into the `@`-annotations above each key:
+
+| field | meaning |
+| --- | --- |
+| `type` | the literal `@type:` string, e.g. `"array<uint> [size 1 :->: 3]"` -- richer than the JSON type |
+| `default` | the literal `@default:` text, for defaults the code computes at runtime (`"N_GHOSTS"`, `"1% of the domain size"`) or that need a specific notation (`"1e-4"` rather than `0.0001`) |
+| `notes` | ordered `@note:` lines; embedded newlines are kept as hard line breaks |
+| `examples` | ordered `@example:` lines |
+| `enum` | an *illustrative, non-exhaustive* value list, never validated (e.g. `output.fields.quantities`) |
+| `deprecated` | the `@deprecated:` text, paired with the standard `"deprecated": true` |
+| `inferred` | see below |
+
+`x-entity.inferred` sits on a **table** and lists quantities the code derives rather than reads -- `grid.dim`, `scales.sigma0`, `checkpoint.start_step`. They are deliberately *not* in `properties`, so `additionalProperties: false` rejects them as input keys, and the generator emits them as an `@inferred:` comment block after that table's own keys.
+
+### Adding a new input parameter
+
+1. Add the key to `entity.schema.json`, in the position you want it to appear in the reference input -- property order is emission order, and scalar keys are emitted before sub-tables regardless.
+2. Give it a `description` (the brief line) and an `x-entity.type`; add real constraints (`minimum`, `enum`, `minItems`, ...) wherever they are checkable, and a `default` when it has a literal one.
+3. Regenerate `input.default.toml`.
+4. Parse it in `src/framework/parameters/`, and register any derived quantity under `x-entity.inferred`.
+
+Three things to keep in mind:
+
+* **String enums are matched case-insensitively by the code** (`fmt::toLower` is applied to `engine`, `metric`, the boundary lists, `pusher`, `log_level`, ...), so a bare `"enum"` would reject perfectly valid input. The convention is `anyOf: [{"enum": [<canonical>]}, {"type": "string", "pattern": "(?i)^(<canonical>|...)$"}]` -- the enum branch drives completion and hover, the pattern branch keeps any casing legal. Note `(?i)` is a Rust/Python regex extension: tombi honours it, JS-based validators do not.
+* **Every table is closed.** Set `additionalProperties: false` so typos are caught; tombi's `strict = true` closes objects that omit it anyway. `[setup]` is the one deliberate exception (`additionalProperties: true`), since its keys belong to the problem generator.
+* **If a key's documented default is `[]`, the empty array must validate**, which `minItems` would otherwise forbid -- use `anyOf: [{"maxItems": 0}, {<the real shape>}]` (see `render.extent.x1`).
+
 ## Code guidelines
 
 ### Formatting
 
 To maintain coherence throughout the source code, we use `clang-format` to enforce a uniform style. A corresponding `.clang-format` file with all the style-related settings can be found in the root directory of the code. To use this, one needs to have the `clang-format` executable (typically provided with the `llvm` package). After installing the `clang-format` itself (check by running `clang-format --version`), you can use it either manually by running `clang-format .` in the route directory of the code, or attach it to your favorite code editor to run on save. For VSCode, the recommended extension is [`xaver.clang-format`](https://github.com/xaverh/vscode-clang-format), for vim -- [`rhysd/vim-clang-format`](https://vimawesome.com/plugin/vim-clang-format), for nvim -- [`stevearc/conform.nvim`](https://github.com/stevearc/conform.nvim), for [emacs](https://www.vim.org/download.php).
 
-You can run the formatting on all files with `./dev/scripts/format.sh`.
+You can run the formatting on all files with `./dev/scripts/format.sh` (this covers C++ and CMake; TOML is handled separately, below).
+
+TOML files are formatted and validated with [`tombi`](https://tombi-toml.github.io/tombi/), which is a formatter, linter and language server in one. The settings live in `.tombi.toml` in the root directory, which also associates `entity.schema.json` with every `.toml` file in the tree -- so input files are checked against the schema as you edit them, with completion and hover documentation for every key. It is provided by the nix shell (`dev/nix`); otherwise install it with `uvx tombi`, `pip install tombi`, `npm i -g tombi` or `brew install tombi`.
+
+From the command line:
+
+```sh
+tombi format              # formats the whole project (or pass files/directories)
+tombi format --check      # verify only, for CI -- mirrors `format.sh --verify`
+tombi lint <file.toml>    # schema validation only
+```
+
+In the editor, point it at the `tombi lsp` language server. For VSCode, the extension is [`tombi-toml.tombi`](https://marketplace.visualstudio.com/items?itemName=tombi-toml.tombi); for nvim, `tombi` ships as a built-in `nvim-lspconfig` server, so `vim.lsp.enable('tombi')` is enough. Individual input files can opt into the schema explicitly -- useful outside the repo -- with a directive on the first line:
+
+```toml
+#:schema ./entity.schema.json
+```
+
+> `tombi` replaces `taplo`, which the project used previously and which is no longer maintained.
 
 Best practices are also enforced using `clang-tidy`; to generate recommendations for all the files, run `./dev/scripts/tidy.sh --build build_dir` where `build_dir` is the directory where the code was built, or for specific files: `./dev/scripts/tidy.sh --build build_dir --files "(file1|file2).cpp"` or only for the changed files: `./dev/scripts/tidy.sh --build build_dir --changed`. The recommendations will be in the `tidy/` directory.
 
@@ -120,4 +187,4 @@ Best practices are also enforced using `clang-tidy`; to generate recommendations
 
 * There is no difference between `.h` and `.hpp` files as both indicate C++ header files. As a consistency convention, we use `.h` for common headers which may be included from multiple `.cpp` files (e.g., metrics), while `.hpp` are very specific headers for only a single (or a couple of) .cpp file (e.g. kernels).
 
-* Do assertions on parameters and quantities whenever possible. Outside the kernels, use `raise::Error(message, HERE)` and `raise::ErrorIf(condition, message, HERE)` to throw exceptions. Inside the kernels, use `raise::KernelError(HERE, message, **args)`. To enable compile-time errors, use `static_assert(condition, message)`. The `HERE` keyword is macro that includes the filename and line number in the error message.
+* Do assertions on parameters and quantities whenever possible. Outside the kernels, use `raise::Error(message, HERE)` and `raise::ErrorIf(condition, message, HERE)` to throw exceptions. Inside the kernels, use `raise::KernelError(HERE, message)`. To enable compile-time errors, use `static_assert(condition, message)`. The `HERE` keyword is macro that includes the filename and line number in the error message.
diff --git a/cmake/defaults.cmake b/cmake/defaults.cmake
@@ -93,16 +93,22 @@ endif()
 
 set_property(CACHE default_gpu_aware_mpi PROPERTY TYPE BOOL)
 
-if(DEFINED ENV{Entity_ENABLE_TEAM_POLICY})
-  set(default_team_policy
+if(DEFINED ENV{Entity_ENABLE_TILED_DEPOSIT})
+  set(default_tiled_deposit
+      $ENV{Entity_ENABLE_TILED_DEPOSIT}
+      CACHE INTERNAL "Default flag for tiled_deposit tile-blocked kernels")
+elseif(DEFINED ENV{Entity_ENABLE_TEAM_POLICY})
+  message(WARNING "`Entity_ENABLE_TEAM_POLICY` is deprecated, "
+                  "use `Entity_ENABLE_TILED_DEPOSIT` instead")
+  set(default_tiled_deposit
       $ENV{Entity_ENABLE_TEAM_POLICY}
-      CACHE INTERNAL "Default flag for team_policy tile-blocked kernels")
+      CACHE INTERNAL "Default flag for tiled_deposit tile-blocked kernels")
 else()
-  set(default_team_policy
+  set(default_tiled_deposit
       OFF
-      CACHE INTERNAL "Default flag for team_policy tile-blocked kernels")
+      CACHE INTERNAL "Default flag for tiled_deposit tile-blocked kernels")
 endif()
-set_property(CACHE default_team_policy PROPERTY TYPE BOOL)
+set_property(CACHE default_tiled_deposit PROPERTY TYPE BOOL)
 
 if(DEFINED ENV{Entity_ENABLE_VENDOR_SORT})
   set(default_vendor_sort
@@ -117,13 +123,11 @@ else()
 endif()
 set_property(CACHE default_vendor_sort PROPERTY TYPE BOOL)
 
-set(default_team_policy_tile_size
+set(default_tiled_deposit_tile_size
     8
-    CACHE INTERNAL "Default tile edge length in cells for team_policy")
+    CACHE INTERNAL "Default tile edge length in cells for tiled_deposit")
 
-set(default_team_policy_drift
+set(default_tiled_deposit_drift
     1
-    CACHE
-      INTERNAL
-      "Default tiled-deposit scratch halo drift for team_policy (cells between sorts)"
-)
+    CACHE INTERNAL
+          "Default tiled-deposit scratch halo drift (cells between sorts)")
diff --git a/cmake/dependencies.cmake b/cmake/dependencies.cmake
@@ -10,7 +10,7 @@ set(adios2_REPOSITORY
     https://github.com/ornladios/ADIOS2.git
     CACHE STRING "ADIOS2 repository")
 set(adios2_TAG
-    v2.11.0
+    v2.12.1
     CACHE STRING "ADIOS2 tag")
 
 set(CONNECTION_CHECKED

diff --git a/cmake/report.cmake b/cmake/report.cmake
@@ -121,22 +121,22 @@ printchoices(
   GPU_AWARE_MPI_REPORT
   44)
 printchoices(
-  "Team Policy"
-  "team_policy"
+  "Tiled Deposit"
+  "tiled_deposit"
   "${ON_OFF_VALUES}"
-  ${team_policy}
+  ${tiled_deposit}
   OFF
   "${Green}"
-  TEAM_POLICY_REPORT
+  TILED_DEPOSIT_REPORT
   44)
 printchoices(
   "Tile Size"
-  "team_policy_tile_size"
-  "${team_policy_tile_sizes}"
-  ${team_policy_tile_size}
-  ${default_team_policy_tile_size}
+  "tiled_deposit_tile_size"
+  "${tiled_deposit_tile_sizes}"
+  ${tiled_deposit_tile_size}
+  ${default_tiled_deposit_tile_size}
   "${Blue}"
-  TEAM_POLICY_TILE_SIZE_REPORT
+  TILED_DEPOSIT_TILE_SIZE_REPORT
   44)
 printchoices(
   "Vendor sort"
@@ -246,18 +246,18 @@ string(
   "    "
   ${GPU_AWARE_MPI_REPORT}
   "\n"
-  "  > Team-policy specs"
-  " ${Dim}[requires team_policy=ON]${ColorReset}"
+  "  > Tiled-deposit specs"
+  " ${Dim}[requires tiled_deposit=ON]${ColorReset}"
   "\n"
   "    "
-  ${TEAM_POLICY_REPORT}
+  ${TILED_DEPOSIT_REPORT}
   "\n"
   "    "
-  ${TEAM_POLICY_TILE_SIZE_REPORT}
+  ${TILED_DEPOSIT_TILE_SIZE_REPORT}
   "\n"
   "    "
-  "- Deposit drift [${Magenta}team_policy_drift${ColorReset}]:      "
-  ${team_policy_drift}
+  "- Deposit drift [${Magenta}tiled_deposit_drift${ColorReset}]:    "
+  ${tiled_deposit_drift}
   "\n")
 
 string(