XdmfWriter.hpp 14.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 : XdmfWriter.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
#ifndef XDMFWRITER_HPP_
#define XDMFWRITER_HPP_
26 27 28

// Forward Declarations
class XdmfArray;
29
class XdmfInformation;
30
class XdmfHeavyDataWriter;
31 32

// Includes
33
#include "XdmfCore.hpp"
34 35 36
#include "XdmfVisitor.hpp"

/**
37 38
 * @brief Traverse the Xdmf graph and write light and heavy data
 * stored to disk.
39
 *
40 41 42 43 44 45
 * XdmfWriter visits each node of an Xdmf graph structure and writes
 * data to disk. Writing begins by calling the accept() operation on
 * any XdmfItem and supplying this writer as the parameter. The
 * XdmfItem as well as all children attached to the XdmfItem are
 * written to disk. Heavy data is written to a heavy data format using
 * an XdmfHeavyDataWriter and light data is written to XML.
46
 *
47 48 49
 * An infinite loop is possible if an XdmfItem somehow ends up as its own child,
 * either directly or by way of another Xdmf Item.
 *
50 51 52 53 54 55 56 57
 * By default, the XdmfWriter writes all heavy data to a single heavy
 * data file specified by the XdmfHeavyDataWriter. If a dataset is
 * encountered that resides in a different heavy data file on disk,
 * the dataset is read from disk and written to the new heavy data
 * file. If this is undesired, the XdmfWriter can be set to
 * DistributedHeavyData mode in which the writer will automatically
 * reference any heavy dataset even if it resides in a different file
 * than the one currently being written to.
58
 */
