Merge branch 'development' into implicit_picard

.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 23.12 && cd -
+        cd ../amrex && git checkout --detach ecaa46d0be4b5c79b8806e48e3469000d8bb7252 && 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/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

.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.0
   hooks:
   - id: isort
     name: isort (python)

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/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:

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
 

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/index.rst

@@ -75,9 +75,9 @@ Usage
    :hidden:
 
    usage/how_to_run
+   usage/examples
    usage/python
    usage/parameters
-   usage/examples
    usage/workflows
    usage/faq
 

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/hpc/leonardo.rst

@@ -103,9 +103,9 @@ Additionally, the following commands will install WarpX as a Python module:
    cmake -S . -B build_gpu_py -DWarpX_COMPUTE=CUDA -DWarpX_PSATD=ON -DWarpX_QED_TABLE_GEN=ON -DWarpX_PYTHON=ON -DWarpX_APP=OFF -DWarpX_DIMS="1;2;RZ;3"
    cmake --build build_gpu_py -j 16 --target pip_install
 
-Now, you can :ref:`submit Leonardo compute jobs <running-cpp-leonardo>` for WarpX :ref:`Python (PICMI) scripts <usage-picmi>` (:ref:`example scripts <usage-examples>`).
+Now, you can :ref:`submit Leonardo compute jobs <running-leonardo>` for WarpX :ref:`Python (PICMI) scripts <usage-picmi>` (:ref:`example scripts <usage-examples>`).
 Or, you can use the WarpX executables to submit Leonardo jobs (:ref:`example inputs <usage-examples>`).
-For executables, you can reference their location in your :ref:`job script <running-cpp-leonardo>` or copy them to a location in ``$CINECA_SCRATCH``.
+For executables, you can reference their location in your :ref:`job script <running-leonardo>` or copy them to a location in ``$CINECA_SCRATCH``.
 
 .. _building-leonardo-update:
 

Docs/source/latex_theory/AMR/AMR.tex

@@ -22,7 +22,7 @@ \section{Mesh refinement}
 In addition, for some implementations where the field that is computed at a given level is affected by the solution at finer levels, there are cases where the procedure violates the integral of Gauss' Law around the refined patch, leading to long range errors \cite{Vaylpb2002,Colellajcp2010}. As will be shown below, in the procedure that has been developed in WarpX, the field at a given refinement level is not affected by the solution at finer levels, and is thus not affected by this type of error.
 
 \subsection{Electrostatic}
-A cornerstone of the Particle-In-Cell method is that assuming a particle lying in a hypothetical infinite grid, then if the grid is regular and symmetrical, and if the order of field gathering matches the order of charge (or current) deposition, then there is no self-force of the particle acting on itself: a) anywhere if using the so-called ``momentum conserving'' gathering scheme; b) on average within one cell if using the ``energy conserving'' gathering scheme \cite{Birdsalllangdon}. A breaking of the regularity and/or symmetry in the grid, whether it is from the use of irregular meshes or mesh refinement, and whether one uses finite difference, finite volume or finite elements, results in a net spurious self-force (which does not average to zero over one cell)  for a macroparticle close to the point of irregularity (mesh refinement interface for the current purpose) \cite{Vaylpb2002,Colellajcp2010}.
+A cornerstone of the Particle-In-Cell method is that, given a particle lying in a hypothetical infinite grid, if the grid is regular and symmetrical, and if the order of field gathering matches the order of charge (or current) deposition, then there is no self-force of the particle acting on itself: a) anywhere if using the so-called ``momentum conserving'' gathering scheme; b) on average within one cell if using the ``energy conserving'' gathering scheme \cite{Birdsalllangdon}. A breaking of the regularity and/or symmetry in the grid, whether it is from the use of irregular meshes or mesh refinement, and whether one uses finite difference, finite volume or finite elements, results in a net spurious self-force (which does not average to zero over one cell)  for a macroparticle close to the point of irregularity (mesh refinement interface for the current purpose) \cite{Vaylpb2002,Colellajcp2010}.
 
 A sketch of the implementation of mesh refinement in WarpX is given in Figure~\ref{fig:ESAMR} (left). Given the solution of the electric potential at a refinement level $L_n$, it is interpolated onto the boundaries of the grid patch(es) at the next refined level $L_{n+1}$. The electric potential is then computed at level $L_{n+1}$ by solving the Poisson equation. This procedure necessitates the knowledge of the charge density at every level of refinement. For efficiency, the macroparticle charge is deposited on the highest level patch that contains them, and the charge density of each patch is added recursively to lower levels, down to the lowest.
 

Docs/source/latex_theory/Boosted_frame/Boosted_frame.tex

@@ -175,7 +175,7 @@ \subsection{Numerical Stability and alternate formulation in a Galilean frame}
 the simulation, and the artificial ``bump'' is again an arbitrary correction
 that departs from the underlying physics.
 
-A new scheme was recently proposed, in \cite{KirchenARXIV2016,LeheARXIV2016}, which
+A new scheme was recently proposed, in \cite{KirchenPOP2016,LehePRE2016}, which
 completely eliminates the NCI for a plasma drifting at a uniform relativistic velocity
 -- with no arbitrary correction -- by simply integrating
 the PIC equations in \emph{Galilean coordinates} (also known as
@@ -217,7 +217,7 @@ \subsection{Numerical Stability and alternate formulation in a Galilean frame}
 \emph{themselves} are not only translated but in this case, the physical equations
 are modified accordingly. Most importantly, the assumed time evolution of
 the current $\vec{J}$ within one timestep is different in a standard PSATD scheme with moving
-window and in a Galilean PSATD scheme \cite{LeheARXIV2016}.
+window and in a Galilean PSATD scheme \cite{LehePRE2016}.
 
 In the Galilean coordinates $\vec{x}'$, the equations of particle
 motion and the Maxwell equations take the form
@@ -235,7 +235,7 @@ \subsection{Numerical Stability and alternate formulation in a Galilean frame}
 
 Integrating these equations from $t=n\Delta
 t$ to $t=(n+1)\Delta t$ results in the following update equations (see
-\cite{LeheARXIV2016} for the details of the derivation):
+\cite{LehePRE2016} for the details of the derivation):
 %
 \begin{subequations}
 \begin{align}
@@ -271,5 +271,5 @@ \subsection{Numerical Stability and alternate formulation in a Galilean frame}
 Note that, in the limit $\vgal=\vec{0}$,
 (\ref{eq:disc-maxwell1}) and (\ref{eq:disc-maxwell2}) reduce to the standard PSATD
 equations \cite{Habericnsp73}, as expected.
-As shown in \cite{KirchenARXIV2016,LeheARXIV2016},
+As shown in \cite{KirchenPOP2016,LehePRE2016},
 the elimination of the NCI with the new Galilean integration is verified empirically via PIC simulations of uniform drifting plasmas and laser-driven plasma acceleration stages, and confirmed by a theoretical analysis of the instability.