Strawman API

The top level API for strawman consists of four calls:

  • Open(condiut::Node)
  • Publish(conduit::Node)
  • Execute(conduit::Node)
  • Close()


Open provides the initial setup of Strawman from a Conduit Node. Options include pipeline type (e.g., VTK-m, Blueprint HDF5, or EAVL) and associated backend if available. If running in parallel (i.e., MPI), then a MPI comm handle must be supplied. Strawman will always check the file system for a file called strawman_options.json that will override compiled in options, and for obvious reasons, a MPI communicator cannot be specified in the file. Here is a file that would set the pipeline to VTK-m using a TBB backend:

  "pipeline/type"    : "vtkm",
  "pipeline/backend" : "tbb"

A typical integration will include the following code:

Strawman strawman;
conduit::Node strawman_options;

strawman_options["mpi_comm"] = MPI_Comm_c2f(MPI_COMM_WORLD);
strawman_options["pipeline/type"] = "vtkm";
strawman_options["pipeline/backend"] = "tbb";


Valid pipelines and backends include:

  • vtkm
    • serial
    • cuda
    • tbb
  • EAVL
    • cpu (will use OpenMP if configured)
    • cuda
  • hdf5


This call publishes data to Strawman through Conduit Blueprint mesh descriptions. In the Lulesh prox-app, data is already in a form that is compatible with the blueprint conventions and the code to create the Conduit Node is straight-forward:

// provide state information
mesh_data["state/domain"] = myRank;

// coordinate system data
mesh_data["coordsets/coords/type"] = "explicit";

// topology data
mesh_data["topologies/mesh/type"] = "unstructured";
mesh_data["topologies/mesh/coordset"] = "coords";
mesh_data["topologies/mesh/elements/shape"] = "hexs";

// one or more scalar fields
mesh_data["fields/p/type"]        = "scalar";
mesh_data["fields/p/topology"]    = "mesh";
mesh_data["fields/p/association"] = "element";

If the data does not match the blueprint mesh conventions, then you must transform the data into a compatible format.

You can check if a node confirms to the mesh blueprint using the verify function provided by conduit.

#include <conduit_blueprint.hpp>

Node verify_info;
    // verify failed, print error message
    STRAWMAN_INFO("Error: Mesh Blueprint Verify Failed!");
    // show details of what went awry

Once the Conduit Node has been populated with data conforming to the mesh blueprint, simply publish the data using the Publish call:


Publish is called each cycle where Strawman is used.


Execute applies some number of actions to published data. Each action is described inside of a Conduit Node and passed to the Execute call. For a full description of supported actions see Strawman Actions Overview.

Here is a simple example of adding a plot using the C++ API:

// In the main simulation loop
conduit::Node actions;
conduit::Node &plot = actions.append();
plot["action"] = "add_plot";
plot["field_name"] = "p";
conduit::Node &draw = actions.append();
draw["action"] = "draw_plots";


Close informs Strawman that all actions are complete, and the call performs the appropriate clean-up.


Error Handling

Strawman uses Conduit’s error handling machinery. By default when errors occur C++ exceptions are thrown, but you can rewire Conduit’s handlers with your own callbacks. For more info see the Conduit Error Handling Tutorial.