Development into branch quad_spin_push

.github/workflows/codeql.yml

@@ -28,7 +28,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - uses: actions/setup-python@v6
         name: Install Python

.github/workflows/cuda.yml

@@ -30,14 +30,14 @@ jobs:
         docker-images: true
         swap-storage: false
 
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
 
     - name: install dependencies
       run: |
         .github/workflows/dependencies/nvcc11-openmpi.sh
 
     - name: CCache Cache
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       # - once stored under a key, they become immutable (even if local cache path content changes)
       # - for a refresh the key has to change, e.g., hash of a tracked file in the key
       with:
@@ -64,4 +64,4 @@ jobs:
           -DImpactX_PRECISION=SINGLE   \
           -DAMReX_CUDA_ERROR_CROSS_EXECUTION_SPACE_CALL=ON \
           -DAMReX_CUDA_ERROR_CAPTURE_THIS=ON
-        cmake --build build -j 4
+        cmake --build build -j 3

.github/workflows/hip.yml

@@ -15,14 +15,14 @@ jobs:
       CMAKE_GENERATOR: Ninja
     if: github.event.pull_request.draft == false
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
 
     - name: install dependencies
       shell: bash
       run: .github/workflows/dependencies/hip-openmpi.sh 6.3.2
 
     - name: CCache Cache
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       # - once stored under a key, they become immutable (even if local cache path content changes)
       # - for a refresh the key has to change, e.g., hash of a tracked file in the key
       with:

.github/workflows/macos.yml

@@ -14,7 +14,7 @@ jobs:
     env:
       HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK: TRUE
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
     - uses: actions/setup-python@v6
       name: Install Python
       with:
@@ -46,7 +46,7 @@ jobs:
         python3 -m pip install --upgrade pipx
         python3 -m pipx install openPMD-validator
     - name: CCache Cache
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       # - once stored under a key, they become immutable (even if local cache path content changes)
       # - for a refresh the key has to change, e.g., hash of a tracked file in the key
       with:
@@ -81,7 +81,7 @@ jobs:
 
     - name: Upload dashboard screenshots
       if: always()
-      uses: actions/upload-artifact@v5
+      uses: actions/upload-artifact@v6
       with:
         name: dashboard-screenshots-macos
         path: |

.github/workflows/source.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-24.04
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
 
     - name: Non-ASCII characters
       run: .github/workflows/source/hasNonASCII

.github/workflows/stubs.yml

@@ -18,10 +18,10 @@ jobs:
       OMP_NUM_THREAD: 4
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
       if: github.event_name != 'push' || github.repository != 'BLAST-ImpactX/impactx' || github.ref != 'refs/heads/development'
 
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
       if: github.event_name == 'push' && github.repository == 'BLAST-ImpactX/impactx' && github.ref == 'refs/heads/development'
       with:
         token: ${{ secrets.IMPACTX_PUSH_TOKEN }}
@@ -41,7 +41,7 @@ jobs:
         python3 -m pip install -U pybind11-stubgen pre-commit
 
     - name: Set Up Cache
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       with:
         path: ~/.cache/ccache
         key: ccache-${{ github.workflow }}-${{ github.job }}-git-${{ github.sha }}

.github/workflows/tooling.yml

@@ -12,14 +12,14 @@ jobs:
     runs-on: ubuntu-22.04
     if: github.event.pull_request.draft == false
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
 
     - name: install dependencies
       run: |
         .github/workflows/dependencies/clang-san-openmpi.sh
 
     - name: CCache Cache
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       # - once stored under a key, they become immutable (even if local cache path content changes)
       # - for a refresh the key has to change, e.g., hash of a tracked file in the key
       with:

.github/workflows/ubuntu.yml

@@ -27,14 +27,14 @@ jobs:
         docker-images: true
         swap-storage: false
 
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
 
     - name: install dependencies
       run: |
         .github/workflows/dependencies/gcc-openmpi.sh
 
     - name: CCache Cache
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       # - once stored under a key, they become immutable (even if local cache path content changes)
       # - for a refresh the key has to change, e.g., hash of a tracked file in the key
       with:
@@ -71,7 +71,7 @@ jobs:
 
     - name: Upload dashboard screenshots
       if: always()
-      uses: actions/upload-artifact@v5
+      uses: actions/upload-artifact@v6
       with:
         name: dashboard-screenshots-ubuntu
         path: |
