Merge remote-tracking branch 'origin/development' into secondary_emis…

…sion_callback

.azure-pipelines.yml

@@ -155,8 +155,16 @@ jobs:
   - bash: |
       # set options
       set -o nounset errexit pipefail
-      # run tests (exclude pytest.AMReX when running Python tests)
-      ctest --test-dir build --output-on-failure -E AMReX
+      # determine if the build was triggered by a push to the development branch
+      if [[ "$(Build.SourceBranch)" == "refs/heads/development" ]]; then
+        # run tests (exclude pytest.AMReX when running Python tests)
+        # and submit results to CDash as Experimental
+        ctest --test-dir build --output-on-failure -E AMReX \
+          -D ExperimentalTest -D ExperimentalSubmit
+      else
+        # run tests (exclude pytest.AMReX when running Python tests)
+        ctest --test-dir build --output-on-failure -E AMReX
+      fi
     displayName: 'Test'
 
   - bash: |

.github/ISSUE_TEMPLATE/blank_issue.md

@@ -0,0 +1,14 @@
+---
+name: Blank issue
+about: Ask us a question
+labels: [question]
+---
+
+Are you here because you have something to report that is neither a bug, a new feature, nor an installation problem?
+
+Before opening this issue, consider opening a [discussion](https://github.com/ECP-WarpX/WarpX/discussions) instead!
+
+Issues are used to report bugs, installation problems or to request new features.
+Discussions are used to ask more open-ended questions, brainstorm, ask our feedback, etc.
+
+You can find more details on how to use issues and discussions [here](https://github.com/ECP-WarpX/WarpX/blob/development/CONTRIBUTING.rst).

.github/ISSUE_TEMPLATE/config.yml

@@ -1 +1 @@
-blank_issues_enabled: true
+blank_issues_enabled: false

.github/workflows/clang_sanitizers.yml

@@ -27,7 +27,7 @@ jobs:
     - uses: actions/checkout@v4
     - name: install dependencies
       run: |
-        .github/workflows/dependencies/clang17.sh
+        .github/workflows/dependencies/clang.sh 17
     - name: CCache Cache
       uses: actions/cache@v4
       with:
@@ -89,7 +89,7 @@ jobs:
     - uses: actions/checkout@v4
     - name: install dependencies
       run: |
-        .github/workflows/dependencies/clang17.sh
+        .github/workflows/dependencies/clang.sh 17
     - name: CCache Cache
       uses: actions/cache@v4
       with:

.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: 180
+    timeout-minutes: 220
     if: github.event.pull_request.draft == false
     steps:
     - uses: actions/checkout@v4
     - name: install dependencies
       run: |
-        .github/workflows/dependencies/clang15.sh
+        .github/workflows/dependencies/clang.sh 15
     - name: set up cache
       uses: actions/cache@v4
       with:

.github/workflows/cuda.yml

@@ -56,7 +56,7 @@ jobs:
         which nvcc || echo "nvcc not in PATH!"
 
         cmake-easyinstall --prefix=/usr/local \
-          git+https://github.com/openPMD/openPMD-api.git@0.15.1 \
+          git+https://github.com/openPMD/openPMD-api.git@0.16.1 \
           -DopenPMD_USE_PYTHON=OFF    \
           -DBUILD_TESTING=OFF         \
           -DBUILD_EXAMPLES=OFF        \
@@ -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 e761abff95afbfa442cbe108027094bbddef5b11 && cd -
+        cd ../amrex && git checkout --detach 0f46a1615c17f0bbeaedb20c27a97c9f6e439781 && 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

.github/workflows/dependencies/clang17.sh → .github/workflows/dependencies/clang.sh

@@ -1,45 +1,50 @@
 #!/usr/bin/env bash
 #
-# Copyright 2024 The WarpX Community
+# Copyright 2025 The WarpX Community
 #
 # License: BSD-3-Clause-LBNL
-# Authors: Luca Fedeli
 
 set -eu -o pipefail
 
-# `man apt.conf`:
-#   Number of retries to perform. If this is non-zero APT will retry
-#   failed files the given number of times.
+# `man apt.conf`: number of retries to perform (if non-zero,
+# APT will retry failed files the given number of times).
 echo 'Acquire::Retries "3";' | sudo tee /etc/apt/apt.conf.d/80-retries
 
-# This dependency file is currently used within a docker container,
-# which does not come (among others) with wget, xz-utils, curl, git,
-# ccache, and pkg-config pre-installed.
-sudo apt-get -qqq update
+sudo apt-get update
 sudo apt-get install -y \
     cmake               \
-    clang-17            \
-    clang-tidy-17       \
     libblas-dev         \
-    libc++-17-dev       \
     libboost-math-dev   \
     libfftw3-dev        \
     libfftw3-mpi-dev    \
     libhdf5-openmpi-dev \
     liblapack-dev       \
     libopenmpi-dev      \
-    libomp-17-dev       \
-    ninja-build         \
-    wget                \
-    xz-utils            \
-    curl                \
-    git                 \
-    ccache              \
-    pkg-config
+    ninja-build
 
-# Use clang 17
-export CXX=$(which clang++-17)
-export CC=$(which clang-17)
+# parse clang version number from command line
+version_number=${1}
+
+# add LLVM repository and install clang tools
+wget https://apt.llvm.org/llvm.sh
+chmod +x llvm.sh
+sudo ./llvm.sh ${version_number}
+
+# install clang, clang-tidy, and
+# LLVM implementations of C++ standard library and OpenMP
+sudo apt-get update
+sudo apt-get install -y          \
+    clang-${version_number}      \
+    clang-tidy-${version_number} \
+    libc++-${version_number}-dev \
+    libomp-${version_number}-dev
+
+# export compiler flags
+export CXX=$(which clang++-${version_number})
+export CC=$(which clang-${version_number})
+
+# ccache
+$(dirname "$0")/ccache.sh
 
 # cmake-easyinstall
 #

.github/workflows/dependencies/icc.sh

@@ -58,7 +58,7 @@ export CEI_TMP="/tmp/cei"
 CXX=$(which icpc) CC=$(which icc) \
   cmake-easyinstall               \
   --prefix=/usr/local             \
-  git+https://github.com/openPMD/openPMD-api.git@0.15.2 \
+  git+https://github.com/openPMD/openPMD-api.git@0.16.1 \
   -DopenPMD_USE_PYTHON=OFF \
   -DBUILD_TESTING=OFF      \
   -DBUILD_EXAMPLES=OFF     \

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

CMakeLists.txt

@@ -193,7 +193,8 @@ if(WarpX_FFT)
     set(ABLASTR_FFT ON CACHE STRING "FFT-based solvers" FORCE)
 endif()
 
-# this defined the variable BUILD_TESTING which is ON by default
+# Define the variable BUILD_TESTING (ON by default),
+# include CDash dashboard testing module
 include(CTest)
 
 

CONTRIBUTING.rst

@@ -12,6 +12,36 @@ Git workflow
 The WarpX project uses `git <https://git-scm.com>`_ for version control.
 If you are new to git, you can follow `this tutorial <https://swcarpentry.github.io/git-novice/>`__.
 
+
+What to do when
+^^^^^^^^^^^^^^^
+
+Issues
+""""""
+
+`Issues <https://github.com/ECP-WarpX/WarpX/issues>`__ are used to track tasks that the contributors and/or maintainers can work on.
+Use issues for reporting bugs or installation problems and for requesting new features.
+
+If you've found a bug and wish to report it, first search the open issues and `pull requests <https://github.com/ECP-WarpX/WarpX/pulls>`__ to see if someone else has already reported the same thing.
+If it's something new, open an issue using a template.
+We'll use the issue to address the problem you've encountered.
+
+Discussions
+"""""""""""
+
+`Discussions <https://github.com/ECP-WarpX/WarpX/discussions>`__ are for open-ended conversations, general questions, brainstorming ideas.
+Please, use discussions if you want to ask us something that is not technically a bug or a feature.
+Feel free to ping us there!
+
+Pull Requests (PRs)
+"""""""""""""""""""
+
+Open a `pull request <https://github.com/ECP-WarpX/WarpX/pulls>`__ if you want to add a new feature yourself.
+Follow the guide below for more details.
+
+
+Thank you for contributing! 🥰
+
 Configure your GitHub Account & Development Machine
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

CTestConfig.cmake

@@ -0,0 +1,18 @@
+## This file should be placed in the root directory of your project.
+## Then modify the CMakeLists.txt file in the root directory of your
+## project to incorporate the testing dashboard.
+##
+## # The following are required to submit to the CDash dashboard:
+##   ENABLE_TESTING()
+##   INCLUDE(CTest)
+
+set(CTEST_PROJECT_NAME WarpX)
+set(CTEST_NIGHTLY_START_TIME 08:00:00 UTC)
+
+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")

Docs/source/dataanalysis/workflows.rst

@@ -1,7 +1,8 @@
+.. _dataanalysis-how-to:
 .. _dataanalysis-workflows:
 
-Workflows
-=========
+How-To Guides
+=============
 
 This section collects typical user workflows and best practices for data analysis with WarpX.
 

Docs/source/developers/gnumake/openpmd.rst

@@ -9,7 +9,7 @@ therefore we recommend to use `spack <https://
 spack.io>`__ in order to facilitate the installation.
 
 More specifically, we recommend that you try installing the
-`openPMD-api library 0.15.1 or newer <https://openpmd-api.readthedocs.io/en/0.15.1/>`__
+`openPMD-api library 0.16.1 or newer <https://openpmd-api.readthedocs.io/en/0.16.1/>`__
 using spack (first section below). If this fails, a back-up solution
 is to install parallel HDF5 with spack, and then install the openPMD-api
 library from source.

Docs/source/developers/local_compile.rst → Docs/source/developers/how_to_compile_locally.rst

@@ -1,7 +1,7 @@
 .. _developers-local-compile:
 
-Fast, Local Compilation
-=======================
+How to compile locally and fast
+===============================
 
 For simplicity, WarpX :ref:`compilation with CMake <building-cmake>` by default downloads, configures and compiles compatible versions of :ref:`central dependencies <install-dependencies>` such as:
 

Docs/source/developers/how_to_guides.rst

@@ -0,0 +1,13 @@
+.. _development-howtoguides:
+
+How-To Guides
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   how_to_profile
+   how_to_test
+   how_to_run_clang_tidy
+   how_to_compile_locally
+   how_to_write_the_docs

Docs/source/developers/profiling.rst → Docs/source/developers/how_to_profile.rst

@@ -1,7 +1,7 @@
 .. _developers-profiling:
 
-Profiling the Code
-==================
+How to profile the code
+=======================
 
 Profiling allows us to find the bottle-necks of the code as it is currently implemented.
 Bottle-necks are the parts of the code that may delay the simulation, making it more computationally expensive.