Merge pull request #69 from LLNL/feature/elliott/bp-example

Feature/elliott/bp example

src/axom/sidre/docs/sphinx/sidre_conduit.rst

@@ -36,7 +36,7 @@ A simulation organizes its Sidre data as the code design dictates.
 Here is a simple example.
 
 .. image:: figs/ds.png
-   :width: 300px
+   :width: 650px
 
 Here is the code to create that Dataset ``ds``.
 
@@ -45,10 +45,9 @@ Here is the code to create that Dataset ``ds``.
    :end-before: _tiny_create_end
    :language: C++
 
-To use the Mesh Blueprint, make a new Datastore ``cds`` conforming to the protocol
-that points at the data of the original Datastore.  The structure of the
-conforming Datastore is shown below (summarizing the
-`Mesh Blueprint <http://llnl-conduit.readthedocs.io/en/latest/blueprint_mesh.html>`_
+To use the Mesh Blueprint, make a new Group ``tinymesh`` conforming to the protocol.
+The structure of the conforming Group is shown below (summarizing
+the `Mesh Blueprint <http://llnl-conduit.readthedocs.io/en/latest/blueprint_mesh.html>`_
 documentation).
 
 First build top-level groups required by the Blueprint.
@@ -61,9 +60,9 @@ First build top-level groups required by the Blueprint.
    :end-before: _blueprint_restructure_toplevel_end
    :language: C++
 
-Add the node coordinates.  The Groups in ``cds`` will use the Buffers within ``ds``
-as external pointers that have a description: while Sidre and Conduit will use the
-array type and shape information, ``cds`` will not deallocate the memory.
+Add the node coordinates.  The Views under ``tinymesh`` will point to the
+same Buffers that were created for the Views under ``nodes``
+so that ``tinymesh`` can use the data without any new allocation or copying.
 
 .. image:: figs/cdscoords.png
    :width: 650px
@@ -74,7 +73,7 @@ array type and shape information, ``cds`` will not deallocate the memory.
    :language: C++
 
 Arrange the nodes into elements.  Each simulation has its own knowledge of
-topology.  This tiny example doesn't encode topology in ``ds``,
+topology.  This tiny example didn't previously encode topology,
 so we must explicitly specify it.
 
 .. image:: figs/cdstopo.png
@@ -85,8 +84,8 @@ so we must explicitly specify it.
    :end-before: _blueprint_restructure_topo_end
    :language: C++
 
-Link the fields into ``cds``.  As with the node positions, ``cds`` gets an external
-pointer to the field data.
+Link the fields into ``tinymesh``.  As with the node positions, the Views
+point to the existing Buffers containing the field data.
 
 .. image:: figs/cdsfields.png
    :width: 650px
@@ -97,7 +96,7 @@ pointer to the field data.
    :language: C++
 
 Conduit includes a ``verify`` method to test if the structure
-of the ``cds`` conforms to the Mesh Blueprint.  This is valuable for writing and 
+of the ``tinymesh`` conforms to the Mesh Blueprint.  This is valuable for writing and 
 debugging data adapters.
 Once the Datastore is properly structured, save it, then use Conduit to save the 
 index file (ending with `.root`).  This toy data set is small enough that we can
@@ -113,7 +112,7 @@ Any code that uses Mesh Blueprint can open and use this pair of files.
 
 The DataStore also contains a method that can automatically generate the
 Blueprint index within a Sidre Group rather than calling directly into
-Conduit.  Set up a mesh similarly to the above.
+Conduit.  Set up a mesh similarly to the example above.
 
 .. literalinclude:: ../../examples/sidre_createdatastore.cpp
    :start-after: _blueprint_generate_toplevel_start

src/axom/sidre/examples/sidre_createdatastore.cpp

@@ -253,6 +253,28 @@ void setup_blueprint_coords(DataStore* ds, Group* coords)
   // We use prior knowledge of the layout of the original datastore
   View* origv = ds->getRoot()->getView("nodes/xs");
   Group* conduitval = coords->createGroup("values");
+  conduitval->createView("x", sidre::DOUBLE_ID,
+                         origv->getNumElements(),
+                         origv->getBuffer());
+  origv = ds->getRoot()->getView("nodes/ys");
+  conduitval->createView("y", sidre::DOUBLE_ID,
+                         origv->getNumElements(),
+                         origv->getBuffer());
+  origv = ds->getRoot()->getView("nodes/zs");
+  conduitval->createView("z", sidre::DOUBLE_ID,
+                         origv->getNumElements(),
+                         origv->getBuffer());
+  // _blueprint_restructure_coords_end
+}
+
+void setup_blueprint_external_coords(DataStore* ds, Group* coords)
+{
+  // _blueprint_external_coords_start
+  // Set up the coordinates as Mesh Blueprint requires
+  coords->createViewString("type", "explicit");
+  // We use prior knowledge of the layout of the original datastore
+  View* origv = ds->getRoot()->getView("nodes/xs");
+  Group* conduitval = coords->createGroup("values");
   conduitval->createView("x", sidre::DOUBLE_ID,
                          origv->getNumElements(),
                          static_cast<double*>(origv->getArray()));
@@ -264,7 +286,7 @@ void setup_blueprint_coords(DataStore* ds, Group* coords)
   conduitval->createView("z", sidre::DOUBLE_ID,
                          origv->getNumElements(),
                          static_cast<double*>(origv->getArray()));
-  // _blueprint_restructure_coords_end
+  // _blueprint_external_coords_end
 }
 
 void setup_blueprint_topos(DataStore* ds, Group* topos)
