Merge remote-tracking branch 'mainline/development' into topic-covari…

…ance-and-transport-maps-chad

.github/workflows/dependencies/hip-openmpi.sh

@@ -54,6 +54,7 @@ sudo apt-get install -y --no-install-recommends \
     rocfft-dev      \
     rocprim-dev     \
     rocrand-dev     \
+    rocsparse-dev   \
     hiprand-dev
 
 # activate

.github/workflows/dependencies/nvcc11-openmpi.sh

@@ -35,7 +35,8 @@ sudo apt-get install -y          \
     cuda-nvml-dev-11-3           \
     cuda-nvtx-11-3               \
     libcufft-dev-11-3            \
-    libcurand-dev-11-3
+    libcurand-dev-11-3           \
+    libcusparse-dev-11-3
 sudo ln -s cuda-11.3 /usr/local/cuda
 
 # cmake-easyinstall

.github/workflows/macos.yml

@@ -12,7 +12,6 @@ jobs:
     runs-on: macos-latest
     if: github.event.pull_request.draft == false
     env:
-      CXXFLAGS: "-Werror -Wno-error=pass-failed"
       HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK: TRUE
     steps:
     - uses: actions/checkout@v4
@@ -64,6 +63,8 @@ jobs:
         export CCACHE_SLOPPINESS=time_macros
         ccache -z
 
+        export CXXFLAGS="-Werror -Wno-error=pass-failed"
+
         cmake -S . -B build            \
           -DCMAKE_VERBOSE_MAKEFILE=ON  \
           -DImpactX_FFT=ON             \

.github/workflows/windows.yml

@@ -44,14 +44,25 @@ jobs:
         # https://github.com/actions/runner-images/issues/10004
         CXXFLAGS: "/D_DISABLE_CONSTEXPR_MUTEX_CONSTRUCTOR"
       run: |
-        cmake -S fftw-3.3.10 -B build_fftw       `
+        cmake -S fftw-3.3.10                     `
+              -B build_fftw                      `
               -DBUILD_SHARED_LIBS=OFF            `
               -DBUILD_TESTS=OFF                  `
               -DCMAKE_BUILD_TYPE=RelWithDebInfo  `
               -DDISABLE_FORTRAN=ON
         if(!$?) { Exit $LASTEXITCODE }
         cmake --build build_fftw --config RelWithDebInfo --target install --parallel 4
         if(!$?) { Exit $LASTEXITCODE }
+        cmake -S fftw-3.3.10                     `
+              -B build_fftwf                     `
+              -DBUILD_SHARED_LIBS=OFF            `
+              -DBUILD_TESTS=OFF                  `
+              -DCMAKE_BUILD_TYPE=RelWithDebInfo  `
+              -DDISABLE_FORTRAN=ON               `
+              -DENABLE_FLOAT=ON
+        if(!$?) { Exit $LASTEXITCODE }
+        cmake --build build_fftwf --config RelWithDebInfo --target install --parallel 4
+        if(!$?) { Exit $LASTEXITCODE }
 
         cmake -S hdf5-hdf5-1_12_2 -B build_hdf5  `
               -DCMAKE_BUILD_TYPE=RelWithDebInfo  `
@@ -83,6 +94,7 @@ jobs:
         CXXFLAGS: "/D_DISABLE_CONSTEXPR_MUTEX_CONSTRUCTOR"
         # FFTW3 install prefix path
         FFTW3_DIR: "C:/Program Files (x86)/fftw/"
