Skip to content

Commit

Permalink
Sphinx: Clean Warnings/Formatting (ECP-WarpX#2758)
Browse files Browse the repository at this point in the history
* Sphinx: Clean Warnings/Formatting

Remove formatting errors in Sphinx that caused warnings/ill-formed
formatting.

* Move `boundary.reflect_all_velocities`

Co-authored-by: Neïl Zaim <49716072+NeilZaim@users.noreply.github.com>

* Fix: character after verbatim

Not allowed and does render broken.

* Fix broken `.. directive::`

Co-authored-by: Neïl Zaim <49716072+NeilZaim@users.noreply.github.com>
ax3l and NeilZaim authored Jan 20, 2022
1 parent aa531aa commit cd3488e
Showing 6 changed files with 24 additions and 20 deletions.
8 changes: 8 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
@@ -33,6 +33,14 @@ repos:
# - id: fix-encoding-pragma
# exclude: ^noxfile.py$

# documentation files: .rst
- repo: https://github.com/pre-commit/pygrep-hooks
rev: v1.9.0
hooks:
# - id: rst-backticks
- id: rst-directive-colons
- id: rst-inline-touching-normal

#- repo: https://github.com/asottile/pyupgrade
# rev: v2.29.0
# hooks:
2 changes: 1 addition & 1 deletion CONTRIBUTING.rst
Original file line number Diff line number Diff line change
@@ -113,7 +113,7 @@ Periodically commit your changes with
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::
.. code-block:: text
This is a short, 40-character title
8 changes: 1 addition & 7 deletions Docs/source/developers/fields.rst
Original file line number Diff line number Diff line change
@@ -96,8 +96,6 @@ This is mostly implemented in ``Source/Parallelization``, see the following func

.. doxygenfunction:: WarpX::SyncCurrent

.. doxygenfunction:: interpolateCurrentFineToCoarse

.. doxygenfunction:: WarpX::RestrictCurrentFromFineToCoarsePatch

.. doxygenfunction:: WarpX::AddCurrentFromFineLevelandSumBoundary
@@ -112,11 +110,7 @@ General functions for filtering can be found in ``Source/Filter/``, where the ma
Bilinear filter
~~~~~~~~~~~~~~~

The multi-pass bilinear filter (applied on the current density) is implemented in ``Source/Filter/``, and class ``WarpX`` holds an instance of this class in member variable ``WarpX::bilinear_filter``. For performance reasons (to avoid creating too many guard cells), this filter is directly applied in communication routines, see

.. doxygenfunction:: WarpX::AddCurrentFromFineLevelandSumBoundary

and
The multi-pass bilinear filter (applied on the current density) is implemented in ``Source/Filter/``, and class ``WarpX`` holds an instance of this class in member variable ``WarpX::bilinear_filter``. For performance reasons (to avoid creating too many guard cells), this filter is directly applied in communication routines, see ``WarpX::AddCurrentFromFineLevelandSumBoundary`` above and

.. doxygenfunction:: WarpX::ApplyFilterandSumBoundaryJ

21 changes: 11 additions & 10 deletions Docs/source/usage/parameters.rst
Original file line number Diff line number Diff line change
@@ -4,6 +4,7 @@ Input Parameters
================

.. note::

The AMReX parser (see :ref:`running-cpp-parameters-parser`) is used for the right-hand-side of all input parameters that consist of one or more integers or floats, so expressions like ``<species_name>.density_max = "2.+1."`` and/or using user-defined constants are accepted.

.. _running-cpp-parameters-overall:
@@ -255,14 +256,14 @@ Domain Boundary Conditions
* ``Periodic``: This option can be used to set periodic domain boundaries. Note that if the fields for lo in a certain dimension are set to periodic, then the corresponding upper boundary must also be set to periodic. If particle boundaries are not specified in the input file, then particles boundaries by default will be set to periodic. If particles boundaries are specified, then they must be set to periodic corresponding to the periodic field boundaries.

* ``pml`` (default): This option can be used to add Perfectly Matched Layers (PML) around the simulation domain. See the :ref:`PML theory section <theory-bc>` for more details.
Additional pml algorithms can be explored using the parameters ``warpx.do_pml_in_domain``, ``warpx.do_particles_in_pml``, and ``warpx.do_pml_j_damping``.
Additional pml algorithms can be explored using the parameters ``warpx.do_pml_in_domain``, ``warpx.do_particles_in_pml``, and ``warpx.do_pml_j_damping``.

* ``absorbing_silver_mueller``: This option can be used to set the Silver-Mueller absorbing boundary conditions. These boundary conditions are simpler and less computationally expensive than the pml, but are also less effective at absorbing the field. They only work with the Yee Maxwell solver.

* ``damped``: This is the recommended option in the moving direction when using the spectral solver with moving window (currently only supported along z). This boundary condition applies a damping factor to the electric and magnetic fields in the outer half of the guard cells, using a sine squared profile. As the spectral solver is by nature periodic, the damping prevents fields from wrapping around to the other end of the domain when the periodicity is not desired. This boundary condition is only valid when using the spectral solver.

* ``pec``: This option can be used to set a Perfect Electric Conductor at the simulation boundary. For the electromagnetic solve, at PEC, the tangential electric field and the normal magnetic field are set to 0. This boundary can be used to model a dielectric or metallic surface. In the guard-cell region, the tangential electric field is set equal and opposite to the respective field component in the mirror location across the PEC boundary, and the normal electric field is set equal to the field component in the mirror location in the domain across the PEC boundary. Similarly, the tangential (and normal) magnetic field components are set equal (and opposite) to the respective magnetic field components in the mirror locations across the PEC boundary. Note that PEC boundary is invalid at `r=0` for the RZ solver. Please use ``none`` option. This boundary condition does not work with the spectral solver.
If an electrostatic field solve is used the boundary potentials can also be set through ``boundary.potential_lo_x/y/z`` and ``boundary.potential_hi_x/y/z`` (default `0`).
If an electrostatic field solve is used the boundary potentials can also be set through ``boundary.potential_lo_x/y/z`` and ``boundary.potential_hi_x/y/z`` (default `0`).

* ``none``: No boundary condition is applied to the fields with the electromagnetic solver. This option must be used for the RZ-solver at `r=0`. If the electrostatic solver is used, a Neumann boundary condition (with gradient equal to 0) will be applied on the specified boundary.

@@ -272,10 +273,10 @@ If an electrostatic field solve is used the boundary potentials can also be set

* ``Periodic``: Particles leaving the boundary will re-enter from the opposite boundary. The field boundary condition must be consistenly set to periodic and both lower and upper boundaries must be periodic.

* ``Reflecting``: Particles leaving the boundary are reflected from the boundary back into the domain. When
``boundary.reflect_all_velocities`` is false, the sign of only the normal velocity is changed, otherwise the sign of all velocities are changed.
* ``Reflecting``: Particles leaving the boundary are reflected from the boundary back into the domain.
When ``boundary.reflect_all_velocities`` is false, the sign of only the normal velocity is changed, otherwise the sign of all velocities are changed.

* ``boundary.reflect_all_velocities`` (`bool`) optional (default `false`)
* ``boundary.reflect_all_velocities`` (`bool`) optional (default `false`)
For a reflecting boundary condition, this flags whether the sign of only the normal velocity is changed or all velocities.


@@ -452,7 +453,7 @@ It can be used in all input parameters that consist of one or more integers or f
Integer input expecting boolean, 0 or 1, are not parsed.
Note that when multiple values are expected, the expressions are space delimited.
For integer input values, the expressions are evaluated as real numbers and the final result rounded to the nearest integer.
See `this section <https://amrex-codes.github.io/amrex/docs_html/Basics.html#parser>`_ of the AMReX documentation for a complete list of functions supported by the math parser.
See `this section <https://amrex-codes.github.io/amrex/docs_html/Basics.html#parser>`__ of the AMReX documentation for a complete list of functions supported by the math parser.

WarpX constants
^^^^^^^^^^^^^^^
@@ -592,8 +593,8 @@ Particle initialization
``<species_name>.charge`` (`double`) optional (default is read from openPMD file) when set this will be the charge of the physical particle represented by the injected macroparticles.
``<species_name>.mass`` (`double`) optional (default is read from openPMD file) when set this will be the charge of the physical particle represented by the injected macroparticles.
``<species_name>.z_shift`` (`double`) optional (default is no shift) when set this value will be added to the longitudinal, ``z``, position of the particles.
The external file must include the species ``openPMD::Record``s labeled ``position`` and ``momentum`` (`double` arrays), with dimensionality and units set via ``openPMD::setUnitDimension`` and ``setUnitSI``.
If the external file also contains ``openPMD::Records``s for ``mass`` and ``charge`` (constant `double` scalars) then the species will use these, unless overwritten in the input file (see ``<species_name>.mass``, ```<species_name>.charge`` or ```<species_name>.species_type``).
The external file must include the species ``openPMD::Record`` labeled ``position`` and ``momentum`` (`double` arrays), with dimensionality and units set via ``openPMD::setUnitDimension`` and ``setUnitSI``.
If the external file also contains ``openPMD::Records`` for ``mass`` and ``charge`` (constant `double` scalars) then the species will use these, unless overwritten in the input file (see ``<species_name>.mass``, ```<species_name>.charge`` or ```<species_name>.species_type``).
The ``external_file`` option is currently implemented for 2D, 3D and RZ geometries, with record components in the cartesian coordinates ``(x,y,z)`` for 3D and RZ, and ``(x,z)`` for 2D.
For more information on the `openPMD format <https://github.com/openPMD>`__ and how to build WarpX with it, please visit :ref:`the install section <install-developers>`.

@@ -1827,7 +1828,7 @@ In-situ capabilities can be used by turning on Sensei or Ascent (provided they a

A typical example for `ADIOS2 output using lossless compression <https://openpmd-api.readthedocs.io/en/0.14.0/details/backendconfig.html#adios2>`__ with ``blosc`` using the ``zstd`` compressor and 6 CPU treads per MPI Rank (e.g. for a `GPU run with spare CPU resources <https://arxiv.org/abs/1706.00522>`__):

.. code-block::
.. code-block:: text
<diag_name>.adios2_operator.type = blosc
<diag_name>.adios2_operator.parameters.compressor = zstd
@@ -1838,7 +1839,7 @@ In-situ capabilities can be used by turning on Sensei or Ascent (provided they a
or for the lossy ZFP compressor using very strong compression per scalar:

.. code-block::
.. code-block:: text
<diag_name>.adios2_operator.type = zfp
<diag_name>.adios2_operator.parameters.precision = 3
2 changes: 1 addition & 1 deletion Docs/source/usage/workflows/debugging.rst
Original file line number Diff line number Diff line change
@@ -27,7 +27,7 @@ Try the following steps to debug a simulation:
#. If the problem looks like a memory violation, this could be from an invalid field or particle index access.
Try compiling with ``-DAMReX_BOUND_CHECK=ON`` (this will make the simulation very slow), and rerun.
#. If the problem looks like a random memory might be used, try initializing memory with signaling Not-a-Number (NaN) values through the runtime option ``fab.init_snan = 1``.
Further useful runtime options are ``amrex.fpe_trap_invalid``, ``amrex.fpe_trap_zero`` and ``amrex.fpe_trap_overflow`` (see details in the AMReX link below).
Further useful runtime options are ``amrex.fpe_trap_invalid``, ``amrex.fpe_trap_zero`` and ``amrex.fpe_trap_overflow`` (see details in the AMReX link below).
#. On Nvidia GPUs, if you suspect the problem might be a race condition due to a missing host / device synchronization, set the environment variable ``export CUDA_LAUNCH_BLOCKING=1`` and rerun.
#. Consider simplifying your input options and re-adding more options after having found a working baseline.

3 changes: 2 additions & 1 deletion Docs/source/usage/workflows/profiling.rst
Original file line number Diff line number Diff line change
@@ -31,5 +31,6 @@ Each set of two timers show the exclusive, top, and inclusive, bottom, informati

For more detailed information please visit the `AMReX profiling documentation <https://amrex-codes.github.io/amrex/docs_html/AMReX_Profiling_Tools_Chapter.html>`__.

.. note:
.. note::

When creating performance-related issues on the WarpX GitHub repo, please include Tiny Profiler tables (besides the usual issue description, input file and submission script), or (even better) the whole standard output.

0 comments on commit cd3488e

Please sign in to comment.