1.5.0 Release Candidate

.gitignore

@@ -64,4 +64,8 @@ action-token
 ignore-*
 tombi/
 tidy/
-.claude
+.claude
+
+# devenv
+.devenv*
+devenv.local.nix

.tombi.toml

@@ -0,0 +1,23 @@
+toml-version = "v1.0.0"
+
+[format]
+  [format.rules]
+    indent-sub-tables = true
+    indent-table-key-value-pairs = true
+    key-value-equals-sign-alignment = true
+    trailing-comment-alignment = true
+
+[schema]
+  enabled = true
+  strict = true
+
+[[schemas]]
+  path = "entity.schema.json"
+  include = ["**/*.toml"]
+  exclude = [
+    ".tombi.toml",
+    "extern/**",
+    ".venv/**",
+    "build/**",
+    "**/*.ckpt/**",
+  ]

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,

CMakeLists.txt

@@ -1,13 +1,13 @@
 # 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)
 
 project(
   ${PROJECT_NAME}
-  VERSION 1.4.4
+  VERSION 1.5.0
   LANGUAGES CXX C)
 add_compile_options("-D ENTITY_VERSION=\"${PROJECT_VERSION}\"")
 set(hash_cmd "git diff --quiet src/ && echo $(git rev-parse HEAD) ")
@@ -58,6 +58,22 @@ set(gpu_aware_mpi
     ${default_gpu_aware_mpi}
     CACHE BOOL "Enable GPU-aware MPI")
 
+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 "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")
+
 # -------------------------- Compilation settings -------------------------- #
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
@@ -136,21 +152,33 @@ else()
   set(DEVICE_ENABLED OFF)
 endif()
 
+if(NOT ${DEVICE_ENABLED})
+  set(vendor_sort OFF)
+endif()
+
+if(NOT ${DEVICE_ENABLED} OR NOT ${mpi})
+  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
 if(${mpi})
-  find_or_fetch_dependency(MPI FALSE REQUIRED)
-  include_directories(${MPI_CXX_INCLUDE_PATH})
-  add_compile_options("-D MPI_ENABLED")
-  set(DEPENDENCIES ${DEPENDENCIES} MPI::MPI_CXX)
-  if(${DEVICE_ENABLED})
-    if(${gpu_aware_mpi})
-      add_compile_options("-D GPU_AWARE_MPI")
-    endif()
-  else()
-    set(gpu_aware_mpi
-        OFF
-        CACHE BOOL "Use explicit copy when using MPI + GPU")
-  endif()
+  include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/mpi.cmake)
 endif()
 
 # Output

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.

README.md

