Merge remote-tracking branch 'mainline/development' into csr_python_p…

…lot_test
ECP-WarpX · Oct 10, 2024 · 1f9ff3d · 1f9ff3d
2 parents be5c705 + a4107e4
commit 1f9ff3d
Show file tree

Hide file tree

Showing 157 changed files with 4,146 additions and 1,354 deletions.
diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml
@@ -16,12 +16,15 @@ jobs:
       HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK: TRUE
     steps:
     - uses: actions/checkout@v4
-    - name: install dependencies
+    - uses: actions/setup-python@v5
+      name: Install Python
+      with:
+        python-version: '3.x'
+    - name: install brew dependencies
       run: |
         set +e
         brew unlink gcc
         brew update
-        brew install --overwrite python
         brew install adios2
         brew install ccache
         brew install cmake
@@ -32,19 +35,15 @@ jobs:
         brew install ninja
         brew install open-mpi
         brew install pkg-config
-
-        python3 -m pip install --upgrade pip
-        python3 -m pip install --upgrade virtualenv
-
-        python3 -m venv py-venv
-        source py-venv/bin/activate
+        set -e
+    - name: install pip dependencies
+      run: |
         python3 -m pip install --upgrade pip
         python3 -m pip install --upgrade build packaging setuptools wheel pytest
         python3 -m pip install --upgrade -r requirements_mpi.txt
         python3 -m pip install --upgrade -r src/python/impactx/dashboard/requirements.txt
         python3 -m pip install --upgrade -r examples/requirements.txt
         python3 -m pip install --upgrade -r tests/python/requirements.txt
-        set -e
         python3 -m pip install --upgrade pipx
         python3 -m pipx install openPMD-validator
     - name: CCache Cache
@@ -65,29 +64,23 @@ jobs:
         export CCACHE_SLOPPINESS=time_macros
         ccache -z
 
-        source py-venv/bin/activate
-
         cmake -S . -B build            \
           -DCMAKE_VERBOSE_MAKEFILE=ON  \
           -DImpactX_FFT=ON             \
-          -DImpactX_PYTHON=ON          \
-          -DPython_EXECUTABLE=$(which python3)
+          -DImpactX_PYTHON=ON
         cmake --build build -j 3
 
         du -hs ~/Library/Caches/ccache
         ccache -s
 
     - name: run tests
       run: |
-        source py-venv/bin/activate
-
         ctest --test-dir build --output-on-failure -E pytest.AMReX
 
     - name: run installed python module
       run: |
         cmake --build build --target pip_install
 
-        source py-venv/bin/activate
         python3 examples/fodo/run_fodo.py
 
     - name: run installed app

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -15,7 +15,7 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
     - id: trailing-whitespace
       args: [--markdown-linebreak-ext=md]
@@ -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.3
+  rev: v0.6.9
   hooks:
     # Run the linter
     - id: ruff

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,7 +1,7 @@
 # Preamble ####################################################################
 #
 cmake_minimum_required(VERSION 3.24.0)
-project(ImpactX VERSION 24.08)
+project(ImpactX VERSION 24.09)
 
 include(${ImpactX_SOURCE_DIR}/cmake/ImpactXFunctions.cmake)
 
@@ -394,9 +394,9 @@ install(CODE "file(CREATE_LINK
 #
 if(ImpactX_PYTHON)
     set(PY_PIP_OPTIONS "-v" CACHE STRING
-        "Additional parameters to pass to `pip`")
+        "Additional parameters to pass to `pip` as ; separated list")
     set(PY_PIP_INSTALL_OPTIONS "" CACHE STRING
-        "Additional parameters to pass to `pip install`")
+        "Additional parameters to pass to `pip install` as ; separated list")
 
     # add a prefix to custom targets so we do not collide if used as a subproject
     if(CMAKE_SOURCE_DIR STREQUAL PROJECT_SOURCE_DIR)