59
class XDMFCORE_EXPORT XdmfWriter : public XdmfVisitor,
60 61
                                   public Loki::Visitor<XdmfArray> {

62
public:
63 64 65 66 67 68 69

  enum Mode {
    Default,
    DistributedHeavyData
  };

  /**
70 71 72 73
   * Create a new XdmfWriter to write Xdmf data to disk. This will
   * create its own hdf5 writer based on the xmlFileName. For example,
   * if supplied "output.xmf" the created hdf5 writer would write to
   * file "output.h5".
74
   *
75 76 77 78
   * Example of use:
   *
   * C++
   *
79
   * @dontinclude ExampleXdmfWriter.cpp
80 81
   * @skipline //#initialization
   * @until //#initialization
82 83 84
   *
   * Python
   *
85
   * @dontinclude XdmfExampleWriter.py
86 87
   * @skipline #//initialization
   * @until #//initialization
88
   *
89
   * @param     xmlFilePath     The path to the xml file to write to.
90
   *
91
   * @return                    The new XdmfWriter.
92
   */
93
  static shared_ptr<XdmfWriter> New(const std::string & xmlFilePath);
94 95

  /**
96 97 98
   * Create a new XdmfWriter to write Xdmf data to disk. This will
   * utilize the passed heavy data writer to write any heavy data to
   * disk.
99
   *
100 101 102 103
   * Example of use:
   *
   * C++
   *
104
   * @dontinclude ExampleXdmfWriter.cpp
105 106
   * @skipline //#heavyinitialization
   * @until //#heavyinitialization
107 108 109
   *
   * Python
   *
110
   * @dontinclude XdmfExampleWriter.py
111 112
   * @skipline #//heavyinitialization
   * @until #//heavyinitialization
113
   *
114 115
   * @param     xmlFilePath             The path to the xml file to write to.
   * @param     heavyDataWriter         The heavy data writer to use when writing.
116
   *
117
   * @return                            The new XdmfWriter.
118
   */
119 120
  static shared_ptr<XdmfWriter> New(const std::string & xmlFilePath, 
                                    const shared_ptr<XdmfHeavyDataWriter> heavyDataWriter);
121

122 123 124 125 126
  /**
   * Create a new XdmfWriter to write Xdmf data to disk. This will
   * write heavy data to disk using the passed heavy data writer and
   * will add xml output to the stream.
   *
127 128 129 130
   * Example of use:
   *
   * C++
   *
131
   * @dontinclude ExampleXdmfWriter.cpp
132 133
   * @skipline #//bufferinitialization
   * @until #//bufferinitialization
134 135 136
   *
   * Python: does not curretnly support this version of New
   *
137 138
   * @param     stream                  The output stream to write light data to.
   * @param     heavyDataWriter         The heavy data writer to use when writing.
139
   *
140
   * @return                            The new XdmfWriter.
141 142 143 144
   */
  static shared_ptr<XdmfWriter> New(std::ostream & stream,
                                    const shared_ptr<XdmfHeavyDataWriter> heavyDataWriter);

145 146 147
  virtual ~XdmfWriter();

  /**
148 149
   * Get the absolute path to the XML file on disk this writer is
   * writing to.
150
   *
151 152 153 154
   * Example of use:
   *
   * C++
   *
155
   * @dontinclude ExampleXdmfWriter.cpp
156 157 158 159
   * @skipline //#heavyinitialization
   * @until //#heavyinitialization
   * @skipline //#getFilePath
   * @until //#getFilePath
160 161 162
   *
   * Python
   *
163
   * @dontinclude XdmfExampleWriter.py
164 165 166 167
   * @skipline //#heavyinitialization
   * @until //#heavyinitialization
   * @skipline //#getFilePath
   * @until //#getFilePath
168
   *
169 170
   * @return    A std::string containing the path to the XML file on disk this
   *            writer is writing to.
171 172 173 174
   */
  std::string getFilePath() const;

  /**
175 176
   * Get the heavy data writer that this XdmfWriter uses to write
   * heavy data to disk.
177
   *
178 179 180 181
   * Example of use:
   *
   * C++
   *
182
   * @dontinclude ExampleXdmfWriter.cpp
183 184 185 186
   * @skipline //#heavyinitialization
   * @until //#heavyinitialization
   * @skipline //#getHeavyDataWriter
   * @until //#getHeavyDataWriter
187 188 189
   *
   * Python
   *
190
   * @dontinclude XdmfExampleWriter.py
191 192 193 194
   * @skipline #//heavyinitialization
   * @until #//heavyinitialization
   * @skipline #//getHeavyDataWriter
   * @until #//getHeavyDataWriter
195
   *
196
   * @return    The requested heavy data writer.
197
   */
198
  shared_ptr<XdmfHeavyDataWriter> getHeavyDataWriter();
199 200

  /**
201 202
   * Get the heavy data writer that this XdmfWriter uses to write
   * heavy data to disk (const version).
203
   *
204 205 206 207
   * Example of use:
   *
   * C++
   *
208
   * @dontinclude ExampleXdmfWriter.cpp
209 210 211 212
   * @skipline //#heavyinitialization
   * @until //#heavyinitialization
   * @skipline //#getHeavyDataWriterconst
   * @until //#getHeavyDataWriterconst
213 214 215
   *
   * Python: Does not support a contant version of this function
   *
216
   * @return    The requested heavy data writer.
217
   */
218
  shared_ptr<const XdmfHeavyDataWriter> getHeavyDataWriter() const;
219

220
  /**
221 222
   * Get the number of values that this writer writes to light data
   * (XML) before switching to a heavy data format.
223
   *
224 225 226 227 228
   * Example of use:
   *
   * C++
   *
   * @dontinclude ExampleXdmfWriter.cpp
229 230 231 232
   * @skipline //#heavyinitialization
   * @until //#heavyinitialization
   * @skipline //#getLightDataLimit
   * @until //#getLightDataLimit
233 234 235 236
   *
   * Python
   *
   * @dontinclude XdmfExampleWriter.py
237 238 239 240
   * @skipline #//heavyinitialization
   * @until #//heavyinitialization
   * @skipline #//getLightDataLimit
   * @until #//getLightDataLimit
241
   *
242
   * @return    An unsigned int containing the number of values.
243
   */
244
  unsigned int getLightDataLimit() const;
245

246
  /**
247
   * Get the Mode of operation for this writer.
248
   *
249 250 251 252
   * Example of use:
   *
   * C++
   *
253
   * @dontinclude ExampleXdmfWriter.cpp
254 255 256 257
   * @skipline //#heavyinitialization
   * @until //#heavyinitialization
   * @skipline //#getMode
   * @until //#getMode
258 259 260
   *
   * Python
   *
261
   * @dontinclude XdmfExampleWriter.py
262 263 264 265
   * @skipline #//heavyinitialization
   * @until #//heavyinitialization
   * @skipline #//getMode
   * @until #//getMode
266
   *
267
   * @return    The Mode of operation for this writer.
268
   */
269
  Mode getMode() const;
270 271

  /**
272
   * Get whether this writer is set to write xpaths.
273
   *
274 275 276 277
   * Example of use:
   *
   * C++
   *
278
   * @dontinclude ExampleXdmfWriter.cpp
279 280 281 282
   * @skipline //#heavyinitialization
   * @until //#heavyinitialization
   * @skipline //#getWriteXPaths
   * @until //#getWriteXPaths
283 284 285
   *
   * Python
   *
286
   * @dontinclude XdmfExampleWriter.py
287 288 289 290
   * @skipline #//heavyinitialization
   * @until #//heavyinitialization
   * @skipline #//getWriteXPaths
   * @until #//getWriteXPaths
291
   *
292
   * @return    bool whether this writer is set to write xpaths.
293
   */
294
  bool getWriteXPaths() const;
295 296

  /**
297
   * Get whether this writer is set to parse xpaths from information.
298
   *
299 300 301 302
   * Example of use:
   *
   * C++
   *
303
   * @dontinclude ExampleXdmfWriter.cpp
304 305 306 307
   * @skipline //#heavyinitialization
   * @until //#heavyinitialization
   * @skipline //#getXPathParse
   * @until //#getXPathParse
308 309 310
   *
   * Python
   *
311
   * @dontinclude XdmfExampleWriter.py
312 313 314 315
   * @skipline #//heavyinitialization
   * @until #//heavyinitialization
   * @skipline #//getXPathParse
   * @until #//getXPathParse
316
   *
317
   * @return    bool whether this writer is set to write xpaths.
318
   */
319
  bool getXPathParse() const;
320

321
  /**
322 323
   * Set the heavy data writer that this XdmfWriter uses to write
   * heavy data to disk.
324 325 326 327 328 329
   *
   * Example of use:
   *
   * C++
   *
   * @dontinclude ExampleXdmfWriter.cpp
330 331 332 333 334 335
   * @skipline //#heavyinitialization
   * @until //#heavyinitialization
   * @skipline //#getHeavyDataWriter
   * @until //#getHeavyDataWriter
   * @skipline //#setHeavyDataWriter
   * @until //#setHeavyDataWriter
336 337 338 339
   *
   * Python
   *
   * @dontinclude XdmfExampleWriter.py
340 341 342 343 344 345 346
   * @skipline #//heavyinitialization
   * @until #//heavyinitialization
   * @skipline #//getHeavyDataWriter
   * @until #//getHeavyDataWriter
   * @skipline #//setHeavyDataWriter
   * @until #//setHeavyDataWriter
   *
347
   * @param     heavyDataWriter         The heavy data writer to set.
348
   */
349
  void setHeavyDataWriter(shared_ptr<XdmfHeavyDataWriter> heavyDataWriter);
350

351
  /**
352 353
   * Set the number of values that this writer writes to light data
   * (XML) before switching to a heavy data format.
354
   *
355 356 357 358
   * Example of use:
   *
   * C++
   *
359
   * @dontinclude ExampleXdmfWriter.cpp
360 361 362 363
   * @skipline //#heavyinitialization
   * @until //#heavyinitialization
   * @skipline //#setLightDataLimit
   * @until //#setLightDataLimit
364 365 366
   *
   * Python
   *
367
   * @dontinclude XdmfExampleWriter.py
368 369 370 371
   * @skipline #//heavyinitialization
   * @until #//heavyinitialization
   * @skipline #//setLightDataLimit
   * @until #//setLightDataLimit
372
   *
373
   * @param     numValues       An unsigned int containing the number of values.
374 375 376 377 378 379
   */
  void setLightDataLimit(const unsigned int numValues);

  /**
   * Set the mode of operation for this writer.
   *
380 381 382 383
   * Example of use:
   *
   * C++
   *
384
   * @dontinclude ExampleXdmfWriter.cpp
385 386 387 388
   * @skipline //#heavyinitialization
   * @until //#heavyinitialization
   * @skipline //#setMode
   * @until //#setMode
389 390 391
   *
   * Python
   *
392
   * @dontinclude XdmfExampleWriter.py
393 394 395 396
   * @skipline #//heavyinitialization
   * @until #//heavyinitialization
   * @skipline #//setMode
   * @until #//setMode
397
   *
398
   * @param     mode    The Mode of operation for this writer.
399 400 401 402 403 404
   */
  void setMode(const Mode mode);

  /**
   * Set whether to write xpaths for this writer.
   *
405 406 407 408
   * Example of use:
   *
   * C++
   *
409
   * @dontinclude ExampleXdmfWriter.cpp
410 411 412 413
   * @skipline //#heavyinitialization
   * @until //#heavyinitialization
   * @skipline //#setWriteXPaths
   * @until //#setWriteXPaths
414 415 416
   *
   * Python
   *
417
   * @dontinclude XdmfExampleWriter.py
418 419 420 421
   * @skipline #//heavyinitialization
   * @until #//heavyinitialization
   * @skipline #//setWriteXPaths
   * @until #//setWriteXPaths
422
   *
423
   * @param     writeXPaths     Whether to write xpaths for this writer.
424 425 426
   */
  void setWriteXPaths(const bool writeXPaths = true);

427 428 429 430 431 432 433 434
  /**
   * Set whether to parse xpaths from infomation for this writer.
   *
   * Example of use:
   *
   * C++
   *
   * @dontinclude ExampleXdmfWriter.cpp
435 436 437 438
   * @skipline //#heavyinitialization
   * @until //#heavyinitialization
   * @skipline //#setXPathParse
   * @until //#setXPathParse
439 440 441 442
   *
   * Python
   *
   * @dontinclude XdmfExampleWriter.py
443 444 445 446
   * @skipline #//heavyinitialization
   * @until #//heavyinitialization
   * @skipline #//setXPathParse
   * @until #//setXPathParse
447
   *
448
   * @param     xPathParse      Whether to write xpaths for this writer.
449 450 451
   */
  void setXPathParse(const bool xPathParse = true);

452 453 454
  /**
   * Write an XdmfArray to disk
   *
455 456 457 458
   * Example of use:
   *
   * C++
   *
459
   * @dontinclude ExampleXdmfWriter.cpp
460 461
   * @skipline //#visitarray
   * @until //#visitarray
462 463 464
   *
   * Python
   *
465
   * @dontinclude XdmfExampleWriter.py
466 467
   * @skipline #//visitarray
   * @until #//visitarray
468
   *
469 470
   * @param     array           An XdmfArray to write to disk.
   * @param     visitor         A smart pointer to this visitor --- aids in grid traversal.
471 472
   */
  virtual void visit(XdmfArray & array,
473
                     const shared_ptr<XdmfBaseVisitor> visitor);
474 475 476 477

  /**
   * Write an XdmfItem to disk
   *
478 479 480 481
   * Example of use:
   *
   * C++
   *
482
   * @dontinclude ExampleXdmfWriter.cpp
483 484
   * @skipline //#visititem
   * @until //#visititem
485 486 487
   *
   * Python
   *
488
   * @dontinclude XdmfExampleWriter.py
489 490
   * @skipline #//visititem
   * @until #//visititem
491
   *
492 493
   * @param     item            An XdmfItem to write to disk.
   * @param     visitor         A smart pointer to this visitor --- aids in grid traversal.
494 495
   */
  virtual void visit(XdmfItem & item,
496
                     const shared_ptr<XdmfBaseVisitor> visitor);
497 498


499
protected:
500 501

  XdmfWriter(const std::string & xmlFilePath,
502 503
             shared_ptr<XdmfHeavyDataWriter> heavyDataWriter,
             std::ostream * stream = NULL);
504 505 506 507

  void setDocumentTitle(std::string title);
  void setVersionString(std::string version);

508
private:
509 510 511 512 513 514 515 516 517 518

  /**
   * PIMPL
   */
  class XdmfWriterImpl;

  XdmfWriter(const XdmfWriter &);  // Not implemented.
  void operator=(const XdmfWriter &);  // Not implemented.

  XdmfWriterImpl * mImpl;
519

520 521
};

522
#ifdef _WIN32
523
XDMFCORE_TEMPLATE template class XDMFCORE_EXPORT
524
shared_ptr<XdmfHeavyDataWriter>;
525
XDMFCORE_TEMPLATE template class XDMFCORE_EXPORT
526
shared_ptr<const XdmfHeavyDataWriter>;
527 528
#endif

529
#endif /* XDMFWRITER_HPP_ */