Xdmf.hpp 7.2 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 : Xdmf.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 _XDMF_HPP
#define _XDMF_HPP
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67

/*! \mainpage XDMF API
*
* \section intro Introduction
*
* The eXtensible Data Model and Format (XDMF) is a distributed data
* hub for accessing scientific data in High Performance Computing
* (HPC) applications. XDMF defines a data model and format as well as
* facilities for accessing the data in a distributed environment.
*
* XDMF differs from other data model and format efforts in that the
* "light data" is logically (and possibly physically) separated from
* the "heavy data". Light data is considered to be both "data about
* the data" such as dimensions and name, as well as small quantities
* of computed data. Heavy data is considered to be large amounts of
* data. For example, in a three dimensional structural mechanics
* calculation, the size and dimensions of the computational grid are
* light data while the actual X, Y, and Z values for the grid are
* heavy data. Calculated values like "Pressure at a node" are heavy,
* while "Total Residual Mass" for the entire calculation is light.
* Light data is stored on disk in a machine parsable language like
* XML. Heavy data is stored in a format suitable for large amounts of
* data like HDF5.
*
* While use of the XDMF API is not necessary to produce or consume
* valid datasets, it is extremely useful for handling the wide variety
* of files that are possible and its use is highly recommended. The
* XDMF API is written in C++ and is wrapped for access from other
* languages including Python and Java.
*
* XDMF utilizes reference counting shared pointers to handle ownership
* of XDMF objects. This allows multiple objects to reference a single
* XDMF object. An object is deleted and memory is reclaimed when no
* other XDMF objects hold a reference to the object. This allows
* flexibility in constructing XDMF structures, as simple structures
* can be shared instead of copied.
*
* All XDMF objects are constructed by calling New(), which returns a
* shared pointer to a newly constructed object. All default
* constructors in the XDMF API are protected, ensuring that only
* shared pointers can be created. These pointers are freed
* automatically by the shared pointer reference counting mechanism.
68
*
69 70 71 72 73 74 75 76 77 78
*
* Structure:
*
* Xdmf2 is structured in a tree format with an XdmfDomain serving
* as the base. The Domain contains multiple grid collections or
* grids; each with their own geometries, topologies, attributes,
* and/or sets. With the inclusion of shared pointers in Xdmf2
* a topology could be shared across multiple grids or a grid 
* could be included in multiple grid collections and/or the domain.
*
79 80 81
* Comparing objects is done by comparing pointer addresses,
* a deep copy will not produce an equivalent object.
*
82
*
83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98
* C++ Examples:
*
* \subpage cppwrite "C++ Example of Xdmf Creation"
*
* \subpage cppread "C++ Example of Reading Xdmf"
*
* \subpage cppedit "C++ Example of Reading and Modifying Xdmf"
*
* Python Examples:
*
* \subpage pywrite "Python Example of Xdmf Creation"
*
* \subpage pyread "Python Example of Reading Xdmf"
*
* \subpage pyedit "Python Example of Reading and Modifying Xdmf"
*
99 100
*/

101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
/*!
* \page cppwrite Example of Xdmf Creation
* \include ExampleXdmfWrite.cpp
*/

/*!
* \page cppread Example of Reading Xdmf
* \include ExampleXdmfRead.cpp
*/

/*!
* \page cppedit Example of Reading and Modifying
* \include ExampleXdmfEdit.cpp
*/

/*!
* \page pywrite Example of Xdmf Creation
* \include XdmfExampleWrite.py
*/

/*!
* \page pyread Example of Reading Xdmf
* \include XdmfExampleRead.py
*/

/*!
* \page pyedit Example of Reading and Modifying
* \include XdmfExampleEdit.py
*/



133 134
/* Keep all our Win32 Conversions here */
#ifdef _WIN32
135 136 137 138 139 140 141 142
#ifdef XDMFSTATIC
#define XDMFCORE_EXPORT
#define XDMFDSM_EXPORT
#define XDMF_EXPORT
#define XDMFCORE_TEMPLATE
#define XDMFDSM_TEMPLATE
#define XDMF_TEMPLATE
#else
143 144 145 146 147
/* Used to export/import from the dlls */
#undef XDMFCORE_EXPORT
#define XDMFCORE_EXPORT __declspec(dllimport)
#undef XDMFCORE_TEMPLATE
#define XDMFCORE_TEMPLATE extern
148

149 150 151 152 153
#undef XDMFDSM_EXPORT
#define XDMFDSM_EXPORT __declspec(dllimport)
#undef XDMFDSM_TEMPLATE
#define XDMFDSM_TEMPLATE extern

154 155 156 157 158 159 160
#ifdef Xdmf_EXPORTS
#define XDMF_EXPORT __declspec(dllexport)
#define XDMF_TEMPLATE
#else /* Xdmf_EXPORTS */
#define XDMF_EXPORT __declspec(dllimport)
#define XDMF_TEMPLATE extern
#endif /* Xdmf_EXPORTS */
161
#endif
162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177

/* Compiler Warnings */
#ifndef XDMF_DEBUG
#pragma warning( disable : 4231 ) /* nonstandard extension used : 'extern' before template explicit instantiation */
#pragma warning( disable : 4251 ) /* needs to have dll-interface to be used by clients (Most of these guys are in private */
#pragma warning( disable : 4275 ) /* non dll-interface class 'std::_Container_base_aux' used as base for dll-interface class */
#pragma warning( disable : 4373 ) /* virtual function overrides,  parameters only differed by const/volatile qualifiers */
#pragma warning( disable : 4748 ) /* /GS can not protect parameters and local variables from local buffer overrun (turned off op)*/
#endif /* XDMF_DEBUG */

/* Compiler Optimizations will result in an 'internal compiler error', so turn them off */
#pragma optimize("g", off)

#else /* _WIN32 */
/* We don't need to export/import since there are no dlls */
#define XDMFCORE_EXPORT
178
#define XDMFDSM_EXPORT
179 180
#define XDMF_EXPORT
#define XDMFCORE_TEMPLATE
181
#define XDMFDSM_TEMPLATE
182 183
#define XDMF_TEMPLATE
#endif /* _WIN32 */
184 185
#endif /* _XDMF_HPP */