[Hackathon] Update "Theory" section in documentation

Docs/source/index.rst

@@ -36,9 +36,9 @@ We also have a `discussion page <https://github.com/ECP-WarpX/WarpX/discussions>
    /* front page: hide chapter titles
     * needed for consistent HTML-PDF-EPUB chapters
     */
+   section#theory,
    section#installation,
    section#usage,
-   section#theory,
    section#data-analysis,
    section#development,
    section#maintenance,
@@ -54,6 +54,16 @@ We also have a `discussion page <https://github.com/ECP-WarpX/WarpX/discussions>
    acknowledge_us
    highlights
 
+Theory
+------
+.. toctree::
+   :titlesonly:
+   :caption: THEORY
+   :maxdepth: 1
+   :hidden:
+
+   theory/intro
+
 Installation
 ------------
 .. toctree::
@@ -99,22 +109,6 @@ Data Analysis
    dataanalysis/reduced_diags
    dataanalysis/workflows
 
-Theory
-------
-.. toctree::
-   :caption: THEORY
-   :maxdepth: 1
-   :hidden:
-
-   theory/intro
-   theory/pic
-   theory/amr
-   theory/boundary_conditions
-   theory/boosted_frame
-   theory/multiphysics_extensions
-   theory/kinetic_fluid_hybrid_model
-   theory/cold_fluid_model
-
 Development
 -----------
 .. toctree::

Docs/source/theory/intro.rst

@@ -1,10 +1,26 @@
 .. _theory:
 
-Introduction
-============
+Models & Algorithms
+===================
+
+.. _theory-pic:
+
+In the *particle-in-cell method* :cite:p:`i-Birdsalllangdon`,
+the electromagnetic fields are solved on a discretized grid while particles are
+evolved in continuous space. A high-level schematic of the method is shown in the
+figure below with details of the different field solvers, particle handling algorithms,
+additional physics modules, etc. described in the sections linked further down.
+
+.. _fig-pic:
+
+.. figure:: PIC.png
+   :alt: [fig:PIC] The Particle-In-Cell (PIC) method follows the evolution of a collection of charged macro-particles (positively charged in blue on the left plot, negatively charged in red) that evolve self-consistently with their electromagnetic (or electrostatic) fields. The core PIC algorithm involves four operations at each time step: 1) evolve the velocity and position of the particles using the Newton-Lorentz equations, 2) deposit the charge and/or current densities through interpolation from the particles distributions onto the grid, 3) evolve Maxwell’s wave equations (for electromagnetic) or solve Poisson’s equation (for electrostatic) on the grid, 4) interpolate the fields from the grid onto the particles for the next particle push. Additional “add-ons” operations are inserted between these core operations to account for additional physics (e.g. absorption/emission of particles, addition of external forces to account for accelerator focusing or accelerating component) or numerical effects (e.g. smoothing/filtering of the charge/current densities and/or fields on the grid).
+
+   The Particle-In-Cell (PIC) method follows the evolution of a collection of charged macro-particles (positively charged in blue on the left plot, negatively charged in red) that evolve self-consistently with their electromagnetic (or electrostatic) fields. The core PIC algorithm involves four operations at each time step: 1) evolve the velocity and position of the particles using the Newton-Lorentz equations, 2) deposit the charge and/or current densities through interpolation from the particles distributions onto the grid, 3) evolve Maxwell’s wave equations (for electromagnetic) or solve Poisson’s equation (for electrostatic) on the grid, 4) interpolate the fields from the grid onto the particles for the next particle push. Additional “add-ons” operations are inserted between these core operations to account for additional physics (e.g. absorption/emission of particles, addition of external forces to account for accelerator focusing or accelerating component) or numerical effects (e.g. smoothing/filtering of the charge/current densities and/or fields on the grid).
+
 
 .. figure:: Plasma_acceleration_sim.png
-   :alt: Plasma laser-driven (top) and charged-particles-driven (bottom) acceleration (rendering from 3-D Particle-In-Cell simulations). A laser beam (red and blue disks in top picture) or a charged particle beam (red dots in bottom picture) propagating (from left to right) through an under-dense plasma (not represented) displaces electrons, creating a plasma wakefield that supports very high electric fields (pale blue and yellow). These electric fields, which can be orders of magnitude larger than with conventional techniques, can be used to accelerate a short charged particle beam (white) to high-energy over a very short distance.
+   :alt: Plasma acceleration diagram
 
    Plasma laser-driven (top) and charged-particles-driven (bottom) acceleration (rendering from 3-D Particle-In-Cell simulations). A laser beam (red and blue disks in top picture) or a charged particle beam (red dots in bottom picture) propagating (from left to right) through an under-dense plasma (not represented) displaces electrons, creating a plasma wakefield that supports very high electric fields (pale blue and yellow). These electric fields, which can be orders of magnitude larger than with conventional techniques, can be used to accelerate a short charged particle beam (white) to high-energy over a very short distance.
 
@@ -19,5 +35,51 @@ Various techniques or reduced models have been developed to allow multidimension
 ponderomotive guiding center (PGC) models :cite:p:`i-Antonsenprl1992,i-Krallpre1993,i-Quickpic,i-Benedettiaac2010,i-Cowanjcp11`, simulation in an optimal Lorentz boosted frame :cite:p:`i-Vayprl07,i-Bruhwileraac08,i-Vayscidac09,i-Vaypac09,i-Martinspac09,i-VayAAC2010,i-Martinsnaturephysics10,i-Martinspop10,i-Martinscpc10,i-Vayjcp2011,i-VayPOPL2011,i-Vaypop2011,i-Yu2016`,
 expanding the fields into a truncated series of azimuthal modes :cite:p:`i-godfrey1985iprop,i-LifschitzJCP2009,i-DavidsonJCP2015,i-Lehe2016,i-AndriyashPoP2016`, fluid approximation :cite:p:`i-Krallpre1993,i-Shadwickpop09,i-Benedettiaac2010` and scaled parameters :cite:p:`i-Cormieraac08,i-Geddespac09`.
 
+Field Solvers
+-------------
+
+.. toctree::
+   :maxdepth: 1
+
+   maxwell_solvers
+   kinetic_fluid_hybrid_model
+
+Grid & Geometries
+-----------------
+
+Boundary Conditions
+-------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   boundary_conditions
+
+Species Representations
+-----------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   kinetic_particles
+   cold_fluid_model
+
+Multiphysics Processes
+----------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   multiphysics_extensions
+
+Advanced Modes of Running
+-------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   amr
+   boosted_frame
+
 .. bibliography::
     :keyprefix: i-

Docs/source/theory/kinetic_particles.rst

