Merge branch 'development' into hackathon-field-register

.github/workflows/cleanup-cache.yml

@@ -2,7 +2,7 @@ name: CleanUpCache
 
 on:
   workflow_run:
-    workflows: [🧹 clang-tidy, 🔍 CodeQL, 🐧 CUDA, 🐧 HIP, 🐧 Intel, 🍏 macOS, 🐧 OpenMP]
+    workflows: [🧴 clang sanitizers, 🧹 clang-tidy, 🔍 CodeQL, 🐧 CUDA, 🐧 HIP, 🐧 Intel, 🍏 macOS, 🐧 OpenMP]
     types:
       - completed
 

.github/workflows/cuda.yml

@@ -131,7 +131,7 @@ jobs:
         which nvcc || echo "nvcc not in PATH!"
 
         git clone https://github.com/AMReX-Codes/amrex.git ../amrex
-        cd ../amrex && git checkout --detach 216ce6f37de4b65be57fc1006b3457b4fc318e03 && cd -
+        cd ../amrex && git checkout --detach 028638564f7be0694b9898f8d4088cdbf9a6f9f5 && cd -
         make COMP=gcc QED=FALSE USE_MPI=TRUE USE_GPU=TRUE USE_OMP=FALSE USE_FFT=TRUE USE_CCACHE=TRUE -j 4
 
         ccache -s

.github/workflows/insitu.yml

@@ -101,8 +101,8 @@ jobs:
         cmake --build build -j 10
     - name: 2D Test
       run: |
-        cp Examples/Tests/ionization/inputs_test_2d_ionization_lab .
-        cp Examples/Tests/ionization/catalyst_pipeline.py .
+        cp Examples/Tests/field_ionization/inputs_test_2d_ionization_lab .
+        cp Examples/Tests/field_ionization/catalyst_pipeline.py .
         mpiexec -n 2 ./build/bin/warpx.2d \
             inputs_test_2d_ionization_lab \
             catalyst.script_paths = catalyst_pipeline.py\

Docs/source/developers/developers.rst

@@ -15,7 +15,6 @@ Implementation Details
    initialization
    diagnostics
    moving_window
-   qed
    portability
    warning_logger
    python

Docs/source/developers/testing.rst

@@ -81,6 +81,24 @@ For easier debugging, it can be convenient to run the tests on your local machin
 
        ctest --test-dir build -E laser_acceleration
 
+* Sometimes two or more tests share a large number of input parameters and differ by a small set of options.
+  Such tests typically also share a base string in their names.
+  For example, you can find three different tests named ``test_3d_langmuir_multi``, ``test_3d_langmuir_multi_nodal`` and ``test_3d_langmuir_multi_picmi``.
+  In such a case, if you wish to run the test ``test_3d_langmuir_multi`` only, this can be done again with the ``-R`` regular `expression filter <https://regex101.com>`__ via
+
+  .. code-block:: sh
+
+       ctest --test-dir build -R "test_3d_langmuir_multi\..*"
+
+  Note that filtering with ``-R "test_3d_langmuir_multi"`` would include the additional tests that have the same substring in their name and would not be sufficient to isolate a single test.
+  Note also that the escaping ``\.`` in the regular expression is necessary in order to take into account the fact that each test is automatically appended with the strings ``.run``, ``.analysis`` and possibly ``.cleanup``.
+
+* Run only tests not labeled with the ``slow`` label:
+
+  .. code-block:: sh
+
+       ctest --test-dir build -LE slow
+
 Once the execution of CTest is completed, you can find all files associated with each test in its corresponding directory under ``build/bin/``.
 For example, if you run the single test ``test_3d_laser_acceleration``, you can find all files associated with this test in the directory ``build/bin/test_3d_laser_acceleration/``.
 
@@ -155,7 +173,7 @@ A new test can be added by adding a corresponding entry in ``CMakeLists.txt`` as
 
 If you need a new Python package dependency for testing, please add it in `Regression/requirements.txt <https://github.com/ECP-WarpX/WarpX/blob/development/Regression/requirements.txt>`__.
 
-Sometimes, two tests share a large number of input parameters. The shared input parameters can be collected in a "base" input file that can be passed as a runtime parameter in the actual test input files through the parameter ``FILE``.
+Sometimes two or more tests share a large number of input parameters. The shared input parameters can be collected in a "base" input file that can be passed as a runtime parameter in the actual test input files through the parameter ``FILE``.
 
 Naming conventions for automated tests
 --------------------------------------

