requested changes as well as updates to the magnetic reconnection exa…

…mple README
roelof-groenewald · Dec 7, 2023 · b70afee · b70afee
1 parent 545c511
commit b70afee
Show file tree

Hide file tree

Showing 5 changed files with 35 additions and 27 deletions.
diff --git a/Docs/source/usage/examples.rst b/Docs/source/usage/examples.rst
@@ -113,9 +113,16 @@ Coming soon:
 Kinetic-fluid Hybrid Models
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Several examples and benchmarks of the kinetic-fluid hybrid model are provided below.
-A few examples are replications of the verification tests described in :cite:t:`ex-MUNOZ2018`.
-The hybrid-PIC model was added to WarpX in `PR #3665 <https://github.com/ECP-WarpX/WarpX/pull/3665>`_ - the figures in the examples below were generated at that time.
+WarpX includes a reduced plasma model in which electrons are treated as a massless
+fluid while ions are kinetically evolved, and Ohm's law is used to calculate
+the electric field. This model is appropriate for problems in which ion kinetics
+dominate (ion cyclotron waves, for instance). See the
+:ref:`theory section <theory-kinetic-fluid-hybrid-model>` for more details. Several
+examples and benchmarks of this kinetic-fluid hybrid model are provided below.
+A few of the examples are replications of the verification tests described in
+:cite:t:`ex-MUNOZ2018`. The hybrid-PIC model was added to WarpX in
+`PR #3665 <https://github.com/ECP-WarpX/WarpX/pull/3665>`_ - the figures in the
+examples below were generated at that time.
 
 .. toctree::
    :maxdepth: 1

diff --git a/Examples/Tests/ohm_solver_EM_modes/README.rst b/Examples/Tests/ohm_solver_EM_modes/README.rst
@@ -1,7 +1,7 @@
 .. _examples-ohm-solver-em-modes:
 
-Electromagnetic modes
-=====================
+Ohm solver: Electromagnetic modes
+=================================
 
 In this example a simulation is seeded with a thermal plasma while an initial magnetic field is applied in either the
 :math:`z` or :math:`x` direction. The simulation is progressed for a large number of steps and the resulting fields are
@@ -69,8 +69,8 @@ Perpendicularly propagating modes are also supported, commonly referred to as io
 
    Calculated ion Bernstein waves spectrum with the theoretical dispersion overlaid.
 
-Cylindrical normal modes
-========================
+Ohm solver: Cylindrical normal modes
+====================================
 
 A RZ-geometry example case for normal modes propagating along an applied magnetic
 field in a cylinder is also available. The analytical solution for these modes

diff --git a/Examples/Tests/ohm_solver_ion_Landau_damping/README.rst b/Examples/Tests/ohm_solver_ion_Landau_damping/README.rst
@@ -1,7 +1,7 @@
 .. _examples-ohm-solver-ion-landau-damping:
 
-Ion Landau Damping
-==================
+Ohm solver: Ion Landau Damping
+==============================
 
 Landau damping is a well known process in which electrostatic (acoustic) waves are
 damped by transferring energy to particles satisfying a resonance condition.

diff --git a/Examples/Tests/ohm_solver_ion_beam_instability/README.rst b/Examples/Tests/ohm_solver_ion_beam_instability/README.rst
@@ -1,7 +1,7 @@
 .. _examples-ohm-solver-ion-beam-instability:
 
-Ion Beam R Instability
-======================
+Ohm solver: Ion Beam R Instability
+==================================
 
 In this example a low density ion beam interacts with a "core" plasma population which induces an instability.
 Based on the relative density between the beam and the core plasma a resonant or non-resonant condition can

diff --git a/Examples/Tests/ohm_solver_magnetic_reconnection/README.rst b/Examples/Tests/ohm_solver_magnetic_reconnection/README.rst
@@ -4,32 +4,33 @@ Ohm Solver: Magnetic Reconnection
 =================================
 
 Hybrid-PIC codes are often used to simulate magnetic reconnection in space plasmas.
-An example of magnetic reconnection from a force-free sheet is provided, based on the simulation described in :cite:t:`ex-Le2016`.
+An example of magnetic reconnection from a force-free sheet is provided, based on
+the simulation described in :cite:t:`ex-Le2016`.
 
 Run
 ---
 
-This example can be run as a **Python** script: ``python3 PICMI_inputs.py``.
+The following **Python** script configures and launches the simulation.
 
-.. literalinclude:: PICMI_inputs.py
-   :language: python3
-   :caption: You can copy this file from ``Examples/Tests/ohm_solver_magnetic_reconnection/PICMI_inputs.py``.
+.. dropdown:: Script ``PICMI_inputs.py``
 
+   .. literalinclude:: PICMI_inputs.py
+      :language: python3
+      :caption: You can copy this file from ``Examples/Tests/ohm_solver_magnetic_reconnection/PICMI_inputs.py``.
 
-Analyze
--------
-
-We run the following script to analyze correctness:
-
-.. note::
+Running the full simulation should take about 4 hours if executed on 1 V100 GPU.
+For `MPI-parallel <https://www.mpi-forum.org>`__ runs, prefix these lines with
+``mpiexec -n 4 ...`` or ``srun -n 4 ...``, depending on the system.
 
-   This section is TODO.
+   .. code-block:: bash
 
+      python3 PICMI_inputs.py
 
-Visualize
----------
+Analyze
+-------
 
-You can run the following script to visualize the B-field evolution over time:
+The following script extracts the reconnection rate as a function of time and
+animates the evolution of the magnetic field (as shown below).
 
 .. dropdown:: Script ``analysis.py``
 
@@ -41,4 +42,4 @@ You can run the following script to visualize the B-field evolution over time:
    :alt: Magnetic reconnection.
    :width: 70%
 
-   Magnetic reconnection.
+   Magnetic reconnection from a force-free sheet.