.. _catalyst: ******** Catalyst ******** `Catalyst `_ is an API specification developed for simulations to analyze and visualize data in situ. The generic Catalyst plugin is designed to provide in situ data visualization and processing capability to the fully coupled Earth system modeling applications or individual model components that use `ESMF (Earth System Modeling Framework) `_ and `NUOPC (National Unified Operational Prediction Capability) Layer `_. ======================================== Plugin Specific Third-party Dependencies ======================================== Catalyst plugin requires following third-party libraries/tools to function: - `Conduit Library `_ - `libcatalyst (>2.0) `_ - `ParaView `_ .. note:: All dependencies can be installed using `Spack `_ package manager. Please refer to Installation section for more detail. ============================================= Building GeoGate with Catalyst Plugin Support ============================================= To build Catalyst plugin user needs to provide ``-DGEOGATE_USE_CATALYST=ON`` CMake option in build time. Otherwise, GeoGate will not build with Catalyst plugin support. ============================= Runtime Configuration Options ============================= In GeoGate, each specific plugin has its own set of runtime configuration options. For Catalyst, users can provide the following options: - **CatalystConvertToCart:** This option allows for the conversion of latitude and longitude-based coordinates into Cartesian coordinates, specifically designed for global applications. This capability enables ParaView to visualize data on a spherical surface. - **CatalystScript:** This option allows users to provide a list of Catalyst Python scripts, which can either be generated by the ParaView Catalyst plugin or created manually. The list can be provided as a double-column-separated list like ``"scriptA.py:scriptB.py"``. In addition to the runtime configuration options, 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. Then, the catalyst scripts that are provided by the ``CatalystScript`` runtime configuration option can be applied to the data provided by the other components. - **CATALYST_IMPLEMENTATION_NAME:** If no implementation is named, a default implementation ``paraview`` is used. - **CATALYST_IMPLEMENTATION_PATHS:** The paths specified by the environment variable (using ``;`` as a separator on Windows and ``:`` otherwise) will be searched to find ParaView Catalyst library. .. note:: More information regarding ParaView Catalyst can be found in its documentation `_. ============================================== Creating Catalyst Python Script using ParaView ============================================== To specify the visualization or co-processing pipelines executed each time Catalyst is triggered, user needs to provide Python script/s directly or generate one interactively through the ParaView UI. This can be done in two-steps: **1.** The Catalyst plugin-enabled application can be run with the script to export available data in one of the supported VTK formats. For this purpose, the script (`catalyst_grid_writer.py `_) found in the GeoGateApps repository can be used. Once the application is run, the script writes the data flowing from each connected component to the disk in parallel. Then, the data can be used to create a visualization or co-processing pipeline by ParaView UI. .. note:: The ``catalystChannelList`` options in the script can be modified to define a list of channels that will be written to the disk. The names of the channels are the same ones specified for each component in the ESMF run sequence. The ``frequency`` option is used to define the interval to write the data to disk, and it is set to 1 by default, which means the data will be written in each coupling interval. .. note:: Also, note that the configuration used to create VTK files needs to be the same as the target application that will use the ParaView UI-created Catalyst pipeline scripts. **2.** Once the data files are written, the desired Catalyst pipeline can be generated as usual by using the ParaView UI. Once the pipeline is finalized, the user needs to append extractor(s) at the end of each pipeline. Extractors can be created through the Extractors menu and allow you 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 can be supplied to the GeoGate through the use of the ``CatalystScript`` runtime configuration option. .. note:: For more details see the `ParaView documentation `_ and specifically the `extractors section `_ in the ParaView User Guide. =========== Limitations =========== The Catalyst plugin can process meshes in quad formats, which include regular lat-lon, curvilinear, and tricolor meshes, as well as tri formats, which refer to unstructured ocean models using triangular mesh construction, along with their combinations. Plans are in place to support higher-order meshes, such as hexagonal structures, in the future. Currently, the implementation only processes two-dimensional (2D) data. Efforts are underway to enable support for three-dimensional (3D) data from connected model components.