Merge branch 'development' of https://github.com/ECP-WarpX/WarpX into…

… docs-spruce-up-input_output.rst

Docs/source/latex_theory/AMR/AMR.tex

@@ -22,7 +22,7 @@ \section{Mesh refinement}
 In addition, for some implementations where the field that is computed at a given level is affected by the solution at finer levels, there are cases where the procedure violates the integral of Gauss' Law around the refined patch, leading to long range errors \cite{Vaylpb2002,Colellajcp2010}. As will be shown below, in the procedure that has been developed in WarpX, the field at a given refinement level is not affected by the solution at finer levels, and is thus not affected by this type of error.
 
 \subsection{Electrostatic}
-A cornerstone of the Particle-In-Cell method is that assuming a particle lying in a hypothetical infinite grid, then if the grid is regular and symmetrical, and if the order of field gathering matches the order of charge (or current) deposition, then there is no self-force of the particle acting on itself: a) anywhere if using the so-called ``momentum conserving'' gathering scheme; b) on average within one cell if using the ``energy conserving'' gathering scheme \cite{Birdsalllangdon}. A breaking of the regularity and/or symmetry in the grid, whether it is from the use of irregular meshes or mesh refinement, and whether one uses finite difference, finite volume or finite elements, results in a net spurious self-force (which does not average to zero over one cell)  for a macroparticle close to the point of irregularity (mesh refinement interface for the current purpose) \cite{Vaylpb2002,Colellajcp2010}.
+A cornerstone of the Particle-In-Cell method is that, given a particle lying in a hypothetical infinite grid, if the grid is regular and symmetrical, and if the order of field gathering matches the order of charge (or current) deposition, then there is no self-force of the particle acting on itself: a) anywhere if using the so-called ``momentum conserving'' gathering scheme; b) on average within one cell if using the ``energy conserving'' gathering scheme \cite{Birdsalllangdon}. A breaking of the regularity and/or symmetry in the grid, whether it is from the use of irregular meshes or mesh refinement, and whether one uses finite difference, finite volume or finite elements, results in a net spurious self-force (which does not average to zero over one cell)  for a macroparticle close to the point of irregularity (mesh refinement interface for the current purpose) \cite{Vaylpb2002,Colellajcp2010}.
 
 A sketch of the implementation of mesh refinement in WarpX is given in Figure~\ref{fig:ESAMR} (left). Given the solution of the electric potential at a refinement level $L_n$, it is interpolated onto the boundaries of the grid patch(es) at the next refined level $L_{n+1}$. The electric potential is then computed at level $L_{n+1}$ by solving the Poisson equation. This procedure necessitates the knowledge of the charge density at every level of refinement. For efficiency, the macroparticle charge is deposited on the highest level patch that contains them, and the charge density of each patch is added recursively to lower levels, down to the lowest.
 

Docs/source/usage/parameters.rst

@@ -1389,12 +1389,12 @@ Laser initialization
 
         E(\boldsymbol{x},t) \propto Re\left[ \exp\left(  -\frac{(t-t_{peak})^2}{\tau^2 + 2i\phi^{(2)}} + i\omega_0 (t-t_{peak}) + i\phi_0 \right) \right]
 
-    where :math:`\tau` is given by ``<laser_name>.laser_duration`` and represents the
+    where :math:`\tau` is given by ``<laser_name>.profile_duration`` and represents the
     Fourier-limited duration of the laser pulse. Thus, the actual duration of the chirped laser pulse is:
 
     .. math::
 
-        \tau' = \sqrt{ \tau^2 + 4 \phi^{(2)}/\tau^2 }
+        \tau' = \sqrt{ \tau^2 + 4 (\phi^{(2)})^2/\tau^2 }
 
 * ``<laser_name>.do_continuous_injection`` (`0` or `1`) optional (default `0`).
     Whether or not to use continuous injection.

Docs/source/usage/python.rst

@@ -13,7 +13,7 @@ In the input file, instances of classes are created defining the various aspects
 A variable of type :py:class:`pywarpx.picmi.Simulation` is the central object to which all other options are passed, defining the simulation time, field solver, registered species, etc.
 
 Once the simulation is fully configured, it can be used in one of two modes.
-**Interactive** use is the most common and can be :ref:`extended with custom runtime functionality <usage-picmi-extend>`:
+**Interactive** use is the most common and can be :ref:`extended with custom runtime functionality <usage-python-extend>`:
 
 .. tab-set::
 
@@ -25,6 +25,9 @@ Once the simulation is fully configured, it can be used in one of two modes.
 
       :py:meth:`~pywarpx.picmi.Simulation.write_input_file`: create an :ref:`inputs file for a WarpX executable <running-cpp-parameters>`
 
+When run directly from Python, one can also extend WarpX with further custom user logic.
+See the :ref:`detailed workflow page <usage-python-extend>` on how to extend WarpX from Python.
+
 
 .. _usage-picmi-parameters:
 
@@ -137,118 +140,3 @@ Laser profiles can be used to initialize laser pulses in the simulation.
 Laser injectors control where to initialize laser pulses on the simulation grid.
 
 .. autoclass:: pywarpx.picmi.LaserAntenna
