XdmfHeavyDataController.hpp 11.7 KB
Newer Older
Kenneth Leiter's avatar
Kenneth Leiter committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
/*****************************************************************************/
/*                                    XDMF                                   */
/*                       eXtensible Data Model and Format                    */
/*                                                                           */
/*  Id : XdmfHeavyDataController.hpp                                         */
/*                                                                           */
/*  Author:                                                                  */
/*     Kenneth Leiter                                                        */
/*     kenneth.leiter@arl.army.mil                                           */
/*     US Army Research Laboratory                                           */
/*     Aberdeen Proving Ground, MD                                           */
/*                                                                           */
/*     Copyright @ 2011 US Army Research Laboratory                          */
/*     All Rights Reserved                                                   */
/*     See Copyright.txt for details                                         */
/*                                                                           */
/*     This software is distributed WITHOUT ANY WARRANTY; without            */
/*     even the implied warranty of MERCHANTABILITY or FITNESS               */
/*     FOR A PARTICULAR PURPOSE.  See the above copyright notice             */
/*     for more information.                                                 */
/*                                                                           */
/*****************************************************************************/

24 25 26 27 28 29 30 31 32
#ifndef XDMFHEAVYDATACONTROLLER_HPP_
#define XDMFHEAVYDATACONTROLLER_HPP_

// Forward Declarations
class XdmfArray;
class XdmfArrayType;

// Includes
#include <string>
33
#include <vector>
34
#include "XdmfCore.hpp"
35
#include "XdmfSharedPtr.hpp"
36 37 38 39

/**
 * @brief Couples an XdmfArray with heavy data stored on disk.
 *
40 41 42 43 44 45 46 47
 * This is an abstract base class to support the reading of different
 * heavy data formats.
 *
 * Serves as an interface between data stored in XdmfArrays and data
 * stored on disk. When an Xdmf file is read from or written to disk
 * an XdmfHeavyController is attached to XdmfArrays. This allows data
 * to be released from memory but still be accessible or have its
 * location written to light data.
48
 */
49
class XDMFCORE_EXPORT XdmfHeavyDataController {
50

51
public:
52 53 54 55

  virtual ~XdmfHeavyDataController() = 0;

  /**
56 57
   * Get the path of the data set within the heavy data file owned by
   * this controller.
58 59
   * For "/home/output.h5:/foo/data" this is "/foo/data"
   *
60 61 62 63
   * Example of use:
   *
   * C++
   *
64
   * @dontinclude ExampleXdmfHeavyDataController.cpp
65 66 67 68
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getDataSetPath
   * @until //#getDataSetPath
69 70 71
   *
   * Python
   *
72
   * @dontinclude XdmfExampleHeavyDataController.py
73 74 75 76
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getDataSetPath
   * @until #//getDataSetPath
77
   *
78
   * @return    A std::string containing the path of the data set.
79 80 81
   */
  std::string getDataSetPath() const;

82 83 84 85 86 87
  /**
   * Get the dimensions of the dataspace owned by this
   * controller. This is the dimension of the entire heavy dataset,
   * which may be larger than the dimensions of the array (if reading
   * a piece of a larger dataset).
   *
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105
   * Example of use:
   *
   * C++
   *
   * @dontinclude ExampleXdmfHeavyDataController.cpp
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getDataspaceDimensions
   * @until //#getDataspaceDimensions
   *
   * Python
   *
   * @dontinclude XdmfExampleHeavyDataController.py
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getDataspaceDimensions
   * @until #//getDataspaceDimensions
   *
106 107
   * @return    A vector containing the size in each dimension of the dataspace
   *            owned by this controller.
108 109 110
   */
  std::vector<unsigned int> getDataspaceDimensions() const;

111 112 113
  /**
   * Get the dimensions of the heavy data set owned by this controller.
   *
114 115 116 117
   * Example of use:
   *
   * C++
   *
118
   * @dontinclude ExampleXdmfHeavyDataController.cpp
119 120 121 122
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getDimensions
   * @until //#getDimensions
123 124 125
   *
   * Python
   *
126
   * @dontinclude XdmfExampleHeavyDataController.py
127 128 129 130
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getDimensions
   * @until #//getDimensions
131
   *
132 133
   * @return    A vector containing the size in each dimension of the heavy data
   *            set owned by this controller.
134 135 136
   */
  std::vector<unsigned int> getDimensions() const;

137
  /**
138 139
   * Get the absolute path to the heavy data file on disk where the
   * data set owned by this controller resides.
140 141
   * For "/home/output.h5:/foo/data" this is "/home/output.h5"
   *
142 143 144 145
   * Example of use:
   *
   * C++
   *
146
   * @dontinclude ExampleXdmfHeavyDataController.cpp
147 148 149 150
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getFilePath
   * @until //#getFilePath
151 152 153
   *
   * Python
   *
154
   * @dontinclude XdmfExampleHeavyDataController.py
155 156 157 158
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getFilePath
   * @until #//getFilePath
159
   *
160
   * @return    A std::string containing the path to the heavy data file.
161 162 163 164
   */
  std::string getFilePath() const;

