Python documentation updates (#936)

* Update Python documentation

* Added numpy as a requirement for the Python installation

* Cleaned EOL white space in Python documentation

* Add periodictable to the Python packages required

Co-Authored-By: Axel Huebl <axel.huebl@plasma.ninja>

* Added periodictable to required packages for pure Python version

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

1 files changed, 42 insertions, 6 deletions

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.
+