MFEM  v4.5.2
Finite element discretization library
conduitdatacollection.hpp
Go to the documentation of this file.
1 // Copyright (c) 2010-2023, 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  const std::string &main_adjset_name = "main_adjset");
171 
172  /// Describes a MFEM grid function using the mesh blueprint
173  /** Sets up passed conduit::Node out to describe the given grid function
174  using the mesh field blueprint.
175 
176  Zero-copies as much data as possible.
177 
178  @a main_toplogy_name is used to set the associated topology name.
179  With the default setting, the resulting field is associated with the
180  topology `main`.
181  */
183  conduit::Node &out,
184  const std::string &main_topology_name = "main");
185 
186  /// Constructs and MFEM mesh from a Conduit Blueprint Description
187  /** @a main_topology_name is used to select which topology to use, when
188  empty ("") the first topology entry will be used.
189 
190  If zero_copy == true, tries to construct a mesh that points to the data
191  described by the conduit node. This is only possible if the data in the
192  node matches the data types needed for the MFEM API (ints for
193  connectivity, doubles for field values, etc). If these constraints are
194  not met, a mesh that owns the data is created and returned.
195  */
196  static Mesh *BlueprintMeshToMesh(const conduit::Node &n_mesh,
197  const std::string &main_toplogy_name = "",
198  bool zero_copy = false);
199 
200  /// Constructs and MFEM Grid Function from a Conduit Blueprint Description
201  /** If zero_copy == true, tries to construct a grid function that points to
202  the data described by the conduit node. This is only possible if the data
203  in the node matches the data types needed for the MFEM API (doubles for
204  field values, allocated in soa or aos ordering, etc). If these
205  constraints are not met, a grid function that owns the data is created
206  and returned.
207  */
209  const conduit::Node &n_field,
210  bool zero_copy = false);
211 
212 private:
213  /// Converts from MFEM element type enum to mesh bp shape name
214  static std::string ElementTypeToShapeName(Element::Type element_type);
215 
216  /// Converts a mesh bp shape name to a MFEM geom type
217  static mfem::Geometry::Type ShapeNameToGeomType(const std::string &shape_name);
218 };
219 
220 } // end namespace mfem
221 
222 #endif
223 
224 #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.
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", const std::string &main_adjset_name="main_adjset")
Describes a MFEM mesh using the mesh blueprint.
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 >= 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.
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
std::string MeshDirectoryName()
Returns the mesh output directory for the current cycle.
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.
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.