Strawman API¶

Open¶

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;

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

strawman.Open(strawman_options);

Valid pipelines and backends include:

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

Publish¶

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/time"].set_external(&m_time);
mesh_data["state/cycle"].set_external(&m_cycle);
mesh_data["state/domain"] = myRank;

// coordinate system data
mesh_data["coordsets/coords/type"] = "explicit";
mesh_data["coordsets/coords/x"].set_external(m_x);
mesh_data["coordsets/coords/y"].set_external(m_y);
mesh_data["coordsets/coords/z"].set_external(m_z);

// topology data
mesh_data["topologies/mesh/type"] = "unstructured";
mesh_data["topologies/mesh/coordset"] = "coords";
mesh_data["topologies/mesh/elements/shape"] = "hexs";
mesh_data["topologies/mesh/elements/connectivity"].set_external(m_nodelist);

// one or more scalar fields
mesh_data["fields/p/type"]        = "scalar";
mesh_data["fields/p/topology"]    = "mesh";
mesh_data["fields/p/association"] = "element";
mesh_data["fields/p/values"].set_external(m_p);

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;
if(!conduit::blueprint::mesh::verify(mesh_data,verify_info))
{
    // verify failed, print error message
    STRAWMAN_INFO("Error: Mesh Blueprint Verify Failed!");
    // show details of what went awry
    verify_info.print();
}

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

straman.Publish(mesh_data);

Publish is called each cycle where Strawman is used.

Execute¶

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";
strawman.Publish(mesh_data);
strawman.Execute(actions);

Close¶

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

strawman.Close();

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.