ExodusII
6.05
Loading...
Searching...
No Matches
doxygen.h
Go to the documentation of this file.
1
/*! \mainpage ExodusII API Documentation
2
3
\section intro Introduction
4
5
EXODUS is the successor of the widely used finite element (FE) data file format EXODUS
6
(henceforth referred to as EXODUS I) developed by Mills-Curran and Flanagan. It
7
continues the concept of a common database for multiple application codes (mesh generators,
8
analysis codes, visualization software, etc.) rather than code-specific utilities, affording
9
flexibility and robustness for both the application code developer and application code user.
10
By using the EXODUS data model, a user inherits the flexibility of using a large array of
11
application codes (including vendor-supplied codes) which access this common data file
12
directly or via translators.
13
14
The uses of the EXODUS data model include the following:
15
- Problem definition -- mesh generation, specification of locations of boundary conditions and load application, specification of material types.
16
- Simulation -- model input and results output.
17
- Visualization -- model verification, results postprocessing, data interrogation, and analysis tracking.
18
19
\section avail License and Availability
20
The EXODUS library is licensed under the BSD open source license.
21
22
Copyright (c) 2005 Sandia Corporation. Under the terms of Contract DE-AC04-94AL85000
23
with Sandia Corporation, the U.S. Government retains certain rights in this software.
24
25
Redistribution and use in source and binary forms, with or without modification, are permitted
26
provided that the following conditions are met:
27
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
28
- Redistributions in binary form must reproduce the above copyright notice, this list
29
of conditions and the following disclaimer in the documentation and/or other
30
materials provided with the distribution.
31
-Neither the name of Sandia Corporation nor the names of its contributors may be
32
used to endorse or promote products derived from this software without specific
33
prior written permission.
34
35
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
36
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
37
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
38
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
39
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
42
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
43
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
44
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
45
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
46
47
The ExodusII library source code is available on Sourceforge at
48
http://sourceforge.net/projects/exodusii
49
50
For bug reports, documentation errors, and enhancement suggestions, contact:
51
- Gregory D. Sjaardema
52
- PHONE: (505) 844-2701
53
- EMAIL: gdsjaar@sandia.gov
54
55
\section devel Development of EXODUS
56
57
The evolution of the EXODUS data model has been steered by FE application code developers
58
who desire the advantages of a common data format. The EXODUS model has been
59
designed to overcome deficiencies in the EXODUS I file format and meet the following
60
functional requirements as specified by these developers:
61
- Random read/write access.
62
- Application programming interface (API) -- provide routines callable from FORTRAN, C, and C++ application codes.
63
- Extensible -- allow new data objects to be added without modifying the application programs that use the file format.
64
- Machine independent -- data should be independent of the machine which generated it.
65
- Real-time access during analysis -- allow access to the data in a file while the file is
66
being created.
67
68
To address these requirements, the open source database library
69
etCDF (http://www.unidata.ucar.edu/software/netcdf/) was selected to handle the low-level data storage. The EXODUS
70
II library functions provide the mapping between FE data objects and
71
netCDF dimensions, attributes, and variables. Thus, the code developer
72
interacts with the data model using the vocabulary of an FE analyst
73
(element connectivity, nodal coordinates, etc.) and is relieved of the
74
details of the data access mechanism.
75
76
Because an EXODUS file is a netCDF file, an application program can
77
access data via the EXODUS API or the netCDF API directly. Although
78
accessing the data directly via the netCDF API requires more in-depth
79
understanding of netCDF, this capability is a powerful feature that
80
allows the development of auxiliary libraries of special purpose
81
functions not offered in the standard EXODUS library. For example,
82
if an application required access to the coordinates of a single node
83
(the standard library function returns the coordinates for all of the
84
nodes in the model), a simple function could be written that calls
85
netCDF routines directly to read the data of interest.
86
87
\section descrip Description of Data Objects
88
89
The data in EXODUS files can be divided into three primary
90
categories: initialization data, model, and results.
91
92
Initialization data includes sizing parameters (number of nodes,
93
number of elements, etc.), optional quality assurance information
94
(names of codes that have operated on the data), and optional
95
informational text.
96
97
The model is described by data which are static (do not change through
98
time). These data include nodal coordinates, element connectivity
99
(node lists for each element), element attributes, and node sets and
100
side sets (used to aid in applying loading conditions and boundary
101
constraints).
102
103
The results are optional and include five types of variables -- nodal,
104
element, nodeset, sideset, and global -- each of which is stored
105
through time. Nodal results are output (at each time step) for all the
106
nodes in the model. An example of a nodal variable is displacement in
107
the X direction. Element, nodeset, and sideset results are output (at
108
each time step) for all entities (elements, nodes, sides) in one or
109
more entity block. For example, stress may be an element
110
variable. Another use of element variables is to record element status
111
(a binary flag indicating whether each element is "alive" or "dead")
112
through time. Global results are output (at each time step) for a
113
single element or node, or for a single property. Linear momentum of a
114
structure and the acceleration at a particular point are both examples
115
of global variables. Although these examples correspond to typical FE
116
applications, the data format is flexible enough to accommodate a
117
spectrum of uses.
118
119
A few conventions and limitations must be cited:
120
121
- There are no restrictions on the frequency of results output except
122
that the time value associated with each successive time step must
123
increase monotonically.
124
- To output results at different frequencies (i.e., variable A at
125
every simulation time step, variable B at every other time step)
126
multiple EXODUS files must be used.
127
- There are no limits to the number of each type of results, but once
128
declared, the number cannot change.
129
- If the mesh geometry or topology changes in time (i.e., number of
130
nodes increases, connectivity changes), then the new geometrymust be
131
output to a new EXODUS file.
132
133
\section int64 Integer Bulkdata Storage Details
134
135
The EXODUS database can store integer bulk data, entity map data, and
136
mesh entity (block/set) ids in either 32-bit or 64-bit integer format. The data
137
considered "bulk data" are:
138
139
- element, face, and edge connectivity lists,
140
- element, face, edge, and node set entity lists,
141
142
The entity map data is any data stored in one of the 'map' objects on
143
the exodus file. This includes:
144
- id maps
145
- number maps
146
- order maps
147
- processor node maps
148
- processor element maps.
149
150
A mesh entity id is the id of any block (element block, edge block,
151
...); set (node set, face set, ...), coordinate frame, and
152
communication map.
153
154
When an EXODUS file is created via the ex_create() function, the
155
'mode' argument provides the mechanism for specifying how integer data
156
will be passed as arguments to the API functions and also how the
157
integer data will be stored on the database. The ex_open() function
158
also provides a mechanism for specifying how integer data will be
159
passed as arguments.
160
161
The method uses the 'mode' argument to the ex_open() and
162
ex_create() functions. The mode is a 32-bit integer in which certain
163
bits are turned on by or'ing certain predefined constants.
164
165
exoid = ex_create( EX_TEST_FILENAME,
166
EX_CLOBBER|EX_MAPS_INT64_DB|EX_MAPS_INT64_API,
167
&appWordSize, &diskWordSize );
168
169
The constants related to the integer size (32-bit or 64-bit)
170
specification are:
171
172
- EX_MAPS_INT64_DB -- entity map data
173
- EX_IDS_INT64_DB -- mesh entity ids
174
- EX_BULK_INT64_DB -- bulk data
175
- EX_ALL_INT64_DB -- (the above 3 or'd together)
176
- EX_MAPS_INT64_API -- entity map data
177
- EX_IDS_INT64_API -- mesh entity ids
178
- EX_BULK_INT64_API -- bulk data
179
- EX_ALL_INT64_API -- (the above 3 or'd together)
180
181
The constants that end with "_DB" specify that that particular integer
182
data is stored on the database as 64-bit integers; the constants that
183
end with "_API" specify that that particular integer data is passed
184
to/from API functions as 64-bit integers.
185
186
If the range of the data being transmitted is larger than the
187
permitted integer range (for example, if the data is stored on the
188
database as 64-bit ints and the application specifies passing data as
189
32-bit ints), the api function will return an error.
190
191
The three types of integer data whose storage can be specified are
192
- maps (EX_MAPS_INT64_),
193
- "bulk data" including connectivity lists and entity lists (EX_BULK_INT64_), and
194
- entity ids which are the ids of element, face, edge, and node sets
195
and blocks; and map ids (EX_IDS_INT64_)
196
197
The function ex_int64_status(exoid) is used to determine the integer
198
storage types being used for the EXODUS database 'exoid'. It returns
199
an integer which can be and'ed with the above flags to determine
200
either the storage type or function parameter type.
201
202
For example, if
203
(EX_MAPS_INT64_DB \& ex_int64_status(exoid)) is true, then map data is
204
being stored as 64-bit integers for that database.
205
206
It is not possible to determine the integer data size on a database
207
without opening the database via an ex_open() call. However, the
208
integer size specification for API functions can be changed at any
209
time via the ex_set_int64_status(exoid, mode) function. The mode is
210
one or more of EX_MAPS_INT64_API, EX_IDS_INT64_API, or
211
EX_BULK_INT64_API, or'd together. Any exodus function calls after
212
that point will use the specified integer size. Note that a call to
213
ex_set_int64_status(exoid, mode) overrides any previous setting for
214
the integer sizes used in the API. The ex_create() function is the
215
only way to specify the integer sizes specification for database
216
integers.
217
218
\subsection int64_fortran_api Fortran API
219
The fortran api is uses the same mechanism as was described above for
220
the C API. If using the "8-byte real and 8-byte int" fortran mode
221
typically used by the SEACAS applications (the compiler automatically
222
promotes all integers and reals to 8-byte quantities), then the
223
fortran exodus library will automatically enable the *_API
224
options; the client still needs to specify the *_DB options.
225
226
\subsection int64_fortran_imp Fortran Implementation
227
228
The new capability to pass 64-bit integer data through the fortran and
229
C API functions simplifies the implementation of the "8-byte real
230
8-byte int" usage of the exodus library. Previously, the wrapper
231
routines in addrwrap.F were required to convert the 8-byte integer
232
data on the client side to/from 4-byte integers on the library
233
side. This required extra memory allocation and complications that are
234
now handled at the lowest level in the netcdf library. The
235
map-related functions in the fortran api have all been converted to
236
pass 64-bit integers down to the C API which has removed some code and
237
simplified those functions.
238
239
240
\section Database Options (Compression, Name Length, File Type)
241
242
The ex_set_option() function call is used to set various options on the
243
database. Valid values for 'option' are:
244
245
| Option Name | Option Values
246
-------------------------|---------------
247
| EX_OPT_MAX_NAME_LENGTH | Maximum length of names that will be returned/passed via api call.
248
| EX_OPT_COMPRESSION_TYPE | Not currently used; default is gzip
249
| EX_OPT_COMPRESSION_LEVEL | In the range [0..9]. A value of 0 indicates no compression
250
| EX_OPT_COMPRESSION_SHUFFLE | 1 if enabled, 0 if disabled
251
| EX_OPT_INTEGER_SIZE_API | 4 or 8 indicating byte size of integers used in api functions.
252
| EX_OPT_INTEGER_SIZE_DB | Query only, returns 4 or 8 indicating byte size of integers stored on database.
253
254
The compression-related options are only available on netcdf-4 files
255
since the underlying hdf5 compression functionality is used for the
256
implementation. The compression level indicates how much effort should
257
be expended in the compression and the computational expense increases
258
with higher levels; in many cases, a compression level of 1 is
259
sufficient.
260
261
\defgroup ResultsData Results Data
262
@{
263
This section describes data file utility functions for creating /
264
opening a file, initializing a file with global parameters, reading /
265
writing information text, inquiring on parameters stored in the data
266
file, and error reporting.
267
@}
268
269
\defgroup Utilities Data File Utilities
270
@{
271
This section describes data file utility functions for creating /
272
opening a file, initializing a file with global parameters, reading /
273
writing information text, inquiring on parameters stored in the data
274
file, and error reporting.
275
@}
276
277
\defgroup ModelDescription Model Description
278
@{
279
The routines in this section read and write information which
280
describe an exodus finite element model. This includes nodal
281
coordinates, element order map, element connectivity arrays,
282
element attributes, node sets, side sets, and object properties.
283
@}
284
285
286
*/
cbind
include
doxygen.h
Generated on Fri Jul 23 2021 13:00:59 for ExodusII by
1.10.0