@@ -412,7 +412,8 @@ if(ImpactX_PYTHON)
         ${CMAKE_COMMAND} -E rm -f -r impactx-whl
         COMMAND
             ${CMAKE_COMMAND} -E env PYIMPACTX_LIBDIR=$<TARGET_FILE_DIR:pyImpactX>
-                ${Python_EXECUTABLE} -m pip ${PY_PIP_OPTIONS} wheel --no-build-isolation --no-deps --wheel-dir=impactx-whl ${ImpactX_SOURCE_DIR}
+                ${Python_EXECUTABLE} -m pip ${PY_PIP_OPTIONS} wheel --no-build-isolation --no-deps --wheel-dir=impactx-whl "${ImpactX_SOURCE_DIR}"
+        COMMAND_EXPAND_LISTS VERBATIM
         WORKING_DIRECTORY
             ${ImpactX_BINARY_DIR}
         DEPENDS
@@ -427,6 +428,7 @@ if(ImpactX_PYTHON)
     endif()
     add_custom_target(${ImpactX_CUSTOM_TARGET_PREFIX}pip_install_requirements
         ${Python_EXECUTABLE} -m pip ${PY_PIP_OPTIONS} install ${PY_PIP_INSTALL_OPTIONS} -r "${ImpactX_SOURCE_DIR}/${pyImpactX_REQUIREMENT_FILE}"
+        COMMAND_EXPAND_LISTS VERBATIM
         WORKING_DIRECTORY
             ${ImpactX_BINARY_DIR}
     )