+        FFTW3f_DIR: "C:/Program Files (x86)/fftw/"
       run: |
         $env:HDF5_DIR = "C:/Program Files/HDF_Group/HDF5/1.12.2/cmake/"
         cmake -S . -B build               `
@@ -159,6 +171,17 @@ jobs:
         if errorlevel 1 exit 1
         cmake --build build_fftw --config Release --target install --parallel 4
         if errorlevel 1 exit 1
+        cmake -S fftw-3.3.10                    ^
+              -B build_fftwf                    ^
+              -G "Ninja"                        ^
+              -DBUILD_TESTS=OFF                 ^
+              -DBUILD_SHARED_LIBS=OFF           ^
+              -DCMAKE_BUILD_TYPE=Release        ^
+              -DDISABLE_FORTRAN=ON              ^
+              -DENABLE_FLOAT=ON
+        if errorlevel 1 exit 1
+        cmake --build build_fftwf --config Release --target install --parallel 4
+        if errorlevel 1 exit 1
 
         cmake -S hdf5-hdf5-1_12_2 -B build_hdf5 ^
             -G "Ninja"                          ^
@@ -191,6 +214,7 @@ jobs:
       env:
         # FFTW3 install prefix path
         FFTW3_DIR: "C:/Program Files (x86)/fftw/"
+        FFTW3f_DIR: "C:/Program Files (x86)/fftw/"
       run: |
         call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\vc\Auxiliary\build\vcvarsall.bat" x64
 

.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.6.9
+  rev: v0.8.6
   hooks:
     # Run the linter
     - id: ruff
@@ -86,7 +86,7 @@ repos:
 
 # Checks the manifest for missing files (native support)
 - repo: https://github.com/mgedmin/check-manifest
-  rev: "0.49"
+  rev: "0.50"
   hooks:
   - id: check-manifest
     # This is a slow hook, so only run this if --hook-stage manual is passed

CMakeLists.txt

@@ -1,7 +1,7 @@
 # Preamble ####################################################################
 #
 cmake_minimum_required(VERSION 3.24.0)
-project(ImpactX VERSION 24.10)
+project(ImpactX VERSION 25.01)
 
 include(${ImpactX_SOURCE_DIR}/cmake/ImpactXFunctions.cmake)
 
@@ -136,7 +136,7 @@ impactx_make_third_party_includes_system(WarpX::ablastr_3d ablastr_3d)
 
 # Python
 if(ImpactX_PYTHON)
-    find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)
+    find_package(Python 3.8 COMPONENTS Interpreter Development.Module REQUIRED)
 
     # default installation directories: Python
     impactx_set_default_install_dirs_python()
@@ -265,7 +265,7 @@ if(ImpactX_PYTHON)
             impactx_enable_IPO(pyImpactX)
         else()
             # conditionally defined target in pybind11
-            # https://github.com/pybind/pybind11/blob/v2.12.0/tools/pybind11Common.cmake#L397-L403
+            # https://github.com/pybind/pybind11/blob/v2.13.0/tools/pybind11Common.cmake#L407-L413
             target_link_libraries(pyImpactX PRIVATE pybind11::lto)
         endif()
     endif()

cmake/dependencies/ABLASTR.cmake

@@ -58,6 +58,7 @@ macro(find_ablastr)
         set(CMAKE_POLICY_DEFAULT_CMP0077 NEW)
 
         set(ABLASTR_FFT ${ImpactX_FFT} CACHE BOOL "" FORCE)
+        set(AMReX_FFT ${ImpactX_FFT} CACHE BOOL "" FORCE)
 
         set(WarpX_APP OFF CACHE BOOL "" FORCE)
         set(WarpX_LIB OFF CACHE BOOL "" FORCE)
@@ -127,7 +128,7 @@ macro(find_ablastr)
         set(COMPONENT_DIM 3D)
         set(COMPONENT_PRECISION ${ImpactX_PRECISION} P${ImpactX_PRECISION})
 
-        find_package(ABLASTR 24.10 CONFIG REQUIRED COMPONENTS ${COMPONENT_DIM})
+        find_package(ABLASTR 25.01 CONFIG REQUIRED COMPONENTS ${COMPONENT_DIM})
         message(STATUS "ABLASTR: Found version '${ABLASTR_VERSION}'")
     endif()
 
@@ -161,15 +162,15 @@ set(ImpactX_openpmd_src ""
 set(ImpactX_ablastr_repo "https://github.com/ECP-WarpX/WarpX.git"
     CACHE STRING
     "Repository URI to pull and build ABLASTR from if(ImpactX_ablastr_internal)")
-set(ImpactX_ablastr_branch "24.10"
+set(ImpactX_ablastr_branch "25.01"
     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 "e64ffef57a7608d1d60f9abe738cc634e9c1272e"
+set(ImpactX_amrex_branch "041f225dc5c97a5e3baf2559046ceabffd75f002"
     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 24.10 CONFIG REQUIRED)
+        find_package(pyAMReX 25.01 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 "8742a79c29b7db30c7287c8e33109c0d8be1277a"
+set(ImpactX_pyamrex_branch "25.01"
     CACHE STRING
     "Repository branch for ImpactX_pyamrex_repo if(ImpactX_pyamrex_internal)")
 

cmake/dependencies/pybind11.cmake

@@ -10,6 +10,11 @@ function(find_pybind11)
         message(STATUS "pybind11 repository: ${ImpactX_pybind11_repo} (${ImpactX_pybind11_branch})")
         include(FetchContent)
     endif()
+
+    # rely on our find_package(Python ...) call
+    # https://pybind11.readthedocs.io/en/stable/compiling.html#modules-with-cmake
+    set(PYBIND11_FINDPYTHON ON)
+
     if(ImpactX_pybind11_internal OR ImpactX_pybind11_src)
         set(CMAKE_POLICY_DEFAULT_CMP0077 NEW)
 
@@ -32,7 +37,7 @@ function(find_pybind11)
             mark_as_advanced(FETCHCONTENT_UPDATES_DISCONNECTED_FETCHEDpybind11)
         endif()
     else()
-        find_package(pybind11 2.12.0 CONFIG REQUIRED)
+        find_package(pybind11 2.13.0 CONFIG REQUIRED)
         message(STATUS "pybind11: Found version '${pybind11_VERSION}'")
     endif()
 endfunction()
@@ -47,7 +52,7 @@ option(ImpactX_pybind11_internal "Download & build pybind11" ON)
 set(ImpactX_pybind11_repo "https://github.com/pybind/pybind11.git"
     CACHE STRING
     "Repository URI to pull and build pybind11 from if(ImpactX_pybind11_internal)")
-set(ImpactX_pybind11_branch "v2.12.0"
+set(ImpactX_pybind11_branch "v2.13.6"
     CACHE STRING
     "Repository branch for ImpactX_pybind11_repo if(ImpactX_pybind11_internal)")
 

docs/source/conf.py

@@ -73,9 +73,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = "24.10"
+version = "25.01"
 # The full version, including alpha/beta/rc tags.
-release = "24.10"
+release = "25.01"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/install/dependencies.rst

@@ -28,7 +28,7 @@ Optional dependencies include:
   - see `optional I/O backends <https://github.com/openPMD/openPMD-api#dependencies>`__
 - `CCache <https://ccache.dev>`__: to speed up rebuilds (For CUDA support, needs version 3.7.9+ and 4.2+ is recommended)
 - `Ninja <https://ninja-build.org>`__: for faster parallel compiles
