FieldIO.h 15.1 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
///////////////////////////////////////////////////////////////////////////////
//
// File FieldIO.h
//
// For more information, please see: http://www.nektar.info
//
// The MIT License
//
// Copyright (c) 2006 Division of Applied Mathematics, Brown University (USA),
// Department of Aeronautics, Imperial College London (UK), and Scientific
// Computing and Imaging Institute, University of Utah (USA).
//
// License for the specific language governing rights and limitations under
// Permission is hereby granted, free of charge, to any person obtaining a
// copy of this software and associated documentation files (the "Software"),
// to deal in the Software without restriction, including without limitation
// the rights to use, copy, modify, merge, publish, distribute, sublicense,
// and/or sell copies of the Software, and to permit persons to whom the
// Software is furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included
// in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.
//
// Description: Field IO prototype definitions
//
///////////////////////////////////////////////////////////////////////////////

#ifndef NEKTAR_LIB_UTILITIES_BASIC_UTILS_FIELDIO_H
#define NEKTAR_LIB_UTILITIES_BASIC_UTILS_FIELDIO_H

39
40
#include <LibUtilities/BasicUtils/SessionReader.h>
#include <LibUtilities/Communication/Comm.h>
41
42
43
44
#include <LibUtilities/BasicUtils/ParseUtils.hpp>
#include <LibUtilities/BasicUtils/ShapeType.hpp>
#include <LibUtilities/Foundations/Basis.h>
#include <LibUtilities/Foundations/Points.h>
45
#include <tinyxml.h>
46

47
48
#include <LibUtilities/BasicUtils/NekFactory.hpp>

