Exodus 7.22

doxygen.h
Go to the documentation of this file.
1 /* clang-format off */
2
3 /*! \mainpage Exodus API Documentation
4
5 \section intro Introduction
6
7 EXODUS is the successor of the widely used finite element (FE) data file format EXODUS
8 (henceforth referred to as EXODUS I) developed by Mills-Curran and Flanagan. It
9 continues the concept of a common database for multiple application codes (mesh generators,
10 analysis codes, visualization software, etc.) rather than code-specific utilities, affording
11 flexibility and robustness for both the application code developer and application code user.
12 By using the EXODUS data model, a user inherits the flexibility of using a large array of
13 application codes (including vendor-supplied codes) which access this common data file
14 directly or via translators.
15
16 The uses of the EXODUS data model include the following:
17 - Problem definition -- mesh generation, specification of locations of boundary conditions and
18 load application, specification of material types.
19 - Simulation -- model input and results output.
20 - Visualization -- model verification, results postprocessing, data interrogation, and analysis
21 tracking.
22
23 \section avail Availability
24
25 The Exodus library source code is available on Github at
26 https://github.com/gsjaardema/seacas
27
28 For bug reports, documentation errors, and enhancement suggestions, contact:
29 - Gregory D. Sjaardema
30 - WEB: https://github.com/gsjaardema/seacas/issues
31 - EMAIL: gdsjaar@sandia.gov
32 - EMAIL: gsjaardema@gmail.com
33 - PHONE: (505) 844-2701 (office)
34 - PHONE: (505) 999-8991 (cell)
35
36 \section license License
37 The EXODUS library is licensed under the BSD open source license.
38
39 Copyright (c) 2005-2017 National Technology & Engineering Solutions
40 of Sandia, LLC (NTESS). Under the terms of Contract DE-NA0003525 with
41 NTESS, the U.S. Government retains certain rights in this software.
42
43 Redistribution and use in source and binary forms, with or without
44 modification, are permitted provided that the following conditions are
45 met:
46
47 * Redistributions of source code must retain the above copyright
48 notice, this list of conditions and the following disclaimer.
49
50 * Redistributions in binary form must reproduce the above
51 copyright notice, this list of conditions and the following
52 disclaimer in the documentation and/or other materials provided
53 with the distribution.
54
55 * Neither the name of NTESS nor the names of its
56 contributors may be used to endorse or promote products derived
57 from this software without specific prior written permission.
58
59 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
60 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
61 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
62 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
63 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
64 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
65 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
66 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
67 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
68 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
69 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
70
71 \section devel Development of EXODUS
72
73 The evolution of the EXODUS data model has been steered by FE application code developers
74 who desire the advantages of a common data format. The EXODUS model has been
75 designed to overcome deficiencies in the EXODUS I file format and meet the following
76 functional requirements as specified by these developers:
77 - Random read/write access.
78 - Application programming interface (API) -- provide routines callable from FORTRAN, C, and C++
79 application codes.
80 - Extensible -- allow new data objects to be added without modifying the application programs
81 that use the file format.
82 - Machine independent -- data should be independent of the machine which generated it.
83 - Real-time access during analysis -- allow access to the data in a file while the file is
84 being created.
85
86 To address these requirements, the open source database library
87 NetCDF (http://www.unidata.ucar.edu/software/netcdf/) was selected to handle the low-level data
88 storage. The EXODUS
89 II library functions provide the mapping between FE data objects and
90 NetCDF dimensions, attributes, and variables. Thus, the code developer
91 interacts with the data model using the vocabulary of an FE analyst
92 (element connectivity, nodal coordinates, etc.) and is relieved of the
93 details of the data access mechanism.
94
95 Because an EXODUS file is a NetCDF file, an application program can
96 access data via the EXODUS API or the NetCDF API directly. Although
97 accessing the data directly via the NetCDF API requires more in-depth
98 understanding of NetCDF, this capability is a powerful feature that
99 allows the development of auxiliary libraries of special purpose
100 functions not offered in the standard EXODUS library. For example,
101 if an application required access to the coordinates of a single node
102 (the standard library function returns the coordinates for all of the
103 nodes in the model), a simple function could be written that calls
104 NetCDF routines directly to read the data of interest.
105
106 \section descrip Description of Data Objects
107
108 The data in EXODUS files can be divided into three primary
109 categories: initialization data, model, and results.
110
111 Initialization data includes sizing parameters (number of nodes,
112 number of elements, etc.), optional quality assurance information
113 (names of codes that have operated on the data), and optional
114 informational text.
115
116 The model is described by data which are static (do not change through
117 time). These data include nodal coordinates, element connectivity
118 (node lists for each element), element attributes, and node sets and
119 side sets (used to aid in applying loading conditions and boundary
120 constraints).
121
122 The results are optional and include five types of variables -- nodal,
123 element, nodeset, sideset, and global -- each of which is stored
124 through time. Nodal results are output (at each time step) for all the
125 nodes in the model. An example of a nodal variable is displacement in
126 the X direction. Element, nodeset, and sideset results are output (at
127 each time step) for all entities (elements, nodes, sides) in one or
128 more entity block. For example, stress may be an element
129 variable. Another use of element variables is to record element status
130 (a binary flag indicating whether each element is "alive" or "dead")
131 through time. Global results are output (at each time step) for a
132 single element or node, or for a single property. Linear momentum of a
133 structure and the acceleration at a particular point are both examples
134 of global variables. Although these examples correspond to typical FE
135 applications, the data format is flexible enough to accommodate a
136 spectrum of uses.
137
138 A few conventions and limitations must be cited:
139
140 - There are no restrictions on the frequency of results output except
141 that the time value associated with each successive time step must
142 increase monotonically.
143 - To output results at different frequencies (i.e., variable A at
144 every simulation time step, variable B at every other time step)
145 multiple EXODUS files must be used.
146 - There are no limits to the number of each type of results, but once
147 declared, the number cannot change.
148 - If the mesh geometry or topology changes in time (i.e., number of
149 nodes increases, connectivity changes), then the new geometry must be
150 output to a new EXODUS file.
151
152 \section int64 Integer Bulkdata Storage Details (32-bit and 64-bit integers)
153
154 The EXODUS database can store integer bulk data, entity map data, and
155 mesh entity (block/set) ids in either 32-bit or 64-bit integer format. The data
156 considered "bulk data" are:
157
158 - element, face, and edge connectivity lists,
159 - element, face, edge, and node set entity lists,
160
161 The entity map data is any data stored in one of the 'map' objects on
162 the exodus file. This includes:
163 - id maps
164 - number maps
165 - order maps
166 - processor node maps
167 - processor element maps.
168
169 A mesh entity id is the id of any block (element block, edge block,
170 ...); set (node set, face set, ...), coordinate frame, and
171 communication map.
172
173 When an EXODUS file is created via the ex_create() function, the
174 'mode' argument provides the mechanism for specifying how integer data
175 will be passed as arguments to the API functions and also how the
176 integer data will be stored on the database. The ex_open() function
177 also provides a mechanism for specifying how integer data will be
178 passed as arguments.
179
180 The method uses the 'mode' argument to the ex_open() and
181 ex_create() functions. The mode is a 32-bit integer in which certain
182 bits are turned on by or'ing certain predefined constants.
183
184 exoid = ex_create( "test.exo",
185 EX_CLOBBER|EX_MAPS_INT64_DB|EX_MAPS_INT64_API,
186 &appWordSize, &diskWordSize );
187
188 The constants related to the integer size (32-bit or 64-bit)
189 specification are:
190
191 | Constant Name | Which data are 64-bit
192 ---------------------|----------------------
193 | #EX_MAPS_INT64_DB | entity map data
194 | #EX_IDS_INT64_DB | mesh entity ids
195 | #EX_BULK_INT64_DB | bulk data
196 | #EX_ALL_INT64_DB | (the above 3 or'd together)
197 | #EX_MAPS_INT64_API | entity map data
198 | #EX_IDS_INT64_API | mesh entity ids
199 | #EX_BULK_INT64_API | bulk data
200 | #EX_INQ_INT64_API | integers passed to/from ex_inquire()
201 | #EX_ALL_INT64_API | (the above 4 or'd together)
202
203 The constants that end with `_DB` specify that that particular integer
204 data is stored on the database as 64-bit integers; the constants that
205 end with `_API` specify that that particular integer data is passed
206 to/from API functions as 64-bit integers.
207
208 If the range of the data being transmitted is larger than the
209 permitted integer range (for example, if the data is stored on the
210 database as 64-bit ints and the application specifies passing data as
211 32-bit ints), the API function will return an error.
212
213 The three types of integer data whose storage can be specified are
214 - maps (`EX_MAPS_INT64_`),
215 - "bulk data" including connectivity lists and entity lists (`EX_BULK_INT64_`), and
216 - entity ids which are the ids of element, face, edge, and node sets
217 and blocks; and map ids (`EX_IDS_INT64_`)
218
219 The function ex_int64_status()(exoid) is used to determine the integer
220 storage types being used for the EXODUS database `exoid`. It returns
221 an integer which can be and'ed with the above flags to determine
222 either the storage type or function parameter type.
223
224 For example, if
225 `(#EX_MAPS_INT64_DB & ex_int64_status()(exoid))` is true, then map data is
226 being stored as 64-bit integers for that database.
227
228 It is not possible to determine the integer data size on a database
229 without opening the database via an ex_open() call. However, the
230 integer size specification for API functions can be changed at any
231 time via the ex_set_int64_status()(exoid, mode) function. The mode is
232 one or more of `#EX_MAPS_INT64_API`, `#EX_IDS_INT64_API`, or
233 `#EX_BULK_INT64_API`, or'd together. Any exodus function calls after
234 that point will use the specified integer size. Note that a call to
235 ex_set_int64_status()(exoid, mode) overrides any previous setting for
236 the integer sizes used in the API. The ex_create() function is the
237 only way to specify the integer sizes specification for database
238 integers.
239
240 \subsection int64_fortran_api Fortran API
241 The fortran API is uses the same mechanism as was described above for
242 the C API. If using the "8-byte real and 8-byte int" fortran mode
243 typically used by the SEACAS applications (the compiler automatically
244 promotes all integers and reals to 8-byte quantities), then the
245 fortran exodus library will automatically enable the `EX_*_INT64_API`
246 options; the client still needs to specify the `EX_*_INT64_DB` options.
247
248 \subsection int64_fortran_imp Fortran Implementation
249
250 The new capability to pass 64-bit integer data through the fortran and
251 C API functions simplifies the implementation of the "8-byte real
252 8-byte int" usage of the exodus library. Previously, the wrapper
253 routines in addrwrap.F were required to convert the 8-byte integer
254 data on the client side to/from 4-byte integers on the library
255 side. This required extra memory allocation and complications that are
256 now handled at the lowest level in the NetCDF library. The
257 functions in the fortran API have all been converted to
258 pass 64-bit integers down to the C API which has removed some code and
259 simplified those functions.
260
261
262 \section db_options Database Options (Compression, Name Length, File Type)
263
264 The ex_set_option() function call is used to set various options on the
265 database. Valid values for 'option' are:
266
267 | Option Name | Option Values |
268 -------------------------|---------------|
269 | #EX_OPT_MAX_NAME_LENGTH | Maximum length of names that will be returned/passed via API call. |
270 | #EX_OPT_COMPRESSION_TYPE | Not currently used; default is gzip |
271 | #EX_OPT_COMPRESSION_LEVEL | In the range [0..9]. A value of 0 indicates no compression |
272 | #EX_OPT_COMPRESSION_SHUFFLE | 1 if enabled, 0 if disabled |
273 | #EX_OPT_INTEGER_SIZE_API | 4 or 8 indicating byte size of integers used in API functions. |
274 | #EX_OPT_INTEGER_SIZE_DB | Query only, returns 4 or 8 indicating byte size of integers stored on the database. |
275
276 The compression-related options are only available on NetCDF-4 files
277 since the underlying hdf5 compression functionality is used for the
278 implementation. The compression level indicates how much effort should
279 be expended in the compression and the computational expense increases
280 with higher levels; in many cases, a compression level of 1 is
281 sufficient.
282
283 \section names Variable, Attribute, and Entity Block/Set Names
284 The length of the Variables, Attributes, and Entity Block/Set names is
285 variable. The default length is 32 characters to provide backward
286 compatibility. This is the default on both read and write, so if
287 there is a database with longer names and the reader does not change
288 the length of names to be returned, any API call that returns a name
289 will truncate the name at 32 characters.
290
291 To avoid this, the reading application can all
292 ~~~{.c}
293 // Determine maximum length of names stored on database
294 int max_name_length = ex_inquire_int(exoid, EX_INQ_DB_MAX_USED_NAME_LENGTH);
295
296 // Tell the library to return names this length
297 ex_set_max_name_length(exodusFilePtr, max_name_length);
298 ~~~
299
300 On write, you can call:
301
302 ~~~{.c}
303 ex_set_option(exoid, EX_OPT_MAX_NAME_LENGTH, {max_name_length});
304
305 // or equivalently
306 ex_set_max_name_length(exoid, {max_name_length});
307 ~~~
308
309 which tells the database that you will be using names of that length or shorter.
310
311 Following this call, you can define (i.e., read/write) names of any
312 size; if the names are longer than `{max_name_length}`, then they will be truncated otherwise they will pass through unchanged.
313
314 There are three queries that can be made to ex_inquire() or
315 ex_inquire_int():
316
317 - #EX_INQ_DB_MAX_ALLOWED_NAME_LENGTH -- returns the value of the
318 maximum size that can be specified for `max_name_length`
319 (netcdf/hdf5 limitation)
320 - #EX_INQ_DB_MAX_USED_NAME_LENGTH -- returns the size of the longest
321 name on the database.
322 - #EX_INQ_MAX_READ_NAME_LENGTH -- returns the maximum name length
323 size that will be passed back to the client. 32 by default,
324 set by the previously mentioned ex_set_option() or
325 ex_set_max_name_length() call.
326
327 \note
328 - The length of the QA records (ex_get_qa(), ex_put_qa()) is not affected by this setting and each entry in the QA record is still limited to 32 characters.
329 - The length of the `entity_descrip` type passed and returnen in the
330 ex_get_block() and ex_put_block() calls is still limited to 32 characters.
331 - The length of the title is limited to 80 characters
332 (ex_get_init(), ex_get_init_ext(), ex_put_init(), ex_put_init_ext()).
333 - The length of the info records is limited to 80 characters
334 (ex_put_info(), ex_get_info()).
335
336 \defgroup ResultsData Results Data
337 @{
338 This section describes data file utility functions for creating
339 opening a file, initializing a file with global parameters, reading
340 writing information text, inquiring on parameters stored in the data
341 file, and error reporting.
342
343 The results are optional and include an optional variable type for
344 each block and set type (node, edge, face, and element) in addition
345 there are global variables and sideset variables -- each of which is
346 stored through time. Nodal results are output (at each time step) for
347 all the nodes in the model. An example of a nodal variable is
348 displacement in the X direction. Global results are output (at each
349 time step) for a single element or node, or for a single
350 property. Linear momentum of a structure and the acceleration at a
351 particular point are both examples of global variables. The other
352 results are output (at each time step) for all entities (elements,
353 faces, edges, nodes, or sides) in one or more entity blocks. For
354 example, stress may be an element variable. Another use of element
355 variables is to record element status (a binary flag indicating
356 whether each element is "alive" or "dead") through time. Although
357 these examples correspond to typical FE applications, the data format
358 is flexible enough to accommodate a spectrum of uses.
359
360 A few conventions and limitations must be cited:
361
362 + There are no restrictions on the frequency of results output except
363 that the time value associated with each successive time step should
364 increase monotonically.
365
366 + All variables are output at the same time frequency. To output
367 results at different frequencies (i.e., variable A at every simulation
368 time step, variable B at every other time step) multiple files must be
369 used.
370
371 + There are no limits to the number of each type of results, but once
372 declared, the number cannot change.
373
374 + If the mesh geometry changes in time (i.e., number of nodes
375 increases, connectivity changes), the new geometry must be output to a
376 new file.
377 @}
378
379 \defgroup Utilities Data File Utilities
380 @{
381 This section describes data file utility functions for creating
382 opening a file, initializing a file with global parameters, reading
383 writing information text, inquiring on parameters stored in the data
384 file, and error reporting.
385 @}
386
387 \defgroup ModelDescription Model Description
388 @{
389 The routines in this section read and write information which
390 describe an exodus finite element model. This includes nodal
391 coordinates, element order map, element connectivity arrays,
392 element attributes, node sets, side sets, and object properties.
393 @}
394
395 @example ../test/CreateEdgeFace.c
396 @example ../test/ReadEdgeFace.c
397 @example ../test/create_mesh.c
398 @example ../test/rd_wt_mesh.c
399 @example ../test/test-empty.c
400 @example ../test/test_nemesis.c
401 @example ../test/test_ts_errval.c
402 @example ../test/test_ts_files.c
403 @example ../test/test_ts_nvar.c
404 @example ../test/test_ts_nvar_rd.c
405 @example ../test/test_ts_partial_nvar.c
406 @example ../test/test_ts_partial_nvar_rd.c
407 @example ../test/testcp.c
408 @example ../test/testcp_nl.c
409 @example ../test/testcp_tran.c
410 @example ../test/testcpd.c
411 @example ../test/testrd-groups.c
412 @example ../test/testrd-long-name.c
413 @example ../test/testrd-nfaced.c
414 @example ../test/testrd-nsided.c
415 @example ../test/testrd.c
416 @example ../test/testrd1.c
417 @example ../test/testrd_nc.c
418 @example ../test/testrd_par.c
419 @example ../test/testrd_ss.c
420 @example ../test/testrdd.c
421 @example ../test/testrdwt.c
422 @example ../test/testwt-compress.c
423 @example ../test/testwt-groups.c
424 @example ../test/testwt-long-name.c
425 @example ../test/testwt-nface-nside.c
426 @example ../test/testwt-nfaced.c
427 @example ../test/testwt-nsided.c
428 @example ../test/testwt-one-attrib.c
429 @example ../test/testwt-oned.c
430 @example ../test/testwt-partial.c
431 @example ../test/testwt-results.c
432 @example ../test/testwt-zeroe.c
433 @example ../test/testwt-zeron.c
434 @example ../test/testwt.c
435 @example ../test/testwt1.c
436 @example ../test/testwt2.c
437 @example ../test/testwt_clb.c
438 @example ../test/testwt_nc.c
439 @example ../test/testwt_nossnsdf.c
440 @example ../test/testwt_ss.c
441 @example ../test/testwtd.c
442 @example ../test/testwtm.c
443 @example ../test/twod.c
444
445 @example ../exodus_for/test/test_nem.f
446 @example ../exodus_for/test/testcp.f
447 @example ../exodus_for/test/testcpd.f
448 @example ../exodus_for/test/testcpnl.f
449 @example ../exodus_for/test/testrd.f
450 @example ../exodus_for/test/testrd1.f
451 @example ../exodus_for/test/testrd_nsid.f
452 @example ../exodus_for/test/testrdd.f
453 @example ../exodus_for/test/testwt.f
454 @example ../exodus_for/test/testwt1.f
455 @example ../exodus_for/test/testwt2.f
456 @example ../exodus_for/test/testwt3.f
457 @example ../exodus_for/test/testwt_nsid.f
458 @example ../exodus_for/test/testwtd.f
459 @example ../exodus_for/test/testwtm.f
460 */
461
462 /* clang-format on */