Merge branch 'development' into RecordingDataAtStation

.clang-tidy

@@ -7,13 +7,13 @@ Checks: '
         -bugprone-unchecked-optional-access,
     cert-*,
         -cert-err58-cpp,
+    clang-diagnostic-*,
     cppcoreguidelines-*,
         -cppcoreguidelines-avoid-c-arrays,
         -cppcoreguidelines-avoid-magic-numbers,
         -cppcoreguidelines-avoid-non-const-global-variables,
         -cppcoreguidelines-init-variables,
         -cppcoreguidelines-macro-usage,
-        -cppcoreguidelines-no-malloc,
         -cppcoreguidelines-narrowing-conversions,
         -cppcoreguidelines-non-private-member-variables-in-classes,
         -cppcoreguidelines-owning-memory,
@@ -29,38 +29,20 @@ Checks: '
         -modernize-return-braced-init-list,
         -modernize-use-trailing-return-type,
     mpi-*,
-    performance-faster-string-find,
-    performance-for-range-copy,
-    performance-implicit-conversion-in-loop,
-    performance-inefficient-algorithm,
-    performance-inefficient-string-concatenation,
-    performance-inefficient-vector-operation,
-    performance-move-const-arg,
-    performance-move-constructor-init,
-    performance-no-automatic-move,
-    performance-no-int-to-ptr,
-    readability-avoid-const-params-in-decls,
-    readability-const-return-type,
-    readability-container-contains,
-    readability-container-data-pointer,
-    readability-container-size-empty,
-    readability-non-const-parameter,
-    readability-redundant-control-flow,
-    readability-redundant-declaration,
-    readability-redundant-function-ptr-dereference,
-    readability-redundant-member-init,
-    readability-redundant-preprocessor,
-    readability-redundant-smartptr-get,
-    readability-redundant-string-cstr,
-    readability-redundant-string-init,
-    readability-simplify-boolean-expr,
-    readability-simplify-subscript-expr,
-    readability-static-accessed-through-instance,
-    readability-static-definition-in-anonymous-namespace,
-    readability-string-compare,
-    readability-suspicious-call-argument,
-    readability-uniqueptr-delete-release,
-    readability-use-anyofallof,
+    performance-*,
+        -performance-unnecessary-copy-initialization,
+        -performance-unnecessary-value-param,
+    portability-*,
+    readability-*,
+        -readability-convert-member-functions-to-static,
+        -readability-else-after-return,
+        -readability-function-cognitive-complexity,
+        -readability-identifier-length,
+        -readability-implicit-bool-conversion,
+        -readability-isolate-declaration,
+        -readability-magic-numbers,
+        -readability-make-member-function-const,
+        -readability-named-parameter,
         -readability-uppercase-literal-suffix
     '
 

.github/workflows/clang_tidy.yml

@@ -50,7 +50,7 @@ jobs:
         cmake --build build_clang_tidy -j 2
 
         ${{github.workspace}}/.github/workflows/source/makeMakefileForClangTidy.py --input ${{github.workspace}}/ccache.log.txt
-        make -j2 -f clang-tidy-ccache-misses.mak \
+        make -j2 --keep-going -f clang-tidy-ccache-misses.mak \
             CLANG_TIDY=clang-tidy \
             CLANG_TIDY_ARGS="--config-file=${{github.workspace}}/.clang-tidy --warnings-as-errors=*"
 

.github/workflows/cuda.yml

@@ -115,7 +115,7 @@ jobs:
         which nvcc || echo "nvcc not in PATH!"
 
         git clone https://github.com/AMReX-Codes/amrex.git ../amrex
-        cd ../amrex && git checkout --detach 9b733ec45cd93a80234a7c98248b6eb4816589d5 && cd -
+        cd ../amrex && git checkout --detach 75571e2dcbf2417529c5ed8e24113580e8e1f3f1 && cd -
         make COMP=gcc QED=FALSE USE_MPI=TRUE USE_GPU=TRUE USE_OMP=FALSE USE_PSATD=TRUE USE_CCACHE=TRUE -j 2
 
         ccache -s

.github/workflows/dependencies/hip.sh

@@ -41,7 +41,8 @@ sudo apt-get install -y --no-install-recommends \
     rocm-dev        \
     rocfft-dev      \
     rocprim-dev     \
