ExodusII
5.15
|
00001 /*! \mainpage ExodusII API Documentation 00002 00003 \section intro Introduction 00004 00005 EXODUS is the successor of the widely used finite element (FE) data file format EXODUS 00006 (henceforth referred to as EXODUS I) developed by Mills-Curran and Flanagan. It 00007 continues the concept of a common database for multiple application codes (mesh generators, 00008 analysis codes, visualization software, etc.) rather than code-specific utilities, affording 00009 flexibility and robustness for both the application code developer and application code user. 00010 By using the EXODUS data model, a user inherits the flexibility of using a large array of 00011 application codes (including vendor-supplied codes) which access this common data file 00012 directly or via translators. 00013 00014 The uses of the EXODUS data model include the following: 00015 - Problem definition -- mesh generation, specification of locations of boundary conditions and load application, specification of material types. 00016 - Simulation -- model input and results output. 00017 - Visualization -- model verification, results postprocessing, data interrogation, and analysis tracking. 00018 00019 \section avail License and Availability 00020 The EXODUS library is licensed under the BSD open source license. 00021 00022 Copyright (c) 2005 Sandia Corporation. Under the terms of Contract DE-AC04-94AL85000 00023 with Sandia Corporation, the U.S. Government retains certain rights in this software. 00024 00025 Redistribution and use in source and binary forms, with or without modification, are permitted 00026 provided that the following conditions are met: 00027 - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 00028 - Redistributions in binary form must reproduce the above copyright notice, this list 00029 of conditions and the following disclaimer in the documentation and/or other 00030 materials provided with the distribution. 00031 -Neither the name of Sandia Corporation nor the names of its contributors may be 00032 used to endorse or promote products derived from this software without specific 00033 prior written permission. 00034 00035 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 00036 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 00037 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 00038 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 00039 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 00040 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 00041 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 00042 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 00043 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 00044 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 00045 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00046 00047 The ExodusII library source code is available on Sourceforge at 00048 http://sourceforge.net/projects/exodusii 00049 00050 For bug reports, documentation errors, and enhancement suggestions, contact: 00051 - Gregory D. Sjaardema 00052 - PHONE: (505) 844-2701 00053 - EMAIL: gdsjaar@sandia.gov 00054 00055 \section devel Development of EXODUS 00056 00057 The evolution of the EXODUS data model has been steered by FE application code developers 00058 who desire the advantages of a common data format. The EXODUS model has been 00059 designed to overcome deficiencies in the EXODUS I file format and meet the following 00060 functional requirements as specified by these developers: 00061 - Random read/write access. 00062 - Application programming interface (API) -- provide routines callable from FORTRAN, C, and C++ application codes. 00063 - Extensible -- allow new data objects to be added without modifying the application programs that use the file format. 00064 - Machine independent -- data should be independent of the machine which generated it. 00065 - Real-time access during analysis -- allow access to the data in a file while the file is 00066 being created. 00067 00068 To address these requirements, the open source database library 00069 etCDF (http://www.unidata.ucar.edu/software/netcdf/) was selected to handle the low-level data storage. The EXODUS 00070 II library functions provide the mapping between FE data objects and 00071 netCDF dimensions, attributes, and variables. Thus, the code developer 00072 interacts with the data model using the vocabulary of an FE analyst 00073 (element connectivity, nodal coordinates, etc.) and is relieved of the 00074 details of the data access mechanism. 00075 00076 Because an EXODUS file is a netCDF file, an application program can 00077 access data via the EXODUS API or the netCDF API directly. Although 00078 accessing the data directly via the netCDF API requires more in-depth 00079 understanding of netCDF, this capability is a powerful feature that 00080 allows the development of auxiliary libraries of special purpose 00081 functions not offered in the standard EXODUS library. For example, 00082 if an application required access to the coordinates of a single node 00083 (the standard library function returns the coordinates for all of the 00084 nodes in the model), a simple function could be written that calls 00085 netCDF routines directly to read the data of interest. 00086 00087 \section descrip Description of Data Objects 00088 00089 The data in EXODUS files can be divided into three primary 00090 categories: initialization data, model, and results. 00091 00092 Initialization data includes sizing parameters (number of nodes, 00093 number of elements, etc.), optional quality assurance information 00094 (names of codes that have operated on the data), and optional 00095 informational text. 00096 00097 The model is described by data which are static (do not change through 00098 time). These data include nodal coordinates, element connectivity 00099 (node lists for each element), element attributes, and node sets and 00100 side sets (used to aid in applying loading conditions and boundary 00101 constraints). 00102 00103 The results are optional and include five types of variables -- nodal, 00104 element, nodeset, sideset, and global -- each of which is stored 00105 through time. Nodal results are output (at each time step) for all the 00106 nodes in the model. An example of a nodal variable is displacement in 00107 the X direction. Element, nodeset, and sideset results are output (at 00108 each time step) for all entities (elements, nodes, sides) in one or 00109 more entity block. For example, stress may be an element 00110 variable. Another use of element variables is to record element status 00111 (a binary flag indicating whether each element is "alive" or "dead") 00112 through time. Global results are output (at each time step) for a 00113 single element or node, or for a single property. Linear momentum of a 00114 structure and the acceleration at a particular point are both examples 00115 of global variables. Although these examples correspond to typical FE 00116 applications, the data format is flexible enough to accommodate a 00117 spectrum of uses. 00118 00119 A few conventions and limitations must be cited: 00120 00121 - There are no restrictions on the frequency of results output except 00122 that the time value associated with each successive time step must 00123 increase monotonically. 00124 - To output results at different frequencies (i.e., variable A at 00125 every simulation time step, variable B at every other time step) 00126 multiple EXODUS files must be used. 00127 - There are no limits to the number of each type of results, but once 00128 declared, the number cannot change. 00129 - If the mesh geometry or topology changes in time (i.e., number of 00130 nodes increases, connectivity changes), then the new geometrymust be 00131 output to a new EXODUS file. 00132 00133 \section int64 Integer Bulkdata Storage Details 00134 00135 The EXODUS database can store integer bulk data, entity map data, and 00136 mesh entity (block/set) ids in either 32-bit or 64-bit integer format. The data 00137 considered "bulk data" are: 00138 00139 - element, face, and edge connectivity lists, 00140 - element, face, edge, and node set entity lists, 00141 00142 The entity map data is any data stored in one of the 'map' objects on 00143 the exodus file. This includes: 00144 - id maps 00145 - number maps 00146 - order maps 00147 - processor node maps 00148 - processor element maps. 00149 00150 A mesh entity id is the id of any block (element block, edge block, 00151 ...); set (node set, face set, ...), coordinate frame, and 00152 communication map. 00153 00154 When an EXODUS file is created via the ex_create() function, the 00155 'mode' argument provides the mechanism for specifying how integer data 00156 will be passed as arguments to the API functions and also how the 00157 integer data will be stored on the database. The ex_open() function 00158 also provides a mechanism for specifying how integer data will be 00159 passed as arguments. 00160 00161 The method uses the 'mode' argument to the ex_open() and 00162 ex_create() functions. The mode is a 32-bit integer in which certain 00163 bits are turned on by or'ing certain predefined constants. 00164 00165 exoid = ex_create( EX_TEST_FILENAME, 00166 EX_CLOBBER|EX_MAPS_INT64_DB|EX_MAPS_INT64_API, 00167 &appWordSize, &diskWordSize ); 00168 00169 The constants related to the integer size (32-bit or 64-bit) 00170 specification are: 00171 00172 - EX_MAPS_INT64_DB -- entity map data 00173 - EX_IDS_INT64_DB -- mesh entity ids 00174 - EX_BULK_INT64_DB -- bulk data 00175 - EX_ALL_INT64_DB -- (the above 3 or'd together) 00176 - EX_MAPS_INT64_API -- entity map data 00177 - EX_IDS_INT64_API -- mesh entity ids 00178 - EX_BULK_INT64_API -- bulk data 00179 - EX_ALL_INT64_API -- (the above 3 or'd together) 00180 00181 The constants that end with "_DB" specify that that particular integer 00182 data is stored on the database as 64-bit integers; the constants that 00183 end with "_API" specify that that particular integer data is passed 00184 to/from API functions as 64-bit integers. 00185 00186 If the range of the data being transmitted is larger than the 00187 permitted integer range (for example, if the data is stored on the 00188 database as 64-bit ints and the application specifies passing data as 00189 32-bit ints), the api function will return an error. 00190 00191 The three types of integer data whose storage can be specified are 00192 - maps (EX_MAPS_INT64_), 00193 - "bulk data" including connectivity lists and entity lists (EX_BULK_INT64_), and 00194 - entity ids which are the ids of element, face, edge, and node sets 00195 and blocks; and map ids (EX_IDS_INT64_) 00196 00197 The function ex_int64_status(exoid) is used to determine the integer 00198 storage types being used for the EXODUS database 'exoid'. It returns 00199 an integer which can be and'ed with the above flags to determine 00200 either the storage type or function parameter type. 00201 00202 For example, if 00203 (EX_MAPS_INT64_DB \& ex_int64_status(exoid)) is true, then map data is 00204 being stored as 64-bit integers for that database. 00205 00206 It is not possible to determine the integer data size on a database 00207 without opening the database via an ex_open() call. However, the 00208 integer size specification for API functions can be changed at any 00209 time via the ex_set_int64_status(exoid, mode) function. The mode is 00210 one or more of EX_MAPS_INT64_API, EX_IDS_INT64_API, or 00211 EX_BULK_INT64_API, or'd together. Any exodus function calls after 00212 that point will use the specified integer size. Note that a call to 00213 ex_set_int64_status(exoid, mode) overrides any previous setting for 00214 the integer sizes used in the API. The ex_create() function is the 00215 only way to specify the integer sizes specification for database 00216 integers. 00217 00218 \subsection int64_fortran_api Fortran API 00219 The fortran api is uses the same mechanism as was described above for 00220 the C API. If using the "8-byte real and 8-byte int" fortran mode 00221 typically used by the SEACAS applications (the compiler automatically 00222 promotes all integers and reals to 8-byte quantities), then the 00223 fortran exodus library will automatically enable the *_API 00224 options; the client still needs to specify the *_DB options. 00225 00226 \subsection int64_fortran_imp Fortran Implementation 00227 00228 The new capability to pass 64-bit integer data through the fortran and 00229 C API functions simplifies the implementation of the "8-byte real 00230 8-byte int" usage of the exodus library. Previously, the wrapper 00231 routines in addrwrap.F were required to convert the 8-byte integer 00232 data on the client side to/from 4-byte integers on the library 00233 side. This required extra memory allocation and complications that are 00234 now handled at the lowest level in the netcdf library. The 00235 map-related functions in the fortran api have all been converted to 00236 pass 64-bit integers down to the C API which has removed some code and 00237 simplified those functions. 00238 00239 00240 \section Database Options (Compression, Name Length, File Type) 00241 00242 The ex_set_option() function call is used to set various options on the 00243 database. Valid values for 'option' are: 00244 00245 | Option Name | Option Values 00246 -------------------------|--------------- 00247 | EX_OPT_MAX_NAME_LENGTH | Maximum length of names that will be returned/passed via api call. 00248 | EX_OPT_COMPRESSION_TYPE | Not currently used; default is gzip 00249 | EX_OPT_COMPRESSION_LEVEL | In the range [0..9]. A value of 0 indicates no compression 00250 | EX_OPT_COMPRESSION_SHUFFLE | 1 if enabled, 0 if disabled 00251 | EX_OPT_INTEGER_SIZE_API | 4 or 8 indicating byte size of integers used in api functions. 00252 | EX_OPT_INTEGER_SIZE_DB | Query only, returns 4 or 8 indicating byte size of integers stored on database. 00253 00254 The compression-related options are only available on netcdf-4 files 00255 since the underlying hdf5 compression functionality is used for the 00256 implementation. The compression level indicates how much effort should 00257 be expended in the compression and the computational expense increases 00258 with higher levels; in many cases, a compression level of 1 is 00259 sufficient. 00260 00261 \defgroup ResultsData Results Data 00262 @{ 00263 This section describes data file utility functions for creating / 00264 opening a file, initializing a file with global parameters, reading / 00265 writing information text, inquiring on parameters stored in the data 00266 file, and error reporting. 00267 @} 00268 00269 \defgroup Utilities Data File Utilities 00270 @{ 00271 This section describes data file utility functions for creating / 00272 opening a file, initializing a file with global parameters, reading / 00273 writing information text, inquiring on parameters stored in the data 00274 file, and error reporting. 00275 @} 00276 00277 \defgroup ModelDescription Model Description 00278 @{ 00279 The routines in this section read and write information which 00280 describe an exodus finite element model. This includes nodal 00281 coordinates, element order map, element connectivity arrays, 00282 element attributes, node sets, side sets, and object properties. 00283 @} 00284 00285 00286 */