Blueprint

The flexibility of the Conduit Node allows it to be used to represent a wide range of scientific data. Unconstrained, this flexibly can lead to many application specific choices for common types of data that could potentially be shared between applications.

The goal of Blueprint is to help facilite a set of shared higher-level conventions for using Conduit Nodes to hold common simulation data structures. The Blueprint library in Conduit provides methods to verify if a Conduit Node instance conforms to known conventions, which we call protocols. It also provides property and transform methods that can be used on conforming Nodes.

For now, Blueprint is focused on conventions for two important types of data:

  • Computational Meshes (protocol: mesh)

    Many taxonomies and concrete mesh data models have been developed to allow computational meshes to be used in software. Blueprint’s conventions for representing mesh data were formed by negotiating with simulation application teams at LLNL and from a survey of existing projects that provide scientific mesh-related APIs including: ADIOS, Damaris, EAVL, MFEM, Silo, VTK, VTKm, and Xdmf. Blueprint’s mesh conventions are not a replacement for existing mesh data models or APIs. Our explicit goal is to outline a comprehensive, but small set of options for describing meshes in-core that simplifies the process of adapting data to several existing mesh-aware APIs.

  • One-to-Many Relations (protocol: o2mrelation)

    A one-to-many relation is a collection of arbitrarily grouped values that encode element associations from a source (“one”s) to a destination (“many”s) space. These constructs are used in computational meshes to represent sparse material data, polygonal/polyhedral topologies, and other non-uniform mappings.

  • Multi-Component Arrays (protocol: mcarray)

    A multi-component array is a collection of fixed-sized numeric tuples. They are used in the context computational meshes to represent coordinate data or field data, such as the three directional components of a 3D velocity field. There are a few common in-core data layouts used by several APIs to accept multi-component array data, these include: row-major vs column-major layouts, or the use of arrays of struct vs struct of arrays in C-style languages. Blueprint provides transforms that convert any multi-component array to these common data layouts.

Top Level Blueprint Interface

Blueprint provides a generic top level verify() method, which exposes the verify checks for all supported protocols.

bool conduit::blueprint::verify(const std::string &protocol,
                                const Node &node,
                                Node &info);

verify() returns true if the passed Node node conforms to the named protocol. It also provides details about the verification, including specific errors in the passed info Node.

// setup our candidate and info nodes
Node n, info;

//create an example mesh
conduit::blueprint::mesh::examples::braid("tets",
                                           5,5,5,
                                           n);
// check if n conforms
if(conduit::blueprint::verify("mesh",n,info))
    std::cout << "mesh verify succeeded." << std::endl;
else
    std::cout << "mesh verify failed!" << std::endl;

// show some of the verify details
info["coordsets"].print();
mesh verify succeeded.

valid: "true"
coords: 
  type: 
    valid: "true"
  info: 
    - "mesh::coordset::explicit: 'type' has valid value 'explicit'"
    - "mesh::coordset::explicit: 'values' is an mcarray"
  values: 
    valid: "true"
  valid: "true"

Methods for specific protocols are grouped in namespaces:

// setup our candidate and info nodes
Node n, verify_info, mem_info;

// create an example mcarray
conduit::blueprint::mcarray::examples::xyz("separate",5,n);

std::cout << "example 'separate' mcarray " << std::endl;
n.print();
n.info(mem_info);
mem_info.print();

// check if n conforms
if(conduit::blueprint::verify("mcarray",n,verify_info))
{
    // check if our mcarray has a specific memory layout 
    if(!conduit::blueprint::mcarray::is_interleaved(n))
    {
        // copy data from n into the desired memory layout
        Node xform;
        conduit::blueprint::mcarray::to_interleaved(n,xform);
        std::cout << "transformed to 'interleaved' mcarray " << std::endl;
        xform.print_detailed();
        xform.info(mem_info);
        mem_info.print();
    }
}
example 'separate' mcarray 

x: [1.0, 1.0, 1.0, 1.0, 1.0]
y: [2.0, 2.0, 2.0, 2.0, 2.0]
z: [3.0, 3.0, 3.0, 3.0, 3.0]


mem_spaces: 
  0x7fc814e00960: 
    path: "x"
    type: "allocated"
    bytes: 40
  0x7fc814e00a60: 
    path: "y"
    type: "allocated"
    bytes: 40
  0x7fc814e00bc0: 
    path: "z"
    type: "allocated"
    bytes: 40
total_bytes_allocated: 120
total_bytes_mmaped: 0
total_bytes_compact: 120
total_strided_bytes: 120

transformed to 'interleaved' mcarray 

{
  "x": 
{
"dtype":"float64",
"number_of_elements": 5,
"offset": 0,
"stride": 24,
"element_bytes": 8,
"endianness": "little"
, "value": [1.0, 1.0, 1.0, 1.0, 1.0]},
  "y": 
{
"dtype":"float64",
"number_of_elements": 5,
"offset": 8,
"stride": 24,
"element_bytes": 8,
"endianness": "little"
, "value": [2.0, 2.0, 2.0, 2.0, 2.0]},
  "z": 
{
"dtype":"float64",
"number_of_elements": 5,
"offset": 16,
"stride": 24,
"element_bytes": 8,
"endianness": "little"
, "value": [3.0, 3.0, 3.0, 3.0, 3.0]}
}

mem_spaces: 
  0x7fc814e027e0: 
    path: ""
    type: "allocated"
    bytes: 120
total_bytes_allocated: 120
total_bytes_mmaped: 0
total_bytes_compact: 120
total_strided_bytes: 312