49
50
namespace Nektar
{
51
52
namespace LibUtilities
{
Dave Moxey's avatar
Dave Moxey committed
53

Dave Moxey's avatar
Dave Moxey committed
54
55
56
typedef std::map<std::string, std::string> FieldMetaDataMap;
static FieldMetaDataMap NullFieldMetaDataMap;

Dave Moxey's avatar
Dave Moxey committed
57
58
59
/**
 * @brief Base class for writing hierarchical data (XML or HDF5).
 */
60
61
62
class TagWriter
{
public:
Dave Moxey's avatar
Dave Moxey committed
63
    /// Create a child node.
64
    virtual boost::shared_ptr<TagWriter> AddChild(const std::string &name) = 0;
Dave Moxey's avatar
Dave Moxey committed
65
    /// Set an attribute on the node.
66
67
68
    virtual void SetAttr(const std::string &key, const std::string &val) = 0;

protected:
Dave Moxey's avatar
Dave Moxey committed
69
    virtual ~TagWriter() {}
70
71
72
};
typedef boost::shared_ptr<TagWriter> TagWriterSharedPtr;

Dave Moxey's avatar
Dave Moxey committed
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
/**
 * @class A simple class encapsulating a data source. This allows us to pass
 * around native file formats in virtual functions without resorting to using
 * the filename.
 */
class DataSource
{
};
typedef boost::shared_ptr<DataSource> DataSourceSharedPtr;

/**
 * @brief Metadata that describes the storage properties of field output.
 *
 * The purpose of this struct is to describe the format of binary field data.
 * This can then be used in the library to determine appropriate actions. For
 * example, when restarting a simulation, the information this struct
 * encapsulates can be used to determine whether interpolation is required to a
 * different polynomial order depending on the order of the simulation versus
 * the order of the restart file.
 *
 * We note that some of the parameters here include:
 *
 * - Element shape type and the basis used
 * - Element IDs, which determines the order of data written in a field
 * - The field names (e.g. u for x-velocity) so that multi-field storage can be
 *   agglomerated into one data block. Each field is written in the order
 *   specified here.
 * - Number of modes, including support for variable polynomial order
 * - Homogeneous information (dimension of homogeneity, IDs of planes and/or
 *   strips if they are used)
 */
104
105
struct FieldDefinitions
{
Dave Moxey's avatar
Dave Moxey committed
106
    /// Default constructor
107
108
109
110
111
112
113
114
    FieldDefinitions() : m_shapeType(eNoShapeType),
                         m_numHomogeneousDir(0),
                         m_homoStrips(false),
                         m_pointsDef(false),
                         m_uniOrder(true),
                         m_numPointsDef(false)
    {
    }
115

Dave Moxey's avatar
Dave Moxey committed
116
    /// Simple constructor to allocate all internal properties.
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
    FieldDefinitions(
        ShapeType shapeType,
        const std::vector<unsigned int> &elementIDs, // vector[2]
        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)
        : m_shapeType(shapeType), m_elementIDs(elementIDs), m_basis(basis),
          m_numHomogeneousDir(NumHomoDir), m_homogeneousLengths(HomoLengths),
          m_homoStrips(homoStrips), m_homogeneousSIDs(HomoSIDs),
          m_homogeneousZIDs(HomoZIDs), m_homogeneousYIDs(HomoYIDs),
          m_points(points), m_pointsDef(pointsDef), m_uniOrder(uniOrder),
          m_numModes(numModes), m_numPoints(numPoints),
          m_numPointsDef(numPointsDef), m_fields(fields)
142
143
    {
    }
144

Dave Moxey's avatar
Dave Moxey committed
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
    /// Shape type of this field data.
    ShapeType                             m_shapeType;
    /// Element IDs of the field data.
    std::vector<unsigned int>             m_elementIDs;
    /// Vector of basis types for each of the coordinate directions.
    std::vector<LibUtilities::BasisType>  m_basis;
    /// Number of homogeneous directions, in the range \f$ 0\leq d \leq 3 \f$.
    int                                   m_numHomogeneousDir;
    /// Spatial lengths of each homogeneous direction.
    std::vector<NekDouble>                m_homogeneousLengths;
    /// Boolean determining whether homogeneous strips are used.
    bool                                  m_homoStrips;
    /// IDs corresponding to homogeneous strip IDs.
    std::vector<unsigned int>             m_homogeneousSIDs;
    /// IDs corresponding to z-direction homogeneous IDs.
    std::vector<unsigned int>             m_homogeneousZIDs;
    /// IDs corresponding to y-direction homogeneous IDs.
    std::vector<unsigned int>             m_homogeneousYIDs;
163
164
    /// Define the type of points per direction.
    std::vector<LibUtilities::PointsType> m_points;
Dave Moxey's avatar
Dave Moxey committed
165
166
    /// Boolean determining whether points have been defined in output.
    bool                                  m_pointsDef;
167
168
169
    /// Define order of the element group.
    /// * UniOrder: same order for each element
    /// * MixOrder: definition of a different order for each element.
Dave Moxey's avatar
Dave Moxey committed
170
    bool                                  m_uniOrder;
171
    /// Define number of modes per direction.
Dave Moxey's avatar
Dave Moxey committed
172
173
174
175
176
177
178
    std::vector<unsigned int>             m_numModes;
    /// Define number of points per direction.
    std::vector<unsigned int>             m_numPoints;
    /// Boolean determining whether number of points has been defined.
    bool                                  m_numPointsDef;
    /// Vector of field names that this data encapsulates.
    std::vector<std::string>              m_fields;
179
180
181
182
183
184
185
186
187
188
189
190
191
192
};

typedef boost::shared_ptr<FieldDefinitions> FieldDefinitionsSharedPtr;

LIB_UTILITIES_EXPORT void Write(
    const std::string &outFile,
    std::vector<FieldDefinitionsSharedPtr> &fielddefs,
    std::vector<std::vector<NekDouble> > &fielddata,
    const FieldMetaDataMap &fieldinfomap = NullFieldMetaDataMap);
LIB_UTILITIES_EXPORT void Import(
    const std::string &infilename,
    std::vector<FieldDefinitionsSharedPtr> &fielddefs,
    std::vector<std::vector<NekDouble> > &fielddata = NullVectorNekDoubleVector,
    FieldMetaDataMap &fieldinfomap                  = NullFieldMetaDataMap,
Dave Moxey's avatar
Dave Moxey committed
193
    const Array<OneD, int> &ElementIDs = NullInt1DArray);
194
195
196
197
198
199
200
201
202
203
204
205

// Forward declare
class FieldIO;

/// Datatype of the NekFactory used to instantiate classes
typedef LibUtilities::NekFactory<std::string,
                                 FieldIO,
                                 LibUtilities::CommSharedPtr,
                                 bool> FieldIOFactory;

LIB_UTILITIES_EXPORT FieldIOFactory &GetFieldIOFactory();

206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
/**
 * @brief Class for operating on Nektar++ input/output files.
 *
 * Nektar++ input/output of field data can be described as follows:
 *
 *   - The FieldDefinitions class defines the metadata that is associated with
 *     one or more scalar field variables, and determines the storage length.
 *   - Each scalar field is stored in a single contiguous vector which is
 *     written/read by the functions defined in this class.
 *   - Optional metadata can be read/written in a simple key/value pair map
 *     FieldMetaDataMap. This can be used to define, e.g. the timestep of the
 *     simulation.
 *
 * This base class represents the minimum functionality that subclasses need to
 * implement in order to implement the above functionality. Each subclass is
 * free to determine its own file structure and parallel behaviour.
 */
223
224
225
class FieldIO : public boost::enable_shared_from_this<FieldIO>
{
public:
Dave Moxey's avatar
Dave Moxey committed
226
227
    LIB_UTILITIES_EXPORT FieldIO(
        LibUtilities::CommSharedPtr pComm, bool sharedFilesystem);
228

229
230
231
232
    LIB_UTILITIES_EXPORT virtual ~FieldIO()
    {
    }

Dave Moxey's avatar
Dave Moxey committed
233
    LIB_UTILITIES_EXPORT inline void Write(
234
235
236
237
238
        const std::string &outFile,
        std::vector<FieldDefinitionsSharedPtr> &fielddefs,
        std::vector<std::vector<NekDouble> > &fielddata,
        const FieldMetaDataMap &fieldinfomap = NullFieldMetaDataMap);

Dave Moxey's avatar
Dave Moxey committed
239
240
    LIB_UTILITIES_EXPORT inline void Import(
        const std::string &infilename,
241
        std::vector<FieldDefinitionsSharedPtr> &fielddefs,
Dave Moxey's avatar
Dave Moxey committed
242
243
244
        std::vector<std::vector<NekDouble> > &fielddata =
            NullVectorNekDoubleVector,
        FieldMetaDataMap &fieldinfomap    = NullFieldMetaDataMap,
Dave Moxey's avatar
Dave Moxey committed
245
        const Array<OneD, int> &ElementIDs = NullInt1DArray);
Dave Moxey's avatar
Dave Moxey committed
246
247

