# Strawman API¶

The top level API for strawman consists of four calls:

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

## 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["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.