Add Catalyst Plugin.

AUTHORS

@@ -25,6 +25,9 @@ Benoit Martin - CEA (bmartin@cea.fr)
 * support for const data in `PDI_share`, `PDI_expose` and `PDI_multi_expose`
 * Initial implementation of the cmake test
 
+François Mazen - Kitware (francois.mazen@kitware.com)
+* Catalyst plugin creation
+
 François-Xavier Mordant - CEA (francois-xavier.mordant@cea.fr)
 * Fixed CMake issues, internal API enhancement
 * Bug fix, JSON plugin

CHANGELOG.md

@@ -28,6 +28,7 @@ and this project adheres to
 * Update the error messages for invalid SYSTEM dependencies of NetCDF and HDF5,
   and document the cmake option to override 'NetCDF_FIND_STRATEGIES' as
   requested in [#500](https://github.com/pdidev/pdi/issues/500)
+* Add Catalyst plugin from Kitware [#496](https://github.com/pdidev/pdi/pull/496)
 
 #### Changed
 

CMakeLists.txt

@@ -1,5 +1,6 @@
 #=============================================================================
 # Copyright (C) 2015-2026 Commissariat a l'energie atomique et aux energies alternatives (CEA)
+# Copyright (C) 2024-2025 Kitware SAS
 #
 # All rights reserved.
 #
@@ -34,8 +35,6 @@
 cmake_minimum_required(VERSION 3.22...4.2)
 project(PDI_DIST LANGUAGES C CXX)
 
-
-
 ### Build options
 
 ## Global options
@@ -77,6 +76,7 @@ option(BUILD_TRACE_PLUGIN       "Build Trace plugin" ON)
 option(BUILD_USER_CODE_PLUGIN   "Build User-code plugin" ON)
 option(BUILD_JSON_PLUGIN        "Build JSON plugin" OFF)
 option(ENABLE_BENCHMARKING      "Activate benchmarks in the test suite" OFF)
+option(BUILD_CATALYST_PLUGIN    "Build Catalyst plugin" "${BUILD_UNSTABLE}")
 
 
 
@@ -554,3 +554,10 @@ sbuild_add_module(PDI_API_TESTS
 	INSTALL_COMMAND ""
 	SUBSTEPS test
 )
+
+sbuild_add_module(CATALYST_PLUGIN
+	ENABLE_BUILD_FLAG BUILD_CATALYST_PLUGIN
+	SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/plugins/catalyst"
+	DEPENDS PDI
+	SUBSTEPS test
+)

bin/build_and_run_all_tests

@@ -77,7 +77,7 @@ fi
 if [[ "x${PDI_SYSTEM}" =~ ^x(ubuntu|debian) && "x${PDI_MPI}" = "xmpich" ]]
 then
 	# Workaround: mpi4py in debuntu is packaged for openmpi only
-	EXCLUDED_PDI_TESTS="${EXCLUDED_PDI_TESTS:+$EXCLUDED_PDI_TESTS|}PDI_example_trace_P|PDI_example_decl_hdf5_P"
+	EXCLUDED_PDI_TESTS="${EXCLUDED_PDI_TESTS:+$EXCLUDED_PDI_TESTS|}PDI_example_trace_P|PDI_example_decl_hdf5_P|PDI_example_catalyst_P"
 fi
 
 if [[ "x${PDI_SYSTEM}" =~ ^x(ubuntu|debian) && "x${PDI_LIBS}" = "xprovided" ]]
@@ -95,6 +95,15 @@ then
 	CMAKE_FLAGS="${CMAKE_FLAGS} -DUSE_spdlog=SYSTEM"
 fi
 
+if [[ "x${PDI_SYSTEM}" =~ ^x(ubuntu|debian) ]] && [ -d /opt/catalyst/lib ];
+then
+	# Workaround: catalyst need a minimal version of cmake when catalyst is compiled the directory contains the library of catalyst
+	CMAKE_FLAGS="${CMAKE_FLAGS} -DBUILD_CATALYST_PLUGIN=ON"
+else
+	CMAKE_FLAGS="${CMAKE_FLAGS} -DBUILD_CATALYST_PLUGIN=OFF"
+fi
+
+
 # And now for the actual tests
 
 printf "\n\n\n\e[1;36m *** Configure, build & test the whole pdi distribution\e[m\n\n"

example/CMakeLists.txt

@@ -42,6 +42,7 @@ option(BUILD_PYCALL_PLUGIN      "Build Pycall plug-in"       OFF)
 option(BUILD_PYTHON             "Build with Python support"  OFF)
 option(BUILD_JSON_PLUGIN        "Build JSON plug-in"         OFF)
 option(DISABLE_PDI              "Disable the use of both PDI and Paraconf in the project" OFF)
+option(BUILD_CATALYST_PLUGIN    "Build Catalyst plug-in"     OFF)
 
 if("${BUILD_FORTRAN}")
 	enable_language(Fortran)
@@ -91,11 +92,9 @@ end module
 	endif()
 endif()
 
-
 add_executable(PDI_example_C example.c)
 target_link_libraries(PDI_example_C PRIVATE PDI::PDI_C paraconf::paraconf MPI::MPI_C m)
 
-
 if("${BUILD_FORTRAN}")
 add_executable(PDI_example_F example.F90)
 target_link_libraries(PDI_example_F PRIVATE PDI::PDI_f90 paraconf::paraconf_f90 MPI_with_mod m)
@@ -161,3 +160,32 @@ add_test(NAME PDI_example_trace_P COMMAND "${MPIEXEC}" "${MPIEXEC_NUMPROC_FLAG}"
 set_property(TEST PDI_example_trace_P PROPERTY TIMEOUT 15)
 set_property(TEST PDI_example_trace_P PROPERTY PROCESSORS 3)
 endif("${BUILD_PYTHON}")
+
+if("${BUILD_CATALYST_PLUGIN}")
+find_package(catalyst REQUIRED)
+## These examples are only valid with MPI, check if catalyst is compiling with MPI
+if("${CATALYST_USE_MPI}")
+set(RUNTEST_DIR_CATALYST "${CMAKE_CURRENT_SOURCE_DIR}/cmake/runtest-dir-catalyst")
+
+## set directory to find the catalyst python script
+set(CATALYST_SCRIPT_FOLDER ${CMAKE_CURRENT_SOURCE_DIR})
+## configure the yaml file with the previous directory
+configure_file(catalyst_serial.yml.in ${CMAKE_BINARY_DIR}/catalyst_serial.yml) ## keep serial for personal testing
+configure_file(catalyst.yml.in ${CMAKE_BINARY_DIR}/catalyst.yml)
+
+add_test(NAME PDI_example_catalyst_C_serial COMMAND "${RUNTEST_DIR_CATALYST}" "${MPIEXEC}" "${MPIEXEC_NUMPROC_FLAG}" 1 ${MPIEXEC_PREFLAGS} "$<TARGET_FILE:PDI_example_C>" ${MPIEXEC_POSTFLAGS} "${CMAKE_BINARY_DIR}/catalyst_serial.yml")
+set_property(TEST PDI_example_catalyst_C_serial PROPERTY TIMEOUT 15)
+set_property(TEST PDI_example_catalyst_C_serial PROPERTY PROCESSORS 1)
+
+add_test(NAME PDI_example_catalyst_C COMMAND "${RUNTEST_DIR_CATALYST}" "${MPIEXEC}" "${MPIEXEC_NUMPROC_FLAG}" 3 ${MPIEXEC_PREFLAGS} "$<TARGET_FILE:PDI_example_C>" ${MPIEXEC_POSTFLAGS} "${CMAKE_BINARY_DIR}/catalyst.yml")
+set_property(TEST PDI_example_catalyst_C PROPERTY TIMEOUT 15)
+set_property(TEST PDI_example_catalyst_C PROPERTY PROCESSORS 3)
+
+if("${BUILD_PYTHON}" AND "${CATALYST_USE_PYTHON}")
+add_test(NAME PDI_example_catalyst_P COMMAND "${RUNTEST_DIR_CATALYST}" "${MPIEXEC}" "${MPIEXEC_NUMPROC_FLAG}" 1 ${MPIEXEC_PREFLAGS} "$<TARGET_FILE:PDI::pdirun>" "${Python3_EXECUTABLE}" ${MPIEXEC_POSTFLAGS} "${CMAKE_CURRENT_SOURCE_DIR}/example.py" "${CMAKE_BINARY_DIR}/catalyst_serial.yml")
+set_property(TEST PDI_example_catalyst_P PROPERTY TIMEOUT 15)
+set_property(TEST PDI_example_catalyst_P PROPERTY PROCESSORS 1)
+endif("${BUILD_PYTHON}" AND "${CATALYST_USE_PYTHON}")
+
+endif("${CATALYST_USE_MPI}")
+endif("${BUILD_CATALYST_PLUGIN}")

example/catalyst.yml.in

@@ -0,0 +1,56 @@
+# duration in seconds
+duration: 1.75
+# global [height, width] (excluding boundary conditions or ghosts)
+datasize: [60, 12]
+# degree of parallelism
+parallelism: { height: 3, width: 1 }
+
+# only the following config is passed to PDI
+pdi:
+  metadata: # type of small values for which PDI keeps a copy
+    iter:   int                    # current iteration id
+    dsize:  { size: 2, type: array, subtype: int } # local data size including ghosts/boundary
+    psize:  { size: 2, type: array, subtype: int } # number of processes in each dimension
+    pcoord: { size: 2, type: array, subtype: int } # coordinate of the process
+  data: # type of values for which PDI does not keep a copy
+    main_field: { size: [ '$dsize[0]', '$dsize[1]' ], type: array, subtype: double }
+
+  plugins:
+    mpi:
+    catalyst:
+      scripts:
+        script1: "@CATALYST_SCRIPT_FOLDER@/catalyst_pipeline_with_rendering.py"
+      on_event: "newiter"
+      execute:
+        state:
+          timestep: '$iter'
+          time: '1.0*$iter'
+          multiblock: 0
+        channels:
+          grid:
+            type: "mesh"
+            data:
+              coordsets:
+                my_coords:
+                  type: "uniform"
+                  dims: { i: '1+$dsize[1]', j: '1+$dsize[0]' }
+                  origin: 
+                    x: '1.0*$pcoord[1]*($dsize[1]-2.0)-1.0'
+                    y: '1.0*$pcoord[0]*($dsize[0]-2.0)-1.0'
+                  spacing: { dx: 1.0, dy: 1.0 }
+              topologies:
+                my_mesh:
+                  type: "uniform"
+                  coordset: "my_coords"
+#                  elements:
+#                    dims: {offsets: [] strides: []}
+              fields:
+                temperature:
+                  association: "element"
+                  topology: "my_mesh"
+                  volume_dependent: "false"
+                  values:
+                    PDI_data_array: "main_field"
+                    size: '$dsize[0]*$dsize[1]'
+              ghost_layers:
+                my_mesh: { association: "element", start: ['1', '1'], size: ['$dsize[1]-2', '$dsize[0]-2'] }

example/catalyst_pipeline_with_rendering.py

@@ -0,0 +1,131 @@
+# script-version: 2.0
+from paraview.simple import *
+from paraview import catalyst
+import time
+
+# registrationName must match the channel name used in the
+# 'CatalystAdaptor'.
+producer = TrivialProducer(registrationName="grid")
+
+# ----------------------------------------------------------------
+# setup views used in the visualization
+# ----------------------------------------------------------------
+
+# ######## render view temperature
+
+# Create a new 'Render View'
+renderView1 = CreateView('RenderView')
+# renderView1.Set(
+#     ViewSize=[800, 600],
+#     InteractionMode='2D',
+#     CenterOfRotation=[20.0, 3.0, 0.0],
+#     CameraPosition=[20.0, 30.0, 408.7],
+#     CameraFocalPoint=[20.0, 30.0, 0.0],
+#     CameraFocalDisk=1.0,
+#     CameraParallelScale=32.0,
+# )
+
+renderView1.ViewSize=[800, 600]
+renderView1.InteractionMode='2D'
+renderView1.CenterOfRotation=[20.0, 3.0, 0.0]
+renderView1.CameraPosition=[20.0, 30.0, 408.7]
+renderView1.CameraFocalPoint=[20.0, 30.0, 0.0]
+renderView1.CameraFocalDisk=1.0,
+renderView1.CameraParallelScale=32.0
+
+
+# get color transfer function/color map for 'temperature'
+temperatureLUT = GetColorTransferFunction('temperature')
+## RGB: first line: min value, last line: max value
+# temperatureLUT.Set(
+#     RGBPoints=GenerateRGBPoints(
+#         range_min=0.0,
+#         range_max=200.0,
+#     ),
+#     ScalarRangeInitialized=1.0,
+# )
+
+
+temperatureLUT.RGBPoints=[0.0, 0.231373, 0.298039, 0.752941,
+                        500000.0, 0.865003, 0.865003, 0.865003,
+                        1000000, 0.705882, 0.0156863, 0.14902]
+
+temperatureLUT.ScalarRangeInitialized=1.0
+
+
+
+# show data from grid
+## wgridDisplay = Show(producer, renderView1, 'UnstructuredGridRepresentation')
+gridDisplay = Show(producer, renderView1, 'StructuredGridRepresentation')
+
+gridDisplay.Representation = 'Surface With Edges'
+gridDisplay.ColorArrayName = ['CELLS', 'temperature']
+gridDisplay.LookupTable = temperatureLUT
+
+# get color legend/bar for temperatureLUT in view renderView1
+temperatureLUTColorBar = GetScalarBar(temperatureLUT, renderView1)
+temperatureLUTColorBar.Title = 'temperature'
+
+# set color bar visibility
+temperatureLUTColorBar.Visibility = 1
+
+# show color legend
+gridDisplay.SetScalarBarVisibility(renderView1, True)
+
+# # ----------------------------------------------------------------
+# # setup extractors
+# # ----------------------------------------------------------------
+
+SetActiveView(renderView1)
+# create extractor
+pNG2= CreateExtractor('PNG', renderView1, registrationName='PNG2')
+# trace defaults for the extractor.
+pNG2.Trigger = 'TimeStep'
+
+# init the 'PNG' selected for 'Writer'
+pNG2.Writer.FileName = 'temperature_screenshot_{timestep:06d}.png'
+pNG2.Writer.ImageResolution=[800, 600]
+pNG2.Writer.Format = 'PNG'
+
+# # ----------------------------------------------------------------
+# # setup extractor for saving the solution in VTK file
+# # ----------------------------------------------------------------
+
+extractor_vtk_file = None
+
+mesh_grid = producer.GetClientSideObject().GetOutputDataObject(0)
+if mesh_grid.IsA('vtkUnstructuredGrid'):
+    extractor_vtk_file = CreateExtractor('VTU', producer, registrationName='VTU')
+elif mesh_grid.IsA('vtkMultiBlockDataSet'):
+    extractor_vtk_file = CreateExtractor('VTM', producer, registrationName='VTM')
+elif mesh_grid.IsA('vtkPartitionedDataSet'):
+    extractor_vtk_file = CreateExtractor('VTPD', producer, registrationName='VTPD')
+else:
+    raise RuntimeError("Unsupported data type: %s. Check that the adaptor is providing channel named %s",
+                        mesh_grid.GetClassName(), "grid")
+
+
+# ------------------------------------------------------------------------------
+# Catalyst options
+options = catalyst.Options()
+## 0: no client, generate the png images and vtk files.
+## 1: interactive
+options.EnableCatalystLive = 0
+
+
+# Greeting to ensure that ctest knows this script is being imported
+print("#############################################################")
+print("executing catalyst_pipeline")
+print("#############################################################")
+def catalyst_execute(info):
+    global producer
+    producer.UpdatePipeline()
+    print("-----------------------------------")
+    print("executing (cycle={}, time={})".format(info.cycle, info.time))
+    print("bounds:", producer.GetDataInformation().GetBounds())
+    print("temperature-range:", producer.CellData["temperature"].GetRange(0))
+    # In a real simulation sleep is not needed. We use it here to slow down the
+    # "simulation" and make sure ParaView client can catch up with the produced
+    # results instead of having all of them flashing at once.
+    if options.EnableCatalystLive:
+        time.sleep(0.1)

example/catalyst_serial.yml.in

@@ -0,0 +1,58 @@
+# duration in seconds
+duration: 2.75
+# global [height, width] (excluding boundary conditions or ghosts)
+datasize: [60, 12]
+# degree of parallelism
+parallelism: { height: 1 , width: 1 }
+
+# only the following config is passed to PDI
+pdi:
+  metadata: # type of small values for which PDI keeps a copy
+    iter:   int                    # current iteration id
+    dsize:  { size: 2, type: array, subtype: int } # local data size including ghosts/boundary
+    psize:  { size: 2, type: array, subtype: int } # number of processes in each dimension
+    pcoord: { size: 2, type: array, subtype: int } # coordinate of the process
+  data: # type of values for which PDI does not keep a copy
+    main_field: { size: [ '$dsize[0]', '$dsize[1]' ], type: array, subtype: double }
+
+  logging: debug
+  plugins:
+    mpi:
+    catalyst:
+      scripts:
+        script1: "@CATALYST_SCRIPT_FOLDER@/catalyst_pipeline_with_rendering.py"
+      on_event: "newiter"
+      execute:
+        state:
+          timestep: $iter
+          time: 1.0*$iter
+          multiblock: 0
+        channels:
+           grid:
+            type: "mesh"
+            data:
+              coordsets:
+                my_coords:
+                  type: "uniform"
+                  dims: { i: '1+$dsize[1]', j: '1+$dsize[0]' }
+                  origin: 
+                    x: 1.0*$pcoord[1]*($dsize[1]-2.0)-1.0
+                    y: 1.0*$pcoord[0]*($dsize[0]-2.0)-1.0
+                  spacing: { dx: 1.0, dy: 1.0 }
+              topologies:
+                my_mesh:
+                  type: "uniform"
+                  coordset: "my_coords"
+              fields:
+                temperature:
+                  association: "element"
+                  topology: "my_mesh"
+                  volume_dependent: "false"
+                  values:
+                    PDI_data_array: "main_field"
+                    size: $dsize[0]*$dsize[1]
+              ghost_layers:
+                my_mesh: 
+                  association: "element"
+                  start: ['1', '1']
+                  size: ['$dsize[1]-2', '$dsize[0]-2']