Merge ECP-WarpX:development into EZoni:docs_howto

.azure-pipelines.yml

@@ -13,6 +13,7 @@ pr:
   paths:
     exclude:
     - Docs
+    - '**/*.rst'
 
 jobs:
 - job:

.github/workflows/clang_sanitizers.yml

@@ -7,6 +7,7 @@ on:
   pull_request:
     paths-ignore:
       - "Docs/**"
+      - "**.rst"
 
 concurrency:
   group: ${{ github.ref }}-${{ github.head_ref }}-clangsanitizers

.github/workflows/clang_tidy.yml

@@ -7,6 +7,7 @@ on:
   pull_request:
     paths-ignore:
       - "Docs/**"
+      - "**.rst"
 
 concurrency:
   group: ${{ github.ref }}-${{ github.head_ref }}-clangtidy

.github/workflows/cuda.yml

@@ -7,6 +7,7 @@ on:
   pull_request:
     paths-ignore:
       - "Docs/**"
+      - "**.rst"
 
 concurrency:
   group: ${{ github.ref }}-${{ github.head_ref }}-cuda

.github/workflows/hip.yml

@@ -7,6 +7,7 @@ on:
   pull_request:
     paths-ignore:
       - "Docs/**"
+      - "**.rst"
 
 concurrency:
   group: ${{ github.ref }}-${{ github.head_ref }}-hip

.github/workflows/insitu.yml

@@ -7,6 +7,7 @@ on:
   pull_request:
     paths-ignore:
       - "Docs/**"
+      - "**.rst"
 
 concurrency:
   group: ${{ github.ref }}-${{ github.head_ref }}-insituvis

.github/workflows/intel.yml

@@ -7,6 +7,7 @@ on:
   pull_request:
     paths-ignore:
       - "Docs/**"
+      - "**.rst"
 
 concurrency:
   group: ${{ github.ref }}-${{ github.head_ref }}-intel

.github/workflows/macos.yml

@@ -7,6 +7,7 @@ on:
   pull_request:
     paths-ignore:
       - "Docs/**"
+      - "**.rst"
 
 concurrency:
   group: ${{ github.ref }}-${{ github.head_ref }}-macos

.github/workflows/ubuntu.yml

@@ -7,6 +7,7 @@ on:
   pull_request:
     paths-ignore:
       - "Docs/**"
+      - "**.rst"
 
 concurrency:
   group: ${{ github.ref }}-${{ github.head_ref }}-ubuntu

.github/workflows/windows.yml

@@ -7,6 +7,7 @@ on:
   pull_request:
     paths-ignore:
       - "Docs/**"
+      - "**.rst"
 
 concurrency:
   group: ${{ github.ref }}-${{ github.head_ref }}-windows

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

CMakeLists.txt

@@ -480,7 +480,7 @@ foreach(D IN LISTS WarpX_DIMS)
                 warpx_enable_IPO(pyWarpX_${SD})
             else()
                 # conditionally defined target in pybind11
-                # https://github.com/pybind/pybind11/blob/v2.12.0/tools/pybind11Common.cmake#L397-L403
+                # https://github.com/pybind/pybind11/blob/v2.13.0/tools/pybind11Common.cmake#L407-L413
                 target_link_libraries(pyWarpX_${SD} PRIVATE pybind11::lto)
             endif()
         endif()

Docs/source/developers/checksum.rst

@@ -22,11 +22,6 @@ This relies on the function ``evaluate_checksum``:
 
 .. autofunction:: checksumAPI.evaluate_checksum
 
-Here's an example:
-
-.. literalinclude:: ../../../Examples/Tests/embedded_circle/analysis.py
-   :language: python
-
 This can also be included as part of an existing analysis script.
 
 How to evaluate checksums from the command line

Docs/source/developers/fields.rst

@@ -119,9 +119,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::ApplyFilterMF(const amrex::Vector<std::array<std::unique_ptr<amrex::MultiFab>, 3>> &mfvec, int lev, int idim)
+.. doxygenfunction:: WarpX::ApplyFilterMF(const ablastr::fields::MultiLevelVectorField &mfvec, int lev, int idim)
 
