How to try out Catalyst2

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_initialize to pass the pipeline script, typically called at the beginning of the simulation
  • catalyst_execute to 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_finalize for internal cleanup before ending
  • optionally, catalyst_results to get back data from Live Visualization and modify the simulation, during the main loop.
  • optionally, catalyst_about to get information about current catalyst lib
7 Likes

Nicolas, any objections to me putting this in the Catalyst docs as a getting started section?

This really is good. Thanks Nicolas! If we do move it into the getting started section, there are a few singie/plural and other trivial grammatical errors. Mind if I fix them?

Thank you Nicolas! This is really great! Iā€™m trying to test the example. However, I get an error.

I have already followed your instruction as follows:


1 - Build and Install Catalyst (https://catalyst-in-situ.readthedocs.io)

1.1 - Using CMake

  • mkdir <test_catalyst>

  • cd <test_catalyst>

  • mkdir libcatalyst

  • mkdir catalyst-build

  • git clone https://gitlab.kitware.com/paraview/catalyst.git

  • cd catalyst-build

  • ccmake -G Ninja -DCMAKE_INSTALL_PREFIX=<test_catalyst>/libcatalyst <test_catalyst>/catalyst

  • ninja

  • ninja install

1.2 - Using Make

  • ?

2 - Download Paraview (https://www.paraview.org/download)

  • download paraview nightly from https://www.paraview.org/download.

  • mv <ParaView>.tar.gz <test_catalyst>

  • cd <test_catalyst>

  • mkdir paraview_latest

  • tar -xvf <ParaView>.tar.gz --directory <test_catalyst>/paraview_latest --strip-components 1


3 - Clone ParaView Repo (https://gitlab.kitware.com/paraview/paraview)

  • cd <test_catalyst>

  • git clone https://gitlab.kitware.com/paraview/paraview.git


4 - Build Catalyst Example (CxxFullExample)

4.1 - Using CMake

  • cd <test_catalyst>/paraview/Examples/Catalyst2/CxxFullExample

  • cmake -Dcatalyst_DIR=<test_catalyst>/libcatalyst/lib/cmake/catalyst-2.0 <test_catalyst>/paraview/Examples/Catalyst2/CxxFullExample

  • make

4.2 - Using Make

  • ?

5 - Run Example (CxxFullExample)

  • export CATALYST_IMPLEMENTATION_PATHS="<test_catalyst>/paraview_latest/lib/catalyst"

  • export CATALYST_IMPLEMENTATION_NAME=paraview

  • cd <test_catalyst>/paraview/Examples/Catalyst2/CxxFullExample/

  • ./bin/CxxFullExampleV2 catalyst_pipeline.py


I get this error:

Invalid MIT-MAGIC-COOKIE-1 key Loguru caught a signal: SIGSEGV Stack trace: 10 0x40adce ./bin/CxxFullExampleV2() [0x40adce] 9 0x7f15e083b0b3 __libc_start_main + 243 8 0x414e1a ./bin/CxxFullExampleV2() [0x414e1a] 7 0x412ffd ./bin/CxxFullExampleV2() [0x412ffd] 6 0x7f15e10fb82d catalyst_initialize + 177 5 0x7f15dc4c15fa <test_catalyst>/paraview_latest/lib/catalyst/libcatalyst-paraview.so(+0xa5fa) [0x7f15dc4c15fa] 4 0x7f15dc1a6b19 vtkInSituInitializationHelper::Initialize(unsigned long long) + 601 3 0x7f15d567afb9 vtkMPICommunicator::InitializeExternal(vtkMPICommunicatorOpaqueComm*) + 121 2 0x7f15d567ad18 vtkMPICommunicator::InitializeNumberOfProcesses() + 40 1 0x7f15e0e1832b MPI_Comm_size + 59 0 0x7f15e0a1b420 /lib/x86_64-linux-gnu/libpthread.so.0(+0x15420) [0x7f15e0a1b420] ( 0.003s) [main thread ] :0 FATL| Signal: SIGSEGV Segmentation fault (core dumped)


Best

Ali

@cory.quammen : absolutely no problem to put it in the doc!
@wascott feel free to correct anyhing you want.

@gha3mi , Mixing MPI version is always touchy. You should either:

  • use ParaView nightly and disable MPI in the simulation code (i.e. manually removing some lines)
  • build your own ParaView with MPI, to get same MPI version in simu and paraview.
1 Like

Thanks @nicolas.vuaille, building ParaView solved the problem.

Dear @nicolas.vuaille,

Thanks for this guide, I think it will be very helpful. Having setup Catalyst2 in my simulation code a few month back, I have a few comments on how this guide could be made a bit clearer, if that helps:

In the Building paragraph, clarify that these are additional instructions for building the dummy simulation code provided in the example, not ParaView or Catalyst. Perhaps say that this shows how the Catalyst headers are made available to the simulation code at build time and that this step will need to be reproduced in the real simulation code after running the getting started example.

Best,
Alexandre

1 Like