-
-
-.. _usage-picmi-extend:
-
-Extending a Simulation from Python
-----------------------------------
-
-When running WarpX directly from Python it is possible to interact with the simulation.
-
-For instance, with the :py:meth:`~pywarpx.picmi.Simulation.step` method of the simulation class, one could run ``sim.step(nsteps=1)`` in a loop:
-
-.. code-block:: python3
-
-   # Preparation: set up the simulation
-   #   sim = picmi.Simulation(...)
-   #   ...
-
-   steps = 1000
-   for _ in range(steps):
-       sim.step(nsteps=1)
-
-       # do something custom with the sim object
-
-As a more flexible alternative, one can install `callback functions <https://en.wikipedia.org/wiki/Callback_(computer_programming)>`__, which will execute a given Python function at a
-specific location in the WarpX simulation loop.
-
-.. automodule:: pywarpx.callbacks
-   :members: installcallback, uninstallcallback, isinstalled
-
-Data Access
-^^^^^^^^^^^
-
-While the simulation is running, callbacks can access the WarpX simulation data *in situ*.
-
-An important object for data access is ``Simulation.extension.warpx``, which is available only during the simulation run.
-This object is the Python equivalent to the C++ ``WarpX`` simulation class and provides access to field ``MultiFab`` and ``ParticleContainer`` data.
-
-.. py:function:: pywarpx.picmi.Simulation.extension.warpx.getistep()
-
-.. py:function:: pywarpx.picmi.Simulation.extension.warpx.gett_new()
-
-.. py:function:: pywarpx.picmi.Simulation.extension.warpx.evolve()
-
-.. autofunction:: pywarpx.picmi.Simulation.extension.finalize()
-
-These and other classes are provided through `pyAMReX <https://github.com/AMReX-Codes/pyamrex>`__.
-After the simulation is initialized, pyAMReX can be accessed via
-
-.. code-block:: python
-
-   from pywarpx import picmi, libwarpx
-
-   # ... simulation definition ...
-
-   # equivalent to
-   #   import amrex.space3d as amr
-   # for a 3D simulation
-   amr = libwarpx.amr  # picks the right 1d, 2d or 3d variant
-
-.. py:function:: amr.ParallelDescriptor.NProcs()
-
-.. py:function:: amr.ParallelDescriptor.MyProc()
-
-.. py:function:: amr.ParallelDescriptor.IOProcessor()
-
-.. py:function:: amr.ParallelDescriptor.IOProcessorNumber()
-
-Particles can be added to the simulation at specific positions and with specific attribute values:
-
-.. code-block:: python
-
-   from pywarpx import particle_containers, picmi
-
-   # ...
-
-   electron_wrapper = particle_containers.ParticleContainerWrapper("electrons")
-
-.. autofunction:: pywarpx.particle_containers.ParticleContainerWrapper.add_particles
-
-Properties of the particles already in the simulation can be obtained with various functions.
-
-.. autofunction:: pywarpx.particle_containers.ParticleContainerWrapper.get_particle_count
-
-.. autofunction:: pywarpx.particle_containers.ParticleContainerWrapper.get_particle_structs
-
-.. autofunction:: pywarpx.particle_containers.ParticleContainerWrapper.get_particle_arrays
-
-The ``get_particle_structs()`` and ``get_particle_arrays()`` functions are called
-by several utility functions of the form ``get_particle_{comp_name}`` where
-``comp_name`` is one of ``x``, ``y``, ``z``, ``r``, ``theta``, ``id``, ``cpu``,
-``weight``, ``ux``, ``uy`` or ``uz``.
-
-New components can be added via Python.
-
-.. autofunction:: pywarpx.particle_containers.ParticleContainerWrapper.add_real_comp
-
-Various diagnostics are also accessible from Python.
-This includes getting the deposited or total charge density from a given species as well as accessing the scraped particle buffer.
-See the example in ``Examples/Tests/ParticleBoundaryScrape`` for a reference on how to interact with scraped particle data.
-
-.. autofunction:: pywarpx.particle_containers.ParticleContainerWrapper.get_species_charge_sum
-
-.. autofunction:: pywarpx.particle_containers.ParticleContainerWrapper.deposit_charge_density
-
-.. autofunction:: pywarpx.particle_containers.ParticleBoundaryBufferWrapper.get_particle_boundary_buffer_size
-
-.. autofunction:: pywarpx.particle_containers.ParticleBoundaryBufferWrapper.get_particle_boundary_buffer_structs
-
-.. autofunction:: pywarpx.particle_containers.ParticleBoundaryBufferWrapper.get_particle_boundary_buffer
-
-.. autofunction:: pywarpx.particle_containers.ParticleBoundaryBufferWrapper.clear_buffer
-
-The embedded boundary conditions can be modified when using the electrostatic solver.
-
-.. py:function:: pywarpx.picmi.Simulation.extension.warpx.set_potential_on_eb()

Docs/source/usage/workflows.rst

@@ -8,11 +8,12 @@ This section collects typical user workflows and best practices for WarpX.
 .. toctree::
    :maxdepth: 2
 
+   workflows/python_extend
    workflows/domain_decomposition
+   workflows/plot_distribution_mapping
    workflows/debugging
    workflows/libensemble
    workflows/plot_timestep_duration
-   workflows/plot_distribution_mapping
    workflows/psatd_stencil
    workflows/archiving
    workflows/ml_dataset_training