Merge branch 'development' into call_boundary_solver

.azure-pipelines.yml

@@ -66,16 +66,6 @@ jobs:
       cacheHitVar: CCACHE_CACHE_RESTORED
     displayName: Cache Ccache Objects
 
-  - task: Cache@2
-    continueOnError: true
-    inputs:
-      key: 'Python3 | "$(System.JobName)" | .azure-pipelines.yml'
-      restoreKeys: |
-         Python3 | "$(System.JobName)" | .azure-pipelines.yml
-      path: /home/vsts/.local/lib/python3.8
-      cacheHitVar: PYTHON38_CACHE_RESTORED
-    displayName: Cache Python Libraries
-
   - bash: |
       set -o nounset errexit pipefail
       cat /proc/cpuinfo | grep "model name" | sort -u
@@ -141,7 +131,7 @@ jobs:
       df -h
       # configure
       export AMReX_CMAKE_FLAGS="-DAMReX_ASSERTIONS=ON -DAMReX_TESTING=ON"
-      export WARPX_TEST_FLAGS="-DWarpX_TEST_CLEANUP=ON -DWarpX_TEST_FPETRAP=ON -DWarpX_TEST_DEBUG=ON"
+      export WARPX_TEST_FLAGS="-DWarpX_TEST_CLEANUP=ON -DWarpX_TEST_FPETRAP=ON -DWarpX_BACKTRACE_INFO=ON"
       cmake -S . -B build    \
         ${AMReX_CMAKE_FLAGS} \
         ${WARPX_CMAKE_FLAGS} \
@@ -176,3 +166,9 @@ jobs:
         -exec cat {} \;
     displayName: 'Logs'
     condition: always()
+
+  - bash: |
+      # clean out so the Post-job Cache "tar" command has more disk space available
+      rm -rf build
+    displayName: 'Clean Build Directory'
+    condition: always()

.clang-tidy

@@ -19,6 +19,7 @@ Checks: '
         -cppcoreguidelines-avoid-non-const-global-variables,
         -cppcoreguidelines-init-variables,
         -cppcoreguidelines-macro-usage,
+        -cppcoreguidelines-missing-std-forward,
         -cppcoreguidelines-narrowing-conversions,
         -cppcoreguidelines-non-private-member-variables-in-classes,
         -cppcoreguidelines-owning-memory,
@@ -29,6 +30,7 @@ Checks: '
     misc-*,
         -misc-no-recursion,
         -misc-non-private-member-variables-in-classes,
+        -misc-include-cleaner,
     modernize-*,
         -modernize-avoid-c-arrays,
         -modernize-return-braced-init-list,
@@ -55,6 +57,9 @@ CheckOptions:
   value:        "H,"
 - key:          modernize-pass-by-value.ValuesOnly
   value:        "true"
-
+- key:          misc-use-anonymous-namespace.HeaderFileExtensions
+  value:        "H,"
+- key:          performance-move-const-arg.CheckTriviallyCopyableMove
+  value:        "false"
 
 HeaderFilterRegex: 'Source[a-z_A-Z0-9\/]+\.H$'

.github/workflows/clang_tidy.yml

@@ -20,13 +20,13 @@ jobs:
         dim: [1, 2, RZ, 3]
     name: clang-tidy-${{ matrix.dim }}D
     runs-on: ubuntu-22.04
-    timeout-minutes: 220
+    timeout-minutes: 250
     if: github.event.pull_request.draft == false
     steps:
     - uses: actions/checkout@v4
     - name: install dependencies
       run: |
-        .github/workflows/dependencies/clang.sh 15
+        .github/workflows/dependencies/clang.sh 17
     - name: set up cache
       uses: actions/cache@v4
       with:
@@ -43,8 +43,8 @@ jobs:
         export CCACHE_LOGFILE=${{ github.workspace }}/ccache.log.txt
         ccache -z
 
-        export CXX=$(which clang++-15)
-        export CC=$(which clang-15)
+        export CXX=$(which clang++-17)
+        export CC=$(which clang-17)
 
         cmake -S . -B build_clang_tidy      \
           -DCMAKE_VERBOSE_MAKEFILE=ON       \
