Enhancement/catalyst docs

README.md

@@ -27,6 +27,11 @@ Agreement number: 956748.
 
 There are multiple ways to install `PySEMTools` which are described below in more detail. For a quick-start, you can use:
 ```bash
+pip install extremeflow-pysemtools[all]
+```
+
+If you are new to the package, it is probably better to get all the examples and scripts by cloning the repository instead:
+```bash
 # Install mpi4py (Assuming your mpi wrapper is mpicc)
 env MPICC=$(which mpicc) python -m pip install --no-cache-dir mpi4py
 
@@ -38,12 +43,6 @@ git clone https://github.com/ExtremeFLOW/pySEMTools.git
 cd pySEMTools/
 pip install --editable .[all]
 ```
-This will allow you to explore all the examples in the repository. 
-
-You can choose to replace the `git clone` command and simply install from `PyPI` with:
-```bash
-pip install extremeflow-pysemtools[all]
-```
 
 ## For minimal functionality
 
@@ -106,6 +105,10 @@ Some functionalities such as data streaming require the use of adios2. You can c
 
 We have also made a [Wiki page](https://github.com/ExtremeFLOW/pySEMTools/wiki/Installing-Adios2) that shows how we have been able to install adios2 in the supercomputers that we generally use.
 
+An example on how adios2 can be used in conjunction with a simulation to perform, for example, insitu proper orthogonal decomposition, can be found [here](https://github.com/ExtremeFLOW/neko/tree/develop/examples/turb_pipe).
+
+> This dependency is not installed automatically with PySEMTools, since it requires the installation of the library itself with the python bindings activated.
+
 #### PyTorch
 
 Some classes are compatible with the pytorch module in case you have GPUs and want to use them in the process. We note that we only use pytorch optionally. There are versions that work exclusively with numpy on CPUs so pytorch can be avoided.
@@ -118,6 +121,22 @@ The process of installing pytorch in supercomputers is more intricate. In this c
 
 Once pytorch is available, many of the PySEMTools can be used on GPUs. We prepared examples and a [Wiki page](https://github.com/ExtremeFLOW/pySEMTools/wiki/Running-on-GPU-nodes-(Lumi)) that showcases how devices can be exploited.
 
+#### Catalyst2
+
+Catalyst is a tool generally used for in-situ data visualization. It has interfaces with adios2 already, but we have also added classes that work directly with the types in PySEMTOOls.
+
+This might be useful if you are interested in performing other insitu processing, but also want to get images.
+
+An example on how to run it can be found [here](https://github.com/ExtremeFLOW/pySEMTools/blob/main/scripts/4-insitu_visualization/catalyst_insitu.py).
+
+To perform visualizations in this way, you need to [install catalyst](https://catalyst-in-situ.readthedocs.io/en/latest/build_and_install.html) and then [install paraview](https://www.paraview.org/paraview-docs/latest/cxx/md__builds_gitlab-kitware-sciviz-ci_Documentation_dev_build.html) with the option to use a catalyst implementation `on` pointing to your catalyst installation.
+
+> This dependency is not installed automatically with PySEMTools, since it requires the installation of the library itself with the python bindings activated.
+
+#### HDF5
+
+`h5py` is currently listed among the dependencies of the package, and it will be installed if you do not have it already. Note, however, that this installation from `PyPI` will most likely only work in serial. To use the parallel functionalities for the module, you will likely need to build `HDF5` from source with `MPI` enabled, and then install `h5py` from this build.
+
 # Use
 
 To get an idea on how the codes are used, feel free to check the examples we have provided. Please note that most of the routines included here work in parallel. In fact, python scripts are encouraged rather than notebooks to take advantage of this capability.
@@ -128,7 +147,7 @@ You can use the provided tests to check if your installation is complete (Not al
 
 The tests rely on `pytest`. To install it in your pip environment simply execute `pip install pytest`.
 
-Tests are performed for more functionalities than those needed to use `PySEMTools` in its minimal version. To run them, make sure that you use the `"[all]"` or `"[test]"` argument when installing the package to 
+Tests are performed for more functionalities than those needed to use `PySEMTools` in its minimal version. To run them, make sure that you use the `[all]` or `[test]` argument when installing the package to 
 get all the dependencies (this will also install pytest).
 
 To run the tests, execute the `pytest tests/` command from the root directory of the repository. As an example, the following chain of commands will allow you to run the tests from a fresh python environment:

doc/pages/api.rst

@@ -15,6 +15,7 @@ The presently included submodules are:
     pysemtools.io.ppymech
     pysemtools.io.adios2
     pysemtools.io.hdf
+    pysemtools.io.catalyst
     pysemtools.io.wrappers
     pysemtools.monitoring
     pysemtools.rom
@@ -79,6 +80,12 @@ HDF
 .. automodule :: pysemtools.io.hdf
     :members:
 
+Catalyst2
+^^^^^^^^^
+
+.. automodule :: pysemtools.io.catalyst
+    :members:
+
 wrappers
 ^^^^^^^^
 

doc/pages/catalyst.rst

@@ -0,0 +1,15 @@
+:orphan:
+
+Catalyst
+--------
+
+The Catalyst module contains classes to aid with insitu visualization with Catalyst2.
+
+The objects in this module simply wrap around the Catalyst2 API to make it easier.
+
+Catalyst2
+~~~~~~~~~~~~~~~
+
+.. automodule :: pysemtools.io.catalyst
+    :members:
+    :exclude-members: __weakref__ __dict__

doc/pages/io.rst

@@ -8,6 +8,7 @@ The main modules are:
     - :doc:`ppymech`
     - :doc:`adios2`
     - :doc:`hdf`
+    - :doc:`catalyst`
 
 We have developed wrapper functions that can be used to read and write data in a more user-friendly way. Here we show them:
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "extremeflow-pysemtools"
-version = "1.2.1.dev0"
+version = "1.3.0.dev0"
 readme = "README.md"
 requires-python = ">= 3.10"
 dependencies = [

pysemtools/io/catalyst/insitu_visualization.py

@@ -5,9 +5,16 @@
 import numpy as np
 
 from mpi4py import MPI
-import paraview
-import catalyst
-import catalyst_conduit as conduit
+try :
+    import paraview
+    import catalyst
+    import catalyst_conduit as conduit
+except ImportError:
+    paraview = None
+    catalyst = None
+    conduit = None
+    Warning('Can not use catalyst for in-situ. Please install it or use the pvbatch python wrapper and add catalyst to PYTHONPATH')
+
 from ...monitoring import Logger
 from ...datatypes.msh_vtk import VTKMesh, VTK_HEXAHEDRON