Catalyst for Simulation Developers¶
This section describes how simulation (and other computational codes) can use Catalyst.
Building with Catalyst¶
To use the Catalyst API in any code, the code must be built against an implementation of the Catalyst API. While one can use any implementation of the Catalyst API, the stub implementation is probably the easiest to build against since it doesn’t have any external dependencies besides compiler tools.
If your code already uses CMake as the build system generator, then to use
Catalyst APIs, you simply need to find the Catalyst install using
and the link against the
catalyst::catalyst target. This is done as follows:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
# Find the Catalyst install. # # The version is optional but recommended since it lets you choose # the compatibility version. The only supported value currently is 2.0 # # REQUIRED ensures that CMake raises errors if Catalyst is not found # properly. find_package(catalyst 2.0 REQUIRED) # Your simulation will have an executable (or a library) that # houses the main-loop in which you'll make the Catalyst API falls. # You need to link that executable (or the library) target with Catalyst. # This is done as follows (where simulation_target must be replaced by the # name of the correct executable (or library) target. target_link_library(simulation_target PRIVATE catalyst::catalyst)
Now, when you run
cmake on your simulation code, a new cache variable
catalyst_DIR can be set to the directory containing the file
to help CMake find where you built Catalyst. That file can be found in either the
Catalyst build directory or the Catalyst install directory.
Using make (or similar)¶
If not using CMake as the build system generator for your simulation code, it is still easy to make it aware of Catalyst. You simply need to pass the include path i.e. the location where the Catalyst headers are available, and the location and library to link against.
In a typical Catalyst install at location,
CATALYST_INSTALL_PREFIX, these are:
- Include path:
- Library path:
gcc, for example, this translates to the following command-line:
[TODO: fix me]
Catalyst API is used by simulations to invoke Catalyst for co-processing. To use
the Catalyst API, one must include the
catalyst.h header file.
enum catalyst_status catalyst_initialize(const conduit_node* params);
This function must be called once to initialize Catalyst. Metadata that can be
used to configure the initialize is provided using a
The catalyst will attempt to load the implementation named using
params["catalyst_load/implementation"]. If not specified, but the
CATALYST_IMPLEMENTATION_NAME environment variable is, it will be used. If
no implementation is named, a default implementation using the stub functions
will be used.
If an implementation is named, it will be loaded at runtime using
(or the platform equivalent) by searching the nodes specified under the
params["catalyst_load/search_paths"] node. Next, the paths specified by
; as a separator on Windows
: otherwise) will be searched. Finally, the
libcatalyst will be searched. Once found, it will be loaded and
inspected for compatibility. If it is compatible, the implementation will be
loaded and made available. The return code indicates the error received, if
The search priority of the
CATALYST_IMPLEMENTATION_ environment variables
may be made first by setting teh
environment variable to a non-empty value.
enum catalyst_status catalyst_finalize(const conduit_node* params);
This function must be called once to finalize Catalyst. Metadata is passed using
enum catalyst_status catalyst_execute(const conduit_node* params);
This function is called for every time step as the simulation advances. This is
the call in which the analysis may execute.
params provides metadata as well
as the data generated by the simulation for that time-step.
enum catalyst_status catalyst_about(conduit_node* params);
This function fills up the
params instance with metadata about the Catalyst
library being used.
enum catalyst_status catalyst_results(conduit_node* params);
This function fills up the
params instance with updated parameters values
from the Catalyst implementation side.
All the above functions use a
params object which is a conduit_node. It is
simply a hierarchical mechanism for describing data and/or metadata including
simulation meshes and fields. Essentially, think of it as a map where keys are
strings called paths and values are either data or pointers to data. What these
keys can be and what they mean is totally up to the Catalyst API implementation
To create and populate the
conduit_node instance, you use the Conduit
conduit_node* node = conduit_node_create(); conduit_node_set_path_int(node, "sim/timestep", 0); conduit_node_set_path_double(node, "sim/time", 1.212); ... conduit_node_destroy(node);
Refer to Conduit documentation for details of the
C API. [TODO: there are
no docs for Conduit C API upstream].