Catalyst is an in-situ framework created as a part of ParaView a few years ago. With time and use, we saw the different drawbacks of our approach and then it was decided to create a new architecture, Catalyst2
With this new implementation, it is:
- easier to implement in your simulation (less knowledges required)
- easier to update from a version to another (less dependencies, binary compatibility)
- possible to activate Steering mode, where ParaView can modify simulation parameters at runtime
A previous tip explains how to use the legacy Catalyst.
Here is a short introduction on how to use a c++ example from ParaView code base. This code represents a simple simulation that make use of Catalyst2:
-
FEDriver.cxx: the main loop of the simulation -
FEDataStructure.[h,cxx]: simulations files managing data -
CatalystAdaptor.h: the interface with Catalyst library. Quite all the changes you need in your simulation code are contained in this file. -
catalyst_pipeline.py: a script called at runtime -
CMakeLists.txt: the CMake code to configure the project. Look at it to see how to find the Catalyst library and link against it.
Prerequisites
- MPI
- an installed version of Catalyst2
- CMake
- a ParaView binary (can comes from the download page but 5.10.0 is known to be buggy with MPI. Nightly or future release should be ok).
- The example in its own directory, and an empty build directory
Building the example
Once ok with this example, adapt this part to your own simulation.
- no need for paraview
- use CMake for configuration and to find the catalyst package:
cmake -Dcatalyst_DIR=<catalyst-install-dir>/lib/cmake/catalyst-2.0 <simu-source-dir>
- use make or ninja to build
Simple Run
Run the generated executable with a catalyst pipeline script as parameter (can be generated from ParaView, see bellow). The command is also added as a test (you can enable it in CMake and then use ctest).
The executable needs to find the paraview catalyst lib to do effective computation, so we need to point them through environment variables.
export CATALYST_IMPLEMENTATION_PATHS="<paraview-install-dir>/lib/catalyst"
export CATALYST_IMPLEMENTATION_NAME=paraview
./bin/CxxFullExample catalyst_pipeline.py
Default script only print some info in the standard output. To have some processing done, you have to configure it.
Note on MPI
Be careful that the MPI version used to build the simulation should be the same that the MPI used by ParaView. In case of errors, you may have to build ParaView by yourself, so ParaView and simulation share the same version of MPI.
For this tutorial, you can also remove MPI-related line in the example source code.
Configure Pipeline and Live Visualization
To create your own script, start creating a pipeline in ParaView. Use the Extractors to write your results (screenshots or meshes).
Then use File / Save Catalyst State to export the python script. Live Visualization is an option you can enable in the export wizard.
catalyst2_pipeline.py (4.2 KB) is sample script taking screenshot and with live visualization enabled. You can also load it as a State File to inspect its content.
Use Catalyst / Connect menu in ParaView so ParaView will wait for catalyst input. Then run your simulation as explained above. The configured pipeline will appears in your ParaView session.
Tips
Use Catalyst / pause simu menu before starting the simu, so it will be paused on the first timestep, letting you inspect what you want. Useful because the simu will close the connection when terminating. (and examples code go fast).
Notes
When simulation stops, it breaks the connection with the ParaView application so it is expected to have some error message like the following:
ERROR: In /home/nicolas/ParaView/releases/5.10/VTK/Parallel/Core/vtkSocketCommunicator.cxx, line 781
vtkSocketCommunicator (0x563b4cb9b5b0): Could not receive tag. 1
ERROR: In /home/nicolas/ParaView/releases/5.10/Remoting/Core/vtkTCPNetworkAccessManager.cxx, line 296
vtkTCPNetworkAccessManager (0x563b457d9000): Some error in socket processing.
Notes for simulation developers
The catalyst API is really small (5 methods including an about()). What you have to do is to create a Conduit node to describe your data and pass it to the Catalyst API. This is usually done in an object called the Adaptor.
The API is as follow:
-
catalyst_initializeto pass the pipeline script, typically called at the beginning of the simulation -
catalyst_executeto run the pipeline, each time want it to run in your main loop. This is where you should wrap your data in Conduit node -
catalyst_finalizefor internal cleanup before ending - optionally,
catalyst_resultsto get back data from Live Visualization and modify the simulation, during the main loop. - optionally,
catalyst_aboutto get information about current catalyst lib