Update memaster (#110)

* Fix Init of Vector Members (ECP-WarpX#2595)

Fix default init of `Vector` member variables. The old construct
is not valid C++.

https://stackoverflow.com/a/11491003/2719194

* C++17: Work-Around NVCC gatherParticles (ECP-WarpX#2596)

The `noexcept` lambda does not compile in C++17 mode due to an NVCC compiler bug, at least in NVCC 11.3.109. Compiles in C++14 mode with the same compiler.

* requirements.txt - PICMI development version (ECP-WarpX#2588)

Document in `requirements.txt` on how to install a pre-release
version of PICMI.

* CONTRIBUTING: Update/Modernize (ECP-WarpX#2600)

* CONTRIBUTING: Update/Modernize

- Add GitHub account setup
- Add local git setup
- Modernize for CMake workflows

* Apply suggestions by Edoardo

Co-authored-by: Edoardo Zoni <59625522+EZoni@users.noreply.github.com>

* Replaced duplicated current deposition documentation (ECP-WarpX#2604)

* Throwing a warning if particle_shape>1 with EB (ECP-WarpX#2592)

* Aborting if particle_shape!=1 with EB

* Throw warning instead of aborting

* Checking at runtime if EB is initialized

* Added missing preprocessor directive

* Ignoring an unused variable

* Fix typo

* Improve style

Co-authored-by: Axel Huebl <axel.huebl@plasma.ninja>

* Fix segfault when importing _libwarpx without initializing WarpX (ECP-WarpX#2580)

* Added check for if warpx was initialized when calling finalize

* Renamed to be warpx_initialized

* Fixed reference to global variable

Co-authored-by: Peter Scherpelz <31747262+peterscherpelz@users.noreply.github.com>

* Changed global variable to member of libwarpx

* Fixed syntax errors

* Remove custom arg from argv to avoid parmparse error

Co-authored-by: Peter Scherpelz <31747262+peterscherpelz@users.noreply.github.com>

* Added parallel pragma to ApplyBoundaryConditions (ECP-WarpX#2612)

* Note that CCache 4.2 introduced large CUDA improvements (ECP-WarpX#2606)

* Dimensionality Docs: Default (ECP-WarpX#2609)

Just adds the note that 3D is the default geometry.

* AMReX: Weekly Update (ECP-WarpX#2613)

* MergeBuffersForPlotfile: Barrier (ECP-WarpX#2608)

Make sure that all MPI ranks are in sync, i.e., have closed the
files that they wrote, before trying to merge them.

* Fix installation location for libraries (ECP-WarpX#2583)

During configuration the installation location for libraries is given by
dumping the cmake variable `CMAKE_INSTALL_LIBDIR`.
This commit adjusts the installation of WarpX libraries (WarpX_LIB=ON)
to respect this setting.

Co-authored-by: Rolf Pfeffertal <tropf@users.noreply.github.com>

* Release 21.12 (ECP-WarpX#2614)

* AMReX: 21.12

* PICSAR: 21.12

* WarpX: 21.12

* div(E,B) Cleaning Options for PSATD (ECP-WarpX#2403)

* Implement div(E)/div(B) Cleaning with Standard PSATD

* Cleaning

* Update Benchmark

* Add Nodal Synchronization of F,G

* OneStep_multiJ: Nodal Syncs, Damp PML

* OneStep_multiJ: Push PSATD Fields in PML

* div Cleaning Defaults (Domain v. PML)

* Include Fix of ECP-WarpX#2429 until Merged

* Reset Benchmark of Langmuir_multi_psatd_div_cleaning

* Multi-J: Remove PML Support

* Include Fix of ECP-WarpX#2474 Until Merged

* Exchange All Guard Cells for F,G

* Fix Defaults

* Update Test, Reset Benchmark

* Fix Defaults

* Cleaning

* Default update_with_rho=1 if do_dive_cleaning=1

* Update CI Test pml_psatd_dive_divb_cleaning

* Replace Warning with Abort

* Add 2D Langmuir Test w/ MR & PSATD (ECP-WarpX#2605)

* Add 2D Langmuir Test w/ MR & PSATD

* Add Missing Compile String

* Fix out-of-bound in Inverse FFT of F,G (ECP-WarpX#2619)

* Mention that the potentail should be constant inside EB (ECP-WarpX#2618)

* Mention that the potentail should be constant inside EB

* Update text

* Replace AMREX_SPACEDIM: Boundary & Parallelization (ECP-WarpX#2620)

* AMREX_SPACEDIM : Boundary Conditions
* AMREX_SPACEDIM : Parallelization
* Fix compilation
* Update Source/Parallelization/WarpXComm_K.H

* Fix out-of-bound in the initialization of EB (ECP-WarpX#2607)

* Call FillBoundary when initializing EB

* Avoid out-of-bound

* Bug fix

* Apply suggestions from code review

* update version number

Co-authored-by: Axel Huebl <axel.huebl@plasma.ninja>
Co-authored-by: Edoardo Zoni <59625522+EZoni@users.noreply.github.com>
Co-authored-by: Remi Lehe <remi.lehe@normalesup.org>
Co-authored-by: Lorenzo Giacomel <47607756+lgiacome@users.noreply.github.com>
Co-authored-by: Kevin Z. Zhu <86268612+KZhu-ME@users.noreply.github.com>
Co-authored-by: Peter Scherpelz <31747262+peterscherpelz@users.noreply.github.com>
Co-authored-by: David Grote <grote1@llnl.gov>
Co-authored-by: Phil Miller <phil@intensecomputing.com>
Co-authored-by: s9105947 <80697868+s9105947@users.noreply.github.com>
Co-authored-by: Rolf Pfeffertal <tropf@users.noreply.github.com>
Co-authored-by: Prabhat Kumar <89051199+prkkumar@users.noreply.github.com>

CMakeLists.txt

@@ -1,7 +1,7 @@
 # Preamble ####################################################################
 #
 cmake_minimum_required(VERSION 3.15.0)
-project(WarpX VERSION 21.11)
+project(WarpX VERSION 21.12)
 
 include(${WarpX_SOURCE_DIR}/cmake/WarpXFunctions.cmake)
 
@@ -345,7 +345,7 @@ if(WarpX_LIB)
     endif()
     install(CODE "file(CREATE_LINK
         $<TARGET_FILE_NAME:shared>
-        ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/libwarpx.${lib_suffix}.${mod_ext}
+        ${CMAKE_INSTALL_LIBDIR}/libwarpx.${lib_suffix}.${mod_ext}
         COPY_ON_ERROR SYMBOLIC)")
 endif()
 

CONTRIBUTING.rst

@@ -15,91 +15,127 @@ If you are new to git, you can follow one of these tutorials:
 - `Learn git with bitbucket <https://www.atlassian.com/git/tutorials/learn-git-with-bitbucket-cloud>`_
 - `git - the simple guide <http://rogerdudler.github.io/git-guide/>`_
 
-Make your own fork and create a branch on it
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configure your GitHub Account & Development Machine
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The basic WarpX workflow is:
+First, let's setup your Git environment and GitHub account.
 
-1. Fork the main repo (or update it if you already created it).
-2. Implement your changes and push them on a new branch ``<branch_name>`` on your fork.
-3. Create a Pull Request from branch ``<branch_name>`` on your fork to branch ``development`` on the main WarpX repo.
+1. Go to https://github.com/settings/profile and add your real name and affiliation
+2. Go to https://github.com/settings/emails and add & verify the professional e-mails you want to be associated with.
+3. Configure ``git`` on the machine you develop on to *use the same spelling of your name and email*:
 
-First, let us setup your local git repo. Make your own fork of the main (``upstream``) WarpX repo:
-on the `WarpX Github page <https://github.com/ECP-WarpX/WarpX>`_, press the fork button.
-Then, you can execute:
+   - ``git config --global user.name "FIRSTNAME LASTNAME"``
+   - ``git config --global user.email EMAIL@EXAMPLE.com``
+4. Go to https://github.com/settings/keys and add the SSH public key of the machine you develop on. (Check out the GitHub guide to `generating SSH keys <https://docs.github.com/articles/generating-an-ssh-key/>`__ or `troubleshoot common SSH problems <https://docs.github.com/ssh-issues/>`__. )
+
+Make your own fork
+^^^^^^^^^^^^^^^^^^
+
+First, fork the WarpX `"mainline" repo on GitHub <https://github.com/ECP-WarpX/WarpX>`__ by pressing the *Fork* button on the top right of the page.
+A fork is a copy of WarpX on GitHub, which is under your full control.
+
+Then, we create local copies, for development:
 
 .. code-block:: sh
 
-   # These 4 first lines are the same as for a standard WarpX install
-   mkdir warpx_directory
-   cd warpx_directory
-   git clone --branch development https://github.com/ECP-WarpX/picsar.git
-   git clone --branch development https://github.com/AMReX-Codes/amrex.git
+   # Clone the mainline WarpX source code to your local computer.
+   # You cannot write to this repository, but you can read from it.
+   git clone git@github.com:ECP-WarpX/WarpX.git
+   cd WarpX
+
+   # rename what we just cloned: call it "mainline"
+   git remote rename origin mainline
 
-   # Clone your fork on your local computer. You can get this address on your fork's Github page.
-   git clone https://github.com/<myGithubUsername>/WarpX.git
-   cd warpx
-   # Keep track of the main WarpX repo, to remain up-to-date.
-   git remote add upstream https://github.com/ECP-WarpX/WarpX.git
+   # Add your own fork. You can get this address on your fork's Github page.
+   # Here is where you will publish new developments, so that they can be
+   # reviewed and integrated into "mainline" later on.
+   # "myGithubUsername" needs to be replaced with your user name on GitHub.
+   git remote add myGithubUsername git@github.com:myGithubUsername/WarpX.git
 
 Now you are free to play with your fork (for additional information, you can visit the
-`Github fork help page <https://help.github.com/en/articles/fork-a-repo>`_).
+`Github fork help page <https://help.github.com/en/articles/fork-a-repo>`__).
 
 .. note::
 
-   You do not have to re-do the setup above every time.
-   Instead, in the future, all you need is to update the ``development`` branch on your fork with:
+   We only need to do the above steps for the first time.
 
-   .. code-block:: sh
+Let's Develop
+^^^^^^^^^^^^^
 
-      git checkout development
-      git pull upstream development
+You are all set!
+Now, the basic WarpX development workflow is:
 
-Make sure you are on WarpX ``development`` branch with
+1. Implement your changes and push them on a new branch ``branch_name`` on your fork.
+2. Create a Pull Request from branch ``branch_name`` on your fork to branch ``development`` on the main WarpX repo.
+
+Create a branch ``branch_name`` (the branch name should reflect the piece of code you want to add, like ``fix-spectral-solver``) with
 
 .. code-block:: sh
 
+   # start from an up-to-date development branch
    git checkout development
+   git pull mainline development
 
-in the WarpX directory.
+   # create a fresh branch
+   git checkout -b branch_name
 
-Create a branch ``<branch_name>`` (the branch name should reflect the piece of code you want to add, like ``fix_spectral_solver``) with
+and do the coding you want.
 
-.. code-block:: sh
+It is probably a good time to look at the `AMReX documentation <https://amrex-codes.github.io/amrex/docs_html/>`_ and at the Doxygen reference pages:
 
-   git checkout -b <branch_name>
+* WarpX Doxygen: https://warpx.readthedocs.io/en/latest/_static/doxyhtml
+* AMReX Doxygen: https://amrex-codes.github.io/amrex/doxygen
+* PICSAR Doxygen: (todo)
 
-and do the coding you want.
-It is probably a good time to look at the `AMReX documentation <https://amrex-codes.github.io/amrex/docs_html/>`_ and at the `AMReX Doxygen reference <https://ccse.lbl.gov/pub/AMReX_Docs/index.html>`_.
-Add the files you work on to the git staging area with
+Once you are done developing, add the files you created and/or modified to the ``git`` *staging area* with
 
 .. code-block:: sh
 
    git add <file_I_created> <and_file_I_modified>
 
+
+Build your changes
+^^^^^^^^^^^^^^^^^^
+
+If you changed C++ files, then now is a good time to test those changes by compiling WarpX locally.
+Follow the `developer instructions in our manual <https://warpx.readthedocs.io/en/latest/install/cmake.html>`__ to set up a local development environment, then compile and `run <https://warpx.readthedocs.io/en/latest/usage/how_to_run.html>`__ WarpX.
+
+
 Commit & push your changes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Periodically commit your changes with
 
 .. code-block:: sh
 
-   git commit -m "This is a 50-char description to explain my work"
+   git commit
+
+The commit message (between quotation marks) is super important in order to follow the developments during code-review and identify bugs.
+A typical format is:
+
+.. code-block::
+
+   This is a short, 40-character title
+
+   After a newline, you can write arbitray paragraphs. You
+   usually limit the lines to 70 characters, but if you don't, then
+   nothing bad will happen.
 
-The commit message (between quotation marks) is super important in order to follow the developments and identify bugs.
+   The most important part is really that you find a descriptive title
+   and add an empty newline after it.
 
 For the moment, commits are on your local repo only.
 You can push them to your fork with
 
 .. code-block:: sh
 
-   git push -u origin <branch_name>
+   git push -u myGithubUsername branch_name
 
-If you want to synchronize your branch with the ``development`` branch (this is useful when the ``development`` branch is being modified while you are working on ``<branch_name>``), you can use
+If you want to synchronize your branch with the ``development`` branch (this is useful when the ``development`` branch is being modified while you are working on ``branch_name``), you can use
 
 .. code-block:: sh
 
-   git pull upstream development
+   git pull mainline development
 
 and fix any conflict that may occur.
 
@@ -120,8 +156,8 @@ Right after you push changes, a banner should appear on the Github page of your
 - Press ``Create pull request``.
   Now you can navigate through your PR, which highlights the changes you made.
 
-Please DO NOT write large Pull Requests, as they are very difficult and time-consuming to review.
-As much as possible, split them into small targeted PRs.
+Please DO NOT write large pull requests, as they are very difficult and time-consuming to review.
+As much as possible, split them into small, targeted PRs.
 For example, if find typos in the documentation open a pull request that only fixes typos.
 If you want to fix a bug, make a small pull request that only fixes a bug.
 
@@ -131,7 +167,6 @@ Submit tests, documentation changes and implementation of a feature together for
 
 Even before your work is ready to merge, it can be convenient to create a PR (so you can use Github tools to visualize your changes).
 In this case, please put the ``[WIP]`` tag (for Work-In-Progress) at the beginning of the PR title.
-Another tag you may want to use is ``[mini]``, if your changes are very few lines and quick to review.
 You can also use the GitHub project tab in your fork to organize the work into separate tasks/PRs and share it with the WarpX community to get feedback.
 
 Include a test to your PR
@@ -146,7 +181,7 @@ Include documentation about your PR
 """""""""""""""""""""""""""""""""""
 
 Now, let users know about your new feature by describing its usage in the `WarpX documentation <https://warpx.readthedocs.io>`_.
-Our documentation uses `Sphinx <http://www.sphinx-doc.org/en/master/usage/quickstart.html>`_, and it is located in ``Docs/``.
+Our documentation uses `Sphinx <http://www.sphinx-doc.org/en/master/usage/quickstart.html>`_, and it is located in ``Docs/source/``.
 For instance, if you introduce a new runtime parameter in the input file, you can add it to :ref:`Docs/source/running_cpp/parameters.rst <running-cpp-parameters>`.
 If Sphinx is installed on your computer, you should be able to generate the html documentation with
 

Docs/source/conf.py

@@ -66,9 +66,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'21.11'
+version = u'21.12'
 # The full version, including alpha/beta/rc tags.
-release = u'21.11'
+release = u'21.12'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

Docs/source/developers/dimensionality.rst

@@ -8,14 +8,14 @@ This section describes the handling of dimensionality in WarpX.
 Build Options
 -------------
 
-==========  ===================
+==========  ==========================
 Dimensions  CMake Option
-==========  ===================
-**3D3V**    ``WarpX_DIMS=3``
+==========  ==========================
+**3D3V**    ``WarpX_DIMS=3`` (default)
 **2D3V**    ``WarpX_DIMS=2``
 **1D3V**    ``WarpX_DIMS=1``
 **RZ**      ``WarpX_DIMS=RZ``
-==========  ===================
+==========  ==========================
 
 See :ref:`building from source <install-developers>` for further details.
 

Docs/source/install/dependencies.rst

@@ -23,7 +23,7 @@ Optional dependencies include:
 - `openPMD-api 0.14.2+ <https://github.com/openPMD/openPMD-api>`__: we automatically download and compile a copy of openPMD-api for openPMD I/O support
 
   - see `optional I/O backends <https://github.com/openPMD/openPMD-api#dependencies>`__
-- `CCache <https://ccache.dev>`__: to speed up rebuilds (needs 3.7.9+ for CUDA)
+- `CCache <https://ccache.dev>`__: to speed up rebuilds (For CUDA support, needs version 3.7.9+ and 4.2+ is recommended)
 - `Ninja <https://ninja-build.org>`__: for faster parallel compiles
 
 

Docs/source/theory/picsar_theory.rst

@@ -472,74 +472,38 @@ Note that in 2D Cartesian geometry, :math:`D_y` is effectively :math:`J_y` and d
 Field gather
 ------------
 
-The current densities are deposited on the computational grid from
-the particle position and velocities, employing splines of various
-orders (Abe et al. 1986).
-
-.. math::
-
-   \begin{aligned}
-   \rho & = & \frac{1}{\Delta x \Delta y \Delta z}\sum_nq_nS_n\\
-   \mathbf{J} & = & \frac{1}{\Delta x \Delta y \Delta z}\sum_nq_n\mathbf{v_n}S_n\end{aligned}
-
-In most applications, it is essential to prevent the accumulation
-of errors resulting from the violation of the discretized Gauss’ Law.
-This is accomplished by providing a method for depositing the current
-from the particles to the grid that preserves the discretized Gauss’
-Law, or by providing a mechanism for “divergence cleaning” (Birdsall and Langdon 1991; Langdon 1992; Marder 1987; Vay and Deutsch 1998; Munz et al. 2000).
-For the former, schemes that allow a deposition of the current that
-is exact when combined with the Yee solver is given in (Villasenor and Buneman 1992)
-for linear splines and in (Esirkepov 2001) for splines of arbitrary order.
-
-The NSFDTD formulations given above and in (Pukhov 1999; Vay et al. 2011; Cowan et al. 2013; Lehe et al. 2013)
-apply to the Maxwell-Faraday
-equation, while the discretized Maxwell-Ampere equation uses the FDTD
-formulation. Consequently, the charge conserving algorithms developed
-for current deposition (Villasenor and Buneman 1992; Esirkepov 2001) apply
-readily to those NSFDTD-based formulations. More details concerning
-those implementations, including the expressions for the numerical
-dispersion and Courant condition are given
-in (Pukhov 1999; Vay et al. 2011; Cowan et al. 2013; Lehe et al. 2013).
-
-In the case of the pseudospectral solvers, the current deposition
-algorithm generally does not satisfy the discretized continuity equation
-in Fourier space :math:`\tilde{\rho}^{n+1}=\tilde{\rho}^{n}-i\Delta t\mathbf{k}\cdot\mathbf{\tilde{J}}^{n+1/2}`.
-In this case, a Boris correction (Birdsall and Langdon 1991) can be applied
-in :math:`k` space in the form :math:`\mathbf{\tilde{E}}_{c}^{n+1}=\mathbf{\tilde{E}}^{n+1}-\left(\mathbf{k}\cdot\mathbf{\tilde{E}}^{n+1}+i\tilde{\rho}^{n+1}\right)\mathbf{\hat{k}}/k`,
-where :math:`\mathbf{\tilde{E}}_{c}` is the corrected field. Alternatively, a correction
-to the current can be applied (with some similarity to the current
-deposition presented by Morse and Nielson in their potential-based
-model in (Morse and Nielson 1971)) using :math:`\mathbf{\tilde{J}}_{c}^{n+1/2}=\mathbf{\tilde{J}}^{n+1/2}-\left[\mathbf{k}\cdot\mathbf{\tilde{J}}^{n+1/2}-i\left(\tilde{\rho}^{n+1}-\tilde{\rho}^{n}\right)/\Delta t\right]\mathbf{\hat{k}}/k`,
-where :math:`\mathbf{\tilde{J}}_{c}` is the corrected current. In this case, the transverse
-component of the current is left untouched while the longitudinal
-component is effectively replaced by the one obtained from integration
-of the continuity equation, ensuring that the corrected current satisfies
-the continuity equation. The advantage of correcting the current rather than
-the electric field is that it is more local and thus more compatible with
-domain decomposition of the fields for parallel computation (Jean Luc Vay, Haber, and Godfrey 2013).
-
-Alternatively, an exact current deposition can be written for the pseudospectral solvers, following the geometrical interpretation of existing methods in real space (Morse and Nielson 1971; Villasenor and Buneman 1992; Esirkepov 2001), thereby averaging the currents of the paths following grid lines between positions :math:`(x^n,y^n)` and :math:`(x^{n+1},y^{n+1})`, which is given in 2D (extension to 3D follows readily) for :math:`k\neq0` by (Jean Luc Vay, Haber, and Godfrey 2013):
-
-.. math::
-
-   \begin{aligned}
-   \mathbf{\tilde{J}}^{k\neq0}=\frac{i\mathbf{\tilde{D}}}{\mathbf{k}}
-   \label{Eq_Jdep_1}\end{aligned}
-
-with
-
-.. math::
-
-   \begin{aligned}
-   D_x   =  \frac{1}{2\Delta t}\sum_i q_i
-     [\Gamma(x_i^{n+1},y_i^{n+1})-\Gamma(x_i^{n},y_i^{n+1}) \nonumber\\
-   +\Gamma(x_i^{n+1},y_i^{n})-\Gamma(x_i^{n},y_i^{n})],\\
-   D_y   =  \frac{1}{2\Delta t}\sum_i q_i
-     [\Gamma(x_i^{n+1},y_i^{n+1})-\Gamma(x_i^{n+1},y_i^{n}) \nonumber \\
-   +\Gamma(x_i^{n},y_i^{n+1})-\Gamma(x_i^{n},y_i^{n})],\end{aligned}
-
-where :math:`\Gamma` is the macro-particle form factor.
-The contributions for :math:`k=0` are integrated directly in real space (Jean Luc Vay, Haber, and Godfrey 2013).
+In general, the field is gathered from the mesh onto the macroparticles
+using splines of the same order as for the current deposition :math:`\mathbf{S}=\left(S_{x},S_{y},S_{z}\right)`.
+Three variations are considered:
+
+-  “momentum conserving”: fields are interpolated from the grid nodes
+   to the macroparticles using :math:`\mathbf{S}=\left(S_{nx},S_{ny},S_{nz}\right)`
+   for all field components (if the fields are known at staggered positions,
+   they are first interpolated to the nodes on an auxiliary grid),
+
+-  “energy conserving (or Galerkin)”: fields are interpolated from
+   the staggered Yee grid to the macroparticles using :math:`\left(S_{nx-1},S_{ny},S_{nz}\right)`
+   for :math:`E_{x}`, :math:`\left(S_{nx},S_{ny-1},S_{nz}\right)` for :math:`E_{y}`,
+   :math:`\left(S_{nx},S_{ny},S_{nz-1}\right)` for :math:`E_{z}`, :math:`\left(S_{nx},S_{ny-1},S_{nz-1}\right)`
+   for :math:`B_{x}`, :math:`\left(S_{nx-1},S_{ny},S_{nz-1}\right)` for :math:`B{}_{y}`
+   and\ :math:`\left(S_{nx-1},S_{ny-1},S_{nz}\right)` for :math:`B_{z}` (if the fields
+   are known at the nodes, they are first interpolated to the staggered
+   positions on an auxiliary grid),
+
+-  “uniform”: fields are interpolated directly form the Yee grid
+   to the macroparticles using :math:`\mathbf{S}=\left(S_{nx},S_{ny},S_{nz}\right)`
+   for all field components (if the fields are known at the nodes, they
+   are first interpolated to the staggered positions on an auxiliary
+   grid).
+
+As shown in :raw-latex:`\cite{BirdsallLangdon,HockneyEastwoodBook,LewisJCP1972}`,
+the momentum and energy conserving schemes conserve momentum and energy
+respectively at the limit of infinitesimal time steps and generally
+offer better conservation of the respective quantities for a finite
+time step. The uniform scheme does not conserve momentum nor energy
+in the sense defined for the others but is given for completeness,
+as it has been shown to offer some interesting properties in the modeling
+of relativistically drifting plasmas :raw-latex:`\cite{GodfreyJCP2013}`.
 
 .. _theory-pic-filter:
 

Docs/source/usage/parameters.rst

@@ -318,7 +318,9 @@ Embedded Boundary Conditions
 * ``warpx.eb_potential(x,y,z,t)`` (`string`)
     Only used when ``warpx.do_electrostatic=labframe``. Gives the value of
     the electric potential at the surface of the embedded boundary,
-    as a function of  `x`, `y`, `z` and time.
+    as a function of  `x`, `y`, `z` and time. This function is also evaluated
+    inside the embedded boundary. For this reason, it is important to define
+    this function in such a way that it is constant inside the embedded boundary.
 
 .. _running-cpp-parameters-parallelization: