Merge development into 2D space charge PR

.github/workflows/codeql.yml

@@ -56,14 +56,14 @@ jobs:
           cmake -S . -B build -DImpactX_FFT=ON -DImpactX_PYTHON=OFF
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v3
+        uses: github/codeql-action/init@v4
         with:
           config-file: ./.github/codeql/impactx-codeql.yml
           languages: ${{ matrix.language }}
           queries: +security-and-quality
 
       - name: Build (py)
-        uses: github/codeql-action/autobuild@v3
+        uses: github/codeql-action/autobuild@v4
         if: ${{ matrix.language == 'python' }}
         env:
           IMPACTX_FFT: ON
@@ -74,7 +74,7 @@ jobs:
           cmake --build build -j 4
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v3
+        uses: github/codeql-action/analyze@v4
         with:
           category: "/language:${{ matrix.language }}"
           upload: False
@@ -96,6 +96,6 @@ jobs:
           output: sarif-results/${{ matrix.language }}.sarif
 
       - name: Upload SARIF
-        uses: github/codeql-action/upload-sarif@v3
+        uses: github/codeql-action/upload-sarif@v4
         with:
           sarif_file: sarif-results/${{ matrix.language }}.sarif

.github/workflows/stubs.yml

@@ -83,7 +83,7 @@ jobs:
       run: |
         mpiexec -np 1 python3 -m pytest tests/python/ --ignore=tests/python/dashboard
 
-    - uses: stefanzweifel/git-auto-commit-action@v6
+    - uses: stefanzweifel/git-auto-commit-action@v7
       name: Commit Updated Stub Files
       if: github.event_name == 'push' && github.repository == 'BLAST-ImpactX/impactx' && github.ref == 'refs/heads/development'
       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.13.1
+  rev: v0.14.0
   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.09)
+project(ImpactX VERSION 25.10)
 
 include(${ImpactX_SOURCE_DIR}/cmake/ImpactXFunctions.cmake)
 
@@ -492,6 +492,13 @@ if(ImpactX_PYTHON)
             pyImpactX
             ${ImpactX_CUSTOM_TARGET_PREFIX}pip_wheel
     )
+
+    # copy examples into pip package, e.g., for dashboard GUI
+    add_custom_command(TARGET pyImpactX POST_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy_directory
+            ${ImpactX_SOURCE_DIR}/examples
+            $<TARGET_FILE_DIR:pyImpactX>/examples
+    )
 endif()
 
 

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.09 CONFIG REQUIRED COMPONENTS ${COMPONENT_DIM})
+        find_package(ABLASTR 25.10 CONFIG REQUIRED COMPONENTS ${COMPONENT_DIM})
         message(STATUS "ABLASTR: Found version '${ABLASTR_VERSION}'")
     endif()
 