@@ -121,14 +121,14 @@ jobs:
         docker-images: true
         swap-storage: false
 
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
 
     - name: install dependencies
       run: |
         .github/workflows/dependencies/gcc.sh
 
     - name: CCache Cache
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       # - once stored under a key, they become immutable (even if local cache path content changes)
       # - for a refresh the key has to change, e.g., hash of a tracked file in the key
       with:

.github/workflows/windows.yml

@@ -12,13 +12,13 @@ jobs:
     runs-on: windows-latest
     if: github.event.pull_request.draft == false
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
     - uses: actions/setup-python@v6
       name: Install Python
       with:
         python-version: '3.12'
     - name: CCache Cache
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       # - once stored under a key, they become immutable (even if local cache path content changes)
       # - for a refresh the key has to change, e.g., hash of a tracked file in the key
       with:
@@ -130,13 +130,13 @@ jobs:
     runs-on: windows-2025
     if: github.event.pull_request.draft == false
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
     - uses: actions/setup-python@v6
       name: Install Python
       with:
         python-version: '3.11'
     - name: CCache Cache
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       # - once stored under a key, they become immutable (even if local cache path content changes)
       # - for a refresh the key has to change, e.g., hash of a tracked file in the key
       with:

.pre-commit-config.yaml

@@ -66,7 +66,7 @@ repos:
 # Python: Ruff linter & formatter
 #   https://docs.astral.sh/ruff/
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.14.4
+  rev: v0.14.9
   hooks:
     # Run the linter
     - id: ruff-check

CMakeLists.txt

@@ -1,7 +1,7 @@
 # Preamble ####################################################################
 #
 cmake_minimum_required(VERSION 3.24.0)
-project(ImpactX VERSION 25.11)
+project(ImpactX VERSION 25.12)
 
 include(${ImpactX_SOURCE_DIR}/cmake/ImpactXFunctions.cmake)
 

cmake/dependencies/ABLASTR.cmake

@@ -139,7 +139,7 @@ macro(find_ablastr)
         set(COMPONENT_DIM 3D)
         set(COMPONENT_PRECISION ${ImpactX_PRECISION} P${ImpactX_PRECISION})
 
-        find_package(ABLASTR 25.11 CONFIG REQUIRED COMPONENTS ${COMPONENT_DIM})
+        find_package(ABLASTR 25.12 CONFIG REQUIRED COMPONENTS ${COMPONENT_DIM})
         message(STATUS "ABLASTR: Found version '${ABLASTR_VERSION}'")
     endif()
 