    LIB_UTILITIES_EXPORT DataSourceSharedPtr ImportFieldMetaData(
Dave Moxey's avatar
Dave Moxey committed
248
249
        const std::string &filename,
        FieldMetaDataMap  &fieldmetadatamap);
250

251
252
253
    LIB_UTILITIES_EXPORT bool GetDoBackup();
    LIB_UTILITIES_EXPORT void SetDoBackup(bool backup);

Dave Moxey's avatar
Dave Moxey committed
254
255
256
    LIB_UTILITIES_EXPORT static const std::string GetFileType(
        const std::string &filename, CommSharedPtr comm);
    LIB_UTILITIES_EXPORT virtual const std::string &GetClassName() const = 0;
257

Dave Moxey's avatar
Dave Moxey committed
258
    LIB_UTILITIES_EXPORT static boost::shared_ptr<FieldIO> CreateDefault(
259
        const LibUtilities::SessionReaderSharedPtr session);
Dave Moxey's avatar
Dave Moxey committed
260
    LIB_UTILITIES_EXPORT static boost::shared_ptr<FieldIO> CreateForFile(
261
262
263
        const LibUtilities::SessionReaderSharedPtr session,
        const std::string &filename);

264
265
266
protected:
    /// Communicator to use when writing parallel format
    LibUtilities::CommSharedPtr m_comm;
Dave Moxey's avatar
Dave Moxey committed
267
268
    /// Boolean dictating whether we are on a shared filesystem.
    bool                        m_sharedFilesystem;
269
270
    /// Boolean dictating whether we should backup existing files
    bool                        m_backup;
271

Dave Moxey's avatar
Dave Moxey committed
272
273
274
    LIB_UTILITIES_EXPORT void AddInfoTag(
        TagWriterSharedPtr      root,
        const FieldMetaDataMap &fieldmetadatamap);
275

Dave Moxey's avatar
Dave Moxey committed
276
277
    LIB_UTILITIES_EXPORT int CheckFieldDefinition(
        const FieldDefinitionsSharedPtr &fielddefs);
278

279
280
281
    /**
     * @brief Helper function that determines default file extension.
     */
282
283
284
285
286
    LIB_UTILITIES_EXPORT virtual std::string GetFileEnding() const
    {
        return "fld";
    }

Dave Moxey's avatar
Dave Moxey committed
287
288
    LIB_UTILITIES_EXPORT std::string SetUpOutput(
        const std::string outname, bool perRank);
289
290