  /**
165 166
   * Get the name of this heavy data format. E.g. "HDF" for hdf5
   * format.
167
   *
168 169 170 171
   * Example of use:
   *
   * C++
   *
172
   * @dontinclude ExampleXdmfHeavyDataController.cpp
173 174 175 176
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getName
   * @until //#getName
177 178 179
   *
   * Python
   *
180
   * @dontinclude XdmfExampleHeavyDataController.py
181 182 183 184
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getName
   * @until #//getName
185
   *
186
   * @return    std::string containing the name of this heavy data format
187 188 189 190 191 192
   */
  virtual std::string getName() const = 0;

  /**
   * Get the size of the heavy data set owned by this controller.
   *
193 194 195 196
   * Example of use:
   *
   * C++
   *
197
   * @dontinclude ExampleXdmfHeavyDataController.cpp
198 199 200 201
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getSize
   * @until //#getSize
202 203 204
   *
   * Python
   *
205
   * @dontinclude XdmfExampleHeavyDataController.py
206 207 208 209
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getSize
   * @until #//getSize
210
   *
211
   * @return    An int containing the size of the heavy data set.
212 213 214
   */
  unsigned int getSize() const;

215
  /**
216 217
   * For use in conjunction with heavy data controllers set to arrays
   * the offset within the array from which the controller will be inserted
218 219 220 221 222
   * Is also set when created by a writer.
   *
   * C++
   *
   * @dontinclude ExampleXdmfHeavyDataController.cpp
223 224 225 226
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#setArrayOffset
   * @until //#setArrayOffset
227 228 229 230
   *
   * Python
   *
   * @dontinclude XdmfExampleHeavyDataController.py
231 232 233 234
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//setArrayOffset
   * @until #//setArrayOffset
235
   *
236
   * @param     newOffset       The new index at which the controller will be written
237 238 239 240
   */
  void setArrayOffset(unsigned int newOffset);

  /**
241 242
   * Gets the index at which the controller will offset when
   * an array reads it from its associated controllers.
243 244 245 246 247
   * Set when created by a Writer or set manually.
   *
   * C++
   *
   * @dontinclude ExampleXdmfHeavyDataController.cpp
248 249 250 251 252 253
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#setArrayOffset
   * @until //#setArrayOffset
   * @skipline //#getArrayOffset
   * @until //#getArrayOffset
254 255 256 257
   *
   * Python
   *
   * @dontinclude XdmfExampleHeavyDataController.py
258 259 260 261 262 263
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//setArrayOffset
   * @until #//setArrayOffset
   * @skipline #//getArrayOffset
   * @until #//getArrayOffset
264
   *
265
   * @return    The offset that the array will read from
266 267 268
   */
  unsigned int getArrayOffset() const;

269 270 271
  /**
   * Get the start index of the heavy data set owned by this controller.
   *
272 273 274
   * C++
   *
   * @dontinclude ExampleXdmfHeavyDataController.cpp
275 276 277 278
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getStart
   * @until //#getStart
279 280 281 282
   *
   * Python
   *
   * @dontinclude XdmfExampleHeavyDataController.py
283 284 285 286
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getStart
   * @until #//getStart
287
   *
288 289
   * @return    A vector containing the start index in each dimension of
   *            the heavy data set owned by this controller.
290 291 292 293 294 295
   */
  std::vector<unsigned int> getStart() const;