-- `Python 3.8+ <https://www.python.org>`__
+- `Python 3.9+ <https://www.python.org>`__
 
   - `mpi4py <https://mpi4py.readthedocs.io>`__
   - `numpy <https://numpy.org>`__

docs/source/usage/examples.rst

@@ -105,6 +105,7 @@ Virtual Test Stands
    examples/pytorch_surrogate_model/README.rst
    examples/apochromatic/README.rst
    examples/fodo_tune/README.rst
+   examples/linac_segment/README.rst
 
 
 Unit tests

docs/source/usage/parameters.rst

@@ -393,6 +393,13 @@ Lattice Elements
             * ``<element_name>.phi_in`` (``float``, in degrees) angle of the reference particle with respect to the longitudinal (z) axis in the original frame
             * ``<element_name>.phi_out`` (``float``, in degrees) angle of the reference particle with respect to the longitudinal (z) axis in the rotated frame
 
+        * ``plane_xyrotation`` for a rotation in the x-y plane (i.e., about the reference velocity vector). This requires these additional parameters:
+
+            * ``<element_name>.angle`` (``float``, in degrees) nominal angle of rotation
+            * ``<element_name>.dx`` (``float``, in meters) horizontal translation error
+            * ``<element_name>.dy`` (``float``, in meters) vertical translation error
+            * ``<element_name>.rotation`` (``float``, in degrees) rotation error in the transverse plane
+
         * ``kicker`` for a thin transverse kicker. This requires these additional parameters:
 
             * ``<element_name>.xkick`` (``float``, dimensionless OR in T-m) the horizontal kick strength
@@ -416,7 +423,10 @@ Lattice Elements
 
             * ``<element_name>.xmax`` (``float``, in meters) maximum value of the horizontal coordinate
             * ``<element_name>.ymax`` (``float``, in meters) maximum value of the vertical coordinate
+            * ``<element_name>.repeat_x`` (``float``, in meters) horizontal period for repeated aperture masking (inactive by default)
+            * ``<element_name>.repeat_y`` (``float``, in meters) vertical period for repeated aperture masking (inactive by default)
             * ``<element_name>.shape`` (``string``) shape of the aperture boundary: ``rectangular`` (default) or ``elliptical``
+            * ``<element_name>.action`` (``string``) action of the aperture domain: ``transmit`` (default) or ``absorb``
             * ``<element_name>.dx`` (``float``, in meters) horizontal translation error
             * ``<element_name>.dy`` (``float``, in meters) vertical translation error
             * ``<element_name>.rotation`` (``float``, in degrees) rotation error in the transverse plane