    /// @copydoc FieldIO::Write
Dave Moxey's avatar
Dave Moxey committed
291
292
293
294
295
    LIB_UTILITIES_EXPORT virtual void v_Write(
        const std::string                      &outFile,
        std::vector<FieldDefinitionsSharedPtr> &fielddefs,
        std::vector<std::vector<NekDouble> >   &fielddata,
        const FieldMetaDataMap                 &fieldinfomap) = 0;
296

297
    /// @copydoc FieldIO::Import
Dave Moxey's avatar
Dave Moxey committed
298
    LIB_UTILITIES_EXPORT virtual void v_Import(
299
300
301
        const std::string &infilename,
        std::vector<FieldDefinitionsSharedPtr> &fielddefs,
        std::vector<std::vector<NekDouble> >
Dave Moxey's avatar
Dave Moxey committed
302
303
304
            &fielddata                     = NullVectorNekDoubleVector,
        FieldMetaDataMap &fieldinfomap     = NullFieldMetaDataMap,
        const Array<OneD, int> &ElementIDs = NullInt1DArray) = 0;
305

306
    /// @copydoc FieldIO::ImportFieldMetaData
Dave Moxey's avatar
Dave Moxey committed
307
    LIB_UTILITIES_EXPORT virtual DataSourceSharedPtr v_ImportFieldMetaData(
Dave Moxey's avatar
Dave Moxey committed
308
        const std::string &filename, FieldMetaDataMap &fieldmetadatamap) = 0;
309
310
311
312
};

typedef boost::shared_ptr<FieldIO> FieldIOSharedPtr;

313
314
315
316
317
318
319
320
321
/**
 * @brief Write out the field information to the file @p outFile.
 *
 * @param outFile       Output filename
 * @param fielddefs     Field definitions that define the output
 * @param fielddata     Binary field data that stores the output corresponding
 *                      to @p fielddefs.
 * @param fieldinfomap  Associated field metadata map.
 */
Dave Moxey's avatar
Dave Moxey committed
322
inline void FieldIO::Write(const std::string                      &outFile,
323
324
                           std::vector<FieldDefinitionsSharedPtr> &fielddefs,
                           std::vector<std::vector<NekDouble> > &fielddata,
Dave Moxey's avatar
Dave Moxey committed
325
                           const FieldMetaDataMap                 &fieldinfomap)
326
327
328
329
{
    v_Write(outFile, fielddefs, fielddata, fieldinfomap);
}

330
331
332
333
334
335
336
337
338
339
340
341
342
/**
 * @brief Read field information from the file @p infilename.
 *
 * @param infilename    Input filename (or directory if parallel format)
 * @param fielddefs     On return contains field definitions as read from the
 *                      input.
 * @param fielddata     On return, contains binary field data that stores the
 *                      input corresponding to @p fielddefs.
 * @param fieldinfo     On returnm, contains the associated field metadata map.
 * @param ElementIDs    Element IDs that lie on this processor, which can be
 *                      optionally supplied to avoid reading the entire file on
 *                      each processor.
 */
Dave Moxey's avatar
Dave Moxey committed
343
inline void FieldIO::Import(const std::string                      &infilename,
344
                            std::vector<FieldDefinitionsSharedPtr> &fielddefs,
Dave Moxey's avatar
Dave Moxey committed
345
346
                            std::vector<std::vector<NekDouble> >   &fielddata,
                            FieldMetaDataMap                       &fieldinfo,
Dave Moxey's avatar
Dave Moxey committed
347
                            const Array<OneD, int>                 &ElementIDs)
348
{
349
    v_Import(infilename, fielddefs, fielddata, fieldinfo, ElementIDs);
350
351
}

352
353
354
355
356
357
358
/**
 * @brief Import the metadata from a field file.
 *
 * @param filename          Input filename.
 * @param fieldmetadatamap  On return contains the field metadata map from @p
 *                          filename.
 */
359
inline DataSourceSharedPtr FieldIO::ImportFieldMetaData(
Dave Moxey's avatar
Dave Moxey committed
360
    const std::string &filename, FieldMetaDataMap &fieldmetadatamap)
361
362
363
{
    return v_ImportFieldMetaData(filename, fieldmetadatamap);
}
Dave Moxey's avatar
Dave Moxey committed
364

365
}
366
367
}
#endif