Getting Started

This is a short introduction on how to use a C++ example from the ParaView code base. This code represents a simple simulation that makes use of the Catalyst API.

Tip

You can skip cloning the entrire ParaView source code by downloading just the example directory.

Contents of the CxxFullExample directory:

  • FEDriver.cxx: the main loop of the simulation

  • FEDataStructure.[h,cxx]: simulation files describing the data structures of the driver.

  • CatalystAdaptor.h: the interface to the Catalyst library. Data descriptions and catalyst setup happens here. This is the main file to edit when you adapt the example for another simulation.

  • catalyst_pipeline.py: a script called at runtime

  • catalyst_pipeline_live.py: Alternative script to call at runtime that enables Live Visualization

  • CMakeLists.txt: The CMake code to configure and build the project. It demonstrates how to find the Catalyst library and link against it.

Prerequisites

Building the example

mkdir build
cd build
cmake -DCMAKE_PREFIX_PATH=<libcatalyst-install-dir> ../CxxFullExample
cmake --build .

Simple Run

Run the generated executable ./bin/CxxFullExampleV2 with catalyst_script.py as a parameter.

The executable needs to link to the ParaViewCatalyst library at runtime. To achieve this, we initialize CATALYST_IMPLEMENTATION_PATHS and CATALYST_IMPLEMENTATION_NAME to the path of the ParaViewCatalyst library and the name of the catalyst library implementation. Finally, we pass catalyst_script.py as script argument:

export CATALYST_IMPLEMENTATION_PATHS="<paraview-install-dir>/lib/catalyst"
export CATALYST_IMPLEMENTATION_NAME=paraview
./bin/CxxFullExample catalyst_pipeline.py

Expected output:

executing catalyst_pipeline
-----------------------------------
executing (cycle=0, time=0.0)
bounds: (0.0, 69.0, 0.0, 64.9, 0.0, 55.9)
velocity-magnitude-range: (0.0, 0.0)
pressure-range: (1.0, 1.0)
-----------------------------------
executing (cycle=1, time=0.1)
bounds: (0.0, 69.0, 0.0, 64.9, 0.0, 55.9)
velocity-magnitude-range: (0.0, 6.490000000000001)
pressure-range: (1.0, 1.0)
-----------------------------------
...

Note

Be careful that the MPI version used to build the simulation should be the same as 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 lines in the example source code.

Generating Catalyst Scripts

To specify the pipelines executed each time Catalyst is triggered you can modify the catalyst_script.py directly or generate one interactively through the ParaView UI.

To generate a catalyst script, assemble your pipelines as usual and append extractor(s) at the end of each pipeline. Extractors can be created through the Extractors menu and allow to extract and save data as meshes, images or even tables. Once the pipeline is ready use File > Save Catalyst State to export the state as a Python script which you can supply to ./bin/CxxFullExampleV2. For more details on extractors see section Extractors in the UserGuide section.

Live Visualization

When saving a Catalyst State you have the option to enable Live Visualization in the export wizard

To create your own script, start creating a pipeline in ParaView. Use 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.

For an example try catalyst_pipeline_live.py to experiment with taking a screenshot and running 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 appear in your ParaView session.

Tip

Use Catalyst > Pause Simulation before starting the simulation to pause the simulation on the first timestep. This allows inspection of the pipeline prior to running it. This is also useful for examples which iterate too fast to see the timestep updates.

Note

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

ERROR: In <paraview_source_dir>/VTK/Parallel/Core/vtkSocketCommunicator.cxx, line 781
vtkSocketCommunicator (0x563b4cb9b5b0): Could not receive tag. 1

ERROR: In <paraview_source_dir>/Remoting/Core/vtkTCPNetworkAccessManager.cxx, line 296
vtkTCPNetworkAccessManager (0x563b457d9000): Some error in socket processing.

Using ParaViewCatalyst in your simulation

To enable the use of ParaViewCatalyst for your simulation code, look at the CatalystAdaptor.h file. It wraps the main catalyst functions catalyst_* while providing the expected arguments. For the protocols used in each of the calls see here.