XDMF API: Difference between revisions

From XdmfWeb
Jump to navigationJump to search
No edit summary
(Replaced content with "Image:XdmfLogo1.gif '''XDMF API''' While use of the XDMF API is not necessary to produce or consume valid XDMF datasets, there are many convenience features that ma...")
 
(9 intermediate revisions by 5 users not shown)
Line 1: Line 1:
[[Image:XdmfLogo1.gif]]
'''XDMF API'''
'''XDMF API'''


While use of the XDMF API is not necessary to produce or consume valid XDMF datasets, there are many convenience features that make it attractive. The XDMF library give access to a C++ class library that is also wrapped for access from scripting languages like Python.
While use of the XDMF API is not necessary to produce or consume valid XDMF datasets, there are many convenience features that make it attractive. The XDMF library give access to a C++ class library that is also wrapped for access from scripting languages like Python.


[[Xdmf3 C++ API]]


All XDMF Objects are derived from XdmfObject. Via this object, debug information can be turned on or off for each object or globally for all objects. The methods DebugOn/Off() and GlobalDebugOn/Off() perform the
[[Xdmf3 Python API]]
se functions respectively.
 
Most examples here are written in Python for clarity.
 
'''XdmfDOM'''
 
To understand access to XDMF data, understanding of the XdmfDOM is critical. XDMF uses the libxml2 library to parse and generate XML documents. XdmfDOM is a slightly higher abstraction of the Document Object Mod
el (DOM). The DOM is an in-memory tree structure that represents the XML file. Nodes of the tree are added, deleted, queried and serialized. The low level libxml2 nodes are typedefed as XdmfXmlNode.
 
The XdmfDOM can parser strings or files :
Status = XdmfDOM.Parse(MyXMLString)
or
Status = XdmfDOM.Parse(<nowiki>"</nowiki>MyXMLFile.xmf<nowiki>"</nowiki>)
 
As with many XDMF objects, status is either XDMF_SUCCESS or XDMF_FAIL which is defined in XdmfObject.h.
 
Once the XML has been parsed into the DOM, the tree can be navigated and modified. There are several useful query mechanisms in XdmfDOM. The first method finds the n<nowiki></nowiki>th instance of an element bel
ow a parent node :
 
  XdmfXmlNode    FindElement (XdmfConstString TagName, XdmfInt32 Index=0, XdmfXmlNode Node=NULL, XdmfInt32 IgnoreInfo=1)
 
If Node==NULL the root node is assumed to be the desired parent node. IgnoreInfo allows for all "Information" elements to be ignored. For example, to find the 3^rd^ Grid element under the Domain element :
 
  DomainNode = XdmfDOM.FindElemet(<nowiki></nowiki>Domain<nowiki></nowiki>)      <nowiki>#</nowiki> Take all defaults
  GridNode = XdmfDOM.FindElement(<nowiki></nowiki>Grid<nowiki></nowiki>, 2, DomainNode)  <nowiki>#</nowiki> Index is zero based
 
By utilizing the XPath functionality of libxml2, the same Grid element can be found by :
  GridNode = XdmfDOM.FindElementByPath(<nowiki></nowiki>/Xdmf/Domain/Grid<nowiki>[</nowiki>3<nowiki>]</nowiki><nowiki></nowiki>)  <nowiki>#</nowiki> XPath is 1 based
 
Once the desired node is found, it can be queried and modified :
NumberOfChildElements = XdmfDOM.GetNumberOfChildren(GridNode)
Name = XdmfDOM.GetAttribute(GridNode, <nowiki></nowiki>Name<nowiki></nowiki>)
SubGrid = XdmfDOM.InsertNew(GridNode, <nowiki></nowiki>Grid<nowiki></nowiki>)
Status = XdmfDOM.Set(SubGrid, <nowiki></nowiki>Name<nowiki></nowiki>, <nowiki></nowiki>My SubGrid<nowiki></nowiki>)
 
And finally written back out :
XmlString = XdmfDOM.Serialize(GridNode)
or
Status = XdmfDOM.Write(<nowiki></nowiki>MyFile.xmf<nowiki></nowiki>)
 
'''XdmfElement'''
 
Each element type in an XDMF XML file has a corresponding XDMF object implementation. All of these are children of XdmfElement. Each XdmfElement must be provided with an XdmfDOM with which to operate. On input,
the UpdateInformation() method will initialize the basic structure of the element
from the XML without reading any HeavyData. The Update() method will access the HeavyData. Each derived object from XdmfElement (XdmfGrid for example) will override these methods.
 
GridNode = DOM.FindElementByPath(<nowiki></nowiki>/Xdmf/Domain/Grid<nowiki>[</nowiki>3<nowiki>]</nowiki><nowiki></nowiki>) 
Grid = XdmfGrid()              <nowiki>#</nowiki> Create
Grid.SetDOM(DOM)
Grid.SetElement(GridNode)
Grid.UpdateInformation()        <nowiki>#</nowiki> Update Light Structure
Grid.Update()                  <nowiki>#</nowiki> Read HeavyData
 
