fix conflicts

1 files changed, 119 insertions, 61 deletions

diff --git a/Docs/source/running_cpp/parameters.rst b/Docs/source/running_cpp/parameters.rst
index 42d43eccc..32ac12104 100644
--- a/Docs/source/running_cpp/parameters.rst
+++ b/Docs/source/running_cpp/parameters.rst
@@ -44,12 +44,16 @@ Setting up the field mesh
 
     For each direction, use 1 for periodic conditions, 0 otherwise.
 
+* ``geometry.coord_sys`` (`integer`) optional (default `0`)
+    Coordinate system used by the simulation. 0 for Cartesian, 1 for cylindrical.
+
 * ``geometry.prob_lo`` and ``geometry.prob_hi`` (`2 floats in 2D`, `3 integers in 3D`; in meters)
     The extent of the full simulation box. This box is rectangular, and thus its
     extent is given here by the coordinates of the lower corner (``geometry.prob_lo``) and
-    upper corner (``geometry.prob_hi``).
+    upper corner (``geometry.prob_hi``). The first axis of the coordinates is x (or r with cylindrical)
+    and the last is z.
 
-* ``warpx.fine_tag_lo`` and ``warpx.fine_tag_hi`` (`2 floats in 2D`, `3 integers in 3D`; in meters)
+* ``warpx.fine_tag_lo`` and ``warpx.fine_tag_hi`` (`2 floats in 2D`, `3 integers in 3D`; in meters) optional
     **When using static mesh refinement with 1 level**, the extent of the refined patch.
     This patch is rectangular, and thus its extent is given here by the coordinates
     of the lower corner (``warpx.fine_tag_lo``) and upper corner (``warpx.fine_tag_hi``).
@@ -58,7 +62,7 @@ Distribution across MPI ranks and parallelization
 -------------------------------------------------
 
 
-* ``amr.max_grid_size`` (`integer`)
+* ``amr.max_grid_size`` (`integer`) optional (default `128`)
     Maximum allowable size of each **subdomain**
     (expressed in number of grid points, in each direction).
     Each subdomain has its own ghost cells, and can be handled by a
@@ -73,7 +77,7 @@ Distribution across MPI ranks and parallelization
     When using mesh refinement, this number applies to the subdomains
     of the coarsest level, but also to any of the finer level.
 
-* ``warpx.load_balance_int`` (`integer`)
+* ``warpx.load_balance_int`` (`integer`) optional (default `-1`)
     How often WarpX should try to redistribute the work across MPI ranks,
     in order to have better load balancing (expressed in number of PIC cycles
     inbetween two consecutive attempts at redistributing the work).
@@ -103,20 +107,17 @@ distribution or the laser field (see below `Particle initialization` and
 
 The parser reads python-style expressions between double quotes, for instance
 ``"a0*x**2 * (1-y*1.e2) * (x>0)"`` is a valid expression where ``a0`` is a
-user-defined constant and ``x`` and ``y`` are variables. The factor
+user-defined constant and ``x`` and ``y`` are variables. The names are case sensitive. The factor
 ``(x>0)`` is `1` where `x>0` and `0` where `x<=0`. It allows the user to
 define functions by intervals. User-defined constants can be used in parsed
-functions only (i.e., ``density_function(x,y,z)`` and ``field_function(x,y,t)``,
-see below). They are specified with:
-
-* ``constants.use_my_constants`` (`bool`)
-    Whether to use user-defined constants.
+functions only (i.e., ``density_function(x,y,z)`` and ``field_function(X,Y,t)``,
+see below). User-defined constants can contain only letter, numbers and character _.
+The name of each constant has to begin with a letter. The following names are used
+by WarpX, and cannot be used as user-defined constants: `x`, `y`, `z`, `X`, `Y`, `t`.
+For example, parameters ``a0`` and ``z_plateau`` can be specified with:
 
-* ``constants.constant_names`` (`strings, separated by spaces`)
-    A list of variables the user wants to define, e.g., ``constants.constant_names = a0 n0``.
-
-* ``constants.constant_values`` (`floats, sepatated by spaces`)
-    Values for the user-defined constants., e.g., ``constants.constant_values = 3. 1.e24``.
+* ``my_constants.a0 = 3.0``
+* ``my_constants.z_plateau = 150.e-6``
 
 Particle initialization
 -----------------------
@@ -128,7 +129,7 @@ Particle initialization
     The name of each species. This is then used in the rest of the input deck ;
     in this documentation we use `<species_name>` as a placeholder.
 
-* ``particles.use_fdtd_nci_corr`` (`0` or `1`)
+* ``particles.use_fdtd_nci_corr`` (`0` or `1`) optional (default `0`)
     Whether to activate the FDTD Numerical Cherenkov Instability corrector.
 
 * ``particles.rigid_injected_species`` (`strings`, separated by spaces)
@@ -164,8 +165,11 @@ Particle initialization
       It requires additional argument ``<species_name>.density_function(x,y,z)``, which is a
       mathematical expression for the density of the species, e.g.
       ``electrons.density_function(x,y,z) = "n0+n0*x**2*1.e12"`` where ``n0`` is a
-      user-defined constant, see above. Note that using this density profile will turn
-      ``warpx.serialize_ics`` to ``1``, which may slow down the simulation.
+      user-defined constant, see above.
+
+* ``<species_name>.radially_weighted`` (`bool`) optional (default `true`)
+    Whether particle's weight is varied with their radius. This only applies to cylindrical geometry.
+    The only valid value is true.
 
     * ``predefined``: use one of WarpX predefined plasma profiles. It requires additional
       arguments ``<species_name>.predefined_profile_name`` and 
@@ -191,8 +195,6 @@ Particle initialization
       file. It requires additional arguments ``<species_name>.momentum_function_ux(x,y,z)``,
       ``<species_name>.momentum_function_uy(x,y,z)`` and ``<species_name>.momentum_function_uz(x,y,z)``,
       which gives the distribution of each component of the momentum as a function of space.
-      Note that using this momentum distribution type will turn
-      ``warpx.serialize_ics`` to ``1``, which may slow down the simulation.
 
 * ``<species_name>.zinject_plane`` (`float`)
     Only read if  ``<species_name>`` is in ``particles.rigid_injected_species``.
@@ -244,7 +246,7 @@ Particle initialization
     fields when running in the boosted frame. See examples.
 
 * ``<species_name>.do_splitting`` (`bool`) optional (default `0`)
-    Split particles of the species when crossing the boundary from a lower 
+    Split particles of the species when crossing the boundary from a lower
     resolution domain to a higher resolution domain.
 
 * ``<species_name>.split_type`` (`int`) optional (default `0`)
@@ -258,28 +260,35 @@ Particle initialization
 Laser initialization
 --------------------
 
-* ``warpx.use_laser`` (`0 or 1`)
-    Whether to activate the injection of a laser pulse in the simulation
+* ``lasers.nlasers`` (`int`) optional (default `0`)
+    Number of lasers pulses.
 
-* ``laser.position`` (`3 floats in 3D and 2D` ; in meters)
+* ``lasers.names`` (list of `string`. Must contain ``lasers.nlasers`` elements)
+    Name of each laser. This is then used in the rest of the input deck ;
+    in this documentation we use `<laser_name>` as a placeholder. The parameters below 
+    must be provided for each laser pulse.
+
+* ```<laser_name>`.position`` (`3 floats in 3D and 2D` ; in meters)
     The coordinates of one of the point of the antenna that will emit the laser.
-    The plane of the antenna is entirely defined by ``laser.position`` and ``laser.direction``.
+    The plane of the antenna is entirely defined by ``<laser_name>.position`` 
+    and ``<laser_name>.direction``.
 
-    ``laser.position`` also corresponds to the origin of the coordinates system
+    ```<laser_name>`.position`` also corresponds to the origin of the coordinates system
     for the laser tranverse profile. For instance, for a Gaussian laser profile,
-    the peak of intensity will be at the position given by ``laser.position``.
+    the peak of intensity will be at the position given by ``<laser_name>.position``.
     This variable can thus be used to shift the position of the laser pulse
     transversally.
 
     .. note::
-        In 2D, ``laser.position`` is still given by 3 numbers, but the second number is ignored.
+        In 2D, ```<laser_name>`.position`` is still given by 3 numbers, 
+        but the second number is ignored.
 
     When running a **boosted-frame simulation**, provide the value of
-    ``laser.position`` in the laboratory frame, and use ``warpx.gamma_boost``
+    ``<laser_name>.position`` in the laboratory frame, and use ``warpx.gamma_boost``
     to automatically perform the conversion to the boosted frame. Note that,
     in this case, the laser antenna will be moving, in the boosted frame.
 
-* ``laser.polarization`` (`3 floats in 3D and 2D`)
+* ``<laser_name>.polarization`` (`3 floats in 3D and 2D`)
     The coordinates of a vector that points in the direction of polarization of
     the laser. The norm of this vector is unimportant, only its direction matters.
 
@@ -287,7 +296,7 @@ Laser initialization
         Even in 2D, all the 3 components of this vectors are important (i.e.
         the polarization can be orthogonal to the plane of the simulation).
 
-*  ``laser.direction`` (`3 floats in 3D`)
+*  ``<laser_name>.direction`` (`3 floats in 3D`)
     The coordinates of a vector that points in the propagation direction of
     the laser. The norm of this vector is unimportant, only its direction matters.
 
@@ -295,10 +304,10 @@ Laser initialization
 
     .. warning::
 
-        When running **boosted-frame simulations**, ``laser.direction`` should
+        When running **boosted-frame simulations**, ``<laser_name>.direction`` should
         be parallel to ``warpx.boost_direction``, for now.
 
-* ``laser.e_max`` (`float` ; in V/m)
+* ``<laser_name>.e_max`` (`float` ; in V/m)
     Peak amplitude of the laser field.
 
     For a laser with a wavelength :math:`\lambda = 0.8\,\mu m`, the peak amplitude
@@ -308,45 +317,45 @@ Laser initialization
 
         E_{max} = a_0 \frac{2 \pi m_e c}{e\lambda} = a_0 \times (4.0 \cdot 10^{12} \;V.m^{-1})
 
-    When running a **boosted-frame simulation**, provide the value of ``laser.e_max``
+    When running a **boosted-frame simulation**, provide the value of ``<laser_name>.e_max``
     in the laboratory frame, and use ``warpx.gamma_boost`` to automatically
     perform the conversion to the boosted frame.
 
-* ``laser.wavelength`` (`float`; in meters)
+* ``<laser_name>.wavelength`` (`float`; in meters)
     The wavelength of the laser in vacuum.
 
     When running a **boosted-frame simulation**, provide the value of
-    ``laser.wavelength`` in the laboratory frame, and use ``warpx.gamma_boost``
+    ``<laser_name>.wavelength`` in the laboratory frame, and use ``warpx.gamma_boost``
     to automatically perform the conversion to the boosted frame.
 
-* ``laser.profile`` (`string`)
+* ``<laser_name>.profile`` (`string`)
     The spatio-temporal shape of the laser. The options that are currently
     implemented are:
 
     - ``"Gaussian"``: The transverse and longitudinal profiles are Gaussian.
     - ``"Harris"``: The transverse profile is Gaussian, but the longitudinal profile
-      is given by the Harris function (see ``laser.profile_duration`` for more details)
+      is given by the Harris function (see ``<laser_name>.profile_duration`` for more details)
     - ``"parse_field_function"``: the laser electric field is given by a function in the
-      input file. It requires additional argument ``laser.field_function(X,Y,t)``, which
+      input file. It requires additional argument ``<laser_name>.field_function(X,Y,t)``, which
       is a mathematical expression , e.g.
-      ``laser.field_function(X,Y,t) = "a0*X**2 * (X>0) * cos(omega0*t)"`` where
+      ``<laser_name>.field_function(X,Y,t) = "a0*X**2 * (X>0) * cos(omega0*t)"`` where
       ``a0`` and ``omega0`` are a user-defined constant, see above. The profile passed
       here is the full profile, not only the laser envelope. ``t`` is time and ``X``
-      and ``Y`` are coordinates orthogonal to ``laser.direction`` (not necessarily the
+      and ``Y`` are coordinates orthogonal to ``<laser_name>.direction`` (not necessarily the
       x and y coordinates of the simulation). All parameters above are required, but
-      none of the parameters below are used when ``laser.parse_field_function=1``. Even
-      though ``laser.wavelength`` and ``laser.e_max`` should be included in the laser
+      none of the parameters below are used when ``<laser_name>.parse_field_function=1``. Even
+      though ``<laser_name>.wavelength`` and ``<laser_name>.e_max`` should be included in the laser
       function, they still have to be specified as they are used for numerical purposes.
 
-*  ``laser.profile_t_peak`` (`float`; in seconds)
+*  ``<laser_name>.profile_t_peak`` (`float`; in seconds)
     The time at which the laser reaches its peak intensity, at the position
-    given by ``laser.position`` (only used for the ``"gaussian"`` profile)
+    given by ``<laser_name>.position`` (only used for the ``"gaussian"`` profile)
 
     When running a **boosted-frame simulation**, provide the value of
-    ``laser.profile_t_peak`` in the laboratory frame, and use ``warpx.gamma_boost``
+    ``<laser_name>.profile_t_peak`` in the laboratory frame, and use ``warpx.gamma_boost``
     to automatically perform the conversion to the boosted frame.
 
-*  ``laser.profile_duration`` (`float` ; in seconds)
+*  ``<laser_name>.profile_duration`` (`float` ; in seconds)
 
     The duration of the laser, defined as :math:`\tau` below:
 
@@ -363,42 +372,61 @@ Laser initialization
         E(\boldsymbol{x},t) \propto \frac{1}{32}\left[10 - 15 \cos\left(\frac{2\pi t}{\tau}\right) + 6 \cos\left(\frac{4\pi t}{\tau}\right) - \cos\left(\frac{6\pi t}{\tau}\right) \right]\Theta(\tau - t)
 
     When running a **boosted-frame simulation**, provide the value of
-    ``laser.profile_duration`` in the laboratory frame, and use ``warpx.gamma_boost``
+    ``<laser_name>.profile_duration`` in the laboratory frame, and use ``warpx.gamma_boost``
     to automatically perform the conversion to the boosted frame.
 
-* ``laser.profile_waist`` (`float` ; in meters)
+* ``<laser_name>.profile_waist`` (`float` ; in meters)
     The waist of the transverse Gaussian laser profile, defined as :math:`w_0` :
 
     .. math::
 
         E(\boldsymbol{x},t) \propto \exp\left( -\frac{\boldsymbol{x}_\perp^2}{w_0^2} \right)
 
-* ``laser.profile_focal_distance`` (`float`; in meters)
+* ``<laser_name>.profile_focal_distance`` (`float`; in meters)
     The distance from ``laser_position`` to the focal plane.
-    (where the distance is defined along the direction given by ``laser.direction``.)
+    (where the distance is defined along the direction given by ``<laser_name>.direction``.)
 
     Use a negative number for a defocussing laser instead of a focussing laser.
 
     When running a **boosted-frame simulation**, provide the value of
-    ``laser.profile_focal_distance`` in the laboratory frame, and use ``warpx.gamma_boost``
+    ``<laser_name>.profile_focal_distance`` in the laboratory frame, and use ``warpx.gamma_boost``
     to automatically perform the conversion to the boosted frame.
 
-* ``laser.stc_direction`` (`3 floats`) optional (default `1. 0. 0.`)
+* ``<laser_name>.stc_direction`` (`3 floats`) optional (default `1. 0. 0.`)
     Direction of laser spatio-temporal couplings.
   	See definition in Akturk et al., Opt Express, vol 12, no 19 (2014).
 
-* ``laser.zeta`` (`float`; in meters.seconds) optional (default `0.`)
-    Spatial chirp at focus in direction ``laser.stc_direction``. See definition in
+* ``<laser_name>.zeta`` (`float`; in meters.seconds) optional (default `0.`)
+    Spatial chirp at focus in direction ``<laser_name>.stc_direction``. See definition in
     Akturk et al., Opt Express, vol 12, no 19 (2014).
 
-* ``laser.beta`` (`float`; in seconds) optional (default `0.`)
-    Angular dispersion (or angular chirp) at focus in direction ``laser.stc_direction``.
+* ``<laser_name>.beta`` (`float`; in seconds) optional (default `0.`)
+    Angular dispersion (or angular chirp) at focus in direction ``<laser_name>.stc_direction``.
     See definition in Akturk et al., Opt Express, vol 12, no 19 (2014).
 
-* ``laser.phi2`` (`float`; in seconds**2) optional (default `0.`)
+* ``<laser_name>.phi2`` (`float`; in seconds**2) optional (default `0.`)
     Temporal chirp at focus.
     See definition in Akturk et al., Opt Express, vol 12, no 19 (2014).
 
+* ``warpx.num_mirrors`` (`int`) optional (default `0`)
+    Users can input perfect mirror condition inside the simulation domain.
+    The number of mirrors is given by ``warpx.num_mirrors``. The mirrors are 
+    orthogonal to the `z` direction. The following parameters are required 
+    when ``warpx.num_mirrors`` is >0.
+
+* ``warpx.mirror_z`` (list of `float`) required if ``warpx.num_mirrors>0``
+    ``z`` location of the front of the mirrors.
+
+* ``warpx.mirror_z_width`` (list of `float`) required if ``warpx.num_mirrors>0``
+    ``z`` width of the mirrors.
+
+* ``warpx.mirror_z_npoints`` (list of `int`) required if ``warpx.num_mirrors>0``
+    In the boosted frame, depending on `gamma_boost`, ``warpx.mirror_z_width`` 
+    can be smaller than the cell size, so that the mirror would not work. This 
+    parameter is the minimum number of points for the mirror. If 
+    ``mirror_z_width < dz/cell_size``, the upper bound of the mirror is increased 
+    so that it contains at least ``mirror_z_npoints``.
+
 Numerics and algorithms
 -----------------------
 
@@ -412,6 +440,10 @@ Numerics and algorithms
     them from the macroparticles. This uses a bilinear filter
     (see the sub-section **Filtering** in :doc:`../theory/theory`).
 
+* ``warpx.filter_npass_each_dir`` (`3 int`) optional (default `1 1 1`)
+    Number of passes along each direction for the bilinear filter.
+    In 2D simulations, only the first two values are read.
+
 * ``algo.current_deposition`` (`integer`)
     The algorithm for current deposition:
 
@@ -439,7 +471,7 @@ Numerics and algorithms
 
     .. warning::
 
-        The vectorized version does not run on GPU. Use 
+        The vectorized version does not run on GPU. Use
 		``algo.field_gather=1`` when running on GPU.
 
 * ``algo.particle_pusher`` (`integer`)
@@ -465,8 +497,14 @@ Numerics and algorithms
 * ``psatd.nox``, ``psatd.noy``, ``pstad.noz`` (`integer`) optional (default `16` for all)
     The order of accuracy of the spatial derivatives, when using the code compiled with a PSATD solver.
 
+* ``psatd.hybrid_mpi_decomposition`` (`0` or `1`; default: 0)
+    Whether to use a different MPI decomposition for the particle-grid operations
+    (deposition and gather) and for the PSATD solver. If `1`, the FFT will
+    be performed over MPI groups.
+
 * ``psatd.ngroups_fft`` (`integer`)
-    The number of MPI groups that are created for the FFT, when using the code compiled with a PSATD solver.
+    The number of MPI groups that are created for the FFT, when using the code compiled with a PSATD solver
+    (and only if `hybrid_mpi_decomposition` is `1`).
     The FFTs are global within one MPI group and use guard cell exchanges in between MPI groups.
     (If ``ngroups_fft`` is larger than the number of MPI ranks used,
     than the actual number of MPI ranks is used instead.)
@@ -487,6 +525,16 @@ Diagnostics and output
     The number of PIC cycles inbetween two consecutive data dumps. Use a
     negative number to disable data dumping.
 
+* ``warpx.dump_plotfiles`` (`0` or `1`) optional
+    Whether to dump the simulation data in
+    `AMReX plotfile <https://amrex-codes.github.io/amrex/docs_html/IO.html>`__
+    format. This is ``1`` by default, unless WarpX is compiled with openPMD support.
+
+* ``warpx.dump_openpmd`` (`0` or `1`) optional
+    Whether to dump the simulation data in
+    `openPMD <https://github.com/openPMD>`__ format.
+    When WarpX is compiled with openPMD support, this is ``1`` by default.
+
 * ``warpx.do_boosted_frame_diagnostic`` (`0 or 1`)
     Whether to use the **back-transformed diagnostics** (i.e. diagnostics that
     perform on-the-fly conversion to the laboratory frame, when running
@@ -518,8 +566,18 @@ Diagnostics and output
     Only used when mesh refinement is activated and ``warpx.plot_raw_fields`` is ``1``.
     Whether to output the data of the coarse patch, in the plot files.
 
+* ``warpx.plot_coarsening_ratio`` (`int` ; default: `1`)
+    Reduce size of the field output by this ratio in each dimension.
+    (This is done by averaging the field.) ``plot_coarsening_ratio`` should
+    be an integer divisor of ``blocking_factor``.
+
+* ``warpx.particle_plot_vars`` (`strings`, separated by spaces ; default: all)
+    Control which particle variables get written to the plot file. Choices are:
+    `w`, `ux`, `uy`, `uz`, `Ex`, `Ey`, `Ez`, `Bx`, `By`, and `Bz`.
+    The particle positions and ids are always included.
+
 * ``amr.plot_file`` (`string`)
-    Root for output file names. Supports sub-directories. Default `plotfiles/plt`
+    Root for output file names. Supports sub-directories. Default `diags/plotfiles/plt`
 
 Checkpoints and restart
 -----------------------