Nektar++
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Pages
FieldIO.h
Go to the documentation of this file.
1 ///////////////////////////////////////////////////////////////////////////////
2 //
3 // File FieldIO.h
4 //
5 // For more information, please see: http://www.nektar.info
6 //
7 // The MIT License
8 //
9 // Copyright (c) 2006 Division of Applied Mathematics, Brown University (USA),
10 // Department of Aeronautics, Imperial College London (UK), and Scientific
11 // Computing and Imaging Institute, University of Utah (USA).
12 //
13 // License for the specific language governing rights and limitations under
14 // Permission is hereby granted, free of charge, to any person obtaining a
15 // copy of this software and associated documentation files (the "Software"),
16 // to deal in the Software without restriction, including without limitation
17 // the rights to use, copy, modify, merge, publish, distribute, sublicense,
18 // and/or sell copies of the Software, and to permit persons to whom the
19 // Software is furnished to do so, subject to the following conditions:
20 //
21 // The above copyright notice and this permission notice shall be included
22 // in all copies or substantial portions of the Software.
23 //
24 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
25 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
27 // THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
29 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
30 // DEALINGS IN THE SOFTWARE.
31 //
32 // Description: Field IO prototype definitions
33 //
34 ///////////////////////////////////////////////////////////////////////////////
35 
36 #ifndef NEKTAR_LIB_UTILITIES_BASIC_UTILS_FIELDIO_H
37 #define NEKTAR_LIB_UTILITIES_BASIC_UTILS_FIELDIO_H
38 
45 #include <tinyxml.h>
46 
48 
49 namespace Nektar
50 {
51 namespace LibUtilities
52 {
53 
54 typedef std::map<std::string, std::string> FieldMetaDataMap;
55 static FieldMetaDataMap NullFieldMetaDataMap;
56 
57 /**
58  * @brief Base class for writing hierarchical data (XML or HDF5).
59  */
60 class TagWriter
61 {
62 public:
63  /// Create a child node.
64  virtual boost::shared_ptr<TagWriter> AddChild(const std::string &name) = 0;
65  /// Set an attribute on the node.
66  virtual void SetAttr(const std::string &key, const std::string &val) = 0;
67 
68 protected:
69  virtual ~TagWriter() {}
70 };
71 typedef boost::shared_ptr<TagWriter> TagWriterSharedPtr;
72 
73 /**
74  * @class A simple class encapsulating a data source. This allows us to pass
75  * around native file formats in virtual functions without resorting to using
76  * the filename.
77  */
79 {
80 };
81 typedef boost::shared_ptr<DataSource> DataSourceSharedPtr;
82 
83 /**
84  * @brief Metadata that describes the storage properties of field output.
85  *
86  * The purpose of this struct is to describe the format of binary field data.
87  * This can then be used in the library to determine appropriate actions. For
88  * example, when restarting a simulation, the information this struct
89  * encapsulates can be used to determine whether interpolation is required to a
90  * different polynomial order depending on the order of the simulation versus
91  * the order of the restart file.
92  *
93  * We note that some of the parameters here include:
94  *
95  * - Element shape type and the basis used
96  * - Element IDs, which determines the order of data written in a field
97  * - The field names (e.g. u for x-velocity) so that multi-field storage can be
98  * agglomerated into one data block. Each field is written in the order
99  * specified here.
100  * - Number of modes, including support for variable polynomial order
101  * - Homogeneous information (dimension of homogeneity, IDs of planes and/or
102  * strips if they are used)
103  */
105 {
106  /// Default constructor
109  m_homoStrips(false),
110  m_pointsDef(false),
111  m_uniOrder(true),
112  m_numPointsDef(false)
113  {
114  }
115 
116  /// Simple constructor to allocate all internal properties.
118  ShapeType shapeType,
119  const std::vector<unsigned int> &elementIDs, // vector[2]
120  const std::vector<LibUtilities::BasisType> &basis,
121  bool uniOrder,
122  const std::vector<unsigned int> &numModes,
123  const std::vector<std::string> &fields,
124  int NumHomoDir = 0,
125  const std::vector<NekDouble> &HomoLengths = NullNekDoubleVector,
126  bool homoStrips = false,
127  const std::vector<unsigned int> &HomoSIDs = NullUnsignedIntVector,
128  const std::vector<unsigned int> &HomoZIDs = NullUnsignedIntVector,
129  const std::vector<unsigned int> &HomoYIDs = NullUnsignedIntVector,
130  const std::vector<LibUtilities::PointsType> &points =
132  bool pointsDef = false,
133  const std::vector<unsigned int> &numPoints = NullUnsignedIntVector,
134  bool numPointsDef = false)
135  : m_shapeType(shapeType), m_elementIDs(elementIDs), m_basis(basis),
136  m_numHomogeneousDir(NumHomoDir), m_homogeneousLengths(HomoLengths),
137  m_homoStrips(homoStrips), m_homogeneousSIDs(HomoSIDs),
138  m_homogeneousZIDs(HomoZIDs), m_homogeneousYIDs(HomoYIDs),
139  m_points(points), m_pointsDef(pointsDef), m_uniOrder(uniOrder),
140  m_numModes(numModes), m_numPoints(numPoints),
141  m_numPointsDef(numPointsDef), m_fields(fields)
142  {
143  }
144 
145  /// Shape type of this field data.
147  /// Element IDs of the field data.
148  std::vector<unsigned int> m_elementIDs;
149  /// Vector of basis types for each of the coordinate directions.
150  std::vector<LibUtilities::BasisType> m_basis;
151  /// Number of homogeneous directions, in the range \f$ 0\leq d \leq 3 \f$.
153  /// Spatial lengths of each homogeneous direction.
154  std::vector<NekDouble> m_homogeneousLengths;
155  /// Boolean determining whether homogeneous strips are used.
157  /// IDs corresponding to homogeneous strip IDs.
158  std::vector<unsigned int> m_homogeneousSIDs;
159  /// IDs corresponding to z-direction homogeneous IDs.
160  std::vector<unsigned int> m_homogeneousZIDs;
161  /// IDs corresponding to y-direction homogeneous IDs.
162  std::vector<unsigned int> m_homogeneousYIDs;
163  /// Define the type of points per direction.
164  std::vector<LibUtilities::PointsType> m_points;
165  /// Boolean determining whether points have been defined in output.
167  /// Define order of the element group.
168  /// * UniOrder: same order for each element
169  /// * MixOrder: definition of a different order for each element.
171  /// Define number of modes per direction.
172  std::vector<unsigned int> m_numModes;
173  /// Define number of points per direction.
174  std::vector<unsigned int> m_numPoints;
175  /// Boolean determining whether number of points has been defined.
177  /// Vector of field names that this data encapsulates.
178  std::vector<std::string> m_fields;
179 };
180 
181 typedef boost::shared_ptr<FieldDefinitions> FieldDefinitionsSharedPtr;
182 
184  const std::string &outFile,
185  std::vector<FieldDefinitionsSharedPtr> &fielddefs,
186  std::vector<std::vector<NekDouble> > &fielddata,
187  const FieldMetaDataMap &fieldinfomap = NullFieldMetaDataMap,
188  const bool backup = false);
190  const std::string &infilename,
191  std::vector<FieldDefinitionsSharedPtr> &fielddefs,
192  std::vector<std::vector<NekDouble> > &fielddata = NullVectorNekDoubleVector,
193  FieldMetaDataMap &fieldinfomap = NullFieldMetaDataMap,
194  const Array<OneD, int> &ElementIDs = NullInt1DArray);
195 
196 // Forward declare
197 class FieldIO;
198 
199 /// Datatype of the NekFactory used to instantiate classes
200 typedef LibUtilities::NekFactory<std::string,
201  FieldIO,
203  bool> FieldIOFactory;
204 
205 LIB_UTILITIES_EXPORT FieldIOFactory &GetFieldIOFactory();
206 
207 /**
208  * @brief Class for operating on Nektar++ input/output files.
209  *
210  * Nektar++ input/output of field data can be described as follows:
211  *
212  * - The FieldDefinitions class defines the metadata that is associated with
213  * one or more scalar field variables, and determines the storage length.
214  * - Each scalar field is stored in a single contiguous vector which is
215  * written/read by the functions defined in this class.
216  * - Optional metadata can be read/written in a simple key/value pair map
217  * FieldMetaDataMap. This can be used to define, e.g. the timestep of the
218  * simulation.
219  *
220  * This base class represents the minimum functionality that subclasses need to
221  * implement in order to implement the above functionality. Each subclass is
222  * free to determine its own file structure and parallel behaviour.
223  */
224 class FieldIO : public boost::enable_shared_from_this<FieldIO>
225 {
226 public:
228  LibUtilities::CommSharedPtr pComm, bool sharedFilesystem);
229 
231  {
232  }
233 
234  LIB_UTILITIES_EXPORT inline void Write(
235  const std::string &outFile,
236  std::vector<FieldDefinitionsSharedPtr> &fielddefs,
237  std::vector<std::vector<NekDouble> > &fielddata,
238  const FieldMetaDataMap &fieldinfomap = NullFieldMetaDataMap,
239  const bool backup = false);
240 
241  LIB_UTILITIES_EXPORT inline void Import(
242  const std::string &infilename,
243  std::vector<FieldDefinitionsSharedPtr> &fielddefs,
244  std::vector<std::vector<NekDouble> > &fielddata =
246  FieldMetaDataMap &fieldinfomap = NullFieldMetaDataMap,
247  const Array<OneD, int> &ElementIDs = NullInt1DArray);
248 
249  LIB_UTILITIES_EXPORT DataSourceSharedPtr ImportFieldMetaData(
250  const std::string &filename,
251  FieldMetaDataMap &fieldmetadatamap);
252 
253  LIB_UTILITIES_EXPORT static const std::string GetFileType(
254  const std::string &filename, CommSharedPtr comm);
255  LIB_UTILITIES_EXPORT virtual const std::string &GetClassName() const = 0;
256 
257  LIB_UTILITIES_EXPORT static boost::shared_ptr<FieldIO> CreateDefault(
259  LIB_UTILITIES_EXPORT static boost::shared_ptr<FieldIO> CreateForFile(
261  const std::string &filename);
262 
263 protected:
264  /// Communicator to use when writing parallel format
265  LibUtilities::CommSharedPtr m_comm;
266  /// Boolean dictating whether we are on a shared filesystem.
268 
270  TagWriterSharedPtr root,
271  const FieldMetaDataMap &fieldmetadatamap);
272 
274  const FieldDefinitionsSharedPtr &fielddefs);
275 
276  /**
277  * @brief Helper function that determines default file extension.
278  */
279  LIB_UTILITIES_EXPORT virtual std::string GetFileEnding() const
280  {
281  return "fld";
282  }
283 
284  LIB_UTILITIES_EXPORT std::string SetUpOutput(
285  const std::string outname, bool perRank, bool backup = false);
286 
287  /// @copydoc FieldIO::Write
288  LIB_UTILITIES_EXPORT virtual void v_Write(
289  const std::string &outFile,
290  std::vector<FieldDefinitionsSharedPtr> &fielddefs,
291  std::vector<std::vector<NekDouble> > &fielddata,
292  const FieldMetaDataMap &fieldinfomap,
293  const bool backup = false) = 0;
294 
295  /// @copydoc FieldIO::Import
296  LIB_UTILITIES_EXPORT virtual void v_Import(
297  const std::string &infilename,
298  std::vector<FieldDefinitionsSharedPtr> &fielddefs,
299  std::vector<std::vector<NekDouble> >
300  &fielddata = NullVectorNekDoubleVector,
301  FieldMetaDataMap &fieldinfomap = NullFieldMetaDataMap,
302  const Array<OneD, int> &ElementIDs = NullInt1DArray) = 0;
303 
304  /// @copydoc FieldIO::ImportFieldMetaData
305  LIB_UTILITIES_EXPORT virtual DataSourceSharedPtr v_ImportFieldMetaData(
306  const std::string &filename, FieldMetaDataMap &fieldmetadatamap) = 0;
307 };
308 
309 typedef boost::shared_ptr<FieldIO> FieldIOSharedPtr;
310 
311 /**
312  * @brief Write out the field information to the file @p outFile.
313  *
314  * @param outFile Output filename
315  * @param fielddefs Field definitions that define the output
316  * @param fielddata Binary field data that stores the output corresponding
317  * to @p fielddefs.
318  * @param fieldinfomap Associated field metadata map.
319  */
320 inline void FieldIO::Write(const std::string &outFile,
321  std::vector<FieldDefinitionsSharedPtr> &fielddefs,
322  std::vector<std::vector<NekDouble> > &fielddata,
323  const FieldMetaDataMap &fieldinfomap,
324  const bool backup)
325 {
326  v_Write(outFile, fielddefs, fielddata, fieldinfomap, backup);
327 }
328 
329 /**
330  * @brief Read field information from the file @p infilename.
331  *
332  * @param infilename Input filename (or directory if parallel format)
333  * @param fielddefs On return contains field definitions as read from the
334  * input.
335  * @param fielddata On return, contains binary field data that stores the
336  * input corresponding to @p fielddefs.
337  * @param fieldinfo On returnm, contains the associated field metadata map.
338  * @param ElementIDs Element IDs that lie on this processor, which can be
339  * optionally supplied to avoid reading the entire file on
340  * each processor.
341  */
342 inline void FieldIO::Import(const std::string &infilename,
343  std::vector<FieldDefinitionsSharedPtr> &fielddefs,
344  std::vector<std::vector<NekDouble> > &fielddata,
345  FieldMetaDataMap &fieldinfo,
346  const Array<OneD, int> &ElementIDs)
347 {
348  v_Import(infilename, fielddefs, fielddata, fieldinfo, ElementIDs);
349 }
350 
351 /**
352  * @brief Import the metadata from a field file.
353  *
354  * @param filename Input filename.
355  * @param fieldmetadatamap On return contains the field metadata map from @p
356  * filename.
357  */
358 inline DataSourceSharedPtr FieldIO::ImportFieldMetaData(
359  const std::string &filename, FieldMetaDataMap &fieldmetadatamap)
360 {
361  return v_ImportFieldMetaData(filename, fieldmetadatamap);
362 }
363 
364 }
365 }
366 #endif
std::vector< unsigned int > m_numPoints
Define number of points per direction.
Definition: FieldIO.h:174
virtual void v_Import(const std::string &infilename, std::vector< FieldDefinitionsSharedPtr > &fielddefs, std::vector< std::vector< NekDouble > > &fielddata=NullVectorNekDoubleVector, FieldMetaDataMap &fieldinfomap=NullFieldMetaDataMap, const Array< OneD, int > &ElementIDs=NullInt1DArray)=0
Read field information from the file infilename.
LibUtilities::NekFactory< std::string, FieldIO, LibUtilities::CommSharedPtr, bool > FieldIOFactory
Datatype of the NekFactory used to instantiate classes.
Definition: FieldIO.h:197
std::vector< unsigned int > m_homogeneousYIDs
IDs corresponding to y-direction homogeneous IDs.
Definition: FieldIO.h:162
void Import(const std::string &infilename, std::vector< FieldDefinitionsSharedPtr > &fielddefs, std::vector< std::vector< NekDouble > > &fielddata, FieldMetaDataMap &fieldinfomap, const Array< OneD, int > &ElementIDs)
This function allows for data to be imported from an FLD file when a session and/or communicator is n...
Definition: FieldIO.cpp:279
std::vector< NekDouble > m_homogeneousLengths
Spatial lengths of each homogeneous direction.
Definition: FieldIO.h:154
FieldDefinitions()
Default constructor.
Definition: FieldIO.h:107
boost::shared_ptr< FieldDefinitions > FieldDefinitionsSharedPtr
Definition: FieldIO.h:181
FieldDefinitions(ShapeType shapeType, const std::vector< unsigned int > &elementIDs, const std::vector< LibUtilities::BasisType > &basis, bool uniOrder, const std::vector< unsigned int > &numModes, const std::vector< std::string > &fields, int NumHomoDir=0, const std::vector< NekDouble > &HomoLengths=NullNekDoubleVector, bool homoStrips=false, const std::vector< unsigned int > &HomoSIDs=NullUnsignedIntVector, const std::vector< unsigned int > &HomoZIDs=NullUnsignedIntVector, const std::vector< unsigned int > &HomoYIDs=NullUnsignedIntVector, const std::vector< LibUtilities::PointsType > &points=NullPointsTypeVector, bool pointsDef=false, const std::vector< unsigned int > &numPoints=NullUnsignedIntVector, bool numPointsDef=false)
Simple constructor to allocate all internal properties.
Definition: FieldIO.h:117
ShapeType m_shapeType
Shape type of this field data.
Definition: FieldIO.h:146
virtual void SetAttr(const std::string &key, const std::string &val)=0
Set an attribute on the node.
virtual DataSourceSharedPtr v_ImportFieldMetaData(const std::string &filename, FieldMetaDataMap &fieldmetadatamap)=0
Import the metadata from a field file.
std::vector< unsigned int > m_homogeneousZIDs
IDs corresponding to z-direction homogeneous IDs.
Definition: FieldIO.h:160
bool m_uniOrder
Define order of the element group.
Definition: FieldIO.h:170
FieldIOFactory & GetFieldIOFactory()
Returns the FieldIO factory.
Definition: FieldIO.cpp:74
void Import(const std::string &infilename, std::vector< FieldDefinitionsSharedPtr > &fielddefs, std::vector< std::vector< NekDouble > > &fielddata=NullVectorNekDoubleVector, FieldMetaDataMap &fieldinfomap=NullFieldMetaDataMap, const Array< OneD, int > &ElementIDs=NullInt1DArray)
Read field information from the file infilename.
Definition: FieldIO.h:342
boost::shared_ptr< SessionReader > SessionReaderSharedPtr
Definition: MeshPartition.h:51
std::map< std::string, std::string > FieldMetaDataMap
Definition: FieldIO.h:54
int CheckFieldDefinition(const FieldDefinitionsSharedPtr &fielddefs)
Check field definitions for correctness and return storage size.
Definition: FieldIO.cpp:545
bool m_numPointsDef
Boolean determining whether number of points has been defined.
Definition: FieldIO.h:176
std::vector< unsigned int > m_homogeneousSIDs
IDs corresponding to homogeneous strip IDs.
Definition: FieldIO.h:158
virtual const std::string & GetClassName() const =0
boost::shared_ptr< DataSource > DataSourceSharedPtr
Definition: FieldIO.h:81
std::vector< LibUtilities::BasisType > m_basis
Vector of basis types for each of the coordinate directions.
Definition: FieldIO.h:150
static std::vector< NekDouble > NullNekDoubleVector
Base class for writing hierarchical data (XML or HDF5).
Definition: FieldIO.h:60
bool m_sharedFilesystem
Boolean dictating whether we are on a shared filesystem.
Definition: FieldIO.h:267
Metadata that describes the storage properties of field output.
Definition: FieldIO.h:104
std::vector< unsigned int > m_numModes
Define number of modes per direction.
Definition: FieldIO.h:172
boost::shared_ptr< Comm > CommSharedPtr
Pointer to a Communicator object.
Definition: Comm.h:55
static const std::string GetFileType(const std::string &filename, CommSharedPtr comm)
Determine file type of given input file.
Definition: FieldIO.cpp:101
#define LIB_UTILITIES_EXPORT
static std::vector< std::vector< NekDouble > > NullVectorNekDoubleVector
static std::vector< unsigned int > NullUnsignedIntVector
DataSourceSharedPtr ImportFieldMetaData(const std::string &filename, FieldMetaDataMap &fieldmetadatamap)
Import the metadata from a field file.
Definition: FieldIO.h:358
boost::shared_ptr< FieldIO > FieldIOSharedPtr
Definition: FieldIO.h:309
std::vector< unsigned int > m_elementIDs
Element IDs of the field data.
Definition: FieldIO.h:148
std::string SetUpOutput(const std::string outname, bool perRank, bool backup=false)
Set up the filesystem ready for output.
Definition: FieldIO.cpp:400
void Write(const std::string &outFile, std::vector< FieldDefinitionsSharedPtr > &fielddefs, std::vector< std::vector< NekDouble > > &fielddata, const FieldMetaDataMap &fieldinfomap, const bool backup)
This function allows for data to be written to an FLD file when a session and/or communicator is not ...
Definition: FieldIO.cpp:235
std::vector< std::string > m_fields
Vector of field names that this data encapsulates.
Definition: FieldIO.h:178
LibUtilities::CommSharedPtr m_comm
Communicator to use when writing parallel format.
Definition: FieldIO.h:265
static boost::shared_ptr< FieldIO > CreateDefault(const LibUtilities::SessionReaderSharedPtr session)
Returns an object for the default FieldIO method.
Definition: FieldIO.cpp:181
static boost::shared_ptr< FieldIO > CreateForFile(const LibUtilities::SessionReaderSharedPtr session, const std::string &filename)
Construct a FieldIO object for a given input filename.
Definition: FieldIO.cpp:212
virtual boost::shared_ptr< TagWriter > AddChild(const std::string &name)=0
Create a child node.
static std::vector< LibUtilities::PointsType > NullPointsTypeVector
Definition: PointsType.h:85
bool m_homoStrips
Boolean determining whether homogeneous strips are used.
Definition: FieldIO.h:156
std::vector< LibUtilities::PointsType > m_points
Define the type of points per direction.
Definition: FieldIO.h:164
Class for operating on Nektar++ input/output files.
Definition: FieldIO.h:224
virtual std::string GetFileEnding() const
Helper function that determines default file extension.
Definition: FieldIO.h:279
boost::shared_ptr< TagWriter > TagWriterSharedPtr
Definition: FieldIO.h:71
bool m_pointsDef
Boolean determining whether points have been defined in output.
Definition: FieldIO.h:166
int m_numHomogeneousDir
Number of homogeneous directions, in the range .
Definition: FieldIO.h:152
static Array< OneD, int > NullInt1DArray
virtual void v_Write(const std::string &outFile, std::vector< FieldDefinitionsSharedPtr > &fielddefs, std::vector< std::vector< NekDouble > > &fielddata, const FieldMetaDataMap &fieldinfomap, const bool backup=false)=0
Write out the field information to the file outFile.
static FieldMetaDataMap NullFieldMetaDataMap
Definition: FieldIO.h:55
void AddInfoTag(TagWriterSharedPtr root, const FieldMetaDataMap &fieldmetadatamap)
Add provenance information to the field metadata map.
Definition: FieldIO.cpp:334
void Write(const std::string &outFile, std::vector< FieldDefinitionsSharedPtr > &fielddefs, std::vector< std::vector< NekDouble > > &fielddata, const FieldMetaDataMap &fieldinfomap=NullFieldMetaDataMap, const bool backup=false)
Write out the field information to the file outFile.
Definition: FieldIO.h:320
Provides a generic Factory class.
Definition: NekFactory.hpp:116
FieldIO(LibUtilities::CommSharedPtr pComm, bool sharedFilesystem)
Constructor for FieldIO base class.
Definition: FieldIO.cpp:313