Merge branch 'development' into topic-covariance-and-transport-maps

ax3l · Oct 10, 2024 · 0044f78 · 0044f78
2 parents b2f158c + 579339b
commit 0044f78
Show file tree

Hide file tree

Showing 147 changed files with 3,788 additions and 1,227 deletions.
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
@@ -30,23 +30,29 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - uses: actions/setup-python@v5
+        name: Install Python
+        with:
+          python-version: '3.x'
+
       - name: Install Packages
         run: |
           sudo apt-get update
           sudo apt-get install --yes cmake openmpi-bin libfftw3-dev libfftw3-mpi-dev libopenmpi-dev libhdf5-openmpi-dev
 
           python -m pip install --upgrade pip
+          python -m pip install --upgrade pipx
           python -m pip install --upgrade wheel
-          python -m pip install --upgrade cmake
-          export CMAKE="$HOME/.local/bin/cmake" && echo "CMAKE=$CMAKE" >> $GITHUB_ENV
           python -m pip install --upgrade numpy
           python -m pip install --upgrade mpi4py
           python -m pip install --upgrade pytest
+          python -m pip install --upgrade cmake
+          python -m pipx install cmake
 
       - name: Configure (C++)
         if: ${{ matrix.language == 'cpp' }}
         run: |
-          $CMAKE -S . -B build -DImpactX_FFT=ON -DImpactX_PYTHON=OFF
+          cmake -S . -B build -DImpactX_FFT=ON -DImpactX_PYTHON=OFF
 
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v3
@@ -64,7 +70,7 @@ jobs:
       - name: Build (C++)
         if: ${{ matrix.language == 'cpp' }}
         run: |
-          $CMAKE --build build -j 4
+          cmake --build build -j 4
 
       - name: Perform CodeQL Analysis
         uses: github/codeql-action/analyze@v3

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.5
+  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.09)
+project(ImpactX VERSION 24.10)
 
 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.09 CONFIG REQUIRED COMPONENTS ${COMPONENT_DIM})
+        find_package(ABLASTR 24.10 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 "24.09"
+set(ImpactX_ablastr_branch "24.10"
     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.09 CONFIG REQUIRED)
+        find_package(pyAMReX 24.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 "24.09"
+set(ImpactX_pyamrex_branch "24.10"
     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.09"
+version = "24.10"
 # The full version, including alpha/beta/rc tags.
-release = "24.09"
+release = "24.10"
 
 # 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/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
@@ -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: