MPL: ImpactXParticleContainer.plot_phasespace() (#469)

* MPL: `ImpactXParticleContainer.plot_phasespace()`

Add an interactive plotter to quickly check the current phase
space of the particle bunch.

This is heavily inspired by Wake-T's `bunch.show()` functionality.

* CI: Update `dependencies/gcc.sh`

Install `requirements.txt`

Chain of `requirements.txt`: tests -> examples -> root

.github/workflows/dependencies/gcc.sh

@@ -24,6 +24,7 @@ sudo apt-get install -y \
 python3 -m pip install -U pip
 python3 -m pip install -U build packaging setuptools wheel
 python3 -m pip install -U cmake pytest
+python3 -m pip install -U -r requirements.txt
 python3 -m pip install -U -r examples/requirements.txt
 
 python3 -m pip install -U openPMD-validator

README.md

@@ -122,7 +122,7 @@ In order to run our tests, you need to have a few Python packages installed:
 ```console
 python3 -m pip install --upgrade pip
 python3 -m pip install --upgrade build packaging setuptools wheel pytest
-python3 -m pip install --upgrade -r examples/requirements.txt
+python3 -m pip install --upgrade -r tests/python/requirements.txt
 ```
 
 You can run all our tests with:

docs/source/dataanalysis/dataanalysis.rst

@@ -3,6 +3,8 @@
 Data Analysis
 =============
 
+.. _dataanalysis-monitor:
+
 Beam Monitor
 ------------
 
@@ -14,6 +16,8 @@ For data analysis of openPMD data, see examples of `many supported tools, Python
 
 See also `WarpX' documentation on openPMD <https://warpx.readthedocs.io/en/latest/dataanalysis/formats.html>`__.
 
+.. _dataanalysis-monitor-refparticle:
+
 Additional Beam Attributes
 """"""""""""""""""""""""""
 
@@ -49,6 +53,8 @@ Example to print the integrated orbit path length ``s`` at each beam monitor pos
        print(f"step {k_i:>3}: s_ref={s_ref}")
 
 
+.. _dataanalysis-beam-characteristics:
+
 Reduced Beam Characteristics
 ----------------------------
 
@@ -78,3 +84,35 @@ The code writes out the values in an ASCII file prefixed ``reduced_beam_characte
     Courant-Snyder (Twiss) beta (unit: meter)
 * ``charge``
     Cumulated beam charge (unit: Coulomb)
+
+
+.. _dataanalysis-plot:
+
+Interactive Analysis
+--------------------
+
+When steering ImpactX from Python, one can at any point visualize the beam phase space with:
+
+.. code-block:: python
+
+   import matplotlib.pyplot as plt
+
+   from impactx import ImpactX, RefPart, distribution, elements
+
+   sim = ImpactX()
+
+   # ... setup and simulate ...
+
+   pc = sim.particle_container()
+
+   fig = pc.plot_phasespace()
+
+   # note: figure data available on MPI rank zero
+   if fig is not None:
+       fig.savefig("phase_space.png")
+       plt.show()
+
+.. figure:: https://user-images.githubusercontent.com/1353258/295041638-8410ba76-9bd2-4dae-9810-5ec9f33dd372.png
+   :alt: In situ visualization of the beam phase space projections.
+
+   In situ visualization of the beam phase space projections.

docs/source/install/dependencies.rst

@@ -29,6 +29,7 @@ Optional dependencies include:
 
   - `mpi4py <https://mpi4py.readthedocs.io>`__
   - `numpy <https://numpy.org>`__
+  - `quantiphy <https://quantiphy.readthedocs.io/>`__
   - `openPMD-api <https://github.com/openPMD/openPMD-api>`__
   - see our ``requirements.txt`` file for compatible versions
 
@@ -66,7 +67,7 @@ Conda (Linux/macOS/Windows)
 
       .. code-block:: bash
 
-         conda create -n impactx-cpu-mpich-dev -c conda-forge blaspp boost ccache cmake compilers git lapackpp "openpmd-api=*=mpi_mpich*" python numpy pandas scipy yt pkg-config matplotlib mamba ninja mpich pip virtualenv
+         conda create -n impactx-cpu-mpich-dev -c conda-forge blaspp boost ccache cmake compilers git lapackpp "openpmd-api=*=mpi_mpich*" python numpy pandas quantiphy scipy yt pkg-config matplotlib mamba ninja mpich pip virtualenv
          conda activate impactx-cpu-mpich-dev
 
          # compile ImpactX with -DImpactX_MPI=ON
@@ -76,7 +77,7 @@ Conda (Linux/macOS/Windows)
 
       .. code-block:: bash
 
-         conda create -n impactx-cpu-dev -c conda-forge blaspp boost ccache cmake compilers git lapackpp openpmd-api python numpy pandas scipy yt pkg-config matplotlib mamba ninja pip virtualenv
+         conda create -n impactx-cpu-dev -c conda-forge blaspp boost ccache cmake compilers git lapackpp openpmd-api python numpy pandas quantiphy scipy yt pkg-config matplotlib mamba ninja pip virtualenv
          conda activate impactx-cpu-dev
 
          # compile ImpactX with -DImpactX_MPI=OFF
@@ -138,7 +139,7 @@ Now install the WarpX/ImpactX dependencies in a new development environment:
 
    # installation
    spack install
-   python3 -m pip install jupyter matplotlib numpy openpmd-api openpmd-viewer pandas scipy virtualenv yt
+   python3 -m pip install jupyter matplotlib numpy openpmd-api openpmd-viewer pandas quantiphy scipy virtualenv yt
 
 In new terminal sessions, re-activate the environment with
 

examples/requirements.txt

@@ -1,3 +1,4 @@
+-r ../requirements.txt
 matplotlib
 numpy
 openpmd-api

requirements.txt

@@ -1 +1,2 @@
 numpy~=1.15
+quantiphy~=2.19