@@ -0,0 +1,110 @@
+.. _theory-kinetic-particles:
+
+Kinetic Particles
+=================
+
+.. _theory-kinetic-particles-push:
+
+Particle push
+-------------
+
+A centered finite-difference discretization of the Newton-Lorentz
+equations of motion is given by
+
+.. math::
+   \frac{\mathbf{x}^{i+1}-\mathbf{x}^{i}}{\Delta t} = \mathbf{v}^{i+1/2},
+   :label: leapfrog_x
+
+.. math::
+   \frac{\gamma^{i+1/2}\mathbf{v}^{i+1/2}-\gamma^{i-1/2}\mathbf{v}^{i-1/2}}{\Delta t} = \frac{q}{m}\left(\mathbf{E}^{i}+\mathbf{\bar{v}}^{i}\times\mathbf{B}^{i}\right).
+   :label: leapfrog_v
+
+In order to close the system, :math:`\bar{\mathbf{v}}^{i}` must be
+expressed as a function of the other quantities. The two implementations that have become the most popular are presented below.
+
+.. _theory-kinetic-particles-push-boris:
+
+Boris relativistic velocity rotation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The solution proposed by Boris :cite:p:`kp-BorisICNSP70` is given by
+
+.. math::
+   \mathbf{\bar{v}}^{i} = \frac{\gamma^{i+1/2}\mathbf{v}^{i+1/2}+\gamma^{i-1/2}\mathbf{v}^{i-1/2}}{2\bar{\gamma}^{i}}
+   :label: boris_v
+
+where :math:`\bar{\gamma}^{i}` is defined by :math:`\bar{\gamma}^{i} \equiv (\gamma^{i+1/2}+\gamma^{i-1/2} )/2`.
+
+The system (:eq:`leapfrog_v`, :eq:`boris_v`) is solved very
+efficiently following Boris’ method, where the electric field push
+is decoupled from the magnetic push. Setting :math:`\mathbf{u}=\gamma\mathbf{v}`, the
+velocity is updated using the following sequence:
+
+.. math::
+
+   \begin{aligned}
+   \mathbf{u^{-}}     & = \mathbf{u}^{i-1/2}+\left(q\Delta t/2m\right)\mathbf{E}^{i}
+   \\
+   \mathbf{u'}        & = \mathbf{u}^{-}+\mathbf{u}^{-}\times\mathbf{t}
+   \\
+   \mathbf{u}^{+}     & = \mathbf{u}^{-}+\mathbf{u'}\times2\mathbf{t}/(1+\mathbf{t}^{2})
+   \\
+   \mathbf{u}^{i+1/2} & = \mathbf{u}^{+}+\left(q\Delta t/2m\right)\mathbf{E}^{i}
+   \end{aligned}
+
+where :math:`\mathbf{t}=\left(q\Delta t/2m\right)\mathbf{B}^{i}/\bar{\gamma}^{i}` and where
+:math:`\bar{\gamma}^{i}` can be calculated as :math:`\bar{\gamma}^{i}=\sqrt{1+(\mathbf{u}^-/c)^2}`.
+
+The Boris implementation is second-order accurate, time-reversible and fast. Its implementation is very widespread and used in the vast majority of PIC codes.
+
+.. _theory-kinetic-particles-push-vay:
+
+Vay Lorentz-invariant formulation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It was shown in :cite:t:`kp-Vaypop2008` that the Boris formulation is
+not Lorentz invariant and can lead to significant errors in the treatment
+of relativistic dynamics. A Lorentz invariant formulation is obtained
+by considering the following velocity average
+
+.. math::
+   \mathbf{\bar{v}}^{i} = \frac{\mathbf{v}^{i+1/2}+\mathbf{v}^{i-1/2}}{2}.
+   :label: new_v
+
+This gives a system that is solvable analytically (see :cite:t:`kp-Vaypop2008`
+for a detailed derivation), giving the following velocity update:
+
+.. math::
+   \mathbf{u^{*}} = \mathbf{u}^{i-1/2}+\frac{q\Delta t}{m}\left(\mathbf{E}^{i}+\frac{\mathbf{v}^{i-1/2}}{2}\times\mathbf{B}^{i}\right),
+   :label: pusher_gamma
+
+.. math::
+   \mathbf{u}^{i+1/2} = \frac{\mathbf{u^{*}}+\left(\mathbf{u^{*}}\cdot\mathbf{t}\right)\mathbf{t}+\mathbf{u^{*}}\times\mathbf{t}}{1+\mathbf{t}^{2}},
+   :label: pusher_upr
+
+where
+
+.. math::
+
+   \begin{align}
+   \mathbf{t} & = \boldsymbol{\tau}/\gamma^{i+1/2},
+   \\
+   \boldsymbol{\tau} & = \left(q\Delta t/2m\right)\mathbf{B}^{i},
+   \\
+   \gamma^{i+1/2} & = \sqrt{\sigma+\sqrt{\sigma^{2}+\left(\boldsymbol{\tau}^{2}+w^{2}\right)}},
+   \\
+   w & = \mathbf{u^{*}}\cdot\boldsymbol{\tau},
+   \\
+   \sigma & = \left(\gamma'^{2}-\boldsymbol{\tau}^{2}\right)/2,
+   \\
+   \gamma' & = \sqrt{1+(\mathbf{u}^{*}/c)^{2}}.
+   \end{align}
+
+This Lorentz invariant formulation
+is particularly well suited for the modeling of ultra-relativistic
+charged particle beams, where the accurate account of the cancellation
+of the self-generated electric and magnetic fields is essential, as
+shown in :cite:t:`kp-Vaypop2008`.
+
+.. bibliography::
+    :keyprefix: kp-