@@ -62,7 +62,7 @@ jobs:
 
         ${{github.workspace}}/.github/workflows/source/makeMakefileForClangTidy.py --input ${{github.workspace}}/ccache.log.txt
         make -j4 --keep-going -f clang-tidy-ccache-misses.mak \
-            CLANG_TIDY=clang-tidy-15 \
+            CLANG_TIDY=clang-tidy-17 \
             CLANG_TIDY_ARGS="--config-file=${{github.workspace}}/.clang-tidy --warnings-as-errors=*"
 
         ccache -s

.github/workflows/cuda.yml

@@ -127,7 +127,7 @@ jobs:
         which nvcc || echo "nvcc not in PATH!"
 
         git clone https://github.com/AMReX-Codes/amrex.git ../amrex
-        cd ../amrex && git checkout --detach 0f46a1615c17f0bbeaedb20c27a97c9f6e439781 && cd -
+        cd ../amrex && git checkout --detach b364becad939a490bca4e7f8b23f7392c558a311 && cd -
         make COMP=gcc QED=FALSE USE_MPI=TRUE USE_GPU=TRUE USE_OMP=FALSE USE_FFT=TRUE USE_CCACHE=TRUE -j 4
 
         ccache -s

.pre-commit-config.yaml

@@ -69,7 +69,7 @@ repos:
 # Python: Ruff linter & formatter
 #   https://docs.astral.sh/ruff/
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.9.3
+  rev: v0.9.6
   hooks:
     # Run the linter
     - id: ruff

CMakeLists.txt

@@ -1,7 +1,7 @@
 # Preamble ####################################################################
 #
 cmake_minimum_required(VERSION 3.24.0)
-project(WarpX VERSION 25.01)
+project(WarpX VERSION 25.02)
 
 include(${WarpX_SOURCE_DIR}/cmake/WarpXFunctions.cmake)
 
