merging

.clang-tidy

@@ -41,7 +41,6 @@ Checks: '
         -readability-implicit-bool-conversion,
         -readability-isolate-declaration,
         -readability-magic-numbers,
-        -readability-make-member-function-const,
         -readability-named-parameter,
         -readability-uppercase-literal-suffix
     '

.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 75571e2dcbf2417529c5ed8e24113580e8e1f3f1 && cd -
+        cd ../amrex && git checkout --detach f1ec8df75c562d2a4822cea84d284cf8e72c2e14 && 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

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/source/conf.py

@@ -103,9 +103,9 @@ def __init__(self, *args, **kwargs):
 # 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.

Docs/source/refs.bib

@@ -277,6 +277,21 @@ @Inbook{VanLeerBookChapter1997
 year = {1997}
 }
 
+@article{Yakimenko2019,
+  title = {Prospect of Studying Nonperturbative QED with Beam-Beam Collisions},
+  author = {Yakimenko, V. and Meuren, S. and Del Gaudio, F. and Baumann, C. and Fedotov, A. and Fiuza, F. and Grismayer, T. and Hogan, M. J. and Pukhov, A. and Silva, L. O. and White, G.},
+  journal = {Phys. Rev. Lett.},
+  volume = {122},
+  issue = {19},
+  pages = {190404},
+  numpages = {7},
+  year = {2019},
+  month = {May},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevLett.122.190404},
+  url = {https://link.aps.org/doi/10.1103/PhysRevLett.122.190404}
+}
+
 @article{Groenewald2023,
 author = {Groenewald, R. E. and Veksler, A. and Ceccherini, F. and Necas, A. and Nicks, B. S. and Barnes, D. C. and Tajima, T. and Dettrick, S. A.},
 title = "{Accelerated kinetic model for global macro stability studies of high-beta fusion reactors}",

Docs/source/usage/examples.rst

@@ -25,14 +25,6 @@ Plasma-Based Acceleration
    examples/pwfa/README.rst
    pwfa.rst
 
-Coming soon:
-
-* LWFA: External injection in the boosted frame
-* LWFA: Ionization injection in the lab frame using a LASY data file
-* PWFA: External injection in the boosted frame
-* PWFA: Self-injection in the lab frame
-* MR case?
-
 
 Laser-Plasma Interaction
 ------------------------
@@ -43,11 +35,6 @@ Laser-Plasma Interaction
    examples/laser_ion/README.rst
    examples/plasma_mirror/README.rst
 
-Coming soon:
-
-* MVA (3D & RZ)
-* MR for the planar example?
-
 
 Particle Accelerator & Beam Physics
 -----------------------------------
@@ -56,12 +43,7 @@ Particle Accelerator & Beam Physics
    :maxdepth: 1
 
    examples/gaussian_beam/README.rst
-
-Coming soon:
-
-* Beam-Beam Collision
-* Beam Transport or Injector
-* Cathode/source
+   examples/beam-beam_collision/README.rst
 
 
 High Energy Astrophysical Plasma Physics
@@ -89,11 +71,6 @@ Nuclear Fusion
 
    TODO
 
-Coming soon:
-
-* Microchannel
-* Magnetically Confined Plasma with a Single Coil - Magnetic bottle: simple geometry with an external field
-
 
 Fundamental Plasma Physics
 --------------------------
@@ -104,9 +81,6 @@ Fundamental Plasma Physics
    examples/langmuir/README.rst
    examples/capacitive_discharge/README.rst
 
-Coming soon:
-
-* Expanding Sphere example
 
 .. _examples-hybrid-model:
 
@@ -149,7 +123,7 @@ Manipulating fields via Python
 
 .. note::
 
-   TODO: The section needs to be sorted into either science cases (above) or later sections (workflows and Python API details).
+   TODO: The section needs to be sorted into either science cases (above) or later sections (:ref:`workflows and Python API details <usage-python-extend>`).
 
 An example of using Python to access the simulation charge density, solve the Poisson equation (using ``superLU``) and write the resulting electrostatic potential back to the simulation is given in the input file below. This example uses the ``fields.py`` module included in the ``pywarpx`` library.
 

Docs/source/usage/examples/beam-beam_collision

@@ -0,0 +1 @@
+../../../../Examples/Physics_applications/beam-beam_collision

Docs/source/usage/parameters.rst

@@ -1167,6 +1167,11 @@ Particle initialization
 * ``<species>.do_field_ionization`` (`0` or `1`) optional (default `0`)
     Do field ionization for this species (using the ADK theory).
 
+* ``<species>.do_adk_correction`` (`0` or `1`) optional (default `0`)
+    Whether to apply the correction to the ADK theory proposed by Zhang, Lan and Lu in `Q. Zhang et al. (Phys. Rev. A 90, 043410, 2014) <https://doi.org/10.1103/PhysRevA.90.043410>`__.
+    If so, the probability of ionization is modified using an empirical model that should be more accurate in the regime of high electric fields.
+    Currently, this is only implemented for Hydrogen, although Argon is also available in the same reference.
+
 * ``<species>.physical_element`` (`string`)
     Only read if `do_field_ionization = 1`. Symbol of chemical element for
     this species. Example: for Helium, use ``physical_element = He``.
@@ -1508,9 +1513,15 @@ Laser initialization
 External fields
 ---------------
 
-Grid initialization
+Applied to the grid
 ^^^^^^^^^^^^^^^^^^^
 
+The external fields defined with input parameters that start with ``warpx.B_ext_grid_init_`` or ``warpx.E_ext_grid_init_``
+are applied to the grid directly. In particular, these fields can be seen in the diagnostics that output the fields on the grid.
+
+    - When using an **electromagnetic** field solver, these fields are applied to the grid at the beginning of the simulation, and serve as initial condition for the Maxwell solver.
+    - When using an **electrostatic** or **magnetostatic** field solver, these fields are added to the fields computed by the Poisson solver, at each timestep.
+
 * ``warpx.B_ext_grid_init_style`` (string) optional
     This parameter determines the type of initialization for the external
     magnetic field. By default, the
@@ -1597,6 +1608,9 @@ Grid initialization
 Applied to Particles
 ^^^^^^^^^^^^^^^^^^^^
 
+The external fields defined with input parameters that start with ``warpx.B_ext_particle_init_`` or ``warpx.E_ext_particle_init_``
+are applied to the particles directly, at each timestep. As a results, these fields **cannot** be seen in the diagnostics that output the fields on the grid.
+
 * ``particles.E_ext_particle_init_style`` & ``particles.B_ext_particle_init_style`` (string) optional (default "none")
     These parameters determine the type of the external electric and
     magnetic fields respectively that are applied directly to the particles at every timestep.
@@ -1657,6 +1671,9 @@ Applied to Particles
 Applied to Cold Relativistic Fluids
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+The external fields defined with input parameters that start with ``warpx.B_ext_init_`` or ``warpx.E_ext_init_``
+are applied to the fluids directly, at each timestep. As a results, these fields **cannot** be seen in the diagnostics that output the fields on the grid.
+
 * ``<fluid_species_name>.E_ext_init_style`` & ``<fluid_species_name>.B_ext_init_style`` (string) optional (default "none")
     These parameters determine the type of the external electric and
     magnetic fields respectively that are applied directly to the cold relativistic fluids at every timestep.
@@ -2585,8 +2602,8 @@ In-situ capabilities can be used by turning on Sensei or Ascent (provided they a
     Only works with ``<diag_name>.format = plotfile``.
 
 * ``<diag_name>.coarsening_ratio`` (list of `int`) optional (default `1 1 1`)
-    Reduce size of the field output by this ratio in each dimension.
-    (This is done by averaging the field over 1 or 2 points along each direction, depending on the staggering).
+    Reduce size of the selected diagnostic fields output by this ratio in each dimension.
+    (For a ratio of N, this is done by averaging the fields over N or (N+1) points depending on the staggering).
     If ``blocking_factor`` and ``max_grid_size`` are used for the domain decomposition, as detailed in
     the :ref:`domain decomposition <usage_domain_decomposition>` section, ``coarsening_ratio`` should be an integer
     divisor of ``blocking_factor``. If ``warpx.numprocs`` is used instead, the total number of cells in a given
@@ -2737,6 +2754,8 @@ This can be important if a large number of particles are lost, avoiding filling
 In addition to their usual attributes, the saved particles have an integer attribute ``timestamp``, which
 indicates the PIC iteration at which each particle was absorbed at the boundary.
 
+``BoundaryScrapingDiagnostics`` can be used with ``<diag_name>.<species>.random_fraction``, ``<diag_name>.<species>.uniform_stride``, and ``<diag_name>.<species>.plot_filter_function``, which have the same behavior as for ``FullDiagnostics``. For ``BoundaryScrapingDiagnostics``, these filters are applied at the time the data is written to file. An implication of this is that more particles may initially be accumulated in memory than are ultimately written. ``t`` in ``plot_filter_function`` refers to the time the diagnostic is written rather than the time the particle crossed the boundary.
+
 .. _running-cpp-parameters-diagnostics-reduced:
 
 Reduced Diagnostics
@@ -2868,8 +2887,9 @@ Reduced Diagnostics
         defaulting to ``1``.
         In RZ geometry, this only saves the
         0'th azimuthal mode component of the fields.
-        Integrated electric and magnetic field components can instead be obtained by specifying
+        Time integrated electric and magnetic field components can instead be obtained by specifying
         ``<reduced_diags_name>.integrate = true``.
+        The integration is done every time step even when the data is written out less often.
         In a *moving window* simulation, the FieldProbe can be set to follow the moving frame by specifying ``<reduced_diags_name>.do_moving_window_FP = 1`` (default 0).
 
         .. warning::

Examples/Physics_applications/beam-beam_collision/README.rst

@@ -0,0 +1,70 @@
+.. _examples-beam-beam_collision:
+
+Beam-beam collision
+====================
+
+This example shows how to simulate the collision between two ultra-relativistic particle beams.
+This is representative of what happens at the interaction point of a linear collider.
+We consider a right-propagating electron bunch colliding against a left-propagating positron bunch.
+
+We turn on the Quantum Synchrotron QED module for photon emission (also known as beamstrahlung in the collider community) and
+the Breit-Wheeler QED module for the generation of electron-positron pairs (also known as coherent pair generation in the collider community).
+
+To solve for the electromagnetic field we use the nodal version of the electrostatic relativistic solver.
+This solver computes the average velocity of each species, and solves the corresponding relativistic Poisson equation (see the WarpX documentation for `warpx.do_electrostatic = relativistic` for more detail). This solver accurately reproduced the subtle cancellation that occur for some component of the ``E + v x B`` terms which are crucial in simulations of relativistic particles.
+
+
+This example is based on the following paper :cite:t:`ex-Yakimenko2019`.
+
+
+Run
+---
+
+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
+   :language: ini
+   :caption: You can copy this file from ``Examples/Physics_applications/beam-beam_collision/inputs``.
+
+
+Visualize
+---------
+
+The figure below shows the number of photons emitted per beam particle (left) and the number of secondary pairs generated per beam particle (right).
+
+We compare different results:
+* (red) simplified WarpX simulation as the example stored in the directory ``/Examples/Physics_applications/beam-beam_collision``;
+* (blue) large-scale WarpX simulation (high resolution and ad hoc generated tables ;
+* (black) literature results from :cite:t:`ex-Yakimenko2019`.
+
+The small-scale simulation has been performed with a resolution of ``nx = 64, ny = 64, nz = 128`` grid cells, while the large-scale one has a much higher resolution of ``nx = 512, ny = 512, nz = 1024``. Moreover, the large-scale simulation uses dedicated QED lookup tables instead of the builtin tables. To generate the tables within WarpX, the code must be compiled with the flag ``-DWarpX_QED_TABLE_GEN=ON``. For the large-scale simulation we have used the following options:
+
+.. code-block:: ini
+
+   qed_qs.lookup_table_mode = generate
+   qed_bw.lookup_table_mode = generate
+   qed_qs.tab_dndt_chi_min=1e-3
+   qed_qs.tab_dndt_chi_max=2e3
+   qed_qs.tab_dndt_how_many=512
+   qed_qs.tab_em_chi_min=1e-3
+   qed_qs.tab_em_chi_max=2e3
+   qed_qs.tab_em_chi_how_many=512
+   qed_qs.tab_em_frac_how_many=512
+   qed_qs.tab_em_frac_min=1e-12
+   qed_qs.save_table_in=my_qs_table.txt
+   qed_bw.tab_dndt_chi_min=1e-2
+   qed_bw.tab_dndt_chi_max=2e3
+   qed_bw.tab_dndt_how_many=512
+   qed_bw.tab_pair_chi_min=1e-2
+   qed_bw.tab_pair_chi_max=2e3
+   qed_bw.tab_pair_chi_how_many=512
+   qed_bw.tab_pair_frac_how_many=512
+   qed_bw.save_table_in=my_bw_table.txt
+
+.. figure:: https://user-images.githubusercontent.com/17280419/291749626-aa61fff2-e6d2-45a3-80ee-84b2851ea0bf.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTEiLCJleHAiOjE3MDMwMzQzNTEsIm5iZiI6MTcwMzAzNDA1MSwicGF0aCI6Ii8xNzI4MDQxOS8yOTE3NDk2MjYtYWE2MWZmZjItZTZkMi00NWEzLTgwZWUtODRiMjg1MWVhMGJmLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFJV05KWUFYNENTVkVINTNBJTJGMjAyMzEyMjAlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjMxMjIwVDAxMDA1MVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWFiYzY2MGQyYzIyZGIzYzUxOWI3MzNjZTk5ZDM1YzgyNmY4ZDYxOGRlZjAyZTIwNTAyMTc3NTgwN2Q0YjEwNGMmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.I96LQpjqmFXirPDVnBlFQIkCuenR6IuOSY0OIIQvtCo
+   :alt: Beam-beam collision benchmark against :cite:t:`ex-Yakimenko2019`.
+   :width: 100%
+
+   Beam-beam collision benchmark against :cite:t:`ex-Yakimenko2019`.