Once the DOM has been set for an XdmfElement, there are convenience methods such as Set() and Get() which are equivalent to the XdmfDOM methods.
GridName = Grid.Get(<nowiki></nowiki>Name<nowiki></nowiki>)
Is the same as
 
DOM = Grid.GetDOM()
GridNode = Grid.GetElement()
GridName = DOM.Get(GridNode, <nowiki></nowiki>Name<nowiki></nowiki>)
 
For output, the XdmfElement methods Insert() and Build() are used.  Each derived object in XDMF will assure that only the proper type of element is inserted. For example, it is illegal to insert a Domain element directly below a Grid element.
 
Info = XdmfInformation() <nowiki>#</nowiki> Arbitrary Name=Value Facility
Info.SetName("Time")
Info.SetValue("0.0123")
Grid = XdmfGrid()
Grid.Set(<nowiki></nowiki>Name<nowiki></nowiki>, <nowiki></nowiki>My Grid<nowiki></nowiki>)
Grid.Insert(Info)
Grid.Build()
 
Results in
 
&lt;Grid Name="My Grid"&gt;
&lt;Information Name="Time" Value="0.0123" /&gt;
&lt;/Grid&gt;
The Build() method is recursive so that Build() will automatically be called for all child elements.
 
'''XdmfArray'''
 
The XdmfArray class is a self describing data structure. It is derived from the XdmfDataDesc class that gives it number type, precision, and shape (rank and dimensions). Many XDMF classes require an XdmfArray as
input to methods. The following C++ example demonstrates creating an interlaced XYZ array from three separate variables:
float  <nowiki>*</nowiki>x, <nowiki>*</nowiki>y, <nowiki>*</nowiki>z;
XdmfInt64      total, dims<nowiki>[</nowiki>3<nowiki>]</nowiki>;
XdmfArray      <nowiki>*</nowiki>xyz = new XdmfArray;
 
dims<nowiki>[</nowiki>0<nowiki>]</nowiki> = 10;
dims<nowiki>[</nowiki>1<nowiki>]</nowiki> = 20;
dims<nowiki>[</nowiki>2<nowiki>]</nowiki> = 30;
total = 10 <nowiki>*</nowiki> 20 <nowiki>*</nowiki> 30;
xyz-&gt;SetNumberType(XDMF_FLOAT64_TYPE)
xyz-&gt;SetShape(3, dims);    // KDim, JDim, IDim
xyz-&gt;SetValues(0, x, total, 3, 1);  //      SetValues (XdmfInt64 Index, XdmfFloat64 <nowiki>*</nowiki>Values,
// XdmfInt64 NumberOfValues, XdmfInt64 ArrayStride=1,  // XdmfInt64 ValuesStride=1)
xyz-&gt;SetValues(1, y, total, 3, 1);
xyz-&gt;SetValues(2, z, total, 3, 1);
 
When an XdmfArray is created, it is given a unique tag name. Array operations can be performed on XdmfArray data by using this name in an XdmfExpr(). The following Python program gives some examples.
from Xdmf import <nowiki>*</nowiki>
 
def Expression(<nowiki>*</nowiki>args) :
    e = <nowiki></nowiki><nowiki></nowiki>
    for arg in args :
        if hasattr(arg, <nowiki></nowiki>GetTagName<nowiki></nowiki>) :
            e += arg.GetTagName() + <nowiki></nowiki> <nowiki></nowiki>
        else :
            e += arg + <nowiki></nowiki> <nowiki></nowiki>
    return XdmfExpr(e)
 
 
