Merge branch 'development' of https://github.com/ECP-WarpX/WarpX into…

… comments-typos

.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,19 @@ 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-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 23.12 && cd -
+        cd ../amrex && git checkout --detach 255d30f387cf2c1a7eff5a31f703c94de803e8d8 && 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

@@ -23,6 +23,7 @@ jobs:
         set +e
         brew unlink gcc
         brew update
+        brew upgrade || true
         brew install --overwrite python
         brew install ccache
         brew install fftw

.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.12)
+project(WarpX VERSION 24.01)
 
 include(${WarpX_SOURCE_DIR}/cmake/WarpXFunctions.cmake)
 

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.12'
+version = u'24.01'
 # The full version, including alpha/beta/rc tags.
-release = u'23.12'
+release = u'24.01'
 
 # 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/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 inner 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

@@ -14,9 +14,9 @@ From a user point of view, you should only need to use ``checksumAPI.py``. It co
 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/profiling.rst

@@ -121,7 +121,7 @@ Perlmutter Example
 """"""""""""""""""
 
 Example on how to create traces on a multi-GPU system that uses the Slurm scheduler (e.g., NERSC's Perlmutter system).
-You can either run this on an interactive node or use the Slurm batch script header :ref:`documented here <running-cpp-perlmutter-A100-GPUs>`.
+You can either run this on an interactive node or use the Slurm batch script header :ref:`documented here <running-cpp-perlmutter>`.
 
 .. code-block:: bash
 

Docs/source/developers/testing.rst

@@ -18,7 +18,7 @@ We slightly modify this file in ``Regression/prepare_file_ci.py``.
 
 For example, if you like to change the compiler to compilation to build on Nvidia GPUs, modify this block to add ``-DWarpX_COMPUTE=CUDA``:
 
-.. code-block:: toml
+.. code-block:: ini
 
    [source]
    dir = /home/regtester/AMReX_RegTesting/warpx

Docs/source/highlights.rst

@@ -149,7 +149,12 @@ Please see :ref:`this section <acknowledge_warpx_all_refs>`.
 Nuclear Fusion - Magnetically Confined Plasmas
 **********************************************
 
-#. Nicks, B. S., Putvinski, S. and Tajima, T.
+#. Nicks B. S., Putvinski S. and Tajima T.
    **Stabilization of the Alfvén-ion cyclotron instability through short plasmas: Fully kinetic simulations in a high-beta regime**.
    Physics of Plasmas **30**, 102108, 2023.
    `DOI:10.1063/5.0163889 <https://doi.org/10.1063/5.0163889>`__
+
+#. Groenewald R. E., Veksler A., Ceccherini F., Necas A., Nicks B. S., Barnes D. C., Tajima T. and Dettrick S. A.
+   **Accelerated kinetic model for global macro stability studies of high-beta fusion reactors**.
+   Physics of Plasmas **30**, 122508, 2023.
+   `DOI:10.1063/5.0178288 <https://doi.org/10.1063/5.0178288>`__

Docs/source/index.rst

@@ -75,9 +75,9 @@ Usage
    :hidden:
 
    usage/how_to_run
+   usage/examples
    usage/python
    usage/parameters
-   usage/examples
    usage/workflows
    usage/faq
 
@@ -107,9 +107,9 @@ Theory
    :hidden:
 
    theory/intro
-   theory/picsar_theory
+   theory/pic
    theory/amr
-   theory/PML
+   theory/boundary_conditions
    theory/boosted_frame
    theory/input_output
    theory/collisions

Docs/source/install/cmake.rst

@@ -130,7 +130,7 @@ CMake Option                  Default & Values                               Des
 ``WarpX_picsar_repo``         ``https://github.com/ECP-WarpX/picsar.git``    Repository URI to pull and build PICSAR from
 ``WarpX_picsar_branch``       *we set and maintain a compatible commit*      Repository branch for ``WarpX_picsar_repo``
 ``WarpX_picsar_internal``     **ON**/OFF                                     Needs a pre-installed PICSAR library if set to ``OFF``
-``WarpX_pyamrex_src``        *None*                                          Path to PICSAR source directory (preferred if set)
+``WarpX_pyamrex_src``         *None*                                         Path to PICSAR source directory (preferred if set)
 ``WarpX_pyamrex_repo``        ``https://github.com/AMReX-Codes/pyamrex.git`` Repository URI to pull and build pyAMReX from
 ``WarpX_pyamrex_branch``      *we set and maintain a compatible commit*      Repository branch for ``WarpX_pyamrex_repo``
 ``WarpX_pyamrex_internal``    **ON**/OFF                                     Needs a pre-installed pyAMReX library if set to ``OFF``

Docs/source/install/dependencies.rst

@@ -18,7 +18,7 @@ Optional dependencies include:
 - for on-node accelerated compute *one of either*:
 
   - `OpenMP 3.1+ <https://www.openmp.org>`__: for threaded CPU execution or
-  - `CUDA Toolkit 11.0+ (11.3+ recommended) <https://developer.nvidia.com/cuda-downloads>`__: for Nvidia GPU support (see `matching host-compilers <https://gist.github.com/ax3l/9489132>`_) or
+  - `CUDA Toolkit 11.7+ <https://developer.nvidia.com/cuda-downloads>`__: for Nvidia GPU support (see `matching host-compilers <https://gist.github.com/ax3l/9489132>`_) or
   - `ROCm 5.2+ (5.5+ recommended) <https://gpuopen.com/learn/amd-lab-notes/amd-lab-notes-rocm-installation-readme/>`__: for AMD GPU support
 - `FFTW3 <http://www.fftw.org>`_: for spectral solver (PSATD) support when running on CPU or SYCL