Docs: Analysis

Add a data analysis & visualization section.
This is meant to show entry points and workflows to work with
openPMD data in larger frameworks and compatible ecosystems.

docs/source/analysis/contrib.rst

@@ -0,0 +1,34 @@
+.. _analysis-contrib:
+
+Contributed
+===========
+
+This page contains contributed projects and third party integrations to analyze openPMD data.
+See the `openPMD-projects <https://github.com/openPMD/openPMD-projects#data-processing-and-visualization>`__ catalog for more community integrations.
+
+
+.. _analysis-contrib-visualpic:
+
+3D Visualization: VisualPIC
+---------------------------
+
+openPMD data can be visualized with the domain-specific VisualPIC renderer.
+Please see `the WarpX page for details <https://warpx.readthedocs.io/en/latest/dataanalysis/visualpic.html>`__.
+
+
+.. _analysis-contrib-visit:
+
+3D Visualization: VisIt
+-----------------------
+
+openPMD **HDF5** data can be visualized with VisIt 3.1.0+.
+VisIt supports openPMD HDF5 files and requires to rename the files from ``.h5`` to ``.opmd`` to be automatically detected.
+
+
+.. _analysis-contrib-yt:
+
+yt-project
+----------
+
+openPMD **HDF5** data can be visualized with `yt-project <https://yt-project.org>`__.
+Please see the `yt documentation <https://yt-project.org/doc/examining/loading_data.html?highlight=openpmd#openpmd-data>`__ for details.

docs/source/analysis/paraview.rst

@@ -0,0 +1,55 @@
+.. _analysis-paraview:
+
+3D Visualization: ParaView
+==========================
+
+openPMD data can be visualized by ParaView, an open source visualization and analysis software.
+ParaView can be downloaded and installed from httpshttps://www.paraview.org.
+Use the latest version for best results.
+
+Tutorials
+---------
+
+ParaView is a powerful, general parallel rendering program.
+If this is your first time using ParaView, consider starting with a tutorial.
+
+* https://www.paraview.org/Wiki/The_ParaView_Tutorial
+* https://www.youtube.com/results?search_query=paraview+introduction
+* https://www.youtube.com/results?search_query=paraview+tutorial
+
+
+openPMD
+-------
+
+openPMD files can be visualized with ParaView 5.9+, using 5.11+ is recommended.
+ParaView supports ADIOS1, ADIOS2 and HDF5 files, as it implements against the Python bindings of openPMD-api.
+
+For openPMD output to be recognized, create a small textfile with ``.pmd`` ending per data series, which can be opened with ParaView:
+
+.. code-block:: console
+
+   $ cat paraview.pmd
+   openpmd_%06T.bp
+
+The file contains the same string as one would put in an openPMD ``Series("....")`` object.
+
+.. tip::
+
+   When you first open ParaView, adjust its global ``Settings`` (Linux: under menu item ``Edit``).
+   ``General`` -> ``Advanced`` -> Search for ``data`` -> ``Data Processing Options``.
+   Check the box ``Auto Convert Properties``.
+
+   This will simplify application of filters, e.g., contouring of components of vector fields, without first adding a calculator that extracts a single component or magnitude.
+
+.. warning::
+
+   As of ParaView 5.11 and older, the axisLabel is not yet read for fields.
+   See, e.g., `WarpX issue 21162 <https://github.com/ECP-WarpX/WarpX/issues/1803>`__.
+   Please apply rotation of, e.g., ``0 -90 0`` to mesh data where needed.
+
+.. warning::
+
+   `ParaView issue 21837 <https://gitlab.kitware.com/paraview/paraview/-/issues/21837>`__:
+   In order to visualize particle traces with the ``Temporal Particles To Pathlines``, you need to apply the ``Merge Blocks`` filter first.
+
+   If you have multiple species, you may have to extract the species you want with ``Extract Block`` before applying ``Merge Blocks``.

docs/source/analysis/viewer.rst

@@ -0,0 +1,68 @@
+.. _analysis-viewer:
+
+openPMD-viewer
+==============
+
+`openPMD-viewer <https://github.com/openPMD/openPMD-viewer>`__ is an open-source Python package to access openPMD data.
+
+It allows to:
+
+* Quickly browse through the data, with a GUI-type interface in the Jupyter notebook
+* Have access to the data numpy array, for more detailed analysis
+
+Installation
+------------
+
+openPMD-viewer can be installed via ``conda`` or ``pip``:
+
+.. code-block:: bash
+
+    conda install -c conda-forge openpmd-viewer openpmd-api
+
+.. code-block:: bash
+
+    python3 -m pip install openPMD-viewer openPMD-api
+
+Usage
+-----
+
+openPMD-viewer can be used either in simple Python scripts or in `Jupyter <https://jupyter.org>`__.
+For interactive plots in Jupyter lab, add this `"cell magic" <https://ipython.readthedocs.io/en/stable/interactive/magics.html>`__ to the first line of your notebook:
+
+.. code-block:: python
+
+   %matplotlib widget
+
+and for Jupyter notebook use this instead:
+
+.. code-block:: python
+
+   %matplotlib notebook
+
+If none of those work, e.g. because `ipympl <https://github.com/matplotlib/ipympl#installation>`__ is not properly installed, you can as a last resort always try ``%matplotlib inline`` for non-interactive plots.
+
+In both interactive and scripted usage, you can import openPMD-viewer, and load the data with the following commands:
+
+.. code-block:: python
+
+    from openpmd_viewer import OpenPMDTimeSeries
+    ts = OpenPMDTimeSeries('path/to/data/series/')
+
+.. note::
+
+    If you are using the Jupyter notebook, then you can start a pre-filled
+    notebook, which already contains the above lines, by typing in a terminal:
+
+    ::
+
+        openPMD_notebook
+
+When using the Jupyter notebook, you can quickly browse through the data
+by using the command:
+
+::
+
+    ts.slider()
+
+You can also access the particle and field data as numpy arrays with the methods ``ts.get_field`` and ``ts.get_particle``.
+See the openPMD-viewer tutorials `here <https://github.com/openPMD/openPMD-viewer/tree/master/tutorials>`_ for more info.

docs/source/index.rst

@@ -21,6 +21,7 @@ Writing & reading through those backends and their associated files is supported
    section#api-details,
    section#utilities,
    section#backends,
+   section#analysis,
    section#development,
    section#maintenance {
        display:none;
@@ -128,6 +129,17 @@ Backends
    backends/adios2
    backends/hdf5
 
+Data Analysis
+-------------
+.. toctree::
+   :caption: ANALYSIS
+   :maxdepth: 1
+   :hidden:
+
+   analysis/viewer
+   analysis/paraview
+   analysis/contrib
+
 Development
 -----------
 .. toctree::