-    rocrand-dev
+    rocrand-dev     \
+    hiprand-dev
 
 # ccache
 $(dirname "$0")/ccache.sh

.github/workflows/macos.yml

@@ -18,25 +18,12 @@ jobs:
       #CMAKE_GENERATOR: Ninja
     steps:
     - uses: actions/checkout@v3
-    - name: Brew Cache
-      uses: actions/cache@v3
-      # - once stored under a key, they become immutable (even if local cache path content changes)
-      # - for a refresh the key has to change, e.g., hash of a tracked file in the key
-      with:
-        path: |
-          /usr/local/bin
-          /usr/local/lib
-          /usr/local/share
-          /Users/runner/Library/Caches/Homebrew
-        key: brew-macos-appleclang-${{ hashFiles('.github/workflows/macos.yml') }}
-        restore-keys: |
-          brew-macos-appleclang-
     - name: install dependencies
       run: |
-        brew --cache
         set +e
         brew unlink gcc
         brew update
+        brew upgrade || true
         brew install --overwrite python
         brew install ccache
         brew install fftw
@@ -69,6 +56,7 @@ jobs:
         export CCACHE_COMPRESS=1
         export CCACHE_COMPRESSLEVEL=10
         export CCACHE_MAXSIZE=100M
+        export CCACHE_DEPEND=1
         ccache -z
 
         source py-venv/bin/activate

.github/workflows/source/wrongFileNameInExamples

@@ -18,6 +18,7 @@ do
        [[ ${file:0:12} != PICMI_inputs ]] &&
        [[ ${file:0:8 } != analysis     ]] &&
        [[ ${file:  -4} != yaml         ]] &&
+       [[ ${file:0:4 } != plot         ]] &&
        [[ ${file:0:6 } != README       ]]
     then
         files+=($file)

.gitignore

@@ -38,7 +38,7 @@ Docs/warpx-doxygen-web.tag.xml
 Docs/openpmd-api-doxygen-web.tag.xml
 Docs/doxyhtml/
 Docs/doxyxml/
-Docs/source/_static/
+Docs/source/_static/doxyhtml
 
 ####################
 # Package Managers #

.pre-commit-config.yaml

@@ -76,7 +76,7 @@ repos:
 # Sorts Python imports according to PEP8
 # https://www.python.org/dev/peps/pep-0008/#imports
 - repo: https://github.com/pycqa/isort
-  rev: 5.12.0
+  rev: 5.13.2
   hooks:
   - id: isort
     name: isort (python)

CMakeLists.txt

@@ -1,7 +1,7 @@
 # Preamble ####################################################################
 #
 cmake_minimum_required(VERSION 3.20.0)
-project(WarpX VERSION 23.11)
+project(WarpX VERSION 23.12)
 
 include(${WarpX_SOURCE_DIR}/cmake/WarpXFunctions.cmake)
 

CONTRIBUTING.rst

@@ -117,7 +117,7 @@ A typical format is:
 
    This is a short, 40-character title
 
-   After a newline, you can write arbitray paragraphs. You
+   After a newline, you can write arbitrary paragraphs. You
    usually limit the lines to 70 characters, but if you don't, then
    nothing bad will happen.
 

Docs/requirements.txt

@@ -9,12 +9,15 @@
 breathe
 docutils>=0.17.1
 
+openpmd-viewer  # for checksumAPI
+
 # PICMI API docs
 # note: keep in sync with version in ../requirements.txt
 picmistandard==0.28.0
 # for development against an unreleased PICMI version, use:
 # picmistandard @ git+https://github.com/picmi-standard/picmi.git#subdirectory=PICMI_Python
 
+pybtex
 pygments
 recommonmark
 # Sphinx<7.2 because we are waiting for
@@ -25,3 +28,4 @@ sphinx-design
 sphinx_rtd_theme>=1.1.1
 sphinxcontrib-bibtex
 sphinxcontrib-napoleon
+yt  # for checksumAPI

Docs/source/_static/custom.css

@@ -0,0 +1,6 @@
+.eqno {
+    /* As of 2023 Dec, sphinx_rtd_theme has a bug where equation numbers appear above the equations instead of on the right */
+    /* The following is a make-shift fix, but comes at the cost of "making the header link invisible," though I'm not sure what that means */
+    /* Copied from https://github.com/readthedocs/sphinx_rtd_theme/issues/301#issuecomment-1205755904 */
+    float: right;
+}

