v1.3.0 Release Candidate

.github/workflows/cpuarch.yml

@@ -0,0 +1,107 @@
+name: CPU Compilation/Unit Tests
+
+on:
+  push:
+
+jobs:
+  check-commit:
+    runs-on: ubuntu-24.04
+    outputs:
+      run_tests: ${{ steps.check_message.outputs.run_tests }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Check commit message
+        id: check_message
+        run: |
+          if git log -1 --pretty=%B | grep -q "CPUTEST"; then
+            echo "run_tests=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "run_tests=false" >> "$GITHUB_OUTPUT"
+          fi
+  tests:
+    needs: check-commit
+    if: needs.check-commit.outputs.run_tests == 'true'
+    name: UNIT_TESTS (precision=${{ matrix.precision }}, mpi=${{ matrix.mpi }}, output=${{ matrix.output }})
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        precision: [single, double]
+        mpi: [ON, OFF]
+        output: [ON, OFF]
+        exclude:
+          - precision: single
+            mpi: ON
+            output: ON
+          - precision: double
+            mpi: ON
+            output: ON
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install GCC 14 and build tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc-14 g++-14 gfortran-14 build-essential wget libevent-dev libhwloc-dev
+          sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-14 50
+          sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-14 50
+          sudo update-alternatives --install /usr/bin/gfortran gfortran /usr/bin/gfortran-14 50
+          gcc --version
+          g++ --version
+      - name: Install CMake (3.x)
+        run: |
+          sudo apt-get install -y cmake
+          cmake --version
+      - name: Install OpenMPI 5
+        run: |
+          sudo apt-get install -y libopenmpi-dev openmpi-bin
+          mpirun --version
+      - name: Configure
+        run: |
+          if [ "${{ matrix.mpi }}" = "ON" ]; then
+            export CC=mpicc
+            export CXX=mpicxx
+          else
+            export CC=gcc-14
+            export CXX=g++-14
+          fi
+          cmake -B build -D TESTS=ON -D precision=${{ matrix.precision }} -D mpi=${{ matrix.mpi }} -D output=${{ matrix.output }}
+      - name: Compile
+        run: cmake --build build -j "$(nproc)"
+      - name: Run tests
+        run: ctest --test-dir build --output-on-failure
+  pgens:
+    needs: check-commit
+    if: needs.check-commit.outputs.run_tests == 'true'
+    name: PGENS (pgen=${{ matrix.pgen }})
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        pgen: [streaming, turbulence, reconnection, shock, magnetosphere, accretion, wald]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install GCC 14 and build tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc-14 g++-14 gfortran-14 build-essential wget libevent-dev libhwloc-dev
+          sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-14 50
+          sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-14 50
+          sudo update-alternatives --install /usr/bin/gfortran gfortran /usr/bin/gfortran-14 50
+          gcc --version
+          g++ --version
+      - name: Install CMake (3.x)
+        run: |
+          sudo apt-get install -y cmake
+          cmake --version
+      - name: Configure
+        run: |
+          cmake -B build -D pgen=${{ matrix.pgen }} -D output=OFF
+      - name: Compile
+        run: cmake --build build -j "$(nproc)"

.github/workflows/actions.yml → .github/workflows/multiarch.yml

@@ -1,11 +1,11 @@
-name: Unit tests
+name: Multi-Arch Local Tests
 
 on:
   push:
 
 jobs:
   check-commit:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     outputs:
       run_tests: ${{ steps.check_message.outputs.run_tests }}
     steps:
@@ -14,7 +14,7 @@ jobs:
       - name: Check commit message
         id: check_message
         run: |
-          if git log -1 --pretty=%B | grep -q "RUNTEST"; then
+          if git log -1 --pretty=%B | grep -q "MARCHTEST"; then
             echo "run_tests=true" >> "$GITHUB_OUTPUT"
           else
             echo "run_tests=false" >> "$GITHUB_OUTPUT"

CITATION

@@ -0,0 +1,43 @@
+As stated in the Code of Conduct document, we have no requirements for any explicit recognition or attribution when using Entity. However, we would greatly appreciate it if you could cite our work in any publications that have benefited from using Entity.
+
+Use the following BibTeX entry to cite the main paper describing the code:
+
+```latex
+@ARTICLE{Entity_2025,
+       author = {{Hakobyan}, Hayk and {B{\"o}ss}, Ludwig M. and {Cai}, Yangyang and {Chernoglazov}, Alexander and {Galishnikova}, Alisa and {Gorbunov}, Evgeny A. and {Mahlmann}, Jens F. and {Philippov}, Alexander and {Solanki}, Siddhant and {Vanthieghem}, Arno and {Zhou}, Muni},
+        title = "{Entity -- Hardware-agnostic Particle-in-Cell Code for Plasma Astrophysics. I: Curvilinear Special Relativistic Module}",
+      journal = {arXiv e-prints},
+     keywords = {High Energy Astrophysical Phenomena, Plasma Physics},
+         year = 2025,
+        month = nov,
+          eid = {arXiv:2511.17710},
+        pages = {arXiv:2511.17710},
+          doi = {10.48550/arXiv.2511.17710},
+archivePrefix = {arXiv},
+       eprint = {2511.17710},
+ primaryClass = {astro-ph.HE},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2025arXiv251117710H},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+```
+
+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}",
+      journal = {arXiv e-prints},
+     keywords = {High Energy Astrophysical Phenomena},
+         year = 2025,
+        month = nov,
+          eid = {arXiv:2511.17701},
+        pages = {arXiv:2511.17701},
+          doi = {10.48550/arXiv.2511.17701},
+archivePrefix = {arXiv},
+       eprint = {2511.17701},
+ primaryClass = {astro-ph.HE},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2025arXiv251117701G},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+```

CMakeLists.txt

@@ -7,7 +7,7 @@ set(PROJECT_NAME entity)
 
 project(
   ${PROJECT_NAME}
-  VERSION 1.2.5
+  VERSION 1.3.0
   LANGUAGES CXX C)
 add_compile_options("-D ENTITY_VERSION=\"${PROJECT_VERSION}\"")
 set(hash_cmd "git diff --quiet src/ && echo $(git rev-parse HEAD) ")
@@ -34,6 +34,15 @@ set(DEBUG
 set(precision
     ${default_precision}
     CACHE STRING "Precision")
+
+set(deposit
+    ${default_deposit}
+    CACHE STRING "Deposit")
+
+set(shape_order
+    ${default_shape_order}
+    CACHE STRING "Shape function")
+
 set(pgen
     ${default_pgen}
     CACHE STRING "Problem generator")
@@ -75,6 +84,20 @@ set(precisions
     "single" "double"
     CACHE STRING "Precisions")
 
+set(deposits
+    "zigzag" "esirkepov"
+    CACHE STRING "Deposits")
+
+if(${deposit} STREQUAL "zigzag")
+  set(shape_order
+      ${default_shape_order}
+      CACHE STRING "Shape functions")
+endif()
+
+set(shape_orders
+    "1;2;3;4;5;6;7;8;9;10;11"
+    CACHE STRING "Shape orders")
+
 include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/config.cmake)
 
 # ------------------------- Third-Party Tests ------------------------------ #
@@ -92,6 +115,7 @@ include_directories(${plog_SRC}/include)
 
 # -------------------------------- Main code ------------------------------- #
 set_precision(${precision})
+set_shape_order(${shape_order})
 if("${Kokkos_DEVICES}" MATCHES "CUDA")
   add_compile_options("-D CUDA_ENABLED")
   set(DEVICE_ENABLED ON)

README.md

@@ -10,6 +10,16 @@ Our [detailed documentation](https://entity-toolkit.github.io/) includes everyth
 
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 
+## News
+
+- [Dec 2025]: **high-order** shape functions [PR #109](https://github.com/entity-toolkit/entity/pull/109) and advanced field stencils [PR #103](https://github.com/entity-toolkit/entity/pull/103) are now supported.
+- [Dec 2025]: **particle tracking** is now fully supported via [PR #144](https://github.com/entity-toolkit/entity/pull/144).
+- [Nov 2025]: our **method papers** are online: [Special relativistic module](https://ui.adsabs.harvard.edu/abs/2025arXiv251117710H/abstract), [GR module](https://ui.adsabs.harvard.edu/abs/2025arXiv251117701G/abstract)!
+
+## Citation
+
+Please, see the `CITATION` document for the relevant BibTeX entries if you would like to cite one of the method papers for the code.
+
 ## Join the community
 
 Everyone is welcome to join our small yet steadily growing community of code users and developers; regardless of how much you are planning to contribute -- we always welcome fresh ideas and feedback. We hold weekly Slack calls on Mondays at 12pm NY time, and have a dedicated Slack channel where you can be easily added by emailing one of the maintainers (indicated with an asterisk in the list below). Anyone is welcome to join both our **Slack workspace** and the weekly meetings -- please feel free to request access by emailing.
@@ -43,3 +53,4 @@ Maintainers indicated with an arrow.
 - All `bug/` and `dev/` branches must have an open pull-request describing in detail its purpose.
 - Before merging to the master branch, all the branches must first be merged to the latest release-candidate branch, which ends with `rc`, via a pull request. This can either be a major release: `1.X.0rc`, or a patch release `1.X.Yrc`. 
 - Stale branches will be archived with a tag starting with `archive/` (can still be accessed via the "Tags" tab) and removed.
+

cmake/adios2Config.cmake

@@ -13,7 +13,7 @@ set(ADIOS2_USE_Fortran
 
 # Format/compression support
 set(ADIOS2_USE_HDF5
-    ON
+    OFF
     CACHE BOOL "Use HDF5 for ADIOS2")
 
 set(ADIOS2_USE_MPI

cmake/benchmark.cmake

@@ -20,7 +20,7 @@ add_executable(${exec} ${src})
 
 set(libs ntt_global ntt_metrics ntt_kernels ntt_archetypes ntt_framework)
 if(${output})
-  list(APPEND libs ntt_output ntt_checkpoint)
+  list(APPEND libs ntt_output)
 endif()
 add_dependencies(${exec} ${libs})
 target_link_libraries(${exec} PRIVATE ${libs} stdc++fs)

cmake/config.cmake

@@ -16,6 +16,16 @@ function(set_precision precision_name)
   endif()
 endfunction()
 
+# ------------------------------- Shape function --------------------------- #
+function(set_shape_order shape_order)
+  if(${deposit} STREQUAL "esirkepov")
+    if(${shape_order} GREATER 11)
+      message(FATAL_ERROR "Shape order must be between 1 and 11.")
+    endif()
+    add_compile_options("-DSHAPE_ORDER=${shape_order}")
+  endif()
+endfunction()
+
 # ---------------------------- Problem generator --------------------------- #
 function(set_problem_generator pgen_name)
   if(pgen_name STREQUAL ".")

cmake/defaults.cmake

@@ -19,6 +19,12 @@ set(default_engine
 set(default_precision
     "single"
     CACHE INTERNAL "Default precision")
+set(default_deposit
+    "zigzag"
+    CACHE INTERNAL "Default deposit")
+set(default_shape_order
+    1
+    CACHE INTERNAL "Default shape function order")
 set(default_pgen
     "."
     CACHE INTERNAL "Default problem generator")

cmake/dependencies.cmake

@@ -58,7 +58,12 @@ function(find_or_fetch_dependency package_name header_only mode)
         FetchContent_Declare(
           ${package_name}
           GIT_REPOSITORY ${${package_name}_REPOSITORY}
-          GIT_TAG 4.6.01)
+          GIT_TAG 4.7.01)
+      elseif(${package_name} STREQUAL "adios2")
+        FetchContent_Declare(
+          ${package_name}
+          GIT_REPOSITORY ${${package_name}_REPOSITORY}
+          GIT_TAG v2.10.2)
       else()
         FetchContent_Declare(${package_name}
                              GIT_REPOSITORY ${${package_name}_REPOSITORY})

cmake/report.cmake

@@ -37,6 +37,24 @@ printchoices(
   "${Blue}"
   PRECISION_REPORT
   46)
+printchoices(
+  "Deposit"
+  "deposit"
+  "${deposits}"
+  ${deposit}
+  ${default_deposit}
+  "${Blue}"
+  DEPOSIT_REPORT
+  46)
+printchoices(
+  "Shape order"
+  "shape_order"
+  "${shape_orders}"
+  ${shape_order}
+  ${default_shape_order}
+  "${Blue}"
+  SHAPEFUNCTION_REPORT
+  46)
 printchoices(
   "Output"
   "output"
@@ -113,6 +131,12 @@ string(
   ${PRECISION_REPORT}
   "\n"
   "  "
+  ${DEPOSIT_REPORT}
+  "\n"
+  "  "
+  ${SHAPEFUNCTION_REPORT}
+  "\n"
+  "  "
   ${OUTPUT_REPORT}
   "\n")
 

cmake/styling.cmake

@@ -140,27 +140,30 @@ function(
   else()
     padto("${rstring}" " " ${Padding} rstring)
 
-    set(new_choices ${Choices})
-    foreach(ch IN LISTS new_choices)
-      string(REPLACE ${ch} "${Dim}${ch}${ColorReset}" new_choices
-                     "${new_choices}")
-    endforeach()
-    set(Choices ${new_choices})
     if(${Value} STREQUAL "ON")
       set(col ${Green})
     elseif(${Value} STREQUAL "OFF")
       set(col ${Red})
     else()
       set(col ${Color})
     endif()
-    if(NOT "${Value}" STREQUAL "")
-      string(REPLACE ${Value} "${col}${Value}${ColorReset}" Choices
-                     "${Choices}")
-    endif()
-    if(NOT "${Default}" STREQUAL "")
-      string(REPLACE ${Default} "${Underline}${Default}${ColorReset}" Choices
-                     "${Choices}")
-    endif()
+    set(new_choices "")
+    foreach(ch IN LISTS Choices)
+      set(elem "${ch}")
+      if((NOT "${Value}" STREQUAL "") AND (${ch} STREQUAL ${Value}))
+        set(elem "${col}${ch}${ColorReset}")
+      else()
+        set(elem "${Dim}${ch}${ColorReset}")
+      endif()
+      if((NOT "${Default}" STREQUAL "") AND (${ch} STREQUAL ${Default}))
+        set(elem "${Underline}${elem}${ColorReset}")
+      endif()
+      string(APPEND new_choices "${elem};")
+    endforeach()
+    string(LENGTH "${new_choices}" nlen)
+    math(EXPR nlen "${nlen} - 1")
+    string(SUBSTRING "${new_choices}" 0 ${nlen} new_choices)
+    set(Choices ${new_choices})
     string(REPLACE ";" "/" Choices "${Choices}")
     string(APPEND rstring "${Choices}")
   endif()