Docs/source/index.rst

@@ -111,8 +111,7 @@ Theory
    theory/amr
    theory/boundary_conditions
    theory/boosted_frame
-   theory/input_output
-   theory/collisions
+   theory/multiphysics_extensions
    theory/kinetic_fluid_hybrid_model
    theory/cold_fluid_model
 

Docs/source/latex_theory/allbibs.bib

@@ -2187,3 +2187,45 @@ @book{godfrey1985iprop
 title = {{The IPROP Three-Dimensional Beam Propagation Code}},
 year = {1985}
 }
+
+@article{Ammosov1986,
+title = {Tunnel ionization of complex atoms and of atomic ions in an alternating electromagnetic field},
+volume = {64},
+issn = {0044-4510},
+doi = {10.1117/12.938695},
+number = {December 1986},
+journal = {Sov. Phys. JETP},
+author = {Ammosov, M. V. and Delone, N. B. and Krainov, V. P.},
+year = {1986},
+pmid = {22232002},
+note = {ISBN: 0892526998},
+pages = {1191--1194},
+}
+
+
+@article{zhang_empirical_2014,
+title = {Empirical formula for over-barrier strong-field ionization},
+volume = {90},
+issn = {1050-2947, 1094-1622},
+doi = {10.1103/PhysRevA.90.043410},
+language = {en},
+number = {4},
+journal = {Physical Review A},
+author = {Zhang, Qingbin and Lan, Pengfei and Lu, Peixiang},
+month = oct,
+year = {2014},
+pages = {043410},
+}
+
+
+@book{Mulser2010,
+title = {High {Power} {Laser}-{Matter} {Interaction}},
+volume = {238},
+isbn = {978-3-540-50669-0},
+publisher = {Springer Berlin Heidelberg},
+author = {Mulser, Peter and Bauer, Dieter},
+year = {2010},
+pmid = {25246403},
+doi = {10.1007/978-3-540-46065-7},
+note = {Series Title: Springer Tracts in Modern Physics},
+}

Docs/source/theory/boosted_frame.rst

@@ -12,7 +12,21 @@ The simulations of plasma accelerators from first principles are extremely compu
 
    A first principle simulation of a short driver beam (laser or charged particles) propagating through a plasma that is orders of magnitude longer necessitates a very large number of time steps. Recasting the simulation in a frame of reference that is moving close to the speed of light in the direction of the driver beam leads to simulating a driver beam that appears longer propagating through a plasma that appears shorter than in the laboratory. Thus, this relativistic transformation of space and time reduces the disparity of scales, and thereby the number of time steps to complete the simulation, by orders of magnitude.
 
-Even using a moving window, however, a full PIC simulation of a plasma accelerator can be extraordinarily demanding computationally, as many time steps are needed to resolve the crossing of the short driver beam with the plasma column. As it turns out, choosing an optimal frame of reference that travels close to the speed of light in the direction of the laser or particle beam (as opposed to the usual choice of the laboratory frame) enables speedups by orders of magnitude :cite:p:`bf-Vayprl07,bf-Vaypop2011`. This is a result of the properties of Lorentz contraction and dilation of space and time. In the frame of the laboratory, a very short driver (laser or particle) beam propagates through a much longer plasma column, necessitating millions to tens of millions of time steps for parameters in the range of the BELLA or FACET-II experiments. As sketched in :numref:`fig_Boosted_frame`, in a frame moving with the driver beam in the plasma at velocity :math:`v=\beta c` (where :math:`c` is the speed of light in vacuum), the beam length is now elongated by :math:`\approx(1+\beta)\gamma` while the plasma contracts by :math:`\gamma` (where :math:`\gamma=1/\sqrt{1-\beta^2}` is the relativistic factor associated with the frame velocity). The number of time steps that is needed to simulate a “longer” beam through a “shorter” plasma is now reduced by up to :math:`\approx(1+\beta) \gamma^2` (a detailed derivation of the speedup is given below).
+Even using a moving window, however, a full PIC simulation of a plasma accelerator can be extraordinarily demanding computationally, as many time steps are needed to resolve the crossing of the short driver beam with the plasma column.
+As it turns out, choosing an optimal frame of reference that travels close to the speed of light in the direction of the laser or particle beam (as opposed to the usual choice of the laboratory frame) enables speedups by orders of magnitude :cite:p:`bf-Vayprl07,bf-Vaypop2011`.
+This is a result of the properties of Lorentz contraction and dilation of space and time.
+In the frame of the laboratory, a very short driver (laser or particle) beam propagates through a much longer plasma column, necessitating millions to tens of millions of time steps for parameters in the range of the BELLA or FACET-II experiments.
+As sketched in :numref:`fig_Boosted_frame`, in a frame moving with the driver beam in the plasma at velocity :math:`v=\beta c` (where :math:`c` is the speed of light in vacuum), the beam length is now elongated by :math:`\approx(1+\beta)\gamma` while the plasma contracts by :math:`\gamma` (where :math:`\gamma=1/\sqrt{1-\beta^2}` is the relativistic factor associated with the frame velocity)
+The number of time steps that is needed to simulate a “longer” beam through a “shorter” plasma is now reduced by up to :math:`\approx(1+\beta) \gamma^2` (a detailed derivation of the speedup is given below).
+
+.. note::
+
+    For additional reading on inputs and outputs in boosted frame simulations, consider the following pages:
+
+    .. toctree::
+        :maxdepth: 1
+
+        boosted_frame/input_output
 
 The modeling of a plasma acceleration stage in a boosted frame
 involves the fully electromagnetic modeling of a plasma propagating at near the speed of light, for which Numerical Cerenkov

