Exodus 7.10

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( EX_TEST_FILENAME,
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_ALL_INT64_API | (the above 3 or'd together)
201
202 The constants that end with `_DB` specify that that particular integer
203 data is stored on the database as 64-bit integers; the constants that
204 end with "_API" specify that that particular integer data is passed
205 to/from API functions as 64-bit integers.
206
207 If the range of the data being transmitted is larger than the
208 permitted integer range (for example, if the data is stored on the
209 database as 64-bit ints and the application specifies passing data as
210 32-bit ints), the API function will return an error.
211
212 The three types of integer data whose storage can be specified are
213 - maps (`EX_MAPS_INT64_`),
214 - "bulk data" including connectivity lists and entity lists (`EX_BULK_INT64_`), and
215 - entity ids which are the ids of element, face, edge, and node sets
216 and blocks; and map ids (`EX_IDS_INT64_`)
217
218 The function `ex_int64_status(exoid)` is used to determine the integer
219 storage types being used for the EXODUS database 'exoid'. It returns
220 an integer which can be and'ed with the above flags to determine
221 either the storage type or function parameter type.
222
223 For example, if
224 (`EX_MAPS_INT64_DB & ex_int64_status(exoid)`) is true, then map data is
225 being stored as 64-bit integers for that database.
226
227 It is not possible to determine the integer data size on a database
228 without opening the database via an ex_open() call. However, the
229 integer size specification for API functions can be changed at any
230 time via the `ex_set_int64_status(exoid, mode)` function. The mode is
231 one or more of `EX_MAPS_INT64_API`, `EX_IDS_INT64_API`, or
232 `EX_BULK_INT64_API`, or'd together. Any exodus function calls after
233 that point will use the specified integer size. Note that a call to
234 `ex_set_int64_status(exoid, mode)` overrides any previous setting for
235 the integer sizes used in the API. The ex_create() function is the
236 only way to specify the integer sizes specification for database
237 integers.
238
239 \subsection int64_fortran_api Fortran API
240 The fortran API is uses the same mechanism as was described above for
241 the C API. If using the "8-byte real and 8-byte int" fortran mode
242 typically used by the SEACAS applications (the compiler automatically
243 promotes all integers and reals to 8-byte quantities), then the
244 fortran exodus library will automatically enable the *_API
245 options; the client still needs to specify the *_DB options.
246
247 \subsection int64_fortran_imp Fortran Implementation
248
249 The new capability to pass 64-bit integer data through the fortran and
250 C API functions simplifies the implementation of the "8-byte real
251 8-byte int" usage of the exodus library. Previously, the wrapper
252 routines in addrwrap.F were required to convert the 8-byte integer
253 data on the client side to/from 4-byte integers on the library
254 side. This required extra memory allocation and complications that are
255 now handled at the lowest level in the NetCDF library. The
256 functions in the fortran API have all been converted to
257 pass 64-bit integers down to the C API which has removed some code and
258 simplified those functions.
259
260
261 \section Database Options (Compression, Name Length, File Type)
262
263 The ex_set_option() function call is used to set various options on the
264 database. Valid values for 'option' are:
265
266 | Option Name | Option Values
267 -------------------------|---------------
268 | EX_OPT_MAX_NAME_LENGTH | Maximum length of names that will be returned/passed via API call.
269 | EX_OPT_COMPRESSION_TYPE | Not currently used; default is gzip
270 | EX_OPT_COMPRESSION_LEVEL | In the range [0..9]. A value of 0 indicates no compression
271 | EX_OPT_COMPRESSION_SHUFFLE | 1 if enabled, 0 if disabled
272 | EX_OPT_INTEGER_SIZE_API | 4 or 8 indicating byte size of integers used in API functions.
273 | EX_OPT_INTEGER_SIZE_DB | Query only, returns 4 or 8 indicating byte size of integers stored on the database.
274
275 The compression-related options are only available on NetCDF-4 files
276 since the underlying hdf5 compression functionality is used for the
277 implementation. The compression level indicates how much effort should
278 be expended in the compression and the computational expense increases
279 with higher levels; in many cases, a compression level of 1 is
280 sufficient.
281
282 \defgroup ResultsData Results Data
283 @{
284 This section describes data file utility functions for creating
285 opening a file, initializing a file with global parameters, reading
286 writing information text, inquiring on parameters stored in the data
287 file, and error reporting.
288
289 The results are optional and include an optional variable type for
290 each block and set type (node, edge, face, and element) in addition
291 there are global variables and sideset variables -- each of which is
292 stored through time. Nodal results are output (at each time step) for
293 all the nodes in the model. An example of a nodal variable is
294 displacement in the X direction. Global results are output (at each
295 time step) for a single element or node, or for a single
296 property. Linear momentum of a structure and the acceleration at a
297 particular point are both examples of global variables. The other
298 results are output (at each time step) for all entities (elements,
299 faces, edges, nodes, or sides) in one or more entity blocks. For
300 example, stress may be an element variable. Another use of element
301 variables is to record element status (a binary flag indicating
302 whether each element is "alive" or "dead") through time. Although
303 these examples correspond to typical FE applications, the data format
304 is flexible enough to accommodate a spectrum of uses.
305
306 A few conventions and limitations must be cited:
307
308 + There are no restrictions on the frequency of results output except
309 that the time value associated with each successive time step should
310 increase monotonically.
311
312 + All variables are output at the same time frequency. To output
313 results at different frequencies (i.e., variable A at every simulation
314 time step, variable B at every other time step) multiple files must be
315 used.
316
317 + There are no limits to the number of each type of results, but once
318 declared, the number cannot change.
319
320 + If the mesh geometry changes in time (i.e., number of nodes
321 increases, connectivity changes), the new geometry must be output to a
322 new file.
323 @}
324
325 \defgroup Utilities Data File Utilities
326 @{
327 This section describes data file utility functions for creating
328 opening a file, initializing a file with global parameters, reading
329 writing information text, inquiring on parameters stored in the data
330 file, and error reporting.
331 @}
332
333 \defgroup ModelDescription Model Description
334 @{
335 The routines in this section read and write information which
336 describe an exodus finite element model. This includes nodal
337 coordinates, element order map, element connectivity arrays,
338 element attributes, node sets, side sets, and object properties.
339 @}
340
341 @example ../test/CreateEdgeFace.c
342 @example ../test/ExoIICTests.cxx
343 @example ../test/MakeTestData.c
344 @example ../test/ReadEdgeFace.c
345 @example ../test/create_mesh.c
346 @example ../test/oned.c
347 @example ../test/rd_wt_mesh.c
348 @example ../test/test-empty.c
349 @example ../test/test.exo_c
350 @example ../test/test_nemesis.c
351 @example ../test/test_ts_errval.c
352 @example ../test/test_ts_files.c
353 @example ../test/test_ts_nvar.c
354 @example ../test/test_ts_nvar_rd.c
355 @example ../test/test_ts_partial_nvar.c
356 @example ../test/test_ts_partial_nvar_rd.c
357 @example ../test/testcp.c
358 @example ../test/testcp_nl.c
359 @example ../test/testcpd.c
360 @example ../test/testrd-groups.c
361 @example ../test/testrd-long-name.c
362 @example ../test/testrd-nfaced.c
363 @example ../test/testrd-nsided.c
364 @example ../test/testrd.c
365 @example ../test/testrd1.c
366 @example ../test/testrd_nc.c
367 @example ../test/testrd_par.c
368 @example ../test/testrd_ss.c
369 @example ../test/testrdd.c
370 @example ../test/testrdwt.c
371 @example ../test/testwt-compress.c
372 @example ../test/testwt-groups.c
373 @example ../test/testwt-localization.C
374 @example ../test/testwt-long-name.c
375 @example ../test/testwt-nface-nside.c
376 @example ../test/testwt-nfaced.c
377 @example ../test/testwt-nsided.c
378 @example ../test/testwt-one-attrib.c
379 @example ../test/testwt-partial.c
380 @example ../test/testwt-zeroe.c
381 @example ../test/testwt-zeron.c
382 @example ../test/testwt.c
383 @example ../test/testwt1.c
384 @example ../test/testwt2.c
385 @example ../test/testwt_clb.c
386 @example ../test/testwt_nc.c
387 @example ../test/testwt_nossnsdf.c
388 @example ../test/testwt_ss.c
389 @example ../test/testwtd.c
390 @example ../test/testwtm.c
391 @example ../test/twod.c
392 */
393
394 /* clang-format on */