Ascent API

The top level API for ascent consists of four calls:

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


Open provides the initial setup of Ascent from a Conduit Node. Options include runtime type (e.g., ascent, flow, or empty) and associated backend if available. If running in parallel (i.e., MPI), then a MPI comm handle must be supplied. Ascent will always check the file system for a file called ascent_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 runtime to the main ascent runtime using a TBB backend (inside VTK-m):

  "runtime/type"    : "ascent",
  "runtine/backend" : "tbb"

A typical integration will include the following code:

Ascent ascent;
conduit::Node ascent_options;

ascent_options["mpi_comm"] = MPI_Comm_c2f(MPI_COMM_WORLD);
ascent_options["runtime/type"] = "ascent";
ascent_options["runtime/backend"] = "tbb";


Valid runtimes include:

  • ascent
  • flow
  • empty

There are a few other options that control behaviors common to all runtimes:

  • messages

    Controls if logged info messages are printed or muted.

    Supported values:

    • quiet (default if omitted) Logged info messages are muted
    • verbose Logged info messages are printed
  • exceptions

    Controls if Ascent traps or forwards C++ exceptions that are thrown.

    Supported values:

    • forward (default if omitted) Exceptions thrown will propagate to the calling code
    • catch Catches conduit::Error exceptions at the Ascent interface and prints info about the error to standard out. This case this provides an easy way to prevent host program crashes when something goes wrong in Ascent.


This call publishes data to Ascent 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_id"] = 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
    ASCENT_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 Ascent 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 Ascent Actions Overview.

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

// In the main simulation loop
conduit::Node actions;

// create a one scene with one plot
conduit::Node scenes;
scenes["s1/plots/p1/type"] = "pseudocolor";
scenes["s1/plots/p1/params/field"] = "braid";

// add the scenes and execute
conduit::Node &add_plots = actions.append();
add_plots["action"] = "add_scenes";
add_plots["scenes"] = scenes;
conduit::Node &execute = actions.append();
execute["action"] = "execute";



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


Error Handling

Ascent 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. You can also stop exceptions at the Ascent interface using the exceptions option for Ascent::open .