if __name__ == <nowiki></nowiki>__main__<nowiki></nowiki> :
    a1 = XdmfArray()
    a1.SetNumberType(XDMF_FLOAT32_TYPE)
    a1.SetNumberOfElements(20)
    a1.Generate(1, 20)
    a2 = XdmfArray()
    a2.SetNumberType(XDMF_INT32_TYPE)
    a2.SetNumberOfElements(5)
    a2.Generate(2, 10)
    print <nowiki></nowiki>a1 Values = <nowiki></nowiki>, a1.GetValues()
    print <nowiki></nowiki>a1<nowiki>[</nowiki>2:10<nowiki>]</nowiki> = <nowiki></nowiki> + Expression(a1 , <nowiki></nowiki><nowiki>[</nowiki> 2:10 <nowiki>] </nowiki><nowiki></nowiki>).GetValues()
    print <nowiki></nowiki>a2 Values = <nowiki></nowiki>, a2.GetValues()
    print <nowiki></nowiki>a1<nowiki>[</nowiki>a2<nowiki>]</nowiki> = <nowiki></nowiki> + Expression(a1 , <nowiki></nowiki><nowiki>[</nowiki><nowiki></nowiki>, a2, <nowiki></nowiki><nowiki>]</nowiki><nowiki></no
wiki>).GetValues()
    print <nowiki></nowiki>a1 + a2 = <nowiki></nowiki> + Expression(a1 , <nowiki></nowiki> + <nowiki></nowiki>, a2).GetValues()
    print <nowiki></nowiki>a1 <nowiki>*</nowiki> a2 = <nowiki></nowiki> + Expression(a1 , <nowiki></nowiki> <nowiki>*</nowiki> <nowiki></nowiki>, a2).GetValues()
    a2.SetNumberType(XDMF_FLOAT32_TYPE)
    a2.SetNumberOfElements(20)
    a2.Generate(21, 40)
    print <nowiki></nowiki>a2 Values = <nowiki></nowiki>, a2.GetValues()
    print <nowiki></nowiki>a1 , a2 (Interlace) = <nowiki></nowiki> + Expression(a1 , <nowiki></nowiki> , <nowiki></nowiki>, a2).GetValues()
    print <nowiki></nowiki>a1 , a2, a1 (Interlace) = <nowiki></nowiki> + Expression(a1 , <nowiki></nowiki> , <nowiki></nowiki>, a2, <nowiki></nowiki> , <nowiki></nowiki>, a1).GetValues()
    print <nowiki></nowiki>a1 ; a2 (Concat) = <nowiki></nowiki> + Expression(a1 , <nowiki></nowiki> ; <nowiki></nowiki>, a2).GetValues()
    print <nowiki></nowiki>where(a1 &gt; 10) = <nowiki></nowiki> + Expression(<nowiki></nowiki>Where( <nowiki></nowiki>, a1 , <nowiki></nowiki> &gt; 10)<nowiki></nowiki>).GetValues()
    print <nowiki></nowiki>a2<nowiki>[</nowiki>where(a1 &gt; 10)<nowiki>]</nowiki> = <nowiki></nowiki> + Expression(a2, <nowiki></nowiki><nowiki>[</nowiki>Where( <nowiki></nowiki>, a1 , <nowiki></nowiki> &gt; 10
)<nowiki>]</nowiki><nowiki></nowiki>).GetValues()
 
While most of the functions are self explanatory the WHERE function is not. WHERE will return the indexes of the XdmfArray where a certain condition is true. In this example WHERE returns the indexes of XdmfArra
y a1 where a1 is greater than 10. Notice that the XdmfExpr() function makes it easy to extract part of an XdmfArray.
 
'''XdmfHDF'''
 
In XDMF Light data is stored in XML while the Heavy data is typically stored in an HDF5 file.
The XdmfHDF class simplifies access to HDF5 data, it is also derived from XdmfDataDesc. The following Python code demonstrates its use :
 
 
        from Xdmf import <nowiki>*</nowiki>
 
Geometry = <nowiki></nowiki>-1.75 -1.25 0 -1.25 -1.25 0 -0.75
Connectivity = <nowiki></nowiki>3 2 5 1 .
Values = <nowiki></nowiki>100 200 300 ..
 
<nowiki>#</nowiki> Geometry
GeometryArray = XdmfArray()
GeometryArray.SetValues(0, Geometry)
H5 = XdmfHDF()
H5.CopyType(GeometryArray)
H5.CopyShape(GeometryArray)
<nowiki>#</nowiki> Open for Writing. This will truncate the file.
H5.Open(<nowiki></nowiki>Example1.h5:/Geometry<nowiki></nowiki>, <nowiki></nowiki>w<nowiki></nowiki>)
H5.Write(GeometryArray)
H5.Close()
 
<nowiki>#</nowiki> Connectivity
ConnectivityArray = XdmfArray()
ConnectivityArray.SetValues(0, Connectivity)
H5 = XdmfHDF()
H5.CopyType(ConnectivityArray)
H5.CopyShape(ConnectivityArray)
<nowiki>#</nowiki> Open for Reading and Writing. This will NOT truncate the file.
H5.Open(<nowiki></nowiki>Example1.h5:/Connectivity<nowiki></nowiki>, <nowiki></nowiki>rw<nowiki></nowiki>)
H5.Write(ConnectivityArray)
H5.Close()
 
 
<nowiki>#</nowiki> Values
ValueArray = XdmfArray()
ValueArray.SetValues(0, Values)
H5 = XdmfHDF()
H5.CopyType(ValueArray)
H5.CopyShape(ValueArray)
<nowiki>#</nowiki> Open for Reading and Writing. This will NOT truncate the file.
H5.Open(<nowiki></nowiki>Example1.h5:/Values<nowiki></nowiki>, <nowiki></nowiki>rw<nowiki></nowiki>)
H5.Write(ValueArray)
H5.Close()
 
