4 files changed, 58 insertions, 47 deletions
diff --git a/Docs/source/running_python/examples.rst b/Docs/source/running_python/examples.rst
index 851d2e52f..4104bcf78 100644
--- a/Docs/source/running_python/examples.rst
+++ b/Docs/source/running_python/examples.rst
@@ -1,16 +1,27 @@
 Example input files
 ===================
 
-This section allows you to **download Python scripts** that correspond to different
-physical situations.
+WarpX includes several example Python input files corresponding to various physical situations.
+These can be downloaded here (or obtained from the WarpX source).
 
 Beam-driven acceleration
 ------------------------
 
-* :download:`Without mesh refinement<../../../Examples/Physics_applications/plasma_acceleration/plasma_acceleration_PICMI.py>`
-* :download:`With mesh refinement<../../../Examples/Physics_applications/plasma_acceleration/plasma_acceleration_PICMI.mr.py>`
+* :download:`Without mesh refinement<../../../Examples/Physics_applications/plasma_acceleration/PICMI_inputs_plasma_acceleration.py>`
+* :download:`With mesh refinement<../../../Examples/Physics_applications/plasma_acceleration/PICMI_inputs_plasma_acceleration_mr.py>`
 
 Laser-driven acceleration
 -------------------------
 
-* :download:`Without mesh refinement<../../../Examples/Physics_applications/laser_acceleration/laser_acceleration_PICMI.py>`
+* :download:`Without mesh refinement<../../../Examples/Physics_applications/laser_acceleration/PICMI_inputs_laser_acceleration.py>`
+
+Test cases
+----------
+
+There are also several test cases included that can be used for reference.
+
+* :download:`Gaussian beam<../../../Examples//Modules/gaussian_beam/PICMI_inputs_gaussian_beam.py>`
+* :download:`Langmuir plasma wave test in 3d<../../../Examples//Tests/Langmuir/PICMI_inputs_langmuir_rt.py>`
+* :download:`Langmuir plasma wave test in RZ<../../../Examples//Tests/Langmuir/PICMI_inputs_langmuir_rz_multimode_analyze.py>`
+* :download:`Langmuir plasma wave test in 2D<../../../Examples//Tests/Langmuir/PICMI_inputs_langmuir2d.py>`
+
diff --git a/Docs/source/running_python/how_to_run.rst b/Docs/source/running_python/how_to_run.rst
index 390abb8c2..870db91a3 100644
--- a/Docs/source/running_python/how_to_run.rst
+++ b/Docs/source/running_python/how_to_run.rst
@@ -1,8 +1,21 @@
-How to run a new simulation
+Using WarpX with Python
 ===========================
 
-After installing WarpX as a Python package, you can use its functionalities in a Python script
-to run a simulation.
+WarpX uses the PICMI standard for its Python input files.
+See `PICMI information and source code <https://github.com/picmi-standard/picmi>`__.
+
+WarpX can be run in one of two modes. It can run as a preprocessor, using the
+Python input file to generate an input file to be used by the C++ version, or
+it can be run directly from Python.
+
+Example input files can be found in the section :doc:`examples`.
+The examples support running in both modes by commenting and uncommenting the appropriate lines.
+
+
+Using Python input as a preprocessor
+------------------------------------
+
+In this case, only the pure Python version needs to be installed, as described in :doc:`../building/python.rst`.
 
 In order to run a new simulation:
 
@@ -10,9 +23,31 @@ In order to run a new simulation:
 
 * Add a **Python script** in the directory.
 
-This file contains the numerical and physical parameters that define
-the situation to be simulated.
-Example input files can be found in the section :doc:`examples`.
+The input file should have the line like "sim.write_input_file(file_name = 'inputs_from_PICMI')"
+which runs the preprocessor, generating the C++ input file.
+
+* **Run** the script with Python:
+
+::
+
+    python <python_script>
+
+where ``<python_script>`` is the name of the script.
+This creates the WarpX input file that you can run as normal with the WarpX executable.
+
+
+Running WarpX directly from Python
+----------------------------------
+
+For this, a full Python installation of WarpX is required, as described in :doc:`../building/python.rst`.
+
+In order to run a new simulation:
+
+* Create a **new directory**, where the simulation will be run.
+
+* Add a **Python script** in the directory.
+
+The input file should have the line "sim.step()" which runs the simulation.
 
 * **Run** the script with Python:
 
@@ -22,3 +57,4 @@ Example input files can be found in the section :doc:`examples`.
 
 where ``<n_ranks>`` is the number of MPI ranks used, and ``<python_script>``
 is the name of the script.
+
diff --git a/Docs/source/running_python/running_picmi.rst b/Docs/source/running_python/running_picmi.rst
deleted file mode 100644
index 509122f2e..000000000
--- a/Docs/source/running_python/running_picmi.rst
+++ /dev/null
@@ -1,35 +0,0 @@
-Running WarpX from PICMI
-========================
-
-See `PICMI information and source code <https://github.com/picmi-standard/picmi>`__.
-
-Generate WarpX input from PICMI python script
----------------------------------------------
-
-You can **install** the PICMI standard via, for example:
-
-::
-
-    pip install picmistandard
-
-For other options, please visit link above.
-
-To install the WarpX implementation of PICMI go to the WarpX directory and do:
-
-::
-
-    cd Python
-    python setup.py install
-
-Then you can **run**, for example, the :download:`Example PICMI input script for laser-plasma acceleration <../../../Examples/Physics_applications/laser_acceleration/PICMI_inputs_laser_acceleration.py>` with
-
-::
-
-    python PICMI_inputs_laser_acceleration.py
-
-to create the WarpX input file that you can run with the WarpX executable.
-
-Running WarpX with python binding form PICMI
---------------------------------------------
-
-This option is not (yet) supported.
diff --git a/Docs/source/running_python/running_python.rst b/Docs/source/running_python/running_python.rst
index fc065cedc..cf960d431 100644
--- a/Docs/source/running_python/running_python.rst
+++ b/Docs/source/running_python/running_python.rst
@@ -6,4 +6,3 @@ Running WarpX from Python
 
    how_to_run
    examples
-   running_picmi