Merge development into 2D space charge PR (#9)

* [pre-commit.ci] pre-commit autoupdate (BLAST-ImpactX#1161)

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.13.1 → v0.13.2](astral-sh/ruff-pre-commit@v0.13.1...v0.13.2)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

* [pre-commit.ci] pre-commit autoupdate (BLAST-ImpactX#1165)

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.13.2 → v0.13.3](astral-sh/ruff-pre-commit@v0.13.2...v0.13.3)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

* Gauss 3D: Fix Push Constants (BLAST-ImpactX#1168)

This fixes the push constants for non-equal x,y,z and
adds an end-point correction for the integration. It
also changes the number of integration points by default
to 101 instead of 401.

Co-authored-by: Ji Qiang <[email protected]>

* [pre-commit.ci] pre-commit autoupdate (BLAST-ImpactX#1174)

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.13.3 → v0.14.0](astral-sh/ruff-pre-commit@v0.13.3...v0.14.0)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

* Bump stefanzweifel/git-auto-commit-action from 6 to 7 (BLAST-ImpactX#1175)

Bumps [stefanzweifel/git-auto-commit-action](https://github.com/stefanzweifel/git-auto-commit-action) from 6 to 7.
- [Release notes](https://github.com/stefanzweifel/git-auto-commit-action/releases)
- [Changelog](https://github.com/stefanzweifel/git-auto-commit-action/blob/master/CHANGELOG.md)
- [Commits](stefanzweifel/git-auto-commit-action@v6...v7)

---
updated-dependencies:
- dependency-name: stefanzweifel/git-auto-commit-action
  dependency-version: '7'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Bump github/codeql-action from 3 to 4 (BLAST-ImpactX#1176)

Bumps [github/codeql-action](https://github.com/github/codeql-action) from 3 to 4.
- [Release notes](https://github.com/github/codeql-action/releases)
- [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md)
- [Commits](github/codeql-action@v3...v4)

---
updated-dependencies:
- dependency-name: github/codeql-action
  dependency-version: '4'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Fix `BeamMonitor`: Delay Open (BLAST-ImpactX#1178)

`BeamMonitor` opens the openPMD series now on first output. This
simplifies usage dramatically, now allowing to:

* create the lattice (monitor elements) before the `sim` is even
  initialized
* creating a monitor element and not using it in a lattice

* CMake `pip_install`: Package Examples (BLAST-ImpactX#1179)

Ensure the `examples/` directory is part of the `pip` wheels
we build, e.g., on `cmake --build build -j 6 --target pip_install`

* Envelope: Silence Warning w/o Space-Charge (BLAST-ImpactX#1173)

Consistent with the other two tracking modes, we only
print options upfront and do not warn every simulation
step if space charge is not used.

* Release 25.10 (BLAST-ImpactX#1180)

* Update Stub Files

* AMReX/ABLASTR/WarpX: development (BLAST-ImpactX#1177)

* ABLASTR/WarpX: development

Update the ABLASTR dependency to the latest development branch.

* pyAMReX: `development`

* Python: Improve `KnownElementsList` (BLAST-ImpactX#1181)

Add per-element by-reference access for manipulation.

* Update Stub Files

* Element Selection Syntax (BLAST-ImpactX#1182)

* Implementation

5hr vibe pair coded in Cursor. Maybe should have just done it xD

* Doc

* Fix Type Hints

* `select`: Fix All-Selected Path

Avoid implicit return of `None`

* Cleanup

* Update Stub Files

* Fix Python import errors (BLAST-ImpactX#1186)

* Update Stub Files

* Fix RFCavity edge case (BLAST-ImpactX#1185)

* Fix RFCavity edge case.

* Remove extra semicolon.

* Fix el typing (BLAST-ImpactX#1190)

* Fix `KnownElementsList` Stubs

Avoid importing `typing` for type hints, because pybind11-stubgen
forgets the import when generating `pyi` files...

* Update Stubs

* Update PALS to 0.2.0 (BLAST-ImpactX#1184)

* Update PALS version

* Fix missing imports in KnownElementsList.pyi

* Fix FODO example script

* Revert changes to stub file

* fix some math issues in examle documentation (BLAST-ImpactX#1191)

* "Starting step" Print: Spaces (BLAST-ImpactX#1187)

- newline before new step
- no space before `++++ Starting step`

* Element Names: All, `None` (BLAST-ImpactX#1189)

It is easier for user-facing workflows if `.name` exists
for all elements, even `Empty`.

In Python, instead of throwing an exception we return the
`None` value for elements without a user-provided name,
which simplifies user-logic. In this case `.has_name` is
`False`.

* Update Stub Files

---------

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Axel Huebl <[email protected]>
Co-authored-by: Ji Qiang <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: ax3l <[email protected]>
Co-authored-by: Edoardo Zoni <[email protected]>
Co-authored-by: Richard Pausch <[email protected]>

Author: 7 people

.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()
 

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()

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

@@ -637,6 +637,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.