Docs/source/conf.py

@@ -30,9 +30,11 @@
 import sys
 import urllib.request
 
+import pybtex.plugin
+from pybtex.style.formatting.unsrt import Style as UnsrtStyle
 import sphinx_rtd_theme
 
-sys.path.insert(0, os.path.join( os.path.abspath(__file__), '../Python') )
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), '../../Regression/Checksum'))
 
 # -- General configuration ------------------------------------------------
 
@@ -43,7 +45,8 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc',
+extensions = [
+    'sphinx.ext.autodoc',
     'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
@@ -57,8 +60,29 @@
 templates_path = ['_templates']
 
 # Relative path to bibliography file, bibliography style
-bibtex_bibfiles = ['./refs.bib']
-bibtex_default_style = 'unsrt'
+bibtex_bibfiles = ['latex_theory/allbibs.bib', 'refs.bib']
+
+# An brief introduction to custom BibTex formatting can be found in the Sphinx documentation:
+# https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#bibtex-custom-formatting
+#
+# More details can be gleaned from looking at the pybtex dist-package files.
+# Some examples include the following:
+# BaseStyle class in pybtex/style/formatting/__init__.py
+# UnsrtStyle class in pybtex/style/formating/unsrt.py
+class WarpXBibStyle(UnsrtStyle):
+    # This option makes the family name, i.e, "last" name, of an author to appear first.
+    # default_name_style = 'lastfirst'
+
+    def __init__(self, *args, **kwargs):
+        # This option makes the given names of an author abbreviated to just initials.
+        # Example: "Jean-Luc" becomes "J.-L."
+        # Set 'abbreviate_names' to True before calling the superclass (BaseStyle class) initializer
+        kwargs['abbreviate_names'] = True
+        super().__init__(*args, **kwargs)
+
+pybtex.plugin.register_plugin('pybtex.style.formatting', 'warpxbibstyle', WarpXBibStyle)
+
+bibtex_default_style = 'warpxbibstyle'
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -79,9 +103,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'23.11'
+version = u'23.12'
 # The full version, including alpha/beta/rc tags.
-release = u'23.11'
+release = u'23.12'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -110,6 +134,11 @@
 html_theme = 'sphinx_rtd_theme'
 
 numfig = True
+math_eqref_format = "{number}"
+numfig_format = {'figure': 'Fig. %s',
+                 'table': 'Table %s',
+                 'code-block': 'Listing %s',
+                 'section': 'Section %s'}
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -122,6 +151,9 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_css_files = [
+    'custom.css',
+]
 
 # -- Options for HTMLHelp output ------------------------------------------
 

Docs/source/dataanalysis/ascent.rst

@@ -274,7 +274,7 @@ Example Actions
 A visualization of the electric field component :math:`E_x` (variable: ``Ex``) with a contour plot and with added particles can be obtained with the following Ascent Action.
 This action can be used both in replay as well as in situ runs.
 
-.. literalinclude:: examples/Physics_applications/laser_acceleration/ascent_actions.yaml
+.. literalinclude:: ../../../Examples/Physics_applications/laser_acceleration/ascent_actions.yaml
    :language: yaml
 
 There are more `Ascent Actions examples available <https://ascent.readthedocs.io/en/latest/Actions/Examples.html#yaml-examples>`_ for you to play.

Docs/source/dataanalysis/sensei.rst

@@ -30,7 +30,7 @@ and bridge code making it easy to use in AMReX based simulation codes.
 SENSEI provides a *configurable analysis adaptor* which uses an XML file to
 select and configure one or more back ends at run time. Run time selection of
 the back end via XML means one user can access Catalyst, another Libsim, yet
-another Python with no changes to the code.  This is depicted in figure
+another Python with no changes to the code.  This is depicted in
 :numref:`sensei_arch`. On the left side of the figure AMReX produces data, the
 bridge code pushes the data through the configurable analysis adaptor to the
 back end that was selected at run time.
@@ -99,7 +99,7 @@ The back end is selected and configured at run time using the SENSEI XML file.
 The XML sets parameters specific to SENSEI and to the chosen back end. Many of
 the back ends have sophisticated configuration mechanisms which SENSEI makes
 use of.  For example the following XML configuration was used on NERSC's Cori
-with WarpX to render 10 iso surfaces, shown in figure :numref:`lpa_visit`, using
+with WarpX to render 10 iso surfaces, shown in :numref:`lpa_visit`, using
 VisIt Libsim.
 
 .. code-block:: xml
@@ -123,7 +123,7 @@ run of the desired simulation.
    quadrant has been clipped away to reveal innner structure.
 
 The same run and visualization was repeated using ParaView Catalyst, shown in
-figure :numref:`lpa_pv`, by providing the following XML configuration.
+:numref:`lpa_pv`, by providing the following XML configuration.
 
 .. code-block:: xml
 

Docs/source/developers/checksum.rst

@@ -9,14 +9,14 @@ The checksum module is located in ``Regression/Checksum/``, and the benchmarks a
 
 For more details on the implementation, the Python files in ``Regression/Checksum/`` should be well documented.
 
-From a user point of view, you should only need to use ``checksumAPI.py``. It contains Python functions that can be imported and used from an analysis Python script. It can also be executed directly as a Python script. Here are recipies for the main tasks related to checksum regression tests in WarpX CI.
+From a user point of view, you should only need to use ``checksumAPI.py``. It contains Python functions that can be imported and used from an analysis Python script. It can also be executed directly as a Python script. Here are recipes for the main tasks related to checksum regression tests in WarpX CI.
 
 Include a checksum regression test in an analysis Python script
 ---------------------------------------------------------------
 
-This relies on function ``evaluate_checksum``:
+This relies on the function ``evaluate_checksum``:
 
-.. doxygenfunction:: evaluate_checksum
+.. autofunction:: checksumAPI.evaluate_checksum
 
 For an example, see
 
@@ -32,7 +32,7 @@ You can execute ``checksumAPI.py`` as a Python script for that, and pass the plo
 
 .. code-block:: bash
 
-   ./checksumAPI.py --evaluate --plotfile <path/to/plotfile> --test-name <test name>
+   ./checksumAPI.py --evaluate --output-file <path/to/plotfile> --format <'openpmd' or 'plotfile'> --test-name <test name>
 
 See additional options
 
@@ -41,17 +41,17 @@ See additional options
 * ``--rtol`` relative tolerance for the comparison
 * ``--atol`` absolute tolerance for the comparison (a sum of both is used by ``numpy.isclose()``)
 
-Reset a benchmark with new values that you know are correct
------------------------------------------------------------
+Create/Reset a benchmark with new values that you know are correct
+------------------------------------------------------------------
 
-Reset a benchmark from a plotfile generated locally
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Create/Reset a benchmark from a plotfile generated locally
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This is using ``checksumAPI.py`` as a Python script.
 
 .. code-block:: bash
 
-   ./checksumAPI.py --reset-benchmark --plotfile <path/to/plotfile> --test-name <test name>
+   ./checksumAPI.py --reset-benchmark --output-file <path/to/plotfile> --format <'openpmd' or 'plotfile'> --test-name <test name>
 
 See additional options
 

Docs/source/developers/fields.rst

@@ -112,9 +112,9 @@ Bilinear filter
 
 The multi-pass bilinear filter (applied on the current density) is implemented in ``Source/Filter/``, and class ``WarpX`` holds an instance of this class in member variable ``WarpX::bilinear_filter``. For performance reasons (to avoid creating too many guard cells), this filter is directly applied in communication routines, see ``WarpX::AddCurrentFromFineLevelandSumBoundary`` above and
 
-.. doxygenfunction:: WarpX::ApplyFilterJ(const amrex::Vector<std::array<std::unique_ptr<amrex::MultiFab>, 3>> &current, const int lev, const int idim)
+.. doxygenfunction:: WarpX::ApplyFilterJ(const amrex::Vector<std::array<std::unique_ptr<amrex::MultiFab>, 3>> &current, int lev, int idim)
 
-.. doxygenfunction:: WarpX::SumBoundaryJ(const amrex::Vector<std::array<std::unique_ptr<amrex::MultiFab>, 3>> &current, const int lev, const int idim, const amrex::Periodicity &period)
+.. doxygenfunction:: WarpX::SumBoundaryJ(const amrex::Vector<std::array<std::unique_ptr<amrex::MultiFab>, 3>> &current, int lev, int idim, const amrex::Periodicity &period)
 
 Godfrey's anti-NCI filter for FDTD simulations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~