For reading, XdmfHDF will allocate an array if none is specified :
Status = H5.Open(<nowiki></nowiki>Example1.h5:/Values<nowiki></nowiki>, <nowiki></nowiki>rw<nowiki></nowiki>)
ValueArray = H5.Read()
 
'''Reading XDMF'''
 
Putting all of this together, assume Points.xmf is a valid XDMF XML file with a single uniform Grid. Here is a Python example to read and print values.
 
dom = XdmfDOM()
dom.Parse(<nowiki></nowiki>Points.xmf<nowiki></nowiki>)
 
ge = dom.FindElementByPath(<nowiki></nowiki>/Xdmf/Domain/Grid<nowiki></nowiki>)
grid = XdmfGrid()
grid.SetDOM(dom)
grid.SetElement(ge)
grid.UpdateInformation()
grid.Update()
 
top = grid.GetTopology()
top.DebugOn()
conn = top.GetConnectivity()
print <nowiki></nowiki>Values = <nowiki></nowiki>, conn.GetValues()
 
geo = grid.GetGeometry()
points = geo.GetPoints()
print <nowiki></nowiki>Geo Type = <nowiki></nowiki>, geo.GetGeometryTypeAsString(), <nowiki></nowiki> <nowiki>#</nowiki> Points = <nowiki></nowiki>,    geo.GetNumberOfPoints()
print <nowiki></nowiki>Points = <nowiki></nowiki>, points.GetValues(0, 6)
 
'''Writing XDMF'''


Using the Insert() and Build() methods, an XDMF dataset can be generated programmatically as well . Internally, as XDMF objects are inserted, the DOM is "decorated" with their pointers. In this manner, the api c
[[Xdmf3 Fortran API]]
an get a object from an node of the DOM if it has been created. For reading XDMF, this allows multiple references to the same DataItem not to result in additional IO. For writing, this allows Build() to work rec
ursively.


d = XdmfDOM()


root = XdmfRoot()
root.SetDOM(d)
root.SetVersion(2.2) <nowiki>#</nowiki> Change the Version number because we can
root.Build()
<nowiki>#</nowiki> Information
i = XdmfInformation() <nowiki>#</nowiki> Arbitrary Name=Value Facility
i.SetName("Time")
i.SetValue("0.0123")
root.Insert(i) <nowiki>#</nowiki> XML DOM is used as the keeper of the structure
                <nowiki>#</nowiki> Insert() creates an XML node and inserts it under
                <nowiki>#</nowiki> the parent
<nowiki>#</nowiki> Domain
dm = XdmfDomain()
root.Insert(dm)
<nowiki>#</nowiki> Grid
g = XdmfGrid()
g.SetName("Structured Grid")
<nowiki>#</nowiki> Topology
t = g.GetTopology()
t.SetTopologyType(XDMF_3DCORECTMESH)
t.GetShapeDesc().SetShapeFromString(<nowiki></nowiki>10 20 30<nowiki></nowiki>)
<nowiki>#</nowiki> Geometry
geo = g.GetGeometry()
geo.SetGeometryType(XDMF_GEOMETRY_ORIGIN_DXDYDZ)
geo.SetOrigin(1, 2, 3)
geo.SetDxDyDz(0.1, 0.2, 0.3)
dm.Insert(g)
<nowiki>#</nowiki> Attribute
attr = XdmfAttribute()
attr.SetName("Pressure")
attr.SetAttributeCenter(XDMF_ATTRIBUTE_CENTER_CELL);
attr.SetAttributeType(XDMF_ATTRIBUTE_TYPE_SCALAR);
p = attr.GetValues()
p.SetNumberOfElements(10 <nowiki>*</nowiki> 20 <nowiki>*</nowiki> 30)
p.Generate(0.0, 1.0, 0, p.GetNumberOfElements() - 1)
g.Insert(attr)
# Update XML and Write Values to DataItems
root.Build() <nowiki>#</nowiki> DataItems &gt; 100 values are heavy
print d.Serialize() <nowiki>#</nowiki> prints to stdout


d.Write(<nowiki></nowiki>MyMesh.xmf<nowiki></nowiki>) <nowiki>#</nowiki> write to file
[[Xdmf2 API Archive]]

Latest revision as of 10:43, 7 November 2014

XdmfLogo1.gif


XDMF API

While use of the XDMF API is not necessary to produce or consume valid XDMF datasets, there are many convenience features that make it attractive. The XDMF library give access to a C++ class library that is also wrapped for access from scripting languages like Python.

Xdmf3 C++ API

Xdmf3 Python API

Xdmf3 Fortran API


Xdmf2 API Archive

Retrieved from "http://www.xdmf.org/index.php?title=XDMF_API&oldid=130"