@@ -178,15 +178,15 @@ set(ImpactX_openpmd_src ""
 set(ImpactX_ablastr_repo "https://github.com/BLAST-WarpX/warpx.git"
     CACHE STRING
     "Repository URI to pull and build ABLASTR from if(ImpactX_ablastr_internal)")
-set(ImpactX_ablastr_branch "25.11"
+set(ImpactX_ablastr_branch "25.12"
     CACHE STRING
     "Repository branch for ImpactX_ablastr_repo if(ImpactX_ablastr_internal)")
 
 # AMReX is transitively pulled through ABLASTR
 set(ImpactX_amrex_repo "https://github.com/AMReX-Codes/amrex.git"
     CACHE STRING
     "Repository URI to pull and build AMReX from if(ImpactX_amrex_internal)")
-set(ImpactX_amrex_branch ""
+set(ImpactX_amrex_branch "4dad1664d7467ae00c133c1425c1a300003fa885"
     CACHE STRING
     "Repository branch for ImpactX_amrex_repo if(ImpactX_amrex_internal)")
 

cmake/dependencies/pyAMReX.cmake

@@ -59,7 +59,7 @@ function(find_pyamrex)
         endif()
     elseif(NOT ImpactX_pyamrex_internal)
         # TODO: MPI control
-        find_package(pyAMReX 25.11 CONFIG REQUIRED)
+        find_package(pyAMReX 25.12 CONFIG REQUIRED)
         message(STATUS "pyAMReX: Found version '${pyAMReX_VERSION}'")
     endif()
 endfunction()
@@ -74,7 +74,7 @@ option(ImpactX_pyamrex_internal "Download & build pyAMReX" ON)
 set(ImpactX_pyamrex_repo "https://github.com/AMReX-Codes/pyamrex.git"
     CACHE STRING
     "Repository URI to pull and build pyamrex from if(ImpactX_pyamrex_internal)")
-set(ImpactX_pyamrex_branch "25.11"
+set(ImpactX_pyamrex_branch "74e213e3186371d5a7412af3d2a5d6040fab51ce"
     CACHE STRING
     "Repository branch for ImpactX_pyamrex_repo if(ImpactX_pyamrex_internal)")
 

docs/README.md

@@ -6,10 +6,13 @@ This explains how to generate the documentation for ImpactX, and contribute to i
 
 ### Installing the requirements
 
-Install the Python requirements for compiling the documentation:
-```
-pip install sphinx sphinx_rtd_theme
-```
+`cd` into the ImpactX `docs/` directory.
+Install the Python requirements for compiling the documentation with **one** of the following package managers:
+
+- pip: `pip install -U -r requirements.txt`
+- uv: `uv pip install -U -r requirements.txt`
+- conda: `conda create -n readthedocs -f conda.yml && conda activate readthedocs`
+- spack: `spack env activate -d . && spack install`
 
 ### Compiling the documentation
 

docs/source/conf.py

@@ -96,9 +96,9 @@ def download_with_headers(url, filename):
 # built documents.
 #
 # The short X.Y version.
-version = "25.11"
+version = "25.12"
 # The full version, including alpha/beta/rc tags.
-release = "25.11"
+release = "25.12"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/install/dependencies.rst

@@ -32,11 +32,12 @@ Optional dependencies include:
 - `Ninja <https://ninja-build.org>`__: for faster parallel compiles
 - `Python 3.9+ <https://www.python.org>`__
 
+  - `matplotlib 3.3+ <https://matplotlib.org>`__
   - `mpi4py <https://mpi4py.readthedocs.io>`__
   - `numpy <https://numpy.org>`__
+  - `openPMD-api <https://github.com/openPMD/openPMD-api>`__
   - `pals-schema <https://github.com/campa-consortium/pals-python>`__
   - `quantiphy <https://quantiphy.readthedocs.io/>`__
-  - `openPMD-api <https://github.com/openPMD/openPMD-api>`__
   - see our ``requirements.txt`` file for compatible versions
   - web browser/Jupyter Dashboard: `trame <https://kitware.github.io/trame/>`__
 

docs/source/install/hpc/perlmutter-nersc/perlmutter_gpu_impactx.profile.example

@@ -37,10 +37,10 @@ fi
 
 # an alias to request an interactive batch node for one hour
 #   for parallel execution, start on the batch node: srun <command>
-alias getNode="salloc -N 1 --ntasks-per-node=4 -t 1:00:00 -q interactive -C gpu --gpu-bind=single:1 -c 32 -G 4 -A $proj"
+alias getNode="salloc -N 1 --ntasks-per-node=4 -t 1:00:00 -q interactive -C gpu --gpu-bind=none -c 32 -G 4 -A $proj"
 # an alias to run a command on a batch node for up to 30min
 #   usage: runNode <command>
-alias runNode="srun -N 1 --ntasks-per-node=4 -t 0:30:00 -q interactive -C gpu --gpu-bind=single:1 -c 32 -G 4 -A $proj"
+alias runNode="srun -N 1 --ntasks-per-node=4 -t 0:30:00 -q interactive -C gpu --gpu-bind=none -c 32 -G 4 -A $proj"
 
 # necessary to use CUDA-Aware MPI and run a job
 export CRAY_ACCEL_TARGET=nvidia80

docs/source/usage/examples.rst

@@ -30,6 +30,7 @@ Single Particle Dynamics
    examples/kicker/README.rst
    examples/thin_dipole/README.rst
    examples/aperture/README.rst
+   examples/polygon_aperture/README.rst
    examples/iota_lens/README.rst
    examples/achromatic_spectrometer/README.rst
    examples/fodo_userdef/README.rst

docs/source/usage/howto/add_element.rst

@@ -98,7 +98,7 @@ As a last step, we expose our C++ beamline elements to Python in `src/python/ele
       :language: cpp
       :dedent: 4
       :start-at: py::class_<Drift, elements::mixin::Named, elements::mixin::Thick, elements::mixin::Alignment, elements::mixin::PipeAperture> py_Drift(me, "Drift");
-      :end-at: register_envelope_push(py_Drift);
+      :end-at: register_push(py_Drift);
 
 Pull requests that added a new element and can be taken as examples are: