Merge pull request #168 from ECP-WarpX/algo_selection

Use string instead of integer to select WarpX algorithms

Docs/source/running_cpp/parameters.rst

@@ -29,12 +29,12 @@ Overall simulation parameters
     (The direction ``y`` cannot be used in 2D simulations.)
 
 * ``warpx.zmax_plasma_to_compute_max_step`` (`float`) optional
-    Can be useful when running in a boosted frame. If specified, automatically 
-    calculates the number of iterations required in the boosted frame for the 
-    lower `z` end of the simulation domain to reach 
-    ``warpx.zmax_plasma_to_compute_max_step`` (typically the plasma end, 
-    given in the lab frame). The value of ``max_step`` is overwritten, and 
-    printed to standard output. Currently only works if the Lorentz boost and 
+    Can be useful when running in a boosted frame. If specified, automatically
+    calculates the number of iterations required in the boosted frame for the
+    lower `z` end of the simulation domain to reach
+    ``warpx.zmax_plasma_to_compute_max_step`` (typically the plasma end,
+    given in the lab frame). The value of ``max_step`` is overwritten, and
+    printed to standard output. Currently only works if the Lorentz boost and
     the moving window are along the z direction.
 
 * ``warpx.verbose`` (`0` or `1`)
@@ -188,8 +188,8 @@ Particle initialization
       This requires the additional parameter ``<species_name>.num_particles_per_cell``.
 
 * ``<species_name>.do_continuous_injection`` (`0` or `1`)
-    Whether to inject particles during the simulation, and not only at 
-    initialization. This can be required whith a moving window and/or when 
+    Whether to inject particles during the simulation, and not only at
+    initialization. This can be required whith a moving window and/or when
     running in a boosted frame.
 
 * ``<species_name>.profile`` (`string`)
@@ -295,20 +295,20 @@ Particle initialization
 * ``<species>.plot_species`` (`0` or `1` optional; default `1`)
     Whether to plot particle quantities for this species.
 
-* ``<species>.plot_vars`` (list of `strings` separated by spaces, optional) 
-    List of particle quantities to write to `plotfiles`. By defaults, all 
-    quantities are written to file. Choices are 
+* ``<species>.plot_vars`` (list of `strings` separated by spaces, optional)
+    List of particle quantities to write to `plotfiles`. By defaults, all
+    quantities are written to file. Choices are
     * ``w`` for the particle weight,
-    * ``ux`` ``uy`` ``uz`` for the particle momentum, 
+    * ``ux`` ``uy`` ``uz`` for the particle momentum,
     * ``Ex`` ``Ey`` ``Ez`` for the electric field on particles,
     * ``Bx`` ``By`` ``Bz`` for the magnetic field on particles.
-    The particle positions are always included. Use 
-    ``<species>.plot_vars = none`` to plot no particle data, except 
+    The particle positions are always included. Use
+    ``<species>.plot_vars = none`` to plot no particle data, except
     particle position.
 
 * ``<species>.do_boosted_frame_diags`` (`0` or `1` optional, default `1`)
-    Only used when ``warpx.do_boosted_frame_diagnostic=1``. When running in a 
-    boosted frame, whether or not to plot back-transformed diagnostics for 
+    Only used when ``warpx.do_boosted_frame_diagnostic=1``. When running in a
+    boosted frame, whether or not to plot back-transformed diagnostics for
     this species.
 
 * ``warpx.serialize_ics`` (`0 or 1`)
@@ -467,13 +467,13 @@ Laser initialization
 
 * ``<laser_name>.do_continuous_injection`` (`0` or `1`) optional (default `0`).
     Whether or not to use continuous injection (`0` or not `0`).
-    If the antenna starts outside of the simulation domain but enters it 
-    at some point (due to moving window or moving antenna in the boosted 
-    frame), use this so that the laser antenna is injected when it reaches 
-    the box boundary. If running in a boosted frame, this requires the 
-    boost direction, moving window direction and laser propagation direction 
-    to be along `z`. If not running in a boosted frame, this requires the 
-    moving window and laser propagation directions to be the same (`x`, `y` 
+    If the antenna starts outside of the simulation domain but enters it
+    at some point (due to moving window or moving antenna in the boosted
+    frame), use this so that the laser antenna is injected when it reaches
+    the box boundary. If running in a boosted frame, this requires the
+    boost direction, moving window direction and laser propagation direction
+    to be along `z`. If not running in a boosted frame, this requires the
+    moving window and laser propagation directions to be the same (`x`, `y`
     or `z`)
 
 * ``warpx.num_mirrors`` (`int`) optional (default `0`)
@@ -512,53 +512,60 @@ Numerics and algorithms
     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:
+* ``algo.current_deposition`` (`string`, optional)
+    The algorithm for current deposition. Available options are:
 
-     - ``0``: Esirkepov deposition, vectorized
-     - ``1``: Esirkepov deposition, non-optimized
-     - ``2``: Direct deposition, vectorized
-     - ``3``: Direct deposition, non-optimized
+     - ``esirkepov``: the charge-conserving Esirkepov algorithm
+       (see `Esirkepov, Comp. Phys. Comm. (2001) <https://www.sciencedirect.com/science/article/pii/S0010465500002289>`__)
+     - ``direct``: simpler current deposition algorithm, described in
+       the section :doc:`../theory/picsar_theory`. Note that this algorithm is not strictly charge-conserving.
+     - ``direct-vectorized`` (only available in 3D, and when running on CPU/KNL - as opposed to GPU):
+       mathematically equivalent to ``direct``, but uses an optimized algorithm
+       for vectorization on CPU/KNL (see `Vincenti, Comp. Phys. Comm. (2017)
+       <https://www.sciencedirect.com/science/article/pii/S0010465516302764>`__)
 
-    .. warning::
+    If ``algo.current_deposition`` is not specified, the default is ``esirkepov``.
 
-        On GPU, use ``algo.current_deposition=0`` for Esirkepov
-	or ``3`` for direct deposition.
+* ``algo.charge_deposition`` (`string`, optional)
+    The algorithm for the charge density deposition. Available options are:
 
-* ``algo.charge_deposition`` (`integer`)
-    The algorithm for the charge density deposition:
+     - ``standard``: standard charge deposition algorithm, described in
+       the section :doc:`../theory/picsar_theory`.
+     - ``vectorized`` (only available in 3D, and when running on CPU/KNL - as opposed to GPU):
+       mathematically equivalent to ``standard``, but uses an optimized algorithm
+       for vectorization on CPU/KNL (see `Vincenti, Comp. Phys. Comm. (2017)
+       <https://www.sciencedirect.com/science/article/pii/S0010465516302764>`__)
 
-     - ``0``: Vectorized version
-     - ``1``: Non-optimized version
+    If ``algo.charge_deposition`` is not specified, ``vectorized`` is the default
+    whenever it is available ; ``standard`` is the default otherwise.
 
-    .. warning::
+* ``algo.field_gathering`` (`string`, optional)
+    The algorithm for field gathering. Available options are:
 
-        The vectorized version does not run on GPU. Use
-		``algo.charge_deposition=1`` when running on GPU.
-
-* ``algo.field_gathering`` (`integer`)
-    The algorithm for field gathering:
+     - ``standard``: gathers directly from the grid points (either staggered
+       or nodal gridpoints depending on ``warpx.do_nodal``).
+     - ``vectorized`` (not available when running on GPU): mathematically
+       equivalent to ``standard``, but uses optimized vector instructions for CPU/KNL.
 
-     - ``0``: Vectorized version
-     - ``1``: Non-optimized version
+    If ``algo.field_gathering`` is not specified, ``vectorized`` is the default
+    on CPU/KNL ; ``standard`` is the default on GPU.
 
-    .. warning::
+* ``algo.particle_pusher`` (`string`, optional)
+    The algorithm for the particle pusher. Available options are:
 
-        The vectorized version does not run on GPU. Use
-		``algo.field_gather=1`` when running on GPU.
+     - ``boris``: Boris pusher.
+     - ``vay``: Vay pusher (see `Vay, Phys. Plasmas (2008) <https://aip.scitation.org/doi/10.1063/1.2837054>`__)
 
-* ``algo.particle_pusher`` (`integer`)
-    The algorithm for the particle pusher:
+     If ``algo.particle_pusher`` is not specified, ``boris`` is the default.
 
-     - ``0``: Boris pusher
-     - ``1``: Vay pusher
+* ``algo.maxwell_fdtd_solver`` (`string`, optional)
+    The algorithm for the FDTD Maxwell field solver. Available options are:
 
-* ``algo.maxwell_fdtd_solver`` (`string`)
-    The algorithm for the FDTD Maxwell field solver:
+     - ``yee``: Yee FDTD solver.
+     - ``ckc``: (not available in ``RZ`` geometry) Cole-Karkkainen solver with Cowan
+       coefficients (see `Cowan, PRSTAB 16 (2013) <https://journals.aps.org/prab/abstract/10.1103/PhysRevSTAB.16.041303>`__)
 
-     - ``yee``: Yee FDTD solver
-     - ``ckc``: Cole-Karkkainen solver with Cowan
-       coefficients (see Cowan - PRST-AB 16, 041303 (2013))
+     If ``algo.maxwell_fdtd_solver`` is not specified, ``yee`` is the default.
 
 * ``interpolation.nox``, ``interpolation.noy``, ``interpolation.noz`` (`integer`)
     The order of the shape factors for the macroparticles, for the 3 dimensions of space.
@@ -581,17 +588,17 @@ Numerics and algorithms
     fields are defined at different points in space)
 
 * ``warpx.do_subcycling`` (`0` or `1`; default: 0)
-    Whether or not to use sub-cycling. Different refinement levels have a 
-    different cell size, which results in different Courant–Friedrichs–Lewy 
-    (CFL) limits for the time step. By default, when using mesh refinement, 
-    the same time step is used for all levels. This time step is 
-    taken as the CFL limit of the finest level. Hence, for coarser 
-    levels, the timestep is only a fraction of the CFL limit for this 
-    level, which may lead to numerical artifacts. With sub-cycling, each level 
-    evolves with its own time step, set to its own CFL limit. In practice, it 
-    means that when level 0 performs one iteration, level 1 performs two 
-    iterations. Currently, this option is only supported when 
-    ``amr.max_level = 1``. More information can be found at 
+    Whether or not to use sub-cycling. Different refinement levels have a
+    different cell size, which results in different Courant–Friedrichs–Lewy
+    (CFL) limits for the time step. By default, when using mesh refinement,
+    the same time step is used for all levels. This time step is
+    taken as the CFL limit of the finest level. Hence, for coarser
+    levels, the timestep is only a fraction of the CFL limit for this
+    level, which may lead to numerical artifacts. With sub-cycling, each level
+    evolves with its own time step, set to its own CFL limit. In practice, it
+    means that when level 0 performs one iteration, level 1 performs two
+    iterations. Currently, this option is only supported when
+    ``amr.max_level = 1``. More information can be found at
     https://ieeexplore.ieee.org/document/8659392.
 
 * ``psatd.nox``, ``psatd.noy``, ``pstad.noz`` (`integer`) optional (default `16` for all)
@@ -658,7 +665,7 @@ Diagnostics and output
     The directory in which to save the lab frame data when using the
     **back-transformed diagnostics**. If not specified, the default is
     is `lab_frame_data`.
-    
+
 * ``warpx.num_snapshots_lab`` (`integer`)
     Only used when ``warpx.do_boosted_frame_diagnostic`` is ``1``.
     The number of lab-frame snapshots that will be written.
@@ -672,9 +679,9 @@ Diagnostics and output
     Whether to use the **back-transformed diagnostics** for the fields.
 
 * ``warpx.boosted_frame_diag_fields`` (space-separated list of `string`)
-    Which fields to dumped in back-transformed diagnostics. Choices are 
-    'Ex', 'Ey', Ez', 'Bx', 'By', Bz', 'jx', 'jy', jz' and 'rho'. Example: 
-    ``warpx.boosted_frame_diag_fields = Ex Ez By``. By default, all fields 
+    Which fields to dumped in back-transformed diagnostics. Choices are
+    'Ex', 'Ey', Ez', 'Bx', 'By', Bz', 'jx', 'jy', jz' and 'rho'. Example:
+    ``warpx.boosted_frame_diag_fields = Ex Ez By``. By default, all fields
     are dumped.
 
 * ``warpx.plot_raw_fields`` (`0` or `1`) optional (default `0`)
@@ -715,13 +722,13 @@ Diagnostics and output
     The extent of the slice are defined by the co-ordinates of the lower corner (``slice.dom_lo``) and upper corner (``slice.dom_hi``). The slice could be 1D, 2D, or 3D, aligned with the co-ordinate axes and the first axis of the coordinates is x. For example: if for a 3D simulation, an x-z slice is to be extracted at y = 0.0, then the y-value of slice.dom_lo and slice.dom_hi must be equal to 0.0
 
 * ``slice.coarsening_ratio`` (`2 integers in 2D`, `3 integers in 3D`; default `1`)
-    The coarsening ratio input must be greater than 0. Default is 1 in all directions. 
-    In the directions that is reduced, i.e., for an x-z slice in 3D, the reduced y-dimension has a default coarsening ratio equal to 1. 
+    The coarsening ratio input must be greater than 0. Default is 1 in all directions.
+    In the directions that is reduced, i.e., for an x-z slice in 3D, the reduced y-dimension has a default coarsening ratio equal to 1.
 
 * ``slice.plot_int`` (`integer`)
     The number of PIC cycles inbetween two consecutive data dumps for the slice. Use a
     negative number to disable slice generation and slice data dumping.
-    
+
 
 
 Checkpoints and restart

Docs/source/theory/picsar_theory.rst

@@ -328,6 +328,8 @@ a collocated and a staggered formulation is application-dependent.
 
 Spectral solvers used to be very popular in the years 1970s to early 1990s, before being replaced by finite-difference methods with the advent of parallel supercomputers that favored local methods. However, it was shown recently that standard domain decomposition with Fast Fourier Transforms that are local to each subdomain could be used effectively with PIC spectral methods (Jean-Luc Vay, Haber, and Godfrey 2013), at the cost of truncation errors in the guard cells that could be neglected. A detailed analysis of the effectiveness of the method with exact evaluation of the magnitude of the effect of the truncation error is given in (Vincenti and Vay 2016) for stencils of arbitrary order (up-to the infinite “spectral” order).
 
+.. _current_deposition:
+
 Current deposition
 ------------------
 

Examples/Modules/RigidInjection/inputs

@@ -23,10 +23,6 @@ geometry.prob_hi     =  2.    2.    4.
 warpx.verbose = 1
 
 # Algorithms
-algo.current_deposition = 0
-algo.charge_deposition = 0
-algo.field_gathering = 0
-algo.particle_pusher = 0
 
 # interpolation
 interpolation.nox = 3

Examples/Modules/boosted_diags/inputs.2d

@@ -24,10 +24,7 @@ geometry.prob_hi     =  150.e-6    150.e-6    0.
 warpx.verbose = 1
 
 # Algorithms
-algo.current_deposition = 3
-algo.charge_deposition = 0
-algo.field_gathering = 0
-algo.particle_pusher = 0
+algo.current_deposition = direct
 
 # Numerics
 interpolation.nox = 3

Examples/Modules/boosted_diags/inputs.3d

@@ -24,10 +24,7 @@ geometry.prob_hi     =  150.e-6    150.e-6    0.
 warpx.verbose = 1
 
 # Algorithms
-algo.current_deposition = 3
-algo.charge_deposition = 0
-algo.field_gathering = 0
-algo.particle_pusher = 0
+algo.current_deposition = direct
 
 # Numerics
 interpolation.nox = 3

Examples/Modules/charged_beam/inputs