Docs/source/theory/input_output.rst → Docs/source/theory/boosted_frame/input_output.rst

@@ -1,4 +1,4 @@
-.. _theory-io:
+.. _boosted_frame-io:
 
 Inputs and Outputs
 ==================

Docs/source/theory/collisions.rst → Docs/source/theory/multiphysics/collisions.rst

@@ -1,4 +1,4 @@
-.. _theory-collisions:
+.. _multiphysics-collisions:
 
 Collisions
 ==========
@@ -8,7 +8,7 @@ including collisions between kinetic particles (Coulomb collisions, DSMC,
 nuclear fusion) as well as collisions between kinetic particles and a fixed
 (i.e. non-evolving) background species (MCC, background stopping).
 
-.. _theory-collisions-mcc:
+.. _multiphysics-collisions-mcc:
 
 Background Monte Carlo Collisions (MCC)
 ---------------------------------------
@@ -52,7 +52,7 @@ for all scattering processes are evaluated at the energy as calculated above.
 
 Once a particle is selected for a specific collision process, that process determines how the particle is scattered as outlined below.
 
-.. _theory-collisions-dsmc:
+.. _multiphysics-collisions-dsmc:
 
 Direct Simulation Monte Carlo (DSMC)
 ------------------------------------

Docs/source/theory/multiphysics/ionization.rst

