MFEM  v4.2.0
Finite element discretization library
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Pages
conduitdatacollection.hpp
Go to the documentation of this file.
1 // Copyright (c) 2010-2020, Lawrence Livermore National Security, LLC. Produced
2 // at the Lawrence Livermore National Laboratory. All Rights reserved. See files
3 // LICENSE and NOTICE for details. LLNL-CODE-806117.
4 //
5 // This file is part of the MFEM library. For more information and source code
6 // availability visit https://mfem.org.
7 //
8 // MFEM is free software; you can redistribute it and/or modify it under the
9 // terms of the BSD-3 license. We welcome feedback and contributions, see file
10 // CONTRIBUTING.md for details.
11 
12 #ifndef MFEM_CONDUITDATACOLLECTION
13 #define MFEM_CONDUITDATACOLLECTION
14 
15 #include "../config/config.hpp"
16 
17 #ifdef MFEM_USE_CONDUIT
18 
19 #include "datacollection.hpp"
20 #include <conduit.hpp>
21 
22 namespace mfem
23 {
24 
25 /** @brief Data collection that uses the Conduit Mesh Blueprint
26  specification. */
27 /** ConduitDataCollection provides json, simple binary, and HDF5-based file
28  formats for visualization or restart. It also provides methods that convert
29  between MFEM Meshes and GridFunctions and Conduit Mesh Blueprint
30  descriptions.
31 
32  For more information, see:
33  - LLNL conduit project, https://github.com/LLNL/conduit
34  - HDF5 library, https://support.hdfgroup.org/HDF5
35 
36  @note The ConduitDataCollection only wraps the mfem objects to save them and
37  creates them on load, Conduit does not own any of the data. The
38  SidreDataCollection provides more features, for example the
39  SidreDataCollection allocates and will own the data backing the mfem objects
40  in the data collection.
41 
42  This class also provides public static methods that convert between MFEM
43  Meshes and GridFunctions and Conduit Mesh Blueprint descriptions.
44 
45  Those that describe MFEM data using Conduit (MFEM to Conduit Blueprint) try
46  to zero-copy as much of data MFEM as possible. The Conduit node result will
47  not own all of the data, however you can easily make a copy of the result
48  node using Conduit's API when necessary.
49 
50  Those that construct MFEM objects from Conduit Nodes (Conduit Blueprint to
51  MFEM) provide a zero-copy option. Zero-copy is only possible if the
52  blueprint data matches the data types provided by the MFEM API, for example:
53  ints for connectivity arrays, doubles for field value arrays, allocations
54  that match MFEM's striding options, etc. If these constraints are not met,
55  MFEM objects that own the data are created and returned. In either case
56  pointers to new MFEM object instances are returned, the zero-copy only
57  applies to data backing the MFEM object instances.
58 
59  @note QuadratureFunction%s (q-fields) are not supported.
60 
61  @note AMR Meshes are not fully supported.
62 
63  @warning This class is still _experimental_, meaning that in future
64  releases, it may not be backward compatible, and the output files generated
65  by the current version may become unreadable.
66 */
67 
68 /// Data collection with Conduit I/O routines
70 {
71 protected:
72  // file name helpers
73 
74  /// Returns blueprint root file name for the current cycle
75  std::string RootFileName();
76 
77  /// Returns the mesh file name for a given domain at the current cycle
78  std::string MeshFileName(int domain_id,
79  const std::string &file_protocol="hdf5");
80 
81  /// Returns the mesh output directory for the current cycle
82  std::string MeshDirectoryName();
83 
84  /// Returns the mesh file pattern for the current cycle
85  std::string MeshFilePattern(const std::string &file_protocol="hdf5");
86 
87  // Helper functions for Save()
88 
89  /// Saves root file for the current cycle
90  void SaveRootFile(int num_domains,
91  const conduit::Node &n_mesh,
92  const std::string &file_protocol);
93 
94  /// Saves all meshes and fields for the current cycle
95  void SaveMeshAndFields(int domain_id,
96  const conduit::Node &n_mesh,
97  const std::string &file_protocol);
98 
99  // Helper functions for Load()
100 
101  /// Loads contents of the root field for the current cycle into n_root_out
102  void LoadRootFile(conduit::Node &n_root_out);
103 
104  /// Loads all meshes and fields of a given domain id for the current cycle
105  void LoadMeshAndFields(int domain_id,
106  const std::string &file_protocol);
107 
108  // holds currently active conduit relay i/o protocol
109  std::string relay_protocol;
110 
111 public:
112  /// Constructor. The collection name is used when saving the data.
113  /** If @a mesh is NULL, then the mesh can be set later by calling either
114  SetMesh() or Load(). The latter works only in serial. */
115  ConduitDataCollection(const std::string& collection_name,
116  Mesh *mesh = NULL);
117 #ifdef MFEM_USE_MPI
118  /// Construct a parallel ConduitDataCollection.
119  ConduitDataCollection(MPI_Comm comm, const std::string& collection_name,
120  Mesh *mesh = NULL);
121 #endif
122 
123  /// We will delete the mesh and fields if we own them
124  virtual ~ConduitDataCollection();
125 
126  /// Set the Conduit relay i/o protocol to use
127  /** Supported options: hdf5 (default), json, conduit_json, conduit_bin */
128  void SetProtocol(const std::string &protocol);
129 
130  /// Save the collection and a Conduit blueprint root file
131  virtual void Save();
132 
133  /// Load the collection based blueprint data
134  virtual void Load(int cycle = 0);
135 
136  /* Methods that convert to and from MFEM objects and Conduit Nodes that
137  conform to the mesh blueprint.
138 
139  These methods could be public Mesh and GF members in the future. One draw
140  back is that would require use of MFEM_USE_CONDUIT in the mesh and
141  gridfunc sources vs having everything contained in the
142  conduitdatacollection sources.
143  */
144 
145  /// Describes a MFEM mesh using the mesh blueprint
146  /** Sets up passed conduit::Node to describe the given mesh using the mesh
147  blueprint.
148 
149  Zero-copies as much data as possible.
150 
151  @a coordset_name, @a main_topology_name, and @a boundary_topology_name
152  control the names used for the mesh blueprint entries.
153 
154  With the default set of names, this method describes the mesh's
155  coordinates with a coordinate set entry named `coords`. Describes the
156  mesh with a topology entry named 'main'. If the mesh has nodes, these
157  are described in a field entry named `mesh_nodes`. If the mesh has an
158  attribute field, this is described in a field entry named
159  `mesh_attribute`.
160 
161  If the mesh has boundary info, this is described in a topology entry
162  named `boundary`. If the boundary has an attribute field, this is
163  described in a field entry named `boundary_attribute`.
164  */
165  static void MeshToBlueprintMesh(Mesh *m,
166  conduit::Node &out,
167  const std::string &coordset_name = "coords",
168  const std::string &main_topology_name = "main",
169  const std::string &boundary_topology_name = "boundary");
170 
171  /// Describes a MFEM grid function using the mesh blueprint
172  /** Sets up passed conduit::Node out to describe the given grid function
173  using the mesh field blueprint.
174 
175  Zero-copies as much data as possible.
176 
177  @a main_toplogy_name is used to set the associated topology name.
178  With the default setting, the resulting field is associated with the
179  topology `main`.
180  */
182  conduit::Node &out,
183  const std::string &main_topology_name = "main");
184 
185  /// Constructs and MFEM mesh from a Conduit Blueprint Description
186  /** @a main_topology_name is used to select which topology to use, when
187  empty ("") the first topology entry will be used.
188 
189  If zero_copy == true, tries to construct a mesh that points to the data
190  described by the conduit node. This is only possible if the data in the
191  node matches the data types needed for the MFEM API (ints for
192  connectivity, doubles for field values, etc). If these constraints are
193  not met, a mesh that owns the data is created and returned.
194  */
195  static Mesh *BlueprintMeshToMesh(const conduit::Node &n_mesh,
196  const std::string &main_toplogy_name = "",
197  bool zero_copy = false);
198 
199  /// Constructs and MFEM Grid Function from a Conduit Blueprint Description
200  /** If zero_copy == true, tries to construct a grid function that points to
201  the data described by the conduit node. This is only possible if the data
202  in the node matches the data types needed for the MFEM API (doubles for
203  field values, allocated in soa or aos ordering, etc). If these
204  constraints are not met, a grid function that owns the data is created
205  and returned.
206  */
208  const conduit::Node &n_field,
209  bool zero_copy = false);
210 
211 private:
212  /// Converts from MFEM element type enum to mesh bp shape name
213  static std::string ElementTypeToShapeName(Element::Type element_type);
214 
215  /// Converts a mesh bp shape name to a MFEM geom type
216  static mfem::Geometry::Type ShapeNameToGeomType(const std::string &shape_name);
217 };
218 
219 } // end namespace mfem
220 
221 #endif
222 
223 #endif
Class for grid function - Vector with associated FE space.
Definition: gridfunc.hpp:30
void SaveMeshAndFields(int domain_id, const conduit::Node &n_mesh, const std::string &file_protocol)
Saves all meshes and fields for the current cycle.
std::string RootFileName()
Returns blueprint root file name for the current cycle.
Data collection that uses the Conduit Mesh Blueprint specification.
virtual void Load(int cycle=0)
Load the collection based blueprint data.
ConduitDataCollection(const std::string &collection_name, Mesh *mesh=NULL)
Constructor. The collection name is used when saving the data.
static Mesh * BlueprintMeshToMesh(const conduit::Node &n_mesh, const std::string &main_toplogy_name="", bool zero_copy=false)
Constructs and MFEM mesh from a Conduit Blueprint Description.
Mesh * mesh
The (common) mesh for the collected fields.
virtual ~ConduitDataCollection()
We will delete the mesh and fields if we own them.
int cycle
Time cycle; for time-dependent simulations cycle &gt;= 0, otherwise = -1.
std::string MeshFileName(int domain_id, const std::string &file_protocol="hdf5")
Returns the mesh file name for a given domain at the current cycle.
Type
Constants for the classes derived from Element.
Definition: element.hpp:41
virtual void Save()
Save the collection and a Conduit blueprint root file.
void LoadRootFile(conduit::Node &n_root_out)
Loads contents of the root field for the current cycle into n_root_out.
void SaveRootFile(int num_domains, const conduit::Node &n_mesh, const std::string &file_protocol)
Saves root file for the current cycle.
void LoadMeshAndFields(int domain_id, const std::string &file_protocol)
Loads all meshes and fields of a given domain id for the current cycle.
std::string MeshDirectoryName()
Returns the mesh output directory for the current cycle.
static void MeshToBlueprintMesh(Mesh *m, conduit::Node &out, const std::string &coordset_name="coords", const std::string &main_topology_name="main", const std::string &boundary_topology_name="boundary")
Describes a MFEM mesh using the mesh blueprint.
std::string MeshFilePattern(const std::string &file_protocol="hdf5")
Returns the mesh file pattern for the current cycle.
static void GridFunctionToBlueprintField(GridFunction *gf, conduit::Node &out, const std::string &main_topology_name="main")
Describes a MFEM grid function using the mesh blueprint.
OutStream out(std::cout)
Global stream used by the library for standard output. Initially it uses the same std::streambuf as s...
Definition: globals.hpp:66
static GridFunction * BlueprintFieldToGridFunction(Mesh *mesh, const conduit::Node &n_field, bool zero_copy=false)
Constructs and MFEM Grid Function from a Conduit Blueprint Description.
void SetProtocol(const std::string &protocol)
Set the Conduit relay i/o protocol to use.