Improvements for accessing ascent-catalyst, plus examples (#1162)

* Adjust SetupCatalyst.cmake to match official docs

* Initial attempt at adding catalyst build

* Make build_ascent_cuda_perlmutter.sh executable

* Fixes for building catalyst

* Set catalyst install directory

* Move libcatalyst-ascent.so to expected directory

* Add initial catalyst example

* Copy ascent-catalyst-mpi example if MPI is found

* Rename ascent-catalyst to ascent-catalyst-mpi

* Add non-mpi catalyst example, other fixes

* Remove leftover instance of _mpi

scripts/build_ascent/build_ascent.sh

@@ -44,6 +44,7 @@ build_camp="${build_camp:=true}"
 build_raja="${build_raja:=true}"
 build_umpire="${build_umpire:=true}"
 build_mfem="${build_mfem:=true}"
+build_catalyst="${build_catalyst:=false}"
 
 # ascent options
 build_ascent="${build_ascent:=true}"
@@ -596,7 +597,7 @@ cmake -S ${mfem_src_dir} -B ${mfem_build_dir} ${cmake_compiler_settings} \
   -DMFEM_ENABLE_EXAMPLES=${enable_tests} \
   -DCMAKE_INSTALL_PREFIX=${mfem_install_dir} 
 
-echo "**** Building MFEM ${vtkm_version}"
+echo "**** Building MFEM ${mfem_version}"
 cmake --build ${mfem_build_dir} --config ${build_config} -j${build_jobs}
 echo "**** Installing MFEM ${mfem_version}"
 cmake --install ${mfem_build_dir}  --config ${build_config}
@@ -606,6 +607,42 @@ else
   echo "**** Skipping MFEM build, install found at: ${mfem_install_dir}"
 fi # build_mfem
 
+################
+# Catalyst
+################
+catalyst_version=2.0.0-rc3
+catalyst_src_dir=$(ospath ${root_dir}/catalyst-v${catalyst_version})
+catalyst_build_dir=$(ospath ${root_dir}/build/catalyst-v${catalyst_version})
+catalyst_install_dir=$(ospath ${root_dir}/install/catalyst-v${catalyst_version}/)
+catalyst_cmake_dir=${catalyst_install_dir}lib64/cmake/catalyst-2.0/
+catalyst_tarball=catalyst-v${catalyst_version}.tar.gz
+
+# build only if install doesn't exist
+if [ ! -d ${catalyst_install_dir} ]; then
+if ${build_catalyst}; then
+if [ ! -d ${catalyst_src_dir} ]; then
+  echo "**** Downloading ${catalyst_tarball}"
+  curl -L https://gitlab.kitware.com/paraview/catalyst/-/archive/v${catalyst_version}/catalyst-v${catalyst_version}.tar.gz -o ${catalyst_tarball}
+  tar -xzf ${catalyst_tarball}
+fi
+
+echo "**** Configuring Catalyst ${catalyst_version}"
+cmake -S ${catalyst_src_dir} -B ${catalyst_build_dir} ${cmake_compiler_settings} \
+  -DCMAKE_VERBOSE_MAKEFILE:BOOL=${enable_verbose}\
+  -DCMAKE_BUILD_TYPE=${build_config} \
+  -DCATALYST_BUILD_TESTING=${enable_tests} \
+  -DCATALYST_USE_MPI=${enable_mpi} \
+  -DCMAKE_INSTALL_PREFIX=${catalyst_install_dir} \
+
+echo "**** Building Catalyst ${catalyst_version}"
+cmake --build ${catalyst_build_dir} --config ${build_config} -j${build_jobs}
+echo "**** Installing Catalyst ${catalyst_version}"
+cmake --install ${catalyst_build_dir} --config ${build_config}
+
+fi
+else
+  echo "**** Skipping Catalyst build, install found at: ${catalyst_install_dir}"
+fi # build_catalyst
 
 ################
 # Ascent
@@ -652,6 +689,10 @@ echo 'set(ENABLE_VTKH ON CACHE BOOL "")' >> ${root_dir}/ascent-config.cmake
 echo 'set(ENABLE_APCOMP ON CACHE BOOL "")' >> ${root_dir}/ascent-config.cmake
 echo 'set(ENABLE_DRAY ON CACHE BOOL "")' >> ${root_dir}/ascent-config.cmake
 
+if ${build_catalyst}; then
+    echo 'set(CATALYST_DIR ' ${catalyst_cmake_dir} ' CACHE PATH "")' >> ${root_dir}/ascent-config.cmake
+fi
+
 if [[ "$enable_cuda" == "ON" ]]; then
     echo 'set(ENABLE_CUDA ON CACHE BOOL "")' >> ${root_dir}/ascent-config.cmake
     echo 'set(CMAKE_CUDA_ARCHITECTURES ' ${CUDA_ARCH} ' CACHE PATH "")' >> ${root_dir}/ascent-config.cmake
@@ -681,10 +722,11 @@ cmake --build ${ascent_build_dir} --config ${build_config} -j${build_jobs}
 echo "**** Installing Ascent"
 cmake --install ${ascent_build_dir}  --config ${build_config}
 
+if ${build_catalyst}; then
+    mv ${ascent_install_dir}/lib/libcatalyst-ascent.so ${catalyst_install_dir}lib64/catalyst/libcatalyst-ascent.so
+fi
+
 fi
 else
   echo "**** Skipping Ascent build, install found at: ${ascent_install_dir}"
 fi # build_ascent
-
-
-

src/cmake/thirdparty/SetupCatalyst.cmake

@@ -20,6 +20,6 @@ if(NOT Catalyst_DIR)
     MESSAGE(FATAL_ERROR "Failed to find CATALYST at CATALYST_DIR=${CATALYST_DIR}")
 endif()
 
-find_package(Catalyst REQUIRED SDK)
+find_package(Catalyst REQUIRED COMPONENTS SDK)
 
 set(CATALYST_FOUND TRUE)

src/examples/CMakeLists.txt

@@ -26,11 +26,11 @@ if(BABELFLOW_FOUND)
 endif()
 
 # install using and python examples
-install(DIRECTORY using-with-cmake using-with-make python tutorial 
+install(DIRECTORY ascent-catalyst using-with-cmake using-with-make python tutorial 
         DESTINATION examples/ascent)
 
 if(MPI_FOUND)
-    install(DIRECTORY using-with-cmake-mpi using-with-make-mpi
+    install(DIRECTORY ascent-catalyst-mpi using-with-cmake-mpi using-with-make-mpi
             DESTINATION examples/ascent)
 endif()
 

src/examples/ascent-catalyst-mpi/CMakeLists.txt

@@ -0,0 +1,57 @@
+# Copyright (c) Lawrence Livermore National Security, LLC and other Ascent
+# Project developers. See top-level LICENSE AND COPYRIGHT files for dates and
+# other details. No copyright assignment is required to contribute to Ascent.
+###############################################################################
+
+###############################################################################
+#
+# Example that shows how to use an installed instance of Ascent in another
+# CMake-based build system.
+#
+# To build:
+#  cmake -DAscent_DIR={ascent install path} -B build -S .
+#  cp ascent_actions.yaml build
+#  cd build
+#  make
+#  ./ascent_catalyst_mpi_example
+#
+# In order to run directly in a sub directory below ascent-catalyst_mpi in an ascent install, 
+# set Ascent_DIR to ../../..
+# 
+#  cmake -DAscent_DIR=../../.. -B build -S .
+#  cp ascent_actions.yaml build
+#  cd build
+#  make
+#  ./ascent_catalyst_mpi_example
+#
+###############################################################################
+
+cmake_minimum_required(VERSION 3.9)
+
+project(ascent_catalyst_mpi)
+
+#
+# Use CMake's find_package to import ascent's targets
+#
+# PATHS is just a hint if someone runs this example from the Ascent install
+# tree without setting up an environment hint to find Ascent
+find_package(Ascent REQUIRED
+             NO_DEFAULT_PATH
+             PATHS ${CMAKE_SOURCE_DIR}/../../../)
+
+find_package(MPI REQUIRED COMPONENTS CXX)
+
+find_package(catalyst 2.0 REQUIRED)
+
+# create our example
+add_executable(ascent_catalyst_mpi_example ascent_catalyst_mpi_example.cpp)
+
+# link to ascent and catalyst
+target_link_libraries(ascent_catalyst_mpi_example ascent::ascent_mpi catalyst::catalyst)
+
+# if cuda is in the mix:
+# we need to make sure CUDA_RESOLVE_DEVICE_SYMBOLS is on for our target
+# (it propgates some way magically in 3.14, but not in 3.21)
+if(CMAKE_CUDA_COMPILER)
+    set_property(TARGET ascent_catalyst_mpi_example PROPERTY CUDA_RESOLVE_DEVICE_SYMBOLS ON)
+endif()

src/examples/ascent-catalyst-mpi/ascent_actions.yaml

@@ -0,0 +1,9 @@
+-
+  action: "add_scenes"
+  scenes:
+    s1:
+      plots:
+        p1:
+          type: "pseudocolor"
+          field: "braid"
+      image_name: "out_ascent_catalyst_mpi_example"

src/examples/ascent-catalyst-mpi/ascent_catalyst_mpi_example.cpp

@@ -0,0 +1,63 @@
+//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~//
+// Copyright (c) Lawrence Livermore National Security, LLC and other Ascent
+// Project developers. See top-level LICENSE AND COPYRIGHT files for dates and
+// other details. No copyright assignment is required to contribute to Ascent.
+//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~//
+
+//-----------------------------------------------------------------------------
+///
+/// file: ascent_catalyst_mpi_example.cpp
+///
+//-----------------------------------------------------------------------------
+
+#include <catalyst.h>
+#include <conduit_blueprint.hpp>
+#include <conduit_cpp_to_c.hpp>
+
+#include <mpi.h>
+#include <iostream>
+
+using namespace conduit;
+
+int main(int argc, char **argv)
+{
+    MPI_Init(&argc, &argv);
+
+    MPI_Comm mpi_comm = MPI_COMM_WORLD;
+    int par_rank, par_size;
+    MPI_Comm_rank(mpi_comm, &par_rank);
+    MPI_Comm_size(mpi_comm, &par_size);
+
+    // Custom catalyst implementations require that we use conduit's C API
+    conduit_node *initialize = conduit_node_create();
+    conduit_node_set_path_char8_str(initialize, "catalyst_load/implementation", "ascent");
+    conduit_node_set_path_char8_str(initialize, "catalyst/scripts/my_actions", "ascent_actions.yaml");
+    catalyst_initialize(initialize);
+
+    if (par_rank == 0)
+    {
+        conduit_node *about = conduit_node_create();
+        catalyst_about(about);
+        conduit_node_print(about);
+    }
+
+    // create an example dataset
+    conduit::Node mesh;
+    conduit::blueprint::mesh::examples::braid("uniform", 10, 10, 10, mesh);
+
+    // to make a multi domain example, offset the x coords by par_rank
+    mesh["coordsets/coords/origin/x"] = -10 + 20 * par_rank;
+
+    // We can still use conduit's C++ API
+    conduit::Node data;
+    data["catalyst/channels/grid/data"].set_external(mesh);
+
+    // We just have to convert cpp_nodes into c_nodes before passing them to catalyst
+    conduit_node *data_converted = c_node(&data);
+    catalyst_execute(data_converted);
+
+    conduit_node *finalize = conduit_node_create();
+    catalyst_finalize(finalize);
+
+    MPI_Finalize();
+}

src/examples/ascent-catalyst/CMakeLists.txt

@@ -0,0 +1,55 @@
+# Copyright (c) Lawrence Livermore National Security, LLC and other Ascent
+# Project developers. See top-level LICENSE AND COPYRIGHT files for dates and
+# other details. No copyright assignment is required to contribute to Ascent.
+###############################################################################
+
+###############################################################################
+#
+# Example that shows how to use an installed instance of Ascent in another
+# CMake-based build system.
+#
+# To build:
+#  cmake -DAscent_DIR={ascent install path} -B build -S .
+#  cp ascent_actions.yaml build
+#  cd build
+#  make
+#  ./ascent_catalyst_example
+#
+# In order to run directly in a sub directory below ascent-catalyst in an ascent install, 
+# set Ascent_DIR to ../../..
+# 
+#  cmake -DAscent_DIR=../../.. -B build -S .
+#  cp ascent_actions.yaml build
+#  cd build
+#  make
+#  ./ascent_catalyst_example
+#
+###############################################################################
+
+cmake_minimum_required(VERSION 3.9)
+
+project(ascent_catalyst)
+
+#
+# Use CMake's find_package to import ascent's targets
+#
+# PATHS is just a hint if someone runs this example from the Ascent install
+# tree without setting up an environment hint to find Ascent
+find_package(Ascent REQUIRED
+             NO_DEFAULT_PATH
+             PATHS ${CMAKE_SOURCE_DIR}/../../../)
+
+find_package(catalyst 2.0 REQUIRED)
+
+# create our example
+add_executable(ascent_catalyst_example ascent_catalyst_example.cpp)
+
+# link to ascent and catalyst
+target_link_libraries(ascent_catalyst_example ascent::ascent catalyst::catalyst)
+
+# if cuda is in the mix:
+# we need to make sure CUDA_RESOLVE_DEVICE_SYMBOLS is on for our target
+# (it propgates some way magically in 3.14, but not in 3.21)
+if(CMAKE_CUDA_COMPILER)
+    set_property(TARGET ascent_catalyst_example PROPERTY CUDA_RESOLVE_DEVICE_SYMBOLS ON)
+endif()

src/examples/ascent-catalyst/ascent_actions.yaml

@@ -0,0 +1,9 @@
+-
+  action: "add_scenes"
+  scenes:
+    s1:
+      plots:
+        p1:
+          type: "pseudocolor"
+          field: "braid"
+      image_name: "out_ascent_catalyst_example"

src/examples/ascent-catalyst/ascent_catalyst_example.cpp

@@ -0,0 +1,47 @@
+//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~//
+// Copyright (c) Lawrence Livermore National Security, LLC and other Ascent
+// Project developers. See top-level LICENSE AND COPYRIGHT files for dates and
+// other details. No copyright assignment is required to contribute to Ascent.
+//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~//
+
+//-----------------------------------------------------------------------------
+///
+/// file: ascent_catalyst_example.cpp
+///
+//-----------------------------------------------------------------------------
+
+#include <catalyst.h>
+#include <conduit_blueprint.hpp>
+#include <conduit_cpp_to_c.hpp>
+
+#include <iostream>
+
+using namespace conduit;
+
+int main(int argc, char **argv)
+{
+    // Custom catalyst implementations require that we use conduit's C API
+    conduit_node *initialize = conduit_node_create();
+    conduit_node_set_path_char8_str(initialize, "catalyst_load/implementation", "ascent");
+    conduit_node_set_path_char8_str(initialize, "catalyst/scripts/my_actions", "ascent_actions.yaml");
+    catalyst_initialize(initialize);
+
+    conduit_node *about = conduit_node_create();
+    catalyst_about(about);
+    conduit_node_print(about);
+
+    // create an example dataset
+    conduit::Node mesh;
+    conduit::blueprint::mesh::examples::braid("uniform", 10, 10, 10, mesh);
+
+    // We can still use conduit's C++ API
+    conduit::Node data;
+    data["catalyst/channels/grid/data"].set_external(mesh);
+
+    // We just have to convert cpp_nodes into c_nodes before passing them to catalyst
+    conduit_node *data_converted = c_node(&data);
+    catalyst_execute(data_converted);
+
+    conduit_node *finalize = conduit_node_create();
+    catalyst_finalize(finalize);
+}