@@ -178,7 +178,7 @@ 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 "a76eecf1553f5d0e72ec948c9a67db4111a1544f"
+set(ImpactX_ablastr_branch "5dc12e9de9fc1428d4ad4d6c132043abedc8c531"
     CACHE STRING
     "Repository branch for ImpactX_ablastr_repo if(ImpactX_ablastr_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.09 CONFIG REQUIRED)
+        find_package(pyAMReX 25.10 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.09"
+set(ImpactX_pyamrex_branch "de24942c76ebc61ffaa184204c2491aebc357a07"
     CACHE STRING
     "Repository branch for ImpactX_pyamrex_repo if(ImpactX_pyamrex_internal)")
 

docs/source/conf.py

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

docs/source/usage/python.rst

@@ -639,6 +639,60 @@ This module provides elements and methods for the accelerator lattice.
       :param pals_line: PALS Python Line with beamline elements
       :param nslice: number of slices used for the application of collective effects
 
+   .. py:method:: select(kind=None, name=None)
+
+      Filter elements by type and/or name.
+      If both are provided, OR-based logic is applied.
+
+      Returns references to original elements, allowing modification and chaining.
+      Chained ``.select(...).select(...)`` selections are AND-filtered.
+
+      :param kind: Element type(s) to filter by. Can be a string (e.g., ``"Drift"``), regex pattern (e.g., ``r".*Quad"``), element type (e.g., ``elements.Drift``), or list/tuple of these.
+      :param name: Element name(s) to filter by. Can be a string, regex pattern, or ``list``/``tuple`` of these.
+
+      **Examples:**
+
+      .. code-block:: python
+
+         # Filter by element type
+         drift_elements = lattice.select(kind="Drift")
+         quad_elements = lattice.select(kind=elements.Quad)
+
+         # Filter by regex pattern
+         all_quads = lattice.select(kind=r".*Quad")  # matches Quad, ChrQuad, ExactQuad
+
+         # Filter by name
+         specific_elements = lattice.select(name="quad1")
+
+         # Chain filters (AND logic)
+         drift_named_d1 = lattice.select(kind="Drift").select(name="drift1")
+
+         # Modify original elements through references
+         drift_elements[0].ds = 2.0  # modifies original lattice
+
+   .. py:method:: get_kinds()
+
+      Get all unique element types in the lattice.
+
+      :return: List of unique element types (sorted by name)
+      :rtype: list[type]
+
+   .. py:method:: count_by_kind(kind_pattern)
+
+      Count elements of a specific kind.
+
+      :param kind_pattern: Element kind to count. Can be string (e.g., "Drift"), regex pattern (e.g., r".*Quad"), or element type (e.g., elements.Drift)
+      :return: Number of elements of the specified kind
+      :rtype: int
+
+   .. py:method:: has_kind(kind_pattern)
+
+      Check if list contains elements of a specific kind.
+
+      :param kind_pattern: Element kind to check for. Can be string (e.g., "Drift"), regex pattern (e.g., r".*Quad"), or element type (e.g., elements.Drift)
+      :return: True if at least one element of the specified kind exists
+      :rtype: bool
+
    .. py:method:: plot_survey(ref=None, ax=None, legend=True, legend_ncols=5)
 
       Plot over s of all elements in the KnownElementsList.

examples/dogleg/README.rst

@@ -15,7 +15,7 @@ The final expected dispersion is 267 mm.
 In this test, the initial and final values of :math:`\sigma_x`, :math:`\sigma_y`, :math:`\sigma_t`, :math:`\epsilon_x`, :math:`\epsilon_y`, and :math:`\epsilon_t` must
 agree with nominal values.
 
-In addition, the initial and final values of :math:`\alpha_x`, :math:`\alpha_y`, :math:`\beta_x`, :math:`\beta_y`, :math:`\dispersion_x`, and :math:`\dispersion_px` must
+In addition, the initial and final values of :math:`\alpha_x`, :math:`\alpha_y`, :math:`\beta_x`, :math:`\beta_y`, :math:`D_x`, and :math:`D_{px}` must
 agree with nominal values.
 
 
@@ -73,7 +73,7 @@ The initial dispersion is taken to be -267 mm.
 In this test, the initial and final values of :math:`\sigma_x`, :math:`\sigma_y`, :math:`\sigma_t`, :math:`\epsilon_x`, :math:`\epsilon_y`, and :math:`\epsilon_t` must
 agree with nominal values.
 
-In addition, the initial and final values of :math:`\alpha_x`, :math:`\alpha_y`, :math:`\beta_x`, :math:`\beta_y`, :math:`\dispersion_x`, and :math:`\dispersion_px` must
+In addition, the initial and final values of :math:`\alpha_x`, :math:`\alpha_y`, :math:`\beta_x`, :math:`\beta_y`, :math:`D_x`, and :math:`D_{px}` must
 agree with nominal values.
 
 Run
@@ -128,10 +128,10 @@ The 2.5% energy offset couples through the lattice R16 (dispersion) to result in
 In this test, the initial and final values of :math:`\sigma_x`, :math:`\sigma_y`, :math:`\sigma_t`, :math:`\epsilon_x`, :math:`\epsilon_y`, and :math:`\epsilon_t` must
 agree with nominal values.
 
-In addition, the initial and final values of :math:`\alpha_x`, :math:`\alpha_y`, :math:`\beta_x`, :math:`\beta_y`, :math:`\dispersion_x`, and :math:`\dispersion_px` must
+In addition, the initial and final values of :math:`\alpha_x`, :math:`\alpha_y`, :math:`\beta_x`, :math:`\beta_y`, :math:`D_x`, and :math:`D_{px}` must
 agree with nominal values.
 
-Finally, the values of :math:`\mean_pt`, :math:`\mean_x`, and :math:`\mean_px` must agree with predicted values.
+Finally, the values of :math:`\mean_pt`, :math:`\mean_x`, and :math:`\mean_{px}` must agree with predicted values.
 
 Run
 ---

examples/initialize_from_array/README.rst

@@ -19,7 +19,7 @@ In this example, a custom beam is specified at fixed t, transformed to fixed s,
 then loaded in ImpactX.
 The custom beam is a ring in x-y,
 with radius r=2 mm,
-radial width :math:`\sigma_r = 5\ \mu`m;
+radial width :math:`\sigma_r = 5\ \mathrm{\mu m}`;
 Gaussian in :math:`p_x` and :math:`p_y` with momentum width :math:`\sigma_p=10`;
 and chirped in z-pz with bunch length :math:`\sigma_z=1` mm,
 mean energy about 10 GeV, 1% uncorrelated energy spread, and z-pz covariance of -0.18.

examples/pals/fodo.pals.yaml

@@ -1,21 +1,22 @@
-kind: BeamLine
-line:
-- drift1:
-    kind: Drift
-    length: 0.25
-- quad1:
-    MagneticMultipoleP:
-      Bn1: 1.0
-    kind: Quadrupole
-    length: 1.0
-- drift2:
-    kind: Drift
-    length: 0.5
-- quad2:
-    MagneticMultipoleP:
-      Bn1: -1.0
-    kind: Quadrupole
-    length: 1.0
-- drift3:
-    kind: Drift
-    length: 0.25
+fodo_cell:
+  kind: BeamLine
+  line:
+  - drift1:
+      kind: Drift
+      length: 0.25
+  - quad1:
+      MagneticMultipoleP:
+        Bn1: 1.0
+      kind: Quadrupole
+      length: 1.0
+  - drift2:
+      kind: Drift
+      length: 0.5
+  - quad2:
+      MagneticMultipoleP:
+        Bn1: -1.0
+      kind: Quadrupole
+      length: 1.0
+  - drift3:
+      kind: Drift
+      length: 0.25

requirements.txt

@@ -1,3 +1,3 @@
 numpy>=1.15
-pals-schema~=0.1.1
+pals-schema~=0.2.0
 quantiphy~=2.19

setup.py

@@ -237,7 +237,7 @@ def build_extension(self, ext):
 setup(
     name="impactx",
     # note PEP-440 syntax: x.y.zaN but x.y.z.devN
-    version="25.09",
+    version="25.10",
     packages=["impactx"],
     # Python sources:
     package_dir={"": "src/python"},

src/elements/Empty.H

@@ -13,20 +13,21 @@
 #include "particles/ImpactXParticleContainer.H"
 #include "mixin/thin.H"
 #include "mixin/lineartransport.H"
+#include "mixin/named.H"
 #include "mixin/nofinalize.H"
 
 #include <AMReX_Extension.H>
 #include <AMReX_REAL.H>
 #include <AMReX_SIMD.H>
 
-#include <stdexcept>
-#include <string>
+#include <optional>
 
 
 namespace impactx::elements
 {
     struct Empty
-    : public mixin::Thin,
+    : public mixin::Named,
+      public mixin::Thin,
       public mixin::LinearTransport<Empty>,
       public mixin::NoFinalize,
       public amrex::simd::Vectorized<amrex::simd::native_simd_size_particlereal>
@@ -37,6 +38,7 @@ namespace impactx::elements
         /** This element does nothing.
          */
         Empty ()
+        : Named(std::nullopt)
         {
         }
 
@@ -118,14 +120,6 @@ namespace impactx::elements
 
         /** This pushes the covariance matrix. */
         using LinearTransport::operator();
-
-        /** Provide impactx::elements::mixin::Named::name */
-        AMREX_FORCE_INLINE
-        std::string name () const { throw std::runtime_error("Name not set on element!"); }
-
-        /** Provide impactx::elements::mixin::Named::has_name */
-        AMREX_FORCE_INLINE
-        bool has_name () const { return false; }
     };
 
 } // namespace impactx

src/elements/RFCavity.H

@@ -408,7 +408,7 @@ namespace RFCavityData
             }
             else  // endpoint of the RF, outsize zlen
             {
-               efieldint = std::copysign(z, z)*zmid*0.5_prt*cos_data[0];;
+               efieldint = std::copysign(zmid, z)*0.5_prt*cos_data[0];
                for (int j=1; j < m_ncoef; ++j)
                {
                  efieldint = efieldint - zlen*sin_data[j] * std::cos(j*pi)/(j*2*pi);

src/elements/diagnostics/BeamMonitor.H

@@ -176,8 +176,12 @@ namespace detail
         finalize ();
 
     private:
+        /** Open the openPMD series (on first access) */
+        void open ();
+
         std::string m_series_name; //! openPMD filename
         std::string m_OpenPMDFileType; //! openPMD backend: usually HDF5 (h5) or ADIOS2 (bp/bp4/bp5) or ADIOS2 SST (sst)
+        std::string m_encoding; //! openPMD iteration encoding: "v"ariable based, "f"ile based, "g"roup based (default)
         std::any m_series; //! openPMD::Series that holds potentially multiple outputs
         int m_step = 0; //! global step for output
 

src/elements/diagnostics/BeamMonitor.cpp

@@ -124,7 +124,10 @@ namespace detail {
     }
 
     BeamMonitor::BeamMonitor (std::string series_name, std::string backend, std::string encoding, int period_sample_intervals) :
-        m_series_name(std::move(series_name)), m_OpenPMDFileType(std::move(backend)), m_period_sample_intervals(period_sample_intervals)
+        m_series_name(std::move(series_name)), m_OpenPMDFileType(std::move(backend)), m_encoding(std::move(encoding)), m_period_sample_intervals(period_sample_intervals) {
+    }
+
+    void BeamMonitor::open ()
     {
 #ifdef ImpactX_USE_OPENPMD
         // pick first available backend if default is chosen
@@ -141,11 +144,11 @@ namespace detail {
 
         // encoding of iterations in the series
         openPMD::IterationEncoding series_encoding = openPMD::IterationEncoding::groupBased;
-        if ("v" == encoding)
+        if ("v" == m_encoding)
             series_encoding = openPMD::IterationEncoding::variableBased;
-        else if ("g" == encoding)
+        else if ("g" == m_encoding)
             series_encoding = openPMD::IterationEncoding::groupBased;
-        else if ("f" == encoding)
+        else if ("f" == m_encoding)
             series_encoding = openPMD::IterationEncoding::fileBased;
 
         // BP5 does not support groupBased (metadata explosion)
@@ -310,6 +313,8 @@ namespace detail {
         if (period % m_period_sample_intervals != 0)
             return;
 
+        this->open();
+
 #ifdef ImpactX_USE_OPENPMD
         std::string profile_name = "impactx::push::" + std::string(BeamMonitor::type);
         BL_PROFILE(profile_name);

src/initialization/Warnings.cpp

@@ -66,7 +66,9 @@ bool ImpactX::early_param_check ()
     int verbose = 1;
     pp_impactx.queryAddWithParser("verbose", verbose);
 
-    if (verbose > 0) {
+    // Print a warning for unused inputs early on, so users are informed and
+    // might decide to abort their long-running runs, if needed.
+    if (verbose > 0 && amrex::ParmParse::hasUnusedInputs()) {
         amrex::Print() << "\n";
     }
     amrex::ParmParse::QueryUnusedInputs();