@@ -314,6 +336,33 @@ void setup_blueprint_fields(DataStore* ds, Group* fields)
   nodefield->createViewString("association", "vertex");
   nodefield->createViewString("type", "scalar");
   nodefield->createViewString("topology", "mesh");
+  nodefield->createView("values", sidre::INT_ID,
+                        origv->getNumElements(),
+                        origv->getBuffer());
+
+  // Set up the element-centered field
+  // Get the original data
+  origv = ds->getRoot()->getView("fields/eltfield");
+  Group* eltfield = fields->createGroup("eltfield");
+  eltfield->createViewString("association", "element");
+  eltfield->createViewString("type", "scalar");
+  eltfield->createViewString("topology", "mesh");
+  eltfield->createView("values", sidre::DOUBLE_ID,
+                       origv->getNumElements(),
+                       origv->getBuffer());
+  // _blueprint_restructure_field_end
+}
+
+void setup_blueprint_external_fields(DataStore* ds, Group* fields)
+{
+  // _blueprint_external_field_start
+  // Set up the node-centered field
+  // Get the original data
+  View* origv = ds->getRoot()->getView("fields/nodefield");
+  Group* nodefield = fields->createGroup("nodefield");
+  nodefield->createViewString("association", "vertex");
+  nodefield->createViewString("type", "scalar");
+  nodefield->createViewString("topology", "mesh");
   nodefield->createView("values", sidre::INT_ID,
                         origv->getNumElements(),
                         static_cast<int*>(origv->getArray()));
@@ -328,19 +377,18 @@ void setup_blueprint_fields(DataStore* ds, Group* fields)
   eltfield->createView("values", sidre::DOUBLE_ID,
                        origv->getNumElements(),
                        static_cast<double*>(origv->getArray()));
-  // _blueprint_restructure_field_end
+  // _blueprint_external_field_end
 }
 
 void save_as_blueprint(DataStore* ds) {
   // _blueprint_restructure_toplevel_start
   // Conduit needs a specific hierarchy.
   // We'll make a new DataStore with that hierarchy, pointing at the
   // application's data.
-  DataStore cds;
   std::string mesh_name = "tinymesh";
 
   // The Conduit specifies top-level groups:
-  Group* mroot = cds.getRoot()->createGroup(mesh_name);
+  Group* mroot = ds->getRoot()->createGroup(mesh_name);
   Group* coords = mroot->createGroup("coordsets/coords");
   Group* topos = mroot->createGroup("topologies");
   // no material sets in this example
@@ -356,7 +404,7 @@ void save_as_blueprint(DataStore* ds) {
 
   // _blueprint_restructure_save_start
   conduit::Node info, mesh_node, root_node;
-  cds.getRoot()->createNativeLayout(mesh_node);
+  ds->getRoot()->createNativeLayout(mesh_node);
   std::string bp_protocol = "mesh";
   if (conduit::blueprint::verify(bp_protocol, mesh_node[mesh_name], info))
   {
@@ -393,15 +441,14 @@ void save_as_blueprint(DataStore* ds) {
 void generate_blueprint(DataStore* ds) {
   // _blueprint_generate_toplevel_start
   // Conduit needs a specific hierarchy.
-  // We'll make a new DataStore with that hierarchy, pointing at the
+  // We'll make a new Group with that hierarchy, pointing at the
   // application's data.
-  DataStore cds;
   std::string domain_name = "domain";
   std::string domain_location = "domain_data/" + domain_name;
   std::string mesh_name = "mesh";
   std::string domain_mesh = domain_location + "/" + mesh_name;
 
-  Group* mroot = cds.getRoot()->createGroup(domain_location);
+  Group* mroot = ds->getRoot()->createGroup(domain_location);
   Group* coords = mroot->createGroup(mesh_name + "/coordsets/coords");
   Group* topos = mroot->createGroup(mesh_name + "/topologies");
   // no material sets in this example
@@ -417,15 +464,15 @@ void generate_blueprint(DataStore* ds) {
 
   // _blueprint_generate_save_start
   conduit::Node info, mesh_node, root_node;
-  cds.getRoot()->createNativeLayout(mesh_node);
+  ds->getRoot()->createNativeLayout(mesh_node);
   std::string bp_protocol = "mesh";
   if (conduit::blueprint::verify(bp_protocol, mesh_node[domain_mesh], info))
   {
     std::string bp("rootfile_data/blueprint_index/automesh");
 
-    cds.generateBlueprintIndex(domain_mesh, mesh_name, bp, 1);
+    ds->generateBlueprintIndex(domain_mesh, mesh_name, bp, 1);
 
-    Group* rootfile_grp = cds.getRoot()->getGroup("rootfile_data");
+    Group* rootfile_grp = ds->getRoot()->getGroup("rootfile_data");
     rootfile_grp->createViewString("protocol/name", "json");
     rootfile_grp->createViewString("protocol/version", "0.1");
     rootfile_grp->createViewScalar("number_of_files", 1);
@@ -434,7 +481,7 @@ void generate_blueprint(DataStore* ds) {
     rootfile_grp->createViewScalar("tree_pattern", "/domain");
     rootfile_grp->save("bpgen.root", "json");
 
-    cds.getRoot()->getGroup("domain_data")->save("bpgen.json", "json");
+    ds->getRoot()->getGroup("domain_data")->save("bpgen.json", "json");
   }
   else
   {
@@ -450,13 +497,12 @@ void generate_blueprint_to_path(DataStore* ds) {
   // Conduit needs a specific hierarchy.
   // For this example, we locate the domain data at a path
   // that is not the top level of its Sidre heirarchy.
-  DataStore cds;
   std::string domain_name = "domain";
   std::string domain_location = "domain_data/level/domains/" + domain_name;
   std::string mesh_name = "pathmesh";
   std::string domain_mesh = domain_location + "/" + mesh_name;
 
-  Group* mroot = cds.getRoot()->createGroup(domain_location);
+  Group* mroot = ds->getRoot()->createGroup(domain_location);
   Group* coords = mroot->createGroup(mesh_name + "/coordsets/coords");
   Group* topos = mroot->createGroup(mesh_name + "/topologies");
   // no material sets in this example
@@ -472,15 +518,15 @@ void generate_blueprint_to_path(DataStore* ds) {
 
   // _blueprint_generate_path_save_start
   conduit::Node info, mesh_node, root_node;
-  cds.getRoot()->createNativeLayout(mesh_node);
+  ds->getRoot()->createNativeLayout(mesh_node);
   std::string bp_protocol = "mesh";
   if (conduit::blueprint::verify(bp_protocol, mesh_node[domain_mesh], info))
   {
     std::string bp("rootfile_data/blueprint_index/automesh");
 
-    cds.generateBlueprintIndex(domain_mesh, mesh_name, bp, 1);
+    ds->generateBlueprintIndex(domain_mesh, mesh_name, bp, 1);
 
-    Group* rootfile_grp = cds.getRoot()->getGroup("rootfile_data");
+    Group* rootfile_grp = ds->getRoot()->getGroup("rootfile_data");
     rootfile_grp->createViewString("protocol/name", "json");
     rootfile_grp->createViewString("protocol/version", "0.1");
     rootfile_grp->createViewScalar("number_of_files", 1);
@@ -489,7 +535,7 @@ void generate_blueprint_to_path(DataStore* ds) {
     rootfile_grp->createViewScalar("tree_pattern", "level/domains/domain");
     rootfile_grp->save("pathbp.root", "json");
 
-    cds.getRoot()->getGroup("domain_data")->save("pathbp.json", "json");
+    ds->getRoot()->getGroup("domain_data")->save("pathbp.json", "json");
   }
   else
   {
@@ -503,13 +549,12 @@ void generate_blueprint_to_path(DataStore* ds) {
 #ifdef AXOM_USE_MPI
 void generate_spio_blueprint(DataStore* ds) {
   // _blueprint_spio_toplevel_start
-  DataStore cds;
   std::string domain_name = "domain";
   std::string domain_location = "domain_data/" + domain_name;
   std::string mesh_name = "mesh";
   std::string domain_mesh = domain_location + "/" + mesh_name;
 
-  Group* mroot = cds.getRoot()->createGroup(domain_location);
+  Group* mroot = ds->getRoot()->createGroup(domain_location);
   Group* coords = mroot->createGroup(mesh_name + "/coordsets/coords");
   Group* topos = mroot->createGroup(mesh_name + "/topologies");
   // no material sets in this example
@@ -527,17 +572,17 @@ void generate_spio_blueprint(DataStore* ds) {
   IOManager writer(MPI_COMM_WORLD);
 
   conduit::Node info, mesh_node, root_node;
-  cds.getRoot()->createNativeLayout(mesh_node);
+  ds->getRoot()->createNativeLayout(mesh_node);
   std::string bp_protocol = "mesh";
   if (conduit::blueprint::verify(bp_protocol, mesh_node[domain_mesh], info))
   {
 
     std::string bp_rootfile("bpspio.root");
 
-    writer.write(cds.getRoot()->getGroup(
+    writer.write(ds->getRoot()->getGroup(
                    domain_location), 1, "bpspio", "sidre_hdf5");
 
-    writer.writeBlueprintIndexToRootFile(&cds, domain_mesh, bp_rootfile,
+    writer.writeBlueprintIndexToRootFile(ds, domain_mesh, bp_rootfile,
                                          mesh_name);
 
   }
@@ -547,41 +592,40 @@ void generate_spio_blueprint(DataStore* ds) {
 
 void generate_spio_blueprint_to_path(DataStore* ds) {
   // _blueprint_spio_path_start
-  DataStore cds;
   std::string domain_name = "domain";
   std::string domain_location = "domain_data/level/domains/" + domain_name;
   std::string mesh_name = "spiopathmesh";
   std::string domain_mesh = domain_location + "/" + mesh_name;
 
-  Group* mroot = cds.getRoot()->createGroup(domain_location);
+  Group* mroot = ds->getRoot()->createGroup(domain_location);
   Group* coords = mroot->createGroup(mesh_name + "/coordsets/coords");
   Group* topos = mroot->createGroup(mesh_name + "/topologies");
   // no material sets in this example
   Group* fields = mroot->createGroup(mesh_name + "/fields");
   // no adjacency sets in this (single-domain) example
   // _blueprint_spio_path_end
 
-  setup_blueprint_coords(ds, coords);
+  setup_blueprint_external_coords(ds, coords);
 
   setup_blueprint_topos(ds, topos);
 
-  setup_blueprint_fields(ds, fields);
+  setup_blueprint_external_fields(ds, fields);
 
   // _blueprint_generate_spio_path_start
   IOManager writer(MPI_COMM_WORLD);
 
   conduit::Node info, mesh_node, root_node;
-  cds.getRoot()->createNativeLayout(mesh_node);
+  ds->getRoot()->createNativeLayout(mesh_node);
   std::string bp_protocol = "mesh";
   if (conduit::blueprint::verify(bp_protocol, mesh_node[domain_mesh], info))
   {
 
     std::string bp_rootfile("pathbpspio.root");
 
-    writer.write(cds.getRoot()->getGroup(
+    writer.write(ds->getRoot()->getGroup(
                    "domain_data"), 1, "pathbpspio", "sidre_hdf5");
 
-    writer.writeBlueprintIndexToRootFile(&cds, domain_mesh, bp_rootfile,
+    writer.writeBlueprintIndexToRootFile(ds, domain_mesh, bp_rootfile,
                                          "level/domains/domain/" + mesh_name);
 
   }