@@ -818,7 +828,7 @@ Overall simulation parameters
 * ``amrex.the_arena_is_managed``  (``0`` or ``1``; default is ``0`` for false)
     When running on GPUs, device memory that is accessed from the host will automatically be transferred with managed memory.
     This is useful for convenience during development, but has sometimes severe performance and memory footprint implications if relied on (and sometimes vendor bugs).
-    For all regular ImpactX operations, we therefore do explicit memory transfers without the need for managed memory and thus changed the AMReX default to false.
+    For all regular ImpactX operations, we therefore do explicit memory transfers without the need for managed memory.
     `Please also see the documentation in AMReX <https://amrex-codes.github.io/amrex/docs_html/GPU.html#inputs-parameters>`__.
 
 * ``amrex.omp_threads``  (``system``, ``nosmt`` or positive integer; default is ``nosmt``)

docs/source/usage/python.rst

@@ -215,7 +215,11 @@ Collective Effects & Overall Simulation Parameters
 
    .. py:method:: evolve()
 
-      Run the main simulation loop for a number of steps.
+      Run the main simulation loop (deprecated, use ``track_particles``)
+
+   .. py:method:: track_particles()
+
+      Run the particle tracking simulation loop.
 
    .. py:method:: resize_mesh()
 
@@ -788,7 +792,7 @@ This module provides elements for the accelerator lattice.
    :param ds: Segment length in m.
    :param k:  focusing strength in m^(-2) (if unit = 0)
               = (azimuthal magnetic field gradient in T/m) / (rigidity in T-m)
-          OR  azimuthal magnetic field gradient in T/m (if unit = 1)
+              OR  azimuthal magnetic field gradient in T/m (if unit = 1)
    :param unit: specification of units for plasma lens focusing strength
    :param dx: horizontal translation error in m
    :param dy: vertical translation error in m
@@ -909,7 +913,7 @@ This module provides elements for the accelerator lattice.
    :param ds: Segment length in m.
    :param bscale: Scaling factor for on-axis magnetic field Bz in inverse meters (if unit = 0)
               = (magnetic field Bz in T) / (rigidity in T-m)
-          OR  Magnetic field Bz in T (SI units, if unit = 1)
+              OR  Magnetic field Bz in T (SI units, if unit = 1)
    :param cos_coefficients: array of ``float`` cosine coefficients in Fourier expansion of on-axis magnetic field Bz
             (optional); default is a thin-shell model from `DOI:10.1016/J.NIMA.2022.166706 <https://doi.org/10.1016/j.nima.2022.166706>`__
    :param sin_coefficients: array of ``float`` sine coefficients in Fourier expansion of on-axis magnetic field Bz
@@ -942,13 +946,26 @@ This module provides elements for the accelerator lattice.
    :param phi_out: angle of the reference particle with respect to the longitudinal (z) axis in the rotated frame in degrees
    :param name: an optional name for the element
 
+.. py:class:: impactx.elements.PlaneXYRot(angle,  dx=0, dy=0, rotation=0, name=None)
+
+   Map for a transverse rotation in the x-y plane (i.e., about the reference velocity vector).
+
+   :param angle: nominal angle of rotation in the x-y plane, in degrees
+   :param dx: horizontal translation error in m
+   :param dy: vertical translation error in m
+   :param rotation: rotation error in the transverse plane [degrees]
+   :param name: an optional name for the element
+
 .. py:class:: impactx.elements.Aperture(xmax, ymax, shape="rectangular", dx=0, dy=0, rotation=0, name=None)
 
    A thin collimator element, applying a transverse aperture boundary.
 
    :param xmax: maximum allowed value of the horizontal coordinate (meter)
    :param ymax: maximum allowed value of the vertical coordinate (meter)
+   :param repeat_x: horizontal period for repeated aperture masking (inactive by default) (meter)
+   :param repeat_y: vertical period for repeated aperture masking (inactive by default) (meter)
    :param shape: aperture boundary shape: ``"rectangular"`` (default) or ``"elliptical"``
+   :param action: aperture domain action: ``"transmit"`` (default) or ``"absorb"``
    :param dx: horizontal translation error in m
    :param dy: vertical translation error in m
    :param rotation: rotation error in the transverse plane [degrees]
@@ -958,6 +975,10 @@ This module provides elements for the accelerator lattice.
 
       aperture type (rectangular, elliptical)
 
+   .. py:property:: action
+
+      aperture type (transmit, absorb)
+
    .. py:property:: xmax
 
       maximum horizontal coordinate