Refactor theory in docs and add multiphysics (ECP-WarpX#5245)

- grouped multiphysics docs in a new subfolder
- moved QED docs away from developer docs
- updated a doxygen function in qed

Docs/source/developers/developers.rst

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

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/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,8 @@
+.. _multiphysics-ionization:
+
+Ionization
+==========
+
+.. note::
+
+    This section will be added soon!

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