Merge branch 'development' into add_apertures_thick

.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/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.8.6
+  rev: v0.9.1
   hooks:
     # Run the linter
     - id: ruff

CMakeLists.txt

@@ -1,7 +1,7 @@
 # Preamble ####################################################################
 #
 cmake_minimum_required(VERSION 3.24.0)
-project(ImpactX VERSION 24.12)
+project(ImpactX VERSION 25.01)
 
 include(${ImpactX_SOURCE_DIR}/cmake/ImpactXFunctions.cmake)
 
@@ -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 "f6d3d70cadfc03036f5fdc4f89b7fcb225792716"
     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

@@ -37,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()
@@ -52,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.12"
+version = "25.01"
 # The full version, including alpha/beta/rc tags.
-release = "24.12"
+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

@@ -31,10 +31,11 @@ Single Particle Dynamics
    examples/aperture/README.rst
    examples/iota_lens/README.rst
    examples/achromatic_spectrometer/README.rst
+   examples/fodo_userdef/README.rst
    examples/fodo_programmable/README.rst
    examples/dogleg/README.rst
    examples/coupled_optics/README.rst
-
+   examples/linear_map/README.rst
 
 Collective Effects
 ------------------

docs/source/usage/parameters.rst

@@ -351,6 +351,25 @@ Lattice Elements
             * ``<element_name>.rotation`` (``float``, in degrees) rotation error in the transverse plane
             * ``<element_name>.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``)
 
+        * ``linear_map`` for a custom, linear transport matrix.
+
+          The matrix elements :math:`R(i,j)` are indexed beginning with 1, so that :math:`i,j=1,2,3,4,5,6`.
+          The transport matrix :math:`R` is defaulted to the identity matrix, so only matrix entries that differ from that need to be specified.
+
+          The matrix :math:`R` multiplies the phase space vector :math:`(x,px,y,py,t,pt)`, where coordinates :math:`(x,y,t)` have units of m
+          and momenta :math:`(px,py,pt)` are dimensionless.  So, for example, :math:`R(1,1)` is dimensionless, and :math:`R(1,2)` has units of m.
+
+          The internal tracking methods used by ImpactX are symplectic.  However, if a user-defined linear map :math:`R` is provided, it is up to the user to ensure that the matrix :math:`R` is symplectic.  Otherwise, this condition may be violated.
+
+          This element requires these additional parameters:
+
+            * ``<element_name>.R(i,j)`` (``float``, ...) matrix entries
+                a 1-indexed, 6x6, linear transport map to multiply with the the phase space vector :math:`x,px,y,py,t,pt`.
+            * ``<element_name>.ds`` (``float``, in meters) length associated with a user-defined linear element (defaults to 0)
+            * ``<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
+
         * ``multipole`` for a thin multipole element.
           This requires these additional parameters:
 
@@ -815,7 +834,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

@@ -616,6 +616,25 @@ This module provides elements for the accelerator lattice.
    :param unit: specification of units (``"dimensionless"`` in units of the magnetic rigidity of the reference particle or ``"T-m"``)
    :param name: an optional name for the element
 
+.. py::class:: impactx.elements.LinearMap(R, dx=0, dy=0, rotation=0, name=None)
+
+   A custom, linear transport matrix.
+
+   The matrix elements :math:`R(i,j)` are indexed beginning with 1, so that :math:`i,j=1,2,3,4,5,6`.
+
+   The matrix :math:`R` multiplies the phase space vector :math:`(x,px,y,py,t,pt)`, where coordinates :math:`(x,y,t)` have units of m
+   and momenta :math:`(px,py,pt)` are dimensionless.  So, for example, :math:`R(1,1)` is dimensionless, and :math:`R(1,2)` has units of m.
+
+   The internal tracking methods used by ImpactX are symplectic.  However, if a user-defined linear map :math:`R` is provided, it is
+   up to the user to ensure that the matrix :math:`R` is symplectic.  Otherwise, this condition may be violated.
+
+   :param R: a linear transport map to multiply with the the phase space vector :math:`(x,px,y,py,t,pt)`.
+   :param ds: length associated with a user-defined linear element (defaults to 0), in m
+   :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.Multipole(multipole, K_normal, K_skew, dx=0, dy=0, rotation=0, name=None)
 
    A general thin multipole element.

docs/source/usage/workflows/add_element.rst

@@ -10,6 +10,28 @@ The workflows described here apply both for thin kicks or thick elements.
 Thick elements can also use soft-edged fringe fields (see `existing soft-edged elements for implementation details <https://github.com/ECP-WarpX/impactx/tree/development/src/particles/elements>`__).
 
 
+.. _usage-workflows-add-element-linmap:
+
+Linear Map
+----------
+
+A custom linear element can be provided by specifying the 6x6 linear transport matrix :math:`R` as an input.
+See the :ref:` example <examples-fodo-userdef>` for Python and inputs file syntax to specify a custom linear element.
+
+The matrix elements :math:`R(i,j)` are indexed beginning with 1, so that :math:`i,j=1,2,3,4,5,6`.
+
+The matrix :math:`R` multiplies the phase space vector :math:`(x,px,y,py,t,pt)`, where coordinates :math:`(x,y,t)` have units of m
+and momenta :math:`(px,py,pt)` are dimensionless.  So, for example, :math:`R(1,1)` is dimensionless, and :math:`R(1,2)` has units of m.
+
+
+.. note::
+
+   If a user-provided linear map is used, it is up to the user to ensure that the 6x6 transport matrix is symplectic.
+   If a more general form of user-defined transport is needed, the :ref:`Python Programmable Element <usage-workflows-add-element-python>` and the :ref:`C++ Element <usage-workflows-add-element-cxx>` provide a more general approach.
+
+
+.. _usage-workflows-add-element-python:
+
 Python Programmable Element
 ---------------------------
 
@@ -30,14 +52,7 @@ Detailed examples that show usage of the programmable element are:
 Detailed particle computing interfaces are presented in the `pyAMReX examples <https://pyamrex.readthedocs.io/en/latest/usage/compute.html#particles>`__.
 
 
-Linear Map
-----------
-
-.. note::
-
-   We plan to add a simple, linear map element that can be configured in user input.
-   Follow `issue #538 <https://github.com/ECP-WarpX/impactx/issues/538>`__ for progress.
-
+.. _usage-workflows-add-element-cxx:
 
 C++ Element
 -----------