@@ -0,0 +1,73 @@
+.. _multiphysics-ionization:
+
+Ionization
+==========
+
+Field Ionization
+----------------
+
+Under the influence of a sufficiently strong external electric field atoms become ionized.
+Particularly the dynamics of interactions between ultra-high intensity laser pulses and matter, e.g., Laser-Plasma Acceleration (LPA) with ionization injection, or Laser-Plasma Interactions with solid density targets (LPI) can depend on field ionization dynamics as well.
+
+WarpX models field ionization based on a description of the Ammosov-Delone-Krainov model:cite:p:`mpion-Ammosov1986` following :cite:t:`mpion-ChenPRSTAB13`.
+
+Implementation Details and Assumptions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+    The current implementation makes the following assumptions
+
+    * Energy for ionization processes is not removed from the electromagnetic fields
+    * Only one single-level ionization process can occur per macroparticle and time step
+    * Ionization happens at the beginning of the PIC loop before the field solve
+    * Angular momentum quantum number :math:`l = 0` and magnetic quantum number :math:`m = 0`
+
+The model implements the following equations (assumptions to :math:`l` and :math:`m` have already been applied).
+
+The electric field amplitude is calculated in the particle's frame of reference.
+
+.. math::
+
+    \begin{aligned}
+        \vec{E}_\mathrm{dc} &= \sqrt{ - \frac{1}{\mathrm{c}^2} \left( \vec{u} \cdot \vec{E} \right)^2
+                          + \left( \gamma \vec{E} + \vec{u} \times \vec{B} \right)^2 }
+        \\
+        \gamma &= \sqrt{1 + \frac{\vec{u}^2}{\mathrm{c}^2}}
+    \end{aligned}
+
+Here, :math:`\vec{u} = (u_x, u_y, u_z)` is the momentum normalized to the particle mass, :math:`u_i = (\beta \gamma)_i \mathrm{c}`.
+:math:`E_\mathrm{dc} = |\vec{E}_\mathrm{dc}|` is the DC-field in the frame of the particle.
+
+.. math::
+
+    \begin{aligned}
+        P &= 1 - \mathrm{e}^{-W\mathrm{d}\tau/\gamma}
+        \\
+        W &= \omega_\mathrm{a} \mathcal{C}^2_{n^* l^*} \frac{U_\mathrm{ion}}{2 U_H}
+                \left[ 2 \frac{E_\mathrm{a}}{E_\mathrm{dc}} \left( \frac{U_\mathrm{ion}}{U_\mathrm{H}} \right)^{3/2} \right]^{2n^*-1}
+                \times \exp\left[ - \frac{2}{3} \frac{E_\mathrm{a}}{E_\mathrm{dc}} \left( \frac{U_\mathrm{ion}}{U_\mathrm{H}} \right)^{3/2} \right]
+        \\
+        \mathcal{C}^2_{n^* l^*} &= \frac{2^{2n^*}}{n^* \Gamma(n^* + l^* + 1) \Gamma(n^* - l^*)}
+    \end{aligned}
+
+where :math:`\mathrm{d}\tau` is the simulation timestep, which is divided by the particle :math:`\gamma` to account for time dilation. The quantities are: :math:`\omega_\mathrm{a}`, the atomic unit frequency, :math:`U_\mathrm{ion}`, the ionization potential, :math:`U_\mathrm{H}`, Hydrogen ground state ionization potential, :math:`E_\mathrm{a}`, the atomic unit electric field, :math:`n^* = Z \sqrt{U_\mathrm{H}/U_\mathrm{ion}}`, the effective principal quantum number (*Attention!* :math:`Z` is the ionization state *after ionization*.) , :math:`l^* = n_0^* - 1`, the effective orbital quantum number.
+
+Empirical Extension to Over-the-Barrier Regime for Hydrogen
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For hydrogen, WarpX offers the modified empirical ADK extension to the Over-the-Barrier (OTB) published in :cite:t:`mpion-zhang_empirical_2014` Eq. (8).
+
+.. math::
+
+    W_\mathrm{M} = \exp\left[ -\left( a_1 \frac{E^2}{E_\mathrm{b}} + a_2 \frac{E}{E_\mathrm{b}} + a_3  \right) \right] W_\mathrm{ADK}
+
+The parameters :math:`a_1` through :math:`a_3` are independent of :math:`E` and can be found in the same reference. :math:`E_\mathrm{b}` is the classical Barrier Suppresion Ionization (BSI) field strength :math:`E_\mathrm{b} = U_\mathrm{ion}^2 / (4 Z)` given here in atomic units (AU). For a detailed description of conversion between unit systems consider the book by :cite:t:`mpion-Mulser2010`.
+
+Testing
+^^^^^^^
+
+* `Testing the field ionization module <../../../../Examples/Tests/field_ionization/README.rst>`_.
+
+.. bibliography::
+    :keyprefix: mpion-

Docs/source/developers/qed.rst → Docs/source/theory/multiphysics/qed.rst

@@ -1,7 +1,7 @@
-.. _developers-qed:
+.. _multiphysics-qed:
 
-QED
-====================
+Quantum Electrodynamics (QED)
+=============================
 
 Quantum synchrotron
 -------------------
@@ -28,7 +28,8 @@ electron-positron pairs can be created in vacuum in the function
 
 ``MultiParticleContainer::doQEDSchwinger`` in turn calls the function ``filterCreateTransformFromFAB``:
 
-.. doxygenfunction:: filterCreateTransformFromFAB(DstTile&, DstTile&, const amrex::Box, const FABs&, const Index, const Index, FilterFunc&&, CreateFunc1&&, CreateFunc2&&, TransFunc&&)
+Filter Create Transform Function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``filterCreateTransformFromFAB`` proceeds in three steps.
 In the filter phase, we loop on every cell and calculate the number of physical pairs created within