@@ -81,18 +81,19 @@ option(WarpX_QED_TABLE_GEN "QED table generation (requires PICSAR and Boost)"
 option(WarpX_QED_TOOLS     "Build external tool to generate QED lookup tables (requires PICSAR and Boost)"
                                                                         OFF)
 
-# Advanced option to automatically clean up CI test directories
-option(WarpX_TEST_CLEANUP "Clean up CI test directories" OFF)
+# Advanced option to run tests
+option(WarpX_TEST_CLEANUP "Clean up automated test directories" OFF)
+option(WarpX_TEST_DEBUGGER "Run automated tests without AMReX signal handling (to attach debuggers)" OFF)
+option(WarpX_TEST_FPETRAP "Run automated tests with FPE-trapping runtime parameters" OFF)
 mark_as_advanced(WarpX_TEST_CLEANUP)
-
-# Advanced option to run CI tests with FPE-trapping runtime parameters
-option(WarpX_TEST_FPETRAP "Run CI tests with FPE-trapping runtime parameters" OFF)
+mark_as_advanced(WarpX_TEST_DEBUGGER)
 mark_as_advanced(WarpX_TEST_FPETRAP)
 
-# Advanced option to run CI tests with the -g compile option
-option(WarpX_TEST_DEBUG "Run CI tests with the -g compile option" OFF)
-mark_as_advanced(WarpX_TEST_DEBUG)
-if(WarpX_TEST_DEBUG)
+# Advanced option to compile with the -g1 option for minimal debug symbols
+# (useful to see, e.g., line numbers in backtraces)
+option(WarpX_BACKTRACE_INFO "Compile with -g1 for minimal debug symbols (currently used in CI tests)" OFF)
+mark_as_advanced(WarpX_BACKTRACE_INFO)
+if(WarpX_BACKTRACE_INFO)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -g1")
 endif()
 

CTestConfig.cmake

@@ -13,6 +13,8 @@ set(CTEST_SUBMIT_URL https://my.cdash.org/submit.php?project=WarpX)
 
 set(CTEST_DROP_SITE_CDASH TRUE)
 
-# Additional settings
-set(CTEST_SITE "Azure-Pipelines")
-set(CTEST_BUILD_NAME "CI-Development")
+# Set site and build names
+# - CTest script variables: CTEST_SITE, CTEST_BUILD_NAME
+# - CTest module variables: SITE, BUILDNAME
+set(SITE "Azure-Pipelines")
+set(BUILDNAME "CI-Development")

Docs/requirements.txt

@@ -27,5 +27,6 @@ sphinx-copybutton
 sphinx-design
 sphinx_rtd_theme>=1.1.1
 sphinxcontrib-bibtex
+sphinxcontrib-googleanalytics
 sphinxcontrib-napoleon
 yt  # for checksumAPI

Docs/source/conf.py

@@ -56,8 +56,13 @@
     "sphinx_design",
     "breathe",
     "sphinxcontrib.bibtex",
+    "sphinxcontrib.googleanalytics",
 ]
 
+# Google Analytics
+googleanalytics_id = "G-QZGY5060MZ"
+googleanalytics_enabled = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -107,9 +112,9 @@ def __init__(self, *args, **kwargs):
 # built documents.
 #
 # The short X.Y version.
-version = "25.01"
+version = "25.02"
 # The full version, including alpha/beta/rc tags.
-release = "25.01"
+release = "25.02"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

Docs/source/developers/particles.rst

@@ -141,7 +141,7 @@ Attribute name        ``int``/``real``  Description                         Wher
                                         Wheeler process                                physics is used.
 ====================  ================  ==================================  ===== ==== ======================
 
-WarpX allows extra runtime attributes to be added to particle containers (through ``NewRealComp("attrname")`` or ``NewIntComp("attrname")``).
+WarpX allows extra runtime attributes to be added to particle containers (through ``AddRealComp("attrname")`` or ``AddIntComp("attrname")``).
 The attribute name can then be used to access the values of that attribute.
 For example, using a particle iterator, ``pti``, to loop over the particles the command ``pti.GetAttribs(particle_comps["attrname"]).dataPtr();`` will return the values of the ``"attrname"`` attribute.
 

Docs/source/highlights.rst

@@ -14,7 +14,12 @@ Plasma-Based Acceleration
 
 Scientific works in laser-plasma and beam-plasma acceleration.
 
-#. Shrock JE, Rockafellow E, Miao B, Le M, Hollinger RC, Wang S, Gonsalves AJ, Picksley A, Rocca JJ, and Milchberg HM
+#. Ma M, Zeng M, Wang J, Lu G, Yan W, Chen L, and Li D.
+   **Particle-in-cell simulation of laser wakefield accelerators with oblique lasers in quasicylindrical geometry**.
+   Phys. Rev. Accel. Beams **28**, 021301, 2025
+   `DOI:10.1103/PhysRevAccelBeams.28.021301 <https://doi.org/10.1103/PhysRevAccelBeams.28.021301>`__
+
+#. Shrock JE, Rockafellow E, Miao B, Le M, Hollinger RC, Wang S, Gonsalves AJ, Picksley A, Rocca JJ, and Milchberg HM.
    **Guided Mode Evolution and Ionization Injection in Meter-Scale Multi-GeV Laser Wakefield Accelerators**.
    Phys. Rev. Lett. **133**, 045002, 2024
    `DOI:10.1103/PhysRevLett.133.045002 <https://link.aps.org/doi/10.1103/PhysRevLett.133.045002>`__
@@ -154,6 +159,21 @@ High Energy Astrophysical Plasma Physics
 
 Scientific works in astrophysical plasma modeling.
 
+#. Sam A, Kumar P, Fletcher AC, Crabtree C, Lee N, Elschot S.
+   **Nonlinear evolution, propagation, electron-trapping, and damping effects of ion-acoustic solitons using fully kinetic PIC simulations**.
+   Phys. Plasmas **32** 022103, 2025
+   `DOI:10.1063/5.0249525 <https://doi.org/10.1063/5.0249525>`__
+
+#. Jambunathan R, Jones H, Corrales L, Klion H, Roward ME, Myers A, Zhang W, Vay J-L.
+   **Application of mesh refinement to relativistic magnetic reconnection**.
+   Physics of Plasmas ***32*** 1, 2025
+   `DOI:10.1063/5.0233583 <https://doi.org/10.1063/5.0233583>`__
+
+#. Ghosh S, Bhat P.
+   **Magnetic Reconnection: An Alternative Explanation of Radio Emission in Galaxy Clusters**.
+   The Astrophysical Journal Letters **979** 1, 2025.
+   `DOI:10.3847/2041-8213/ad9f2d <https://doi.org/10.3847/2041-8213/ad9f2d>`__
+
 #. Klion H, Jambunathan R, Rowan ME, Yang E, Willcox D, Vay J-L, Lehe R, Myers A, Huebl A, Zhang W.
    **Particle-in-Cell simulations of relativistic magnetic reconnection with advanced Maxwell solver algorithms**.
    The Astrophysical Journal **952** 8, 2023.
@@ -199,6 +219,11 @@ Related works using WarpX:
 Nuclear Fusion and Plasma Confinement
 *************************************
 
+#. Tyushev M., Papahn Zadeh M., Chopra N. S., Raitses Y., Romadanov I., Likhanskii A., Fubiani G., Garrigues L., Groenewald R. and Smolyakov A.
+   **Mode transitions and spoke structures in  E×B Penning discharge**.
+   Physics of Plasmas **32**, 013511, 2025.
+   `DOI:10.1063/5.0238577 <https://doi.org/10.1063/5.0238577>`__
+
 #. Scheffel J. and Jäderberg J. and Bendtz K. and Holmberg R. and Lindvall K.,
    **Axial Confinement in the Novatron Mirror Machine**.
    arXiv 2410.20134

Docs/source/install/cmake.rst

@@ -143,6 +143,10 @@ CMake Option                  Default & Values                               Des
 ``WarpX_pybind11_repo``       ``https://github.com/pybind/pybind11.git``     Repository URI to pull and build pybind11 from
 ``WarpX_pybind11_branch``     *we set and maintain a compatible commit*      Repository branch for ``WarpX_pybind11_repo``
 ``WarpX_pybind11_internal``   **ON**/OFF                                     Needs a pre-installed pybind11 library if set to ``OFF``
+``WarpX_TEST_CLEANUP``        ON/**OFF**                                     Clean up automated test directories
+``WarpX_TEST_DEBUGGER``       ON/**OFF**                                     Run automated tests without AMReX signal handling (to attach debuggers)
+``WarpX_TEST_FPETRAP``        ON/**OFF**                                     Run automated tests with FPE-trapping runtime parameters
+``WarpX_BACKTRACE_INFO``      ON/**OFF**                                     Compile with -g1 for minimal debug symbols (currently used in CI tests)
 ============================= ============================================== ===========================================================
 
 For example, one can also build against a local AMReX copy.

Docs/source/install/hpc/perlmutter.rst

@@ -76,7 +76,7 @@ On Perlmutter, you can run either on GPU nodes with fast A100 GPUs (recommended)
       .. code-block:: bash
 
          bash $HOME/src/warpx/Tools/machines/perlmutter-nersc/install_gpu_dependencies.sh
-         source ${CFS}/${proj%_g}/${USER}/sw/perlmutter/gpu/venvs/warpx-gpu/bin/activate
+         source ${PSCRATCH}/storage/sw/warpx/perlmutter/gpu/venvs/warpx-gpu/bin/activate
 
       .. dropdown:: Script Details
          :color: light
@@ -126,7 +126,7 @@ On Perlmutter, you can run either on GPU nodes with fast A100 GPUs (recommended)
       .. code-block:: bash
 
          bash $HOME/src/warpx/Tools/machines/perlmutter-nersc/install_cpu_dependencies.sh
-         source ${CFS}/${proj}/${USER}/sw/perlmutter/cpu/venvs/warpx-cpu/bin/activate
+         source ${PSCRATCH}/storage/sw/warpx/perlmutter/cpu/venvs/warpx-cpu/bin/activate
 
       .. dropdown:: Script Details
          :color: light

Docs/source/install/users.rst

@@ -79,7 +79,7 @@ Using the Spack Package
 -----------------------
 
 Packages for WarpX are available via the `Spack <https://spack.readthedocs.io>`__ package manager.
-The package ``warpx`` installs executables and the package ``py-warpx`` includes Python bindings, i.e. `PICMI <https://github.com/picmi-standard/picmi>`_.
+The package ``warpx`` installs executables and the variant ``warpx +python`` also includes Python bindings, i.e. `PICMI <https://github.com/picmi-standard/picmi>`__.
 
 .. code-block:: bash
 
@@ -88,11 +88,11 @@ The package ``warpx`` installs executables and the package ``py-warpx`` includes
    spack buildcache keys --install --trust
 
    # see `spack info py-warpx` for build options.
-   # optional arguments:  -mpi ^warpx dims=2 compute=cuda
-   spack install py-warpx
-   spack load py-warpx
+   # optional arguments:       -mpi compute=cuda
+   spack install warpx +python
+   spack load warpx +python
 
-See ``spack info warpx`` or ``spack info py-warpx`` and `the official Spack tutorial <https://spack-tutorial.readthedocs.io>`__ for more information.
+See ``spack info warpx`` and `the official Spack tutorial <https://spack-tutorial.readthedocs.io>`__ for more information.
 
 
 .. _install-pypi:

Docs/source/refs.bib

@@ -35,6 +35,17 @@ @ARTICLE{Birdsall1991
 year = {1991}
 }
 
+@misc{Janssen2016
+author = {Janssen, J. F. J. and Pitchford L. C. and Hagelaar G. J. M. and van Dijk J.},
+doi = {10.1088/0963-0252/25/5/055026},
+journal = {Plasma Sources Science and Technology},
+number = {5},
+pages = {055026},
+title = {{Evaluation of angular scattering models for electron-neutral collisions in Monte Carlo simulations}},
+volume = {25},
+year = {2016}
+}
+
 @misc{Lim2007,
 author = {Lim, Chul-Hyun},
 issn = {0419-4217},
@@ -507,3 +518,13 @@ @article{Rhee1987
     url = {https://doi.org/10.1063/1.1139314},
     eprint = {https://pubs.aip.org/aip/rsi/article-pdf/58/2/240/19154912/240\_1\_online.pdf},
 }
+
+@misc{holmstrom2013handlingvacuumregionshybrid,
+      title={Handling vacuum regions in a hybrid plasma solver},
+      author={M. Holmstrom},
+      year={2013},
+      eprint={1301.0272},
+      archivePrefix={arXiv},
+      primaryClass={physics.space-ph},
+      url={https://arxiv.org/abs/1301.0272},
+}

Docs/source/theory/boundary_conditions.rst

@@ -301,3 +301,23 @@ the right boundary is reflecting.
 
 .. bibliography::
    :keyprefix: bc-
+
+.. _theory-bc-pmc:
+
+Perfect Magnetic Conductor
+----------------------------
+
+This boundary can be used to model a symmetric surface, where charges and current are
+symmetric across the boundary.
+This is equivalent to the Neumann (zero-derivative) boundary condition.
+For the electromagnetic solve, at PMC, the tangential magnetic field and the normal electric
+field are odd across the boundary and set to 0 on the boundary.
+In the guard-cell region, those fields are set equal and
+opposite to the respective field component in the mirror location across the PMC boundary.
+The other components, the normal magnetic field and tangential electric field, are even
+and set equal to the field component in the mirror location in the domain across the PMC boundary.
+
+The PMC boundary condition also impacts the deposition of charge and current density.
+The charge and current densities deposited into the guard cells are reflected back into
+the domain, adding them to the mirror cells in the domain.
+This represents the charge and current from the virtual symmetric particles in the guard cells.

Docs/source/theory/multiphysics/collisions.rst

@@ -121,13 +121,23 @@ The particle velocity in the COM frame is then isotropically scattered using the
 Back scattering
 ^^^^^^^^^^^^^^^
 
-The process is the same as for elastic scattering above expect the scattering angle is fixed at :math:`\pi`, meaning the particle velocity in the COM frame is updated to :math:`-\vec{u}_c`.
+The process is the same as for elastic scattering above except the scattering angle is fixed at :math:`\pi`, meaning the particle velocity in the COM frame is updated to :math:`-\vec{u}_c`.
 
 Excitation
 ^^^^^^^^^^
 
 The process is also the same as for elastic scattering except the excitation energy cost is subtracted from the particle energy. This is done by reducing the velocity before a scattering angle is chosen.
 
+Forward scattering
+^^^^^^^^^^^^^^^^^^
+
+This process operates in two ways:
+
+1. If an excitation energy cost is provided, the energy cost is subtracted from the particle energy and no scattering is performed.
+2. If an excitation energy cost is not provided, the particle is not scattered and the velocity is unchanged (corresponding to a scattering angle of :math:`0` in the elastic scattering process above).
+
+See :cite:t:`b-Janssen2016` for a recommended use of this process.
+
 Benchmarks
 ----------