-.. doxygenfunction:: WarpX::SumBoundaryJ(const amrex::Vector<std::array<std::unique_ptr<amrex::MultiFab>, 3>> &current, int lev, int idim, const amrex::Periodicity &period)
+.. doxygenfunction:: WarpX::SumBoundaryJ(const ablastr::fields::MultiLevelVectorField &current, int lev, int idim, const amrex::Periodicity &period)
 
 Godfrey's anti-NCI filter for FDTD simulations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Docs/source/developers/gnumake/python.rst

@@ -3,7 +3,7 @@
 Installing WarpX as a Python package
 ====================================
 
-A full Python installation of WarpX can be done, which includes a build of all of the C++ code, or a pure Python version can be made which only installs the Python scripts. WarpX requires Python version 3.8 or newer.
+A full Python installation of WarpX can be done, which includes a build of all of the C++ code, or a pure Python version can be made which only installs the Python scripts. WarpX requires Python version 3.9 or newer.
 
 For a full Python installation of WarpX
 ---------------------------------------

Docs/source/developers/particles.rst

@@ -83,7 +83,7 @@ Main functions
 
 .. doxygenfunction:: PhysicalParticleContainer::PushPX
 
-.. doxygenfunction:: WarpXParticleContainer::DepositCurrent(amrex::Vector<std::array<std::unique_ptr<amrex::MultiFab>, 3>> &J, amrex::Real dt, amrex::Real relative_time)
+.. doxygenfunction:: WarpXParticleContainer::DepositCurrent(ablastr::fields::MultiLevelVectorField const &J, amrex::Real dt, amrex::Real relative_time)
 
 .. note::
    The current deposition is used both by ``PhysicalParticleContainer`` and ``LaserParticleContainer``, so it is in the parent class ``WarpXParticleContainer``.

Docs/source/highlights.rst

@@ -188,6 +188,14 @@ Scientific works in High-Performance Computing, applied mathematics and numerics
 
 Please see :ref:`this section <acknowledge_warpx_all_refs>`.
 
+Related works using WarpX:
+
+#. Yan Y., Du F., Tang J., Yu D and Zhao Y.,
+   **Numerical study on wave attenuation via 1D fully kinetic electromagnetic particle-in-cell simulations**.
+   Plasma Sources Sci. Technol. **33** 115013, 2024
+   `DOI:10.1088/1361-6595/ad8c7c <https://doi.org/10.1088/1361-6595/ad8c7c>`__
+
+
 Nuclear Fusion and Plasma Confinement
 *************************************
 

Docs/source/install/dependencies.rst

@@ -37,7 +37,7 @@ Optional dependencies include:
 - `SENSEI 4.0.0+ <https://sensei-insitu.org>`__: for in situ analysis and visualization
 - `CCache <https://ccache.dev>`__: to speed up rebuilds (For CUDA support, needs version 3.7.9+ and 4.2+ is recommended)
 - `Ninja <https://ninja-build.org>`__: for faster parallel compiles
-- `Python 3.8+ <https://www.python.org>`__
+- `Python 3.9+ <https://www.python.org>`__
 
   - `mpi4py <https://mpi4py.readthedocs.io>`__
   - `numpy <https://numpy.org>`__

Docs/source/install/hpc/dane.rst

@@ -3,17 +3,17 @@
 Dane (LLNL)
 =============
 
-The `Dane Intel CPU cluster <https://hpc.llnl.gov/hardware/compute-platforms/dane>`_ is located at LLNL.
+The `Dane Intel CPU cluster <https://hpc.llnl.gov/hardware/compute-platforms/dane>`__ is located at LLNL.
 
 
 Introduction
 ------------
 
 If you are new to this system, **please see the following resources**:
 
-* `LLNL user account <https://lc.llnl.gov`__ (login required)
+* `LLNL user account <https://lc.llnl.gov>`__ (login required)
 * `Jupyter service <https://lc.llnl.gov/jupyter>`__ (`documentation <https://lc.llnl.gov/confluence/display/LC/JupyterHub+and+Jupyter+Notebook>`__, login required)
-* `Production directories <https://hpc.llnl.gov/hardware/file-systems>`_:
+* `Production directories <https://hpc.llnl.gov/hardware/file-systems>`__:
 
   * ``/p/lustre1/$(whoami)`` and ``/p/lustre2/$(whoami)``: personal directory on the parallel filesystem
   * Note that the ``$HOME`` directory and the ``/usr/workspace/$(whoami)`` space are NFS mounted and *not* suitable for production quality data generation.