Docs/source/theory/multiphysics_extensions.rst

@@ -0,0 +1,13 @@
+.. _theory-multiphysics:
+
+Multi-Physics Extensions
+========================
+
+WarpX includes various extensions to the traditional PIC loop which enable it to model additional physics.
+
+.. toctree::
+    :maxdepth: 1
+
+    multiphysics/collisions
+    multiphysics/ionization
+    multiphysics/qed

Docs/source/usage/examples.rst

@@ -137,6 +137,11 @@ An example of initializing the fields by accessing their data through Python, ad
 Many Further Examples, Demos and Tests
 --------------------------------------
 
+.. toctree::
+   :maxdepth: 1
+
+   examples/field_ionization/README.rst
+
 WarpX runs over 200 integration tests on a variety of modeling cases, which validate and demonstrate its functionality.
 Please see the `Examples/Tests/ <https://github.com/ECP-WarpX/WarpX/tree/development/Examples/Tests>`__ directory for many more examples.
 

Docs/source/usage/examples/field_ionization

@@ -0,0 +1 @@
+../../../../Examples/Tests/field_ionization/

Docs/source/usage/parameters.rst

@@ -821,7 +821,7 @@ Particle initialization
 * ``particles.rigid_injected_species`` (`strings`, separated by spaces)
     List of species injected using the rigid injection method. The rigid injection
     method is useful when injecting a relativistic particle beam in boosted-frame
-    simulations; see the :ref:`input-output section <theory-io>` for more details.
+    simulations; see the :ref:`input-output section <boosted_frame-io>` for more details.
     For species injected using this method, particles are translated along the `+z`
     axis with constant velocity as long as their ``z`` coordinate verifies
     ``z<zinject_plane``. When ``z>zinject_plane``,
@@ -1953,7 +1953,7 @@ Collision models
 ----------------
 
 WarpX provides several particle collision models, using varying degrees of approximation.
-Details about the collision models can be found in the :ref:`theory section <theory-collisions>`.
+Details about the collision models can be found in the :ref:`theory section <multiphysics-collisions>`.
 
 * ``collisions.collision_names`` (`strings`, separated by spaces)
     The name of each collision type.
@@ -1976,10 +1976,10 @@ Details about the collision models can be found in the :ref:`theory section <the
       (e.g. ``<species_name>.species_type = 'deuterium'``)
     - ``dsmc`` for pair-wise, non-Coulomb collisions between kinetic species.
       This is a "direct simulation Monte Carlo" treatment of collisions between
-      kinetic species. See :ref:`DSMC section <theory-collisions-dsmc>`.
+      kinetic species. See :ref:`DSMC section <multiphysics-collisions-dsmc>`.
     - ``background_mcc`` for collisions between particles and a neutral background.
       This is a relativistic Monte Carlo treatment for particles colliding
-      with a neutral background gas. See :ref:`MCC section <theory-collisions-mcc>`.
+      with a neutral background gas. See :ref:`MCC section <multiphysics-collisions-mcc>`.
     - ``background_stopping`` for slowing of ions due to collisions with electrons or ions.
       This implements the approximate formulae as derived in Introduction to Plasma Physics,
       from Goldston and Rutherford, section 14.2.

Examples/CMakeLists.txt

@@ -218,6 +218,22 @@ function(add_warpx_test
     endif()
 endfunction()
 
+# Add a CTest label to a WarpX test set.
+#
+# Labeling it here will add the label to the run test, its analysis and its cleanup.
+#
+# name: unique name of this test
+# label: ctest LABELS property value to be added
+#
+function(label_warpx_test name label)
+    set(_test_names "${name}.run;${name}.analysis;${name}.cleanup")
+    foreach(_test_name IN LISTS _test_names)
+        if(TEST ${_test_name})
+            set_property(TEST ${_test_name} APPEND PROPERTY LABELS "${label}")
+        endif()
+    endforeach()
+endfunction()
+
 # Add tests (alphabetical order) ##############################################
 #
 

Examples/Physics_applications/beam_beam_collision/CMakeLists.txt

@@ -10,3 +10,4 @@ add_warpx_test(
     diags/diag1/  # output
     OFF  # dependency
 )
+label_warpx_test(test_3d_beam_beam_collision slow)