6 files changed, 119 insertions, 8 deletions
diff --git a/Source/Laser/LaserParticleContainer.H b/Source/Laser/LaserParticleContainer.H
index 63ace31fb..1e83ca02f 100644
--- a/Source/Laser/LaserParticleContainer.H
+++ b/Source/Laser/LaserParticleContainer.H
@@ -10,6 +10,17 @@
 #include <memory>
 #include <limits>
 
+/**
+ * The main method to inject a laser pulse in WarpX is to use an artificial
+ * antenna: particles evenly distributed in a given plane (one particle per
+ * cell) move at each iteration and deposit a current J onto the grid, which
+ * in turns creates an electromagnetic field on the grid. The particles'
+ * displacements are prescribed to create the field requested by the user.
+ *
+ * These artificial particles are contained in the LaserParticleContainer.
+ * LaserParticleContainer derives directly from WarpXParticleContainer. It
+ * requires a DepositCurrent function, but no FieldGather function.
+ */
 class LaserParticleContainer
     : public WarpXParticleContainer
 {
diff --git a/Source/Particles/MultiParticleContainer.H b/Source/Particles/MultiParticleContainer.H
index d7ddc7a72..9db129b05 100644
--- a/Source/Particles/MultiParticleContainer.H
+++ b/Source/Particles/MultiParticleContainer.H
@@ -23,14 +23,20 @@
 #include <string>
 #include <algorithm>
 
-//
-// MultiParticleContainer holds multiple (nspecies or npsecies+1 when
-// using laser) WarpXParticleContainer.  WarpXParticleContainer is
-// derived from amrex::ParticleContainer, and it is
-// polymorphic. PhysicalParticleContainer and LaserParticleContainer are
-// concrete class derived from WarpXParticlContainer.
-//
-
+/**
+ * The class MultiParticleContainer holds multiple instances of the polymorphic
+ * class WarpXParticleContainer, stored in its member variable "allcontainers".
+ * The class WarpX typically has a single (pointer to an) instance of
+ * MultiParticleContainer.
+ *
+ * MultiParticleContainer typically has two types of functions:
+ * - Functions that loop over all instances of WarpXParticleContainer in
+ *   allcontainers and calls the corresponding function (for instance,
+ *   MultiParticleContainer::Evolve loops over all particles containers and
+ *   calls the corresponding WarpXParticleContainer::Evolve function).
+ * - Functions that specifically handle multiple species (for instance
+ *   ReadParameters or mapSpeciesProduct).
+ */
 class MultiParticleContainer
 {
 
diff --git a/Source/Particles/PhotonParticleContainer.H b/Source/Particles/PhotonParticleContainer.H
index 580f13f86..9b688cc59 100644
--- a/Source/Particles/PhotonParticleContainer.H
+++ b/Source/Particles/PhotonParticleContainer.H
@@ -4,6 +4,13 @@
 #include <PhysicalParticleContainer.H>
 #include <AMReX_Vector.H>
 
+/**
+ * Photon particles have no mass, they deposit no charge, and see specific QED
+ * effects. For these reasons, they are stored in the separate particle
+ * container PhotonParticleContainer, that inherts from
+ * PhysicalParticleContainer. The particle pusher and current deposition, in
+ * particular, are overriden in this container.
+ */
 class PhotonParticleContainer
     : public PhysicalParticleContainer
 {
diff --git a/Source/Particles/PhysicalParticleContainer.H b/Source/Particles/PhysicalParticleContainer.H
index 1cd4ba621..0192ffb37 100644
--- a/Source/Particles/PhysicalParticleContainer.H
+++ b/Source/Particles/PhysicalParticleContainer.H
@@ -15,6 +15,13 @@
 
 #include <map>
 
+/**
+ * PhysicalParticleContainer is the ParticleContainer class containing plasma
+ * particles (if a simulation has 2 plasma species, say "electrons" and
+ * "ions"), they will be two instances of PhysicalParticleContainer.
+ *
+ * PhysicalParticleContainer inherits from WarpXParticleContainer.
+ */
 class PhysicalParticleContainer
     : public WarpXParticleContainer
 {
@@ -68,6 +75,39 @@ public:
                       int lev,
                       int depos_lev);
 
+    /**
+     * \brief Evolve is the central function PhysicalParticleContainer that
+     * advances plasma particles for a time dt (typically one timestep).
+     *
+     * \param lev level on which particles are living
+     * \param Ex MultiFab from which field Ex is gathered
+     * \param Ey MultiFab from which field Ey is gathered
+     * \param Ez MultiFab from which field Ez is gathered
+     * \param Bx MultiFab from which field Bx is gathered
+     * \param By MultiFab from which field By is gathered
+     * \param Bz MultiFab from which field Bz is gathered
+     * \param jx MultiFab to which the particles' current jx is deposited
+     * \param jy MultiFab to which the particles' current jy is deposited
+     * \param jz MultiFab to which the particles' current jz is deposited
+     * \param cjx Same as jx (coarser, from lev-1), when using deposition buffers
+     * \param cjy Same as jy (coarser, from lev-1), when using deposition buffers
+     * \param cjz Same as jz (coarser, from lev-1), when using deposition buffers
+     * \param rho MultiFab to which the particles' charge is deposited
+     * \param crho Same as rho (coarser, from lev-1), when using deposition buffers
+     * \param cEx Same as Ex (coarser, from lev-1), when using gather buffers
+     * \param cEy Same as Ey (coarser, from lev-1), when using gather buffers
+     * \param cEz Same as Ez (coarser, from lev-1), when using gather buffers
+     * \param cBx Same as Bx (coarser, from lev-1), when using gather buffers
+     * \param cBy Same as By (coarser, from lev-1), when using gather buffers
+     * \param cBz Same as Bz (coarser, from lev-1), when using gather buffers
+     * \param t current physical time
+     * \param dt time step by which particles are advanced
+     * \param a_dt_type type of time step (used for sub-cycling)
+     *
+     * Evolve iterates over particle iterator (each box) and performs filtering,
+     * field gather, particle push and current deposition for all particles
+     * in the box.
+     */
     virtual void Evolve (int lev,
                          const amrex::MultiFab& Ex,
                          const amrex::MultiFab& Ey,
diff --git a/Source/Particles/RigidInjectedParticleContainer.H b/Source/Particles/RigidInjectedParticleContainer.H
index a2473c5ad..fecb9c48e 100644
--- a/Source/Particles/RigidInjectedParticleContainer.H
+++ b/Source/Particles/RigidInjectedParticleContainer.H
@@ -4,6 +4,24 @@
 #include <PhysicalParticleContainer.H>
 #include <AMReX_Vector.H>
 
+/**
+ * When injecting a particle beam (typically for a plasma wakefield
+ * acceleration simulation), say propagating in the z direction, it can
+ * be necessary to make particles propagate in a straight line up to a given
+ * location z=z0. This is of particular importance when running in a boosted
+ * frame, where the beam may evolve due to its space charge fields before
+ * entering the plasma, causing the actual injected beam, and hence the whole
+ * simulation result, to depend on the Lorentz factor of the boost.
+ *
+ * This feature is implemented in RigidInjectedParticleContainer: At each
+ * iteration, for each particle, if z<z0 the particle moves in a straight line,
+ * and if z>z0 the particle evolves as a regular PhysicalParticleContainer.
+ *
+ * Note: This option is also useful to build self-consistent space charge
+ * fields for the particle beam.
+ *
+ * RigidInjectedParticleContainer derives from PhysicalParticleContainer.
+ */
 class RigidInjectedParticleContainer
     : public PhysicalParticleContainer
 {
diff --git a/Source/Particles/WarpXParticleContainer.H b/Source/Particles/WarpXParticleContainer.H
index 567bb402d..fa5c586da 100644
--- a/Source/Particles/WarpXParticleContainer.H
+++ b/Source/Particles/WarpXParticleContainer.H
@@ -101,8 +101,32 @@ public:
     }
 };
 
+// Forward-declaration needed by WarpXParticleContainer below
 class MultiParticleContainer;
 
+/**
+ * WarpXParticleContainer is the base polymorphic class from which all concrete
+ * particle container classes (that store a collection of particles) derive. Derived
+ * classes can be used for plasma particles, photon particles, or non-physical
+ * particles (e.g., for the laser antenna).
+ * It derives from amrex::ParticleContainer<0,0,PIdx::nattribs>, where the
+ * template arguments stand for the number of int and amrex::Real SoA and AoS
+ * data in amrex::Particle.
+ *  - AoS amrex::Real: x, y, z (default), 0 additional (first template
+ *    parameter)
+ *  - AoS int: id, cpu (default), 0 additional (second template parameter)
+ *  - SoA amrex::Real: PIdx::nattribs (third template parameter), see PIdx for
+ * the list.
+ *
+ * WarpXParticleContainer contains the main functions for initialization,
+ * interaction with the grid (field gather and current deposition) and particle
+ * push.
+ *
+ * Note: many functions are pure virtual (meaning they MUST be defined in
+ * derived classes, e.g., Evolve) or empty function (meaning they
+ * do not do anything, e.g., FieldGather, meant to be overriden by derived
+ * function) or actual functions (e.g. CurrentDeposition).
+ */
 class WarpXParticleContainer
     : public amrex::ParticleContainer<0,0,PIdx::nattribs>
 {
@@ -140,6 +164,11 @@ public:
                            amrex::Real t, amrex::Real dt) = 0;
 #endif // WARPX_DO_ELECTROSTATIC
 
+    /**
+     * Evolve is the central WarpXParticleContainer function that advances
+     * particles for a time dt (typically one timestep). It is a pure virtual
+     * function for flexibility.
+     */
     virtual void Evolve (int lev,
                          const amrex::MultiFab& Ex, const amrex::MultiFab& Ey, const amrex::MultiFab& Ez,
                          const amrex::MultiFab& Bx, const amrex::MultiFab& By, const amrex::MultiFab& Bz,