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.
You can skip cloning the entrire ParaView source code by downloading just the example directory.
Contents of the
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.
Building the example
mkdir build cd build cmake -DCMAKE_PREFIX_PATH=<libcatalyst-install-dir> ../CxxFullExample cmake --build .
Run the generated executable
The executable needs to link to the ParaViewCatalyst library at runtime.
To achieve this, we initialize
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
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) ----------------------------------- ...
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
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.
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.
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.
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
while providing the expected arguments. For the protocols used in each of the
calls see here.