@@ -23,10 +23,7 @@ geometry.prob_hi     =  20.e-6    20.e-6    20.e-6
 warpx.verbose = 1
 
 # Algorithms
-algo.current_deposition = 3
-algo.charge_deposition = 0
-algo.field_gathering = 0
-algo.particle_pusher = 0
+algo.current_deposition = direct
 
 # CFL
 warpx.cfl = 1.0

Examples/Modules/gaussian_beam/inputs

@@ -23,10 +23,6 @@ geometry.prob_hi     =  2.    2.    2.
 warpx.verbose = 1
 
 # Algorithms
-algo.current_deposition = 0
-algo.charge_deposition = 0
-algo.field_gathering = 0
-algo.particle_pusher = 0
 
 # interpolation
 interpolation.nox = 3

Examples/Modules/laser_injection/inputs

@@ -21,10 +21,6 @@ geometry.prob_hi     =  20.e-6    20.e-6    12.e-6
 warpx.verbose = 1
 
 # Algorithms
-algo.current_deposition = 0
-algo.charge_deposition = 0
-algo.field_gathering = 0
-algo.particle_pusher = 0
 
 # CFL
 warpx.cfl = 1.0

Examples/Modules/laser_injection/inputs.2d.rt

@@ -23,10 +23,7 @@ warpx.serialize_ics = 1
 warpx.verbose = 1
 
 # Algorithms
-algo.current_deposition = 1
-algo.charge_deposition = 0
-algo.field_gathering = 0
-algo.particle_pusher = 0
+algo.current_deposition = esirkepov
 
 # CFL
 warpx.cfl = 1.0

Examples/Modules/laser_injection/inputs.rt

@@ -23,10 +23,6 @@ warpx.serialize_ics = 1
 warpx.verbose = 1
 
 # Algorithms
-algo.current_deposition = 0
-algo.charge_deposition = 0
-algo.field_gathering = 0
-algo.particle_pusher = 0
 
 # CFL
 warpx.cfl = 1.0

Examples/Modules/nci_corrector/inputs2d

@@ -25,10 +25,7 @@ warpx.verbose = 1
 warpx.use_filter = 1
 
 # Algorithms
-algo.current_deposition = 1
-algo.charge_deposition = 0
-algo.field_gathering = 0
-algo.particle_pusher = 0
+algo.current_deposition = esirkepov
 interpolation.nox = 3
 interpolation.noy = 3
 interpolation.noz = 3

Examples/Physics_applications/laser_acceleration/inputs.2d

@@ -17,10 +17,6 @@ warpx.fine_tag_hi =  5.e-6   -25.e-6
 #################################
 ############ NUMERICS ###########
 #################################
-algo.current_deposition = 0
-algo.charge_deposition = 0
-algo.field_gathering = 0
-algo.particle_pusher = 0
 interpolation.nox = 3 # Particle interpolation order. Must be the same in x, y, and z
 interpolation.noy = 3
 interpolation.noz = 3

Examples/Physics_applications/laser_acceleration/inputs.2d.boost

@@ -19,10 +19,8 @@ geometry.prob_hi     =  128.e-6     0.96e-6
 #################################
 warpx.verbose = 1
 amrex.v = 1
-algo.current_deposition = 2
-algo.charge_deposition = 0
-algo.field_gathering = 0
-algo.particle_pusher = 1
+algo.current_deposition = direct-vectorized
+algo.particle_pusher = vay
 algo.maxwell_fdtd_solver = ckc
 interpolation.nox = 3
 interpolation.noy = 3

Examples/Physics_applications/laser_acceleration/inputs.3d

@@ -17,10 +17,6 @@ warpx.fine_tag_hi =  5.e-6    5.e-6   -30.e-6
 #################################
 ############ NUMERICS ###########
 #################################
-algo.current_deposition = 0
-algo.charge_deposition = 0
-algo.field_gathering = 0
-algo.particle_pusher = 0
 interpolation.nox = 3 # Particle interpolation order. Must be the same in x, y, and z
 interpolation.noy = 3
 interpolation.noz = 3