1 /*******************************************************************/
2 /*                               XDMF                              */
3 /*                   eXtensible Data Model and Format              */
4 /*                                                                 */
5 /*  Id : Id  */
6 /*  Date : $Date$ */
7 /*  Version : $Revision$ */
8 /*                                                                 */
9 /*  Author:                                                        */
10 /*     Jerry A. Clarke                                             */
11 /*     clarke@arl.army.mil                                         */
12 /*     US Army Research Laboratory                                 */
13 /*     Aberdeen Proving Ground, MD                                 */
14 /*                                                                 */
15 /*     Copyright @ 2002 US Army Research Laboratory                */
16 /*     All Rights Reserved                                         */
17 /*     See Copyright.txt or http://www.arl.hpc.mil/ice for details */
18 /*                                                                 */
19 /*     This software is distributed WITHOUT ANY WARRANTY; without  */
20 /*     even the implied warranty of MERCHANTABILITY or FITNESS     */
21 /*     FOR A PARTICULAR PURPOSE.  See the above copyright notice   */
22 /*     for more information.                                       */
23 /*                                                                 */
24 /*******************************************************************/
25 #ifndef __XdmfGrid_h
26 #define __XdmfGrid_h
27 
28 #include "XdmfElement.h"
29 
30 namespace xdmf2
31 {
32 
33 class XdmfGeometry;
34 class XdmfTopology;
35 class XdmfInformation;
36 class XdmfAttribute;
37 class XdmfArray;
38 class XdmfTime;
39 class XdmfSet;
40 
41 #define XDMF_GRID_UNIFORM       0x00000 // Type xor XDMF_GRID_MASK = XdmfTopology Type
42 #define XDMF_GRID_COLLECTION    0x10000
43 #define XDMF_GRID_TREE          0x20000
44 #define XDMF_GRID_SUBSET        0x40000
45 #define XDMF_GRID_UNSET         0x0FFFF
46 
47 #define XDMF_GRID_MASK          0xF0000
48 
49 
50 #define XDMF_GRID_SECTION_ALL           0x100000
51 #define XDMF_GRID_SECTION_DATA_ITEM     0x200000
52 #define XDMF_GRID_SECTION_MASK          0xF00000
53 
54 #define XDMF_GRID_COLLECTION_TEMPORAL   0x0001
55 #define XDMF_GRID_COLLECTION_SPATIAL    0x0002
56 #define XDMF_GRID_COLLECTION_UNSET      0x0FFFF
57 
58 //! In memory representation of an XDMF Grid
59 /*!
60         XdmfGrid is the in memory representation of the Xdmf Grid
61         structure defined in the XML. XdmfGrids can be one of four
62         types : \b Uniform , \b Collection \b Tree or \b Subset. Uniform is a
63         Homogeneous Single Grid (i.e. a group of triangles). A \b Collection
64         is an array of Uniform grids. A Subset specifies a cell selection
65         of a previously defined grid. A Tree is a Hierarchial group.
66         Uniform XdmfGrids have \b Topolgy (i.e.
67         what type of grid and the connectivity if it's unstructured )
68         \b Geometry ( the XYZ values for the grid nodes ) and zero
69         or more \b Attributes (the computed values such as scalars,
70         vectors, tensors, etc.)
71 
72         The XML for a Uniform Grid might look like :
73 \verbatim
74 <Grid Name="Sphere of Tets"
75 >
76 
77     <Topology Type="Tetrahedron"
78      NumberOfElements="1838"
79      BaseOffset="1" >
80 
81         <DataStructure Format="HDF"
82          Dimensions="1838 4"
83          DataType="Int" >
84                         Shapes.h5:/Block 1/Connections
85         </DataStructure>
86     </Topology>
87     <Geometry Type="XYZ" >
88 
89         <DataStructure Format="HDF"
90          Dimensions="1309 3"
91          DataType="Float" >
92                 Shapes.h5:/Geometry
93         </DataStructure>
94     </Geometry>
95 
96 
97     <!-- ReUse the Geometry as a Scalar Value of X Position -->
98 
99     <Attribute Type="Scalar" Center="Node" Name="X Position">
100         <DataTransform Dimensions="1309 1" Type="HyperSlab" >
101             <DataStructure Format="XML" Dimensions="2 3">
102                 0 0 1 3 1309 1
103             </DataStructure>
104             <DataStructure Format="HDF"
105                  Dimensions="1309 3"
106                  DataType="Float" >
107                 Shapes.h5:/Geometry
108             </DataStructure>
109         </DataTransform>
110     </Attribute>
111 </Grid>
112 
113 
114 
115     XML Element : Grid
116     XML Attribute : Name = Any String
117     XML Attribute : GridType = Uniform* | Collection | Tree | Subset
118     XML Attribute : Section = DataItem* | All  (Only Meaningful if GridType="Subset")
119 
120 \endverbatim
121 
122         Typical API usage might look like :
123         \code
124 
125         XdmfDOM *DOM = new XdmfDOM();
126         XdmfGrid *Grid = new XdmfGrid();
127         XdmfAttribute *XPos;
128         XdmfXNode *GridNode;
129 
130         DOM->SetInputFileName("MyData.xmf");
131         DOM->Parse();
132         GridNode = DOM->FindElement("Grid");
133         Grid->SetDOM(DOM);
134         Grid->SetElement(GridNode);
135         Grid->UpdateInformation(GridNode);
136         cout << "First Grid has " << Grid->GetNumberOfAttributes() << " Attributes" << endl;
137         Grid->AssignAttributeByName("X Position");
138         XPos = Grid->GetAssignedAttribute();
139 
140         \endcode
141 */
142 
143 class XDMF_EXPORT XdmfGrid : public XdmfElement {
144 
145 public:
146   XdmfGrid();
147   ~XdmfGrid();
148 
GetClassName()149   XdmfConstString GetClassName() { return ( "XdmfGrid" ) ; };
150 
151 //! Explicitly set the XdmfGeometry for an XdmfGrid
152   XdmfSetValueMacro( Geometry, XdmfGeometry *);
153 //! Get the XdmfGeometry for an XdmfGrid
154   XdmfGetValueMacro( Geometry, XdmfGeometry *);
155 //! Explicitly set the XdmfTopology for an XdmfGrid
156   XdmfSetValueMacro( Topology, XdmfTopology *);
157 //! Get the XdmfTopology for an XdmfGrid
158   XdmfGetValueMacro( Topology, XdmfTopology *);
159 //! Explicitly set the XdmfTime for an XdmfGrid
160   XdmfSetValueMacro( Time, XdmfTime *);
161 //! Get the XdmfTime for an XdmfGrid
162   XdmfGetValueMacro( Time, XdmfTime *);
163 
164   //! Get the Grid Type as a string
165   XdmfConstString GetGridTypeAsString();
166 
167   XdmfInt32 SetGridTypeFromString(XdmfConstString GridType);
168 
169   //! Get the Collection Type as a string
170   XdmfConstString GetCollectionTypeAsString();
171   XdmfInt32 SetCollectionTypeFromString(XdmfConstString CollectionType);
172 
173 
174   //! Build the XML (OUTPUT)
175   XdmfInt32 Build();
176 
177 //! Create a XML node for the Topology of a Uniform Grid
178   XdmfInt32 InsertTopology();
179 //! Create a XML node for the Geometry of a Uniform Grid
180   XdmfInt32 InsertGeometry();
181 //! Insert an Element
182   XdmfInt32 Insert(XdmfElement *Child);
183   //! Get the Grid Type
184   XdmfGetValueMacro( GridType, XdmfInt32);
185   //! Set the Grid Type
186   XdmfSetValueMacro( GridType, XdmfInt32);
187   //! Get the Collection Type
188   XdmfGetValueMacro( CollectionType, XdmfInt32);
189   //! Set the Collection Type
190   XdmfSetValueMacro( CollectionType, XdmfInt32);
191   //! Get Build Time Flag
192   XdmfGetValueMacro( BuildTime, XdmfInt32);
193   //! Set the Build Time Flag
194   XdmfSetValueMacro( BuildTime, XdmfInt32);
195 
196   //! Copy Information from Another DataItem
197   XdmfInt32 Copy(XdmfElement *Source);
198 
199   //! Get the Number of Children
200   XdmfGetValueMacro( NumberOfChildren, XdmfInt32);
201   //! Set the Number Of Children
202   XdmfSetValueMacro( NumberOfChildren, XdmfInt32);
203 
204   //! Is this a Uniform Grid ?
205   XdmfInt32 IsUniform();
206 
207 //! Get the number of Attributes defined for this grid.
208 /*!
209         Attributes can be Scalars(1 value), Vectors(3 values),
210         Tensors(9 values), or Matrix(NxM array). Attributes can be centered
211         on the Node, Cell, Edge, Face, or Grid.
212 */
213   XdmfGetValueMacro( NumberOfAttributes, XdmfInt32 );
214 
215 //! Get Number of Sets
216   XdmfGetValueMacro( NumberOfSets, XdmfInt32 );
217 
218 //! Get Number of Informations
219   XdmfGetValueMacro( NumberOfInformations, XdmfInt32 );
220 
221 //! Retreive a particilar XdmfAttribute
222 /*!
223         Returns the Xdmf Attribute from the grid.
224         \param Index    0 based index of the Attribute to retreive
225 */
226   XdmfGetIndexValueMacro( Attribute, XdmfAttribute * );
227 
228 //! Get a particular Set
229   XdmfGetIndexValueMacro( Sets, XdmfSet * );
230 
231 //! Update an Attribute and Mark it as Primary
232 /*!
233         When an XdmfGrid is read using SetGridFromElement() the Attribute
234         values are not read in since there could potentially be an enourmous
235         amout of data associated with the computational grid. Instead, for
236         each Attribute of interest, AssignAttribute is called. This updates
237         the Heavy Data and marks it as the primary attribute. So the last
238         Attribute read will be one marked : visualization readers might
239         use this information in their filters. (i.e. An isosurface generator
240         might use the primary scalar to determine the scalar value on which
241         to generate the surface.
242 
243         \param Index    0 based index of the Attribute to retreive
244 */
245   XdmfInt32 AssignAttribute( XdmfInt64 Index );
246 #ifndef SWIG
247   XdmfInt32 AssignAttribute( XdmfAttribute *Attribute );
248 #endif
249 //! Same as AssignAttribute (more verbose for scripting languages)
250   XdmfInt32 AssignAttributeByIndex( XdmfInt64 Index );
251 //! Assign the Attribute with the specified name
252 /*!
253         In the XML of the grid, if an Attribute has a
254         \b Name value, this Attribute will be assigned.
255         Example:
256         \verbatim
257         <Attribute Name="Pressure">
258                 <DataStructure
259                         Format="HDF"
260                         DataType="Float"
261                         Precision="4"
262                         Dimensions="10 20 30">
263                                 Pressure.h5:/Time01/Pressure
264                 </DataStructure>
265         </Attribute>
266         \endverbatim
267 */
268   XdmfInt32 AssignAttributeByName( XdmfString Name );
269 
270 //! Return the currently marked as Primary
GetAssignedAttribute(void)271   XdmfAttribute *GetAssignedAttribute( void ) { return( this->AssignedAttribute ); };
272 //! Returns the index of the Attribute currently marked as Primary
273   XdmfInt64 GetAssignedAttributeIndex( void );
274 
275   //! Initialize Grid from XML but don't access Heavy Data
276   /*!
277         Initializes the basic grid structure based on the information found
278         in the specified XML Node but does not read any of the underlying
279         Heavy data. This can be used to determine the type of grid (structured
280         or unstructured, Hex or Tet) and to determine the rank and dimensions
281         of the grid.
282   */
283   XdmfInt32  UpdateInformation();
284 //! Initialize the grid and read the Heavy Data
285 /*!
286         Initializes the basic grid structure based on the information found
287         in the specified XML Node and Read the associated Heavy Data for the
288         Topology and Geometry. Heavy Data for the Attreibute(s) is not read.
289         Use AssignAttribute to update Attribute Heavy Data.
290 */
291   XdmfInt32  Update();
292 
293  //! Get one of the child Grids from a Collection or Tree
294   XdmfGrid  *GetChild(XdmfInt32 Index);
295 
296  //! Get one of the child Grids from a Collection or Tree
297   XdmfInformation  *GetInformation(XdmfInt32 Index);
298 
299  //! Return indexes of first level children that are valid at a time
300  XdmfInt32 FindGridsInTimeRange(XdmfFloat64 TimeMin, XdmfFloat64 TimeMax, XdmfArray *ArrayToFill);
301 
302  //! Return indexes of first level children that are valid at a time
303  XdmfInt32 FindGridsAtTime(XdmfTime *Time, XdmfArray *ArrayToFill, XdmfFloat64 Epsilon = 0.0, XdmfInt32 Append=0);
304 
305  //! Release Big Data
306  XdmfInt32 Release();
307 
308 protected:
309 
310   XdmfGeometry  *Geometry;
311   XdmfTopology  *Topology;
312   XdmfTime      *Time;
313   XdmfInt32     GeometryIsMine;
314   XdmfInt32     TopologyIsMine;
315   XdmfInt32     TimeIsMine;
316   XdmfInt32     NumberOfAttributes;
317   XdmfInt32	NumberOfInformations;
318   XdmfInt32     NumberOfSets;
319   XdmfInt32     GridType;
320   XdmfInt32     CollectionType;
321   XdmfInt32     NumberOfChildren;
322   XdmfInt32     BuildTime;
323   XdmfGrid      **Children;
324   XdmfSet       **Sets;
325   XdmfAttribute **Attribute;
326   XdmfInformation **Informations;
327   XdmfAttribute *AssignedAttribute;
328 };
329 
330 //! Using a SWIG style Pointer return an XdmfGrid Pointer
331 extern XDMF_EXPORT XdmfGrid *HandleToXdmfGrid( XdmfString Source);
332 }
333 #endif // __XdmfGrid_h
334