@@ -12,6 +12,9 @@ Our [detailed documentation](https://entity-toolkit.github.io/) includes everyth
 
 ## News
 
+- [Oct 2026]: spectra output now support **spatial binning** [PR #226](https://github.com/entity-toolkit/entity/pull/226)
+- [Oct 2026]: native [**on-the-fly plotter**](https://entity-toolkit.github.io/wiki/content/3-advanced/3-rendering/) is now available [PR #219](https://github.com/entity-toolkit/entity/pull/219)
+- [Oct 2026]: added [**dynamic load balancing**](https://entity-toolkit.github.io/wiki/content/3-advanced/4-load_balancing/) for multi-node runs [PR #216](https://github.com/entity-toolkit/entity/pull/216)
 - [May 2026]: our **method paper** for higher-order shape functions and generalized field stencils is [online](https://ui.adsabs.harvard.edu/abs/2026arXiv260515260B/abstract)
 - [Apr 2026]: user-defined **custom particle update** functionality [PR #198](https://github.com/entity-toolkit/entity/pull/198)
 - [Apr 2026]: **moving window** [PR #196](https://github.com/entity-toolkit/entity/pull/196)

cmake/defaults.cmake

@@ -92,3 +92,42 @@ else()
 endif()
 
 set_property(CACHE default_gpu_aware_mpi PROPERTY TYPE BOOL)
+
+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 tiled_deposit tile-blocked kernels")
+else()
+  set(default_tiled_deposit
+      OFF
+      CACHE INTERNAL "Default flag for tiled_deposit tile-blocked kernels")
+endif()
+set_property(CACHE default_tiled_deposit PROPERTY TYPE BOOL)
+
+if(DEFINED ENV{Entity_ENABLE_VENDOR_SORT})
+  set(default_vendor_sort
+      $ENV{Entity_ENABLE_VENDOR_SORT}
+      CACHE INTERNAL
+            "Default flag for vendor sort_by_key (oneDPL/Thrust/rocThrust)")
+else()
+  set(default_vendor_sort
+      ON
+      CACHE INTERNAL
+            "Default flag for vendor sort_by_key (oneDPL/Thrust/rocThrust)")
+endif()
+set_property(CACHE default_vendor_sort PROPERTY TYPE BOOL)
+
+set(default_tiled_deposit_tile_size
+    8
+    CACHE INTERNAL "Default tile edge length in cells for tiled_deposit")
+
+set(default_tiled_deposit_drift
+    1
+    CACHE INTERNAL
+          "Default tiled-deposit scratch halo drift (cells between sorts)")

cmake/dependencies.cmake

@@ -4,13 +4,13 @@ set(Kokkos_REPOSITORY
     https://github.com/kokkos/kokkos.git
     CACHE STRING "Kokkos repository")
 set(Kokkos_TAG
-    5.0.1
+    5.2.1
     CACHE STRING "Kokkos tag")
 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

cmake/mpi.cmake

@@ -0,0 +1,71 @@
+find_or_fetch_dependency(MPI FALSE REQUIRED)
+include_directories(${MPI_CXX_INCLUDE_PATH})
+add_compile_options("-D MPI_ENABLED")
+set(DEPENDENCIES ${DEPENDENCIES} MPI::MPI_CXX)
+if(${DEVICE_ENABLED})
+  if(${gpu_aware_mpi})
+    add_compile_options("-D GPU_AWARE_MPI")
+
+    # On Cray systems (e.g. Frontier) GPU-aware Cray MPICH can only handle
+    # device pointers if the GPU Transport Layer (GTL) library is linked. The
+    # Cray compiler wrappers (cc/CC) inject this automatically, but we build
+    # with hipcc/nvcc directly, so find_package(MPI) only finds base libmpi and
+    # the GTL is left out -> MPI_Sendrecv on a device pointer fails with "OFI
+    # ... Bad address". Add it explicitly here.
+    #
+    # Cray PE exports PE_MPICH_GTL_DIR_<accel> / PE_MPICH_GTL_LIBS_<accel> (e.g.
+    # amd_gfx90a -> -lmpi_gtl_hsa). Their absence means this is not a Cray MPICH
+    # build, in which case nothing extra is needed.
+    if("${Kokkos_DEVICES}" MATCHES "HIP")
+      set(_gtl_accels amd_gfx942 amd_gfx940 amd_gfx90a amd_gfx908 amd_gfx906)
+    elseif("${Kokkos_DEVICES}" MATCHES "CUDA")
+      set(_gtl_accels nvidia90 nvidia80 nvidia70)
+    elseif("${Kokkos_DEVICES}" MATCHES "SYCL")
+      set(_gtl_accels ponteVecchio)
+    else()
+      set(_gtl_accels "")
+    endif()
+
+    set(_gtl_dir "")
+    set(_gtl_libflag "")
+    foreach(_accel ${_gtl_accels})
+      if((NOT _gtl_dir) AND (DEFINED ENV{PE_MPICH_GTL_DIR_${_accel}}))
+        # strip the leading "-L" from the Cray-provided value
+        string(REGEX REPLACE "^-L" "" _gtl_dir
+                             "$ENV{PE_MPICH_GTL_DIR_${_accel}}")
+        string(REGEX REPLACE "^-l" "" _gtl_libflag
+                             "$ENV{PE_MPICH_GTL_LIBS_${_accel}}")
+      endif()
+    endforeach()
+
+    if(_gtl_dir AND _gtl_libflag)
+      find_library(
+        MPI_GTL_LIBRARY
+        NAMES ${_gtl_libflag}
+        HINTS "${_gtl_dir}"
+        NO_DEFAULT_PATH)
+      if(MPI_GTL_LIBRARY)
+        message(
+          STATUS "GPU-aware MPI: linking Cray GTL library ${MPI_GTL_LIBRARY}")
+        set(DEPENDENCIES ${DEPENDENCIES} ${MPI_GTL_LIBRARY})
+      else()
+        message(
+          FATAL_ERROR
+            "${Red}gpu_aware_mpi=ON: Cray MPICH detected but the GTL "
+            "library 'lib${_gtl_libflag}' was not found in '${_gtl_dir}'. "
+            "GPU-aware MPI will crash at runtime without it. Make sure the "
+            "craype-accel module is loaded, or build with gpu_aware_mpi=OFF."
+            "${ColorReset}")
+      endif()
+    else()
+      message(
+        STATUS "GPU-aware MPI: no Cray GTL environment found; assuming the MPI "
+               "implementation is GPU-aware without an extra transport library."
+      )
+    endif()
+  endif()
+else()
+  set(gpu_aware_mpi
+      OFF
+      CACHE BOOL "Use explicit copy when using MPI + GPU")
+endif()