# How to try out Catalyst2

**URL:** https://discourse.paraview.org/t/how-to-try-out-catalyst2/9008
**Category:** Tips and Tricks
**Tags:** catalyst, python
**Created:** [February 18, 2022, 10:43am UTC](https://discourse.paraview.org/t/how-to-try-out-catalyst2/9008 "2022-02-18T10:43:56Z")
**Posts on this page:** 8
**Page:** 1

<div class="post-metadata">

### Author: ![nicolas.vuaille](https://discourse.paraview.org/user_avatar/discourse.paraview.org/nicolas.vuaille/32/5873_2.png) [@nicolas.vuaille](https://discourse.paraview.org/u/nicolas.vuaille)
#### Post date: [February 18, 2022, 10:43am UTC](https://discourse.paraview.org/t/how-to-try-out-catalyst2/9008/1 "2022-02-18T10:43:56Z")

</div>

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](https://catalyst-in-situ.readthedocs.io/en/latest/index.html)

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](https://discourse.paraview.org/t/how-to-try-out-catalyst-legacy/4213/1) explains how to use the legacy Catalyst.

Here is a short introduction on how to use a [c++ example](https://gitlab.kitware.com/paraview/paraview/-/tree/v5.10.0/Examples/Catalyst2/CxxFullExample) 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](https://gitlab.kitware.com/paraview/catalyst)
- CMake
- a ParaView binary (can comes from the [download page](https://www.paraview.org/download/) 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:

```auto
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.

```auto
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](https://docs.paraview.org/en/latest/UsersGuide/savingResults.html#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](https://discourse.paraview.org/uploads/short-url/3V7fbx3ksQaLSso2I3ZE7jMmnpp.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).

 ![catalyst](https://discourse.paraview.org/uploads/default/original/2X/3/3feea6b81a6026c9aaa5c9b583e4d9d84ca0c8ed.png)

### _Notes_

When simulation stops, it breaks the connection with the ParaView application so it is expected to have some error message like the following:

```auto
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](https://llnl-conduit.readthedocs.io/en/latest/index.html) node to describe your data and pass it to the Catalyst API. This is usually done in an object called the [Adaptor](https://gitlab.kitware.com/paraview/paraview/-/blob/v5.10.0/Examples/Catalyst2/CxxFullExample/CatalystAdaptor.h).  
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

---

<div class="post-metadata">

### Author: ![cory.quammen](https://discourse.paraview.org/user_avatar/discourse.paraview.org/cory.quammen/32/11193_2.png) [@cory.quammen](https://discourse.paraview.org/u/cory.quammen)
#### Post date: [February 18, 2022, 2:16pm UTC](https://discourse.paraview.org/t/how-to-try-out-catalyst2/9008/2 "2022-02-18T14:16:47Z")

</div>

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

---

<div class="post-metadata">

### Author: ![wascott](https://discourse.paraview.org/letter_avatar_proxy/v4/letter/w/8e8cbc/32.png) [@wascott](https://discourse.paraview.org/u/wascott)
#### Post date: [February 18, 2022, 5:32pm UTC](https://discourse.paraview.org/t/how-to-try-out-catalyst2/9008/3 "2022-02-18T17:32:29Z")

</div>

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?

---

<div class="post-metadata">

### Author: ![gha3mi](https://discourse.paraview.org/user_avatar/discourse.paraview.org/gha3mi/32/9267_2.png) [@gha3mi](https://discourse.paraview.org/u/gha3mi)
#### Post date: [February 19, 2022, 5:53pm UTC](https://discourse.paraview.org/t/how-to-try-out-catalyst2/9008/4 "2022-02-19T17:53:45Z")

</div>

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](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](https://www.paraview.org/download))

- download paraview nightly from [https://www.paraview.org/download](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](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

---

<div class="post-metadata">

### Author: ![nicolas.vuaille](https://discourse.paraview.org/user_avatar/discourse.paraview.org/nicolas.vuaille/32/5873_2.png) [@nicolas.vuaille](https://discourse.paraview.org/u/nicolas.vuaille)
#### Post date: [February 21, 2022, 9:05am UTC](https://discourse.paraview.org/t/how-to-try-out-catalyst2/9008/5 "2022-02-21T09:05:37Z")

</div>

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

---

<div class="post-metadata">

### Author: ![nicolas.vuaille](https://discourse.paraview.org/user_avatar/discourse.paraview.org/nicolas.vuaille/32/5873_2.png) [@nicolas.vuaille](https://discourse.paraview.org/u/nicolas.vuaille)
#### Post date: [February 21, 2022, 9:12am UTC](https://discourse.paraview.org/t/how-to-try-out-catalyst2/9008/6 "2022-02-21T09:12:05Z")

</div>

@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.

---

<div class="post-metadata">

### Author: ![gha3mi](https://discourse.paraview.org/user_avatar/discourse.paraview.org/gha3mi/32/9267_2.png) [@gha3mi](https://discourse.paraview.org/u/gha3mi)
#### Post date: [February 21, 2022, 11:34am UTC](https://discourse.paraview.org/t/how-to-try-out-catalyst2/9008/7 "2022-02-21T11:34:14Z")

</div>

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

---

<div class="post-metadata">

### Author: ![Alexandre\_Minot](https://discourse.paraview.org/user_avatar/discourse.paraview.org/alexandre_minot/32/7132_2.png) [@Alexandre\_Minot](https://discourse.paraview.org/u/Alexandre_Minot)
#### Post date: [February 21, 2022, 4:41pm UTC](https://discourse.paraview.org/t/how-to-try-out-catalyst2/9008/8 "2022-02-21T16:41:17Z")

</div>

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