  /**
   * Get the stride of the heavy data set owned by this controller.
   *
296 297 298
   * C++
   *
   * @dontinclude ExampleXdmfHeavyDataController.cpp
299 300 301 302
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getStride
   * @until //#getStride
303 304 305 306
   *
   * Python
   *
   * @dontinclude XdmfExampleHeavyDataController.py
307 308 309 310
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getStride
   * @until #//getStride
311
   *
312 313
   * @return    A vector containing the stride in each dimension of the
   *            heavy data set owned by this controller.
314 315 316
   */
  std::vector<unsigned int> getStride() const;

317
  /**
318 319
   * Get the array type of the heavy data set owned by this
   * controller.
320
   *
321 322 323 324
   * Example of use:
   *
   * C++
   *
325
   * @dontinclude ExampleXdmfHeavyDataController.cpp
326 327 328 329
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getType
   * @until //#getType
330 331 332
   *
   * Python
   *
333
   * @dontinclude XdmfExampleHeavyDataController.py
334 335 336 337
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getType
   * @until #//getType
338
   *
339
   * @return    An XdmfArrayType containing the array type of the heavy data set.
340
   */
341
  shared_ptr<const XdmfArrayType> getType() const;
342 343

  /**
344 345
   * Read data owned by this controller on disk into the passed
   * XdmfArray.
346
   *
347 348 349 350
   * Example of use:
   *
   * C++
   *
351
   * @dontinclude ExampleXdmfHeavyDataController.cpp
352 353 354 355
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#read
   * @until //#read
356 357 358
   *
   * Python
   *
359
   * @dontinclude XdmfExampleHeavyDataController.py
360 361 362 363
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//read
   * @until #//read
364
   *
365
   * @param     array   An XdmfArray to read data into.
366 367 368
   */
  virtual void read(XdmfArray * const array) = 0;

369
protected:
370 371 372

  XdmfHeavyDataController(const std::string & filePath,
                          const std::string & dataSetPath,
373
                          const shared_ptr<const XdmfArrayType> type,
374 375 376 377
                          const std::vector<unsigned int> & start,
                          const std::vector<unsigned int> & stride,
                          const std::vector<unsigned int> & dimensions,
                          const std::vector<unsigned int> & dataspaceDimensions);
378

379
  const std::string mDataSetPath;
380
  const std::vector<unsigned int> mDataspaceDimensions;
381 382
  const std::vector<unsigned int> mDimensions;
  const std::string mFilePath;
383 384
  const std::vector<unsigned int> mStart;
  const std::vector<unsigned int> mStride;
385
  unsigned int mArrayStartOffset;
386
  const shared_ptr<const XdmfArrayType> mType;
387

388
private:
389 390 391

  XdmfHeavyDataController(const XdmfHeavyDataController&);  // Not implemented.
  void operator=(const XdmfHeavyDataController &);  // Not implemented.
392 393 394

};

395
#ifdef _WIN32
396
XDMFCORE_TEMPLATE template class XDMFCORE_EXPORT
397
shared_ptr<const XdmfArrayType>;
398 399
#endif

400
#endif /* XDMFHEAVYDATACONTROLLER_HPP_ */