Docs/source/install/hpc/lawrencium.rst

@@ -69,7 +69,7 @@ And since Lawrencium does not yet provide a module for them, install ADIOS2, BLA
    cmake -S src/lapackpp -B src/lapackpp-v100-build -DCMAKE_CXX_STANDARD=17 -Dgpu_backend=cuda -Dbuild_tests=OFF -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=ON -DCMAKE_INSTALL_PREFIX=$HOME/sw/v100/lapackpp-master -Duse_cmake_find_lapack=ON -DBLAS_LIBRARIES=${LAPACK_DIR}/lib/libblas.a -DLAPACK_LIBRARIES=${LAPACK_DIR}/lib/liblapack.a
    cmake --build src/lapackpp-v100-build --target install --parallel 12
 
-Optionally, download and install Python packages for :ref:`PICMI <usage-picmi>` or dynamic ensemble optimizations (:ref:`libEnsemble <libensemble>`):
+Optionally, download and install Python packages for :ref:`PICMI <usage-picmi>` or dynamic ensemble optimizations (`libEnsemble <https://libensemble.readthedocs.io/en/main/>`__):
 
 .. code-block:: bash
 

Docs/source/refs.bib

@@ -458,6 +458,7 @@ @misc{Fallahi2020
 @article{VayFELA2009,
   title = {FULL ELECTROMAGNETIC SIMULATION OF FREE-ELECTRON LASER AMPLIFIER PHYSICS VIA THE LORENTZ-BOOSTED FRAME APPROACH},
   author = {Fawley, William M and Vay, Jean-Luc},
+  journal = {},
   abstractNote = {Numerical simulation of some systems containing charged particles with highly relativistic directed motion can by speeded up by orders of magnitude by choice of the proper Lorentz-boosted frame[1]. A particularly good example is that of short wavelength free-electron lasers (FELs) in which a high energy electron beam interacts with a static magnetic undulator. In the optimal boost frame with Lorentz factor gamma_F , the red-shifted FEL radiation and blue shifted undulator have identical wavelengths and the number of required time-steps (presuming the Courant condition applies) decreases by a factor of 2(gamma_F)**2 for fully electromagnetic simulation. We have adapted the WARP code [2]to apply this method to several FEL problems involving coherent spontaneous emission (CSE) from pre-bunched ebeams, including that in a biharmonic undulator.},
   url = {https://www.osti.gov/biblio/964405},
   place = {United States},

Docs/source/theory/multiphysics/collisions.rst

@@ -131,7 +131,7 @@ The process is also the same as for elastic scattering except the excitation ene
 Benchmarks
 ----------
 
-See the :ref:`MCC example <examples-mcc-turner>` for a benchmark of the MCC
+See the :ref:`MCC example <examples-capacitive-discharge>` for a benchmark of the MCC
 implementation against literature results.
 
 Particle cooling due to elastic collisions

Docs/source/usage/examples.rst

@@ -65,14 +65,6 @@ Microelectronics
 * `ARTEMIS manual <https://artemis-em.readthedocs.io>`__
 
 
-Nuclear Fusion
---------------
-
-.. note::
-
-   TODO
-
-
 Fundamental Plasma Physics
 --------------------------
 

Docs/source/usage/examples/thomson_parabola_spectrometer

@@ -0,0 +1 @@
+../../../../Examples/Physics_applications/thomson_parabola_spectrometer

Examples/Physics_applications/thomson_parabola_spectrometer/README.rst

@@ -28,7 +28,7 @@ The PICMI input file is not available for this example yet.
 
 For `MPI-parallel <https://www.mpi-forum.org>`__ runs, prefix these lines with ``mpiexec -n 4 ...`` or ``srun -n 4 ...``, depending on the system.
 
-.. literalinclude:: inputs
+.. literalinclude:: inputs_test_3d_thomson_parabola_spectrometer
    :language: ini
    :caption: You can copy this file from ``Examples/Physics_applications/thomson_parabola_spectrometer/inputs_test_3d_thomson_parabola_spectrometer``.
 

Python/setup.py

@@ -71,6 +71,6 @@
     description="""Wrapper of WarpX""",
     package_data=package_data,
     install_requires=["numpy", "picmistandard==0.33.0", "periodictable"],
-    python_requires=">=3.8",
+    python_requires=">=3.8",  # left for CI, truly ">=3.9"
     zip_safe=False,
 )

Source/BoundaryConditions/PEC_Insulator.cpp

@@ -69,7 +69,7 @@ namespace
         bool GuardCell = false;
         bool isInsulatorBoundary = false;
         amrex::Real sign = +1._rt;
-        bool is_normal_to_boundary;
+        bool is_normal_to_boundary = false;
         amrex::Real field_value = 0._rt;
         bool set_field = false;
         // Loop over all dimensions

Source/FieldSolver/MagnetostaticSolver/MagnetostaticSolver.cpp

@@ -128,22 +128,22 @@ WarpX::AddMagnetostaticFieldLabFrame()
 
     // const amrex::Real magnetostatic_absolute_tolerance = self_fields_absolute_tolerance*PhysConst::c;
     // temporary fix!!!
-    const amrex::Real magnetostatic_absolute_tolerance = 0.0;
-    amrex::Real self_fields_required_precision;
+    const amrex::Real absolute_tolerance = 0.0;
+    amrex::Real required_precision;
     if constexpr (std::is_same<Real, float>::value) {
-        self_fields_required_precision = 1e-5;
+        required_precision = 1e-5;
     }
     else {
-        self_fields_required_precision = 1e-11;
+        required_precision = 1e-11;
     }
-    const int self_fields_max_iters = 200;
-    const int self_fields_verbosity = 2;
+    const int verbosity = 2;
 
     computeVectorPotential(
         m_fields.get_mr_levels_alldirs(FieldType::current_fp, finest_level),
         m_fields.get_mr_levels_alldirs(FieldType::vector_potential_fp_nodal, finest_level),
-        self_fields_required_precision, magnetostatic_absolute_tolerance, self_fields_max_iters,
-        self_fields_verbosity);
+        required_precision, absolute_tolerance, magnetostatic_solver_max_iters,
+        verbosity
+    );
 }
 
 /* Compute the vector potential `A` by solving the Poisson equation with `J` as

Source/Parallelization/WarpXRegrid.cpp

@@ -320,7 +320,7 @@ WarpX::ComputeCostsHeuristic (amrex::Vector<std::unique_ptr<amrex::LayoutData<am
 
     for (int lev = 0; lev <= finest_level; ++lev)
     {
-        const auto & mypc_ref = GetInstance().GetPartContainer();
+        const auto & mypc_ref = GetPartContainer();
         const auto nSpecies = mypc_ref.nSpecies();
 
         // Species loop

Source/Particles/PhysicalParticleContainer.cpp

@@ -1483,17 +1483,14 @@ PhysicalParticleContainer::AddPlasmaFlux (PlasmaInjector const& plasma_injector,
                 if (eb_flag_arr(i,j,k).isRegular() || eb_flag_arr(i,j,k).isCovered()) { return; }
                 // Scale by the (normalized) area of the EB surface in this cell
                 num_ppc_real_in_this_cell *= eb_bnd_area_arr(i,j,k);
-            } else
+            }
 #else
             amrex::Real const num_ppc_real_in_this_cell = num_ppc_real; // user input: number of macroparticles per cell
 #endif
-            {
-                // Injection from a plane
-                auto lo = getCellCoords(overlap_corner, dx, {0._rt, 0._rt, 0._rt}, iv);
-                auto hi = getCellCoords(overlap_corner, dx, {1._rt, 1._rt, 1._rt}, iv);
-                // Skip cells that do not overlap with the plane
-                if (!flux_pos->overlapsWith(lo, hi)) { return; }
-            }
+            // Skip cells that do not overlap with the bounds specified by the user (xmin/xmax, ymin/ymax, zmin/zmax)
+            auto lo = getCellCoords(overlap_corner, dx, {0._rt, 0._rt, 0._rt}, iv);
+            auto hi = getCellCoords(overlap_corner, dx, {1._rt, 1._rt, 1._rt}, iv);
+            if (!flux_pos->overlapsWith(lo, hi)) { return; }
 
             auto index = overlap_box.index(iv);
             // Take into account refined injection region

Source/WarpX.H

@@ -902,6 +902,7 @@ public:
 
     // Magnetostatic Solver Interface
     MagnetostaticSolver::VectorPoissonBoundaryHandler m_vector_poisson_boundary_handler;
+    int magnetostatic_solver_max_iters = 200;
     void ComputeMagnetostaticField ();
     void AddMagnetostaticFieldLabFrame ();
     void computeVectorPotential (ablastr::fields::MultiLevelVectorField const& curr,

Source/WarpX.cpp

@@ -684,6 +684,7 @@ WarpX::ReadParameters ()
         poisson_solver_id!=PoissonSolverAlgo::IntegratedGreenFunction,
         "To use the FFT Poisson solver, compile with WARPX_USE_FFT=ON.");
 #endif
+        utils::parser::queryWithParser(pp_warpx, "self_fields_max_iters", magnetostatic_solver_max_iters);
 
         WARPX_ALWAYS_ASSERT_WITH_MESSAGE(
         (

Tools/machines/perlmutter-nersc/perlmutter_cpu_warpx.profile.example

@@ -7,7 +7,7 @@ if [ -z ${proj-} ]; then echo "WARNING: The 'proj' variable is not yet set in yo
 
 # required dependencies
 module load cpu
-module load cmake/3.24.3
+module load cmake/3.30.2
 module load cray-fftw/3.3.10.6
 
 # optional: for QED support with detailed tables

Tools/machines/perlmutter-nersc/perlmutter_gpu_warpx.profile.example

@@ -12,7 +12,7 @@ module load craype
 module load craype-x86-milan
 module load craype-accel-nvidia80
 module load cudatoolkit
-module load cmake/3.24.3
+module load cmake/3.30.2
 
 # optional: for QED support with detailed tables
 export BOOST_ROOT=/global/common/software/spackecp/perlmutter/e4s-23.08/default/spack/opt/spack/linux-sles15-zen3/gcc-12.3.0/boost-1.83.0-nxqk3hnci5g3wqv75wvsmuke3w74mzxi

cmake/dependencies/pybind11.cmake

@@ -37,7 +37,7 @@ function(find_pybind11)
             mark_as_advanced(FETCHCONTENT_UPDATES_DISCONNECTED_FETCHEDpybind11)
         endif()
     else()
-        find_package(pybind11 2.12.0 CONFIG REQUIRED)
+        find_package(pybind11 2.13.0 CONFIG REQUIRED)
         message(STATUS "pybind11: Found version '${pybind11_VERSION}'")
     endif()
 endfunction()
@@ -52,7 +52,7 @@ option(WarpX_pybind11_internal "Download & build pybind11" ON)
 set(WarpX_pybind11_repo "https://github.com/pybind/pybind11.git"
     CACHE STRING
     "Repository URI to pull and build pybind11 from if(WarpX_pybind11_internal)")
-set(WarpX_pybind11_branch "v2.12.0"
+set(WarpX_pybind11_branch "v2.13.6"
     CACHE STRING
     "Repository branch for WarpX_pybind11_repo if(WarpX_pybind11_internal)")
 

setup.py

@@ -307,7 +307,7 @@ def build_extension(self, ext):
     cmdclass=cmdclass,
     # scripts=['warpx_1d', 'warpx_2d', 'warpx_rz', 'warpx_3d'],
     zip_safe=False,
-    python_requires=">=3.8",
+    python_requires=">=3.8",  # left for CI, truly ">=3.9"
     # tests_require=['pytest'],
     install_requires=install_requires,
     # see: src/bindings/python/cli
@@ -336,10 +336,11 @@ def build_extension(self, ext):
         "Topic :: Scientific/Engineering :: Physics",
         "Programming Language :: C++",
         "Programming Language :: Python :: 3",
-        "Programming Language :: Python :: 3.8",
         "Programming Language :: Python :: 3.9",
         "Programming Language :: Python :: 3.10",
         "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
         (
             "License :: OSI Approved :: " "BSD License"
         ),  # TODO: use real SPDX: BSD-3-Clause-LBNL