@@ -444,6 +446,7 @@ if(ImpactX_PYTHON)
     add_custom_target(${ImpactX_CUSTOM_TARGET_PREFIX}pip_install
         ${CMAKE_COMMAND} -E env IMPACTX_MPI=${ImpactX_MPI}
             ${Python_EXECUTABLE} -m pip ${PY_PIP_OPTIONS} install --force-reinstall --no-index --no-deps ${PY_PIP_INSTALL_OPTIONS} --find-links=impactx-whl impactx
+        COMMAND_EXPAND_LISTS VERBATIM
         WORKING_DIRECTORY
             ${ImpactX_BINARY_DIR}
         DEPENDS
@@ -456,6 +459,7 @@ if(ImpactX_PYTHON)
     add_custom_target(${ImpactX_CUSTOM_TARGET_PREFIX}pip_install_nodeps
         ${CMAKE_COMMAND} -E env IMPACTX_MPI=${ImpactX_MPI}
             ${Python_EXECUTABLE} -m pip ${PY_PIP_OPTIONS} install --force-reinstall --no-index --no-deps ${PY_PIP_INSTALL_OPTIONS} --find-links=impactx-whl impactx
+        COMMAND_EXPAND_LISTS VERBATIM
         WORKING_DIRECTORY
             ${ImpactX_BINARY_DIR}
         DEPENDS

diff --git a/cmake/dependencies/ABLASTR.cmake b/cmake/dependencies/ABLASTR.cmake
@@ -127,7 +127,7 @@ macro(find_ablastr)
         set(COMPONENT_DIM 3D)
         set(COMPONENT_PRECISION ${ImpactX_PRECISION} P${ImpactX_PRECISION})
 
-        find_package(ABLASTR 24.08 CONFIG REQUIRED COMPONENTS ${COMPONENT_DIM})
+        find_package(ABLASTR 24.09 CONFIG REQUIRED COMPONENTS ${COMPONENT_DIM})
         message(STATUS "ABLASTR: Found version '${ABLASTR_VERSION}'")
     endif()
 
@@ -161,7 +161,7 @@ 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 "0838941a6693df711769a90a8a989c9a920b0abe"
+set(ImpactX_ablastr_branch "d1a338e90ed1ad7ac2f010f47409aa48a2265c88"
     CACHE STRING
     "Repository branch for ImpactX_ablastr_repo if(ImpactX_ablastr_internal)")
 

diff --git a/cmake/dependencies/pyAMReX.cmake b/cmake/dependencies/pyAMReX.cmake
@@ -59,7 +59,7 @@ function(find_pyamrex)
         endif()
     elseif(NOT ImpactX_pyamrex_internal)
         # TODO: MPI control
-        find_package(pyAMReX 24.08 CONFIG REQUIRED)
+        find_package(pyAMReX 24.09 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 "abdf332e25bfeef2b4d613d7adbe93fb8cf3e2f7"
+set(ImpactX_pyamrex_branch "1c66690f83244196c5655293f1381303a7d1589d"
     CACHE STRING
     "Repository branch for ImpactX_pyamrex_repo if(ImpactX_pyamrex_internal)")
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -73,9 +73,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = "24.08"
+version = "24.09"
 # The full version, including alpha/beta/rc tags.
-release = "24.08"
+release = "24.09"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/docs/source/dataanalysis/dataanalysis.rst b/docs/source/dataanalysis/dataanalysis.rst
@@ -84,7 +84,7 @@ The code writes out the values in an ASCII file prefixed ``reduced_beam_characte
 * ``sig_px``, ``sig_py``, ``sig_pt``
     Standard deviation of the particle momentum deviations (energy difference for ``pt``) normalized by the magnitude of the reference particle momentum (unit: dimensionless)
 * ``emittance_x``, ``emittance_y``, ``emittance_t``
-    Normalized rms beam emittance (unit: meter)
+    Unnormalized rms beam emittances (unit: meter)
 * ``alpha_x``, ``alpha_y``, ``alpha_t``
     Courant-Snyder (Twiss) alpha (unit: dimensionless).  Transverse Twiss functions are calculated after removing correlations with particle energy.
 * ``beta_x``, ``beta_y``, ``beta_t``
@@ -93,6 +93,11 @@ The code writes out the values in an ASCII file prefixed ``reduced_beam_characte
     Horizontal and vertical dispersion (unit: meter)
 * ``dispersion_px``, ``dispersion_py``
     Derivative of horizontal and vertical dispersion (unit: dimensionless)
+* ``emittance_xn``, ``emittance_yn``, ``emittance_tn``
+    Normalized rms beam emittances (unit: meter)
+* ``emittance_1``, ``emittance_2``, ``emittance_3``
+    Normalized rms beam eigenemittances (aka mode emittances) (unit: meter)
+    These three diagnostics are written optionally if the flag eigenemittances = True.
 * ``charge``
     Total beam charge (unit: Coulomb)
 

diff --git a/docs/source/install/cmake.rst b/docs/source/install/cmake.rst
@@ -112,8 +112,8 @@ CMake Option                    Default & Values                             Des
 ``ImpactX_PRECISION``           SINGLE/**DOUBLE**                            Floating point precision (single/double)
 ``ImpactX_PYTHON``              ON/**OFF**                                   Python bindings
 ``Python_EXECUTABLE``           (newest found)                               Path to Python executable
-``PY_PIP_OPTIONS``              ``-v``                                       Additional options for ``pip``, e.g., ``-vvv``
-``PY_PIP_INSTALL_OPTIONS``                                                   Additional options for ``pip install``, e.g., ``--user``
+``PY_PIP_OPTIONS``              ``-v``                                       Additional options for ``pip``, e.g., ``-vvv;-q``
+``PY_PIP_INSTALL_OPTIONS``                                                   Additional options for ``pip install``, e.g., ``--user;-q``
 =============================== ============================================ ===========================================================
 
 ImpactX can be configured in further detail with options from AMReX, which are `documented in the AMReX manual <https://amrex-codes.github.io/amrex/docs_html/BuildingAMReX.html#customization-options>`_.

diff --git a/docs/source/install/hpc/lumi-csc/lumi_cpu_impactx.profile.example b/docs/source/install/hpc/lumi-csc/lumi_cpu_impactx.profile.example
@@ -2,10 +2,10 @@
 #export proj="project_..."
 
 # required dependencies
-module load LUMI/23.09  partition/C
+module load LUMI/24.03  partition/C
 module load PrgEnv-aocc
-module load buildtools/23.09
-module load cray-fftw/3.3.10.5
+module load buildtools/24.03
+module load cray-fftw/3.3.10.7
 
 # optional: just an additional text editor
 module load nano
@@ -19,7 +19,7 @@ export PATH=${SW_DIR}/adios2-2.8.3/bin:${PATH}
 export PATH=${SW_DIR}/hdf5-1.14.1.2/bin:${PATH}
 
 # optional: for Python bindings or libEnsemble
-module load cray-python/3.10.10
+module load cray-python/3.11.7
 
 if [ -d "${SW_DIR}/venvs/impactx-cpu-lumi" ]
 then

diff --git a/docs/source/install/hpc/lumi-csc/lumi_gpu_impactx.profile.example b/docs/source/install/hpc/lumi-csc/lumi_gpu_impactx.profile.example
@@ -2,9 +2,9 @@
 #export proj="project_..."
 
 # required dependencies
-module load LUMI/23.09  partition/G
-module load rocm/5.2.3
-module load buildtools/23.09
+module load LUMI/24.03  partition/G
+module load rocm/6.0.3
+module load buildtools/24.03
 
 # optional: just an additional text editor
 module load nano
@@ -18,7 +18,7 @@ export PATH=${SW_DIR}/adios2-2.8.3/bin:${PATH}
 export PATH=${SW_DIR}/hdf5-1.14.1.2/bin:${PATH}
 
 # optional: for Python bindings or libEnsemble
-module load cray-python/3.10.10
+module load cray-python/3.11.7
 
 if [ -d "${SW_DIR}/venvs/impactx-gpu-lumi" ]
 then

diff --git a/docs/source/usage/examples.rst b/docs/source/usage/examples.rst
@@ -33,6 +33,8 @@ Single Particle Dynamics
    examples/achromatic_spectrometer/README.rst
    examples/fodo_programmable/README.rst
    examples/dogleg/README.rst
+   examples/coupled_optics/README.rst
+
 
 Collective Effects
 ------------------
@@ -70,6 +72,16 @@ Beam Distributions
 
    examples/distgen/README
 
+
+Channels & Rings
+----------------
+
+.. toctree::
+   :maxdepth: 1
+
+   examples/fodo_channel/README.rst
+
+
 Lattice Design & Optimization
 -----------------------------
 

diff --git a/docs/source/usage/parameters.rst b/docs/source/usage/parameters.rst
@@ -43,8 +43,8 @@ Initial Beam Distributions
         * ``beam.muypy`` (``float``, dimensionless, default: ``0``) correlation Y-Py
         * ``beam.mutpt`` (``float``, dimensionless, default: ``0``) correlation T-Pt
 
-    * Courant-Snyder / Twiss parameters.
-      To enable input via CS / Twiss parameters, add the suffix ``_from_cs`` or ``from_twiss`` to the name of the distribution.
+    * Courant-Snyder (Twiss) parameters.
+      To enable input via Courant-Snyder (Twiss) parameters, add the suffix ``from_twiss`` to the name of the distribution.
       Use the following parameters to characterize it:
 
         * ``beam.alphaX`` (``float``, dimensionless, default: ``0``) CS / Twiss :math:`\alpha` for X
@@ -59,21 +59,21 @@ Initial Beam Distributions
 
     The following distributions are available:
 
-    * ``waterbag`` or ``waterbag_from_cs``/``waterbag_from_twiss`` for initial Waterbag distribution.
+    * ``waterbag`` or ``waterbag_from_twiss`` for initial Waterbag distribution.
 
-    * ``kurth6d`` or ``kurth6d_from_cs``/``kurth6d_from_twiss`` for initial 6D Kurth distribution.
+    * ``kurth6d`` or ``kurth6d_from_twiss`` for initial 6D Kurth distribution.
 
-    * ``gaussian`` or ``gaussian_from_cs``/``gaussian_from_twiss`` for initial 6D Gaussian (normal) distribution.
+    * ``gaussian`` or ``gaussian_from_twiss`` for initial 6D Gaussian (normal) distribution.
 
-    * ``kvdist`` or ``kvdist_from_cs``/``kvdist_from_twiss`` for initial K-V distribution in the transverse plane.
+    * ``kvdist`` or ``kvdist_from_twiss`` for initial K-V distribution in the transverse plane.
       The distribution is uniform in t and Gaussian in pt.
 
-    * ``kurth4d`` or ``kurth4d_from_cs``/``kurth4d_from_twiss`` for initial 4D Kurth distribution in the transverse plane.
+    * ``kurth4d`` or ``kurth4d_from_twiss`` for initial 4D Kurth distribution in the transverse plane.
       The distribution is uniform in t and Gaussian in pt.
 
-    * ``semigaussian`` or ``semigaussian_from_cs``/``semigaussian_from_twiss`` for initial Semi-Gaussian distribution.  The distribution is uniform within a cylinder in (x,y,z) and Gaussian in momenta (px,py,pt).
+    * ``semigaussian`` or ``semigaussian_from_twiss`` for initial Semi-Gaussian distribution.  The distribution is uniform within a cylinder in (x,y,z) and Gaussian in momenta (px,py,pt).
 
-    * ``triangle`` or ``triangle_from_cs``/``triangle_from_twiss`` a triangle distribution for laser-plasma acceleration related applications.
+    * ``triangle`` or ``triangle_from_twiss`` a triangle distribution for laser-plasma acceleration related applications.
       A ramped, triangular current profile with a Gaussian energy spread (possibly correlated).
       The transverse distribution is a 4D waterbag.
 
@@ -449,6 +449,11 @@ Lattice Elements
                 openPMD `iteration encoding <https://openpmd-api.readthedocs.io/en/0.14.0/usage/concepts.html#iteration-and-series>`__: (v)ariable based, (f)ile based, (g)roup based (default)
                 variable based is an `experimental feature with ADIOS2 <https://openpmd-api.readthedocs.io/en/0.14.0/backends/adios2.html#experimental-new-adios2-schema>`__.
 
+            * ``<element_name>.period_sample_intervals`` (``int``, default value: ``1``)
+
+                for periodic lattice, only output every Nth period (turn).
+                By default, diagnostics are returned every cycle.
+
             * ``<element_name>.nonlinear_lens_invariants`` (``boolean``, default value: ``false``)
 
                 Compute and output the invariants H and I within the nonlinear magnetic insert element (see: ``nonlinear_lens``).
@@ -683,8 +688,8 @@ Diagnostics and output
   This option is ignored for the openPMD output elements (remove them from the lattice to disable).
 
 * ``diag.slice_step_diagnostics`` (``boolean``, optional, default: ``false``)
-  By default, diagnostics is performed at the beginning and end of the simulation.
-  Enabling this flag will write diagnostics every step and slice step
+  By default, diagnostics are computed and written at the beginning and end of the simulation.
+  Enabling this flag will write diagnostics at every step and slice step.
 
 * ``diag.file_min_digits`` (``integer``, optional, default: ``6``)
     The minimum number of digits used for the step number appended to the diagnostic file names.
@@ -694,6 +699,10 @@ Diagnostics and output
   Diagnostics for particles lost in apertures, stored as ``diags/openPMD/particles_lost.*`` at the end of the simulation.
   See the ``beam_monitor`` element for backend values.
 
+* ``diag.eigenemittances`` (``boolean``, optional, default: ``false``)
+  If this flag is enabled, the 3 eigenemittances of the 6D beam distribution are computed and written as diagnostics.
+  This flag is disabled by default to reduce computational cost.
+
 
 .. _running-cpp-parameters-diagnostics-insitu: