CGNS concerns itself with the recording and retrieval of data associated with the computation of fluid flows. Included are such structures as grids, flowfields, boundary conditions, and zone connectivity information. CGNS "understands" this data in the sense that it contains conventions for recording it based on its structure and its role in CFD.
The underlying design of CGNS is that of a common database that is accessed (read, written, or modified) by a collection of "applications" programs such as solvers, grid generators, and postprocessors.
CGNS itself does not synthesize, modify, or interpret the data it stores. The applications create, edit, or display the data; CGNS is limited to recording and retrieving it. Each application's program accesses the data directly using CGNS function calls installed in the application by its developer. The applications are not regarded as part of CGNS itself.
CGNS is passive. It does not initiate action and cannot "push" information into the applications codes or "pull" information out. Rather, the codes must request the information they seek and store the information they produce. The applications must be launched by a user who organizes the location and content of the database. The process and sequence of events remain under user control. Thus CGNS facilitates, but does not incorporate, the development of batch or interactive environments designed to control the CFD process.
The elements of CGNS address all activities associated with the storage of the data on external media and its movement to and from the applications programs. These elements include the following:
The following sections discuss in more detail the roles of the CGNS elements and introduce their documentation.
In this section, the conceptual structure of a CGNS database, and the nodes from which it is built, are discussed. This describes the way in which the CGNS software "sees" the database, not necessarily the way in which it is implementated. The details of the implementation are left to the underlying database manager.
A CGNS database consists of a collection of elements called nodes. These nodes are arranged in a tree structure that is logically similar to a UNIX file system. The nodes are said to be connected in a "child-parent" relationship according to the following simple rules:
Node Identifier. The Node ID is a floating point number assigned by the system when the database is opened or created. Applications may record the ID and use it to return directly to the corresponding node when required. The Node ID is valid only while the database is open; subsequent openings of the same database may be expected to yield different IDs.
Name. The Name field holds a character string chosen by the user or specified by the SIDS to identify the particular instance of the data being recorded.
Label. The Label, also a character string, is specified by the CGNS mapping conventions and identifies the kind of data being recorded. For example, a node with label Zone_t may record (at and below it) information on the zone with Name "UnderWing." No node may have more than one child with the same name, but the CGNS mapping conventions commonly specify many children with the same label. For some nodes, the mapping conventions specify that the name field has significance for the meaning of the data (e.g., EnthalpyStagnation). Although the user may specify another name, these "paper" conventions serve the transfer of data between users and between applications. These names and their meanings are established by the SIDS.
Data Type, Dimension, Dimension Values, Data. Nodes may or may not contain data. For those that do, CGNS specifies a single array whose type (integer, etc.), dimension, and size are recorded in the Data Type, Dimension, and Dimension Value fields, respectively. The mapping conventions specify some nodes that serve to establish the tree structure and point to further data below but contain no data themselves. For these nodes, the Data Type is MT, and the other fields are empty. A link to another node within the current or an external CGNS database is indicated by a Data Type of LK
Child Table. The Child Table contains a list of the node's children. It is maintained by the database manager as children are created and deleted.
A CGNS database consists of a tree of nodes implemented as all or part of one or more database files. All information is identified by and accessed through a single node in one of these files.
By definition, the root node of a CGNS database has the Label CGNSBase_t. The name of the CGNS database can be specified by the user and is stored in the "Name" field of the CGNSBase_t node. Current CGNS conventions require that the CGNSBase_t node be located directly below a "root node" in the database file indentified by the name "/".
A database file may contain multiple CGNS databases, and thus multiple CGNSBase_t nodes. However, each node labeled CGNSBase_t in a single file must have a unique name. The user or application must know the name of the file containing the entry-level node and, if there is more than one node labeled CGNSBase_t in that file, the name of the database as well.
Below the CGNSBase_t node, the mapping conventions specify a subnode for each zone. This node has label Zone_t. Its Name refers to the particular zone whose characteristics are recorded at and below the node, such as "UnderWing." In general, names can be specified by the user, but defaults are specified for nodes that the user does not choose to name. For the Zone_t nodes, the defaults are Zone1, Zone2, and so forth, in order of creation. A similar convention for default names applies elsewhere. It is impossible to create a node without a name (or with a name of zero length). The CGNS Mid-Level Library conforms to the default convention.
Below each zone node will be found nodes for the grid, flowfield, boundary conditions, and connectivity information; these, in turn, are parents of nodes specifying extent, spatial location, and so on.
The file mapping specifies that one or more "Descriptor" nodes may be inserted anywhere in the file. Descriptor nodes are used to record textual information regarding the file contents. The size of Descriptor nodes is unlimited, so entire documents could be named and stored within the data field if desired. Descriptors are intended to store human-readable text, and they are not processed by any supplied CGNS software (except, of course, that the text may be stored and retrieved).
It is possible, by using the linking capability of CGNS, for a child of any node to be a node in another database file, or elsewhere within the same file. This mechanism enables one database to share a grid, for example, with another database without duplicating the information.
The establishment of a standard for storing CFD-related information requires a detailed specification of the content and meaning of the data to be stored. For example, it is necessary to state the meaning of the words "boundary condition" in a form sufficiently concrete to be recorded precisely, and yet sufficiently flexible to embrace current and future practice. The Standard Interface Data Structures (SIDS) document describes this "intellectual content" of CFD-related data in detail.
An exact description of the intellectual content is required not only to define the precise form of the data but also to guarantee that the meaning of the data is consistently interpreted by practitioners. Thus the SIDS include a collection of naming conventions that specify the precise meaning of nomenclature (e.g., the strings DensityStatic and BCWallViscous).
The SIDS are written in a self-contained C-like descriptive language. SIDS data structures are defined in a hierarchical manner in which more complex entities are built from simpler ones. These structures are closely reflected in CGNS-compliant files: simple entities are often stored in single nodes, while more complex structures are stored in entire subtrees.
The mapping provides locations for an extensive set of CFD data. Most applications will make use of only a small subset of this data. Further, inasmuch as applications are viewed as editors that are in the process of building the database, most of them are intended for use on incomplete data sets. Therefore, it is not required that all the data elements specified by the CGNS conventions be complete in order for a database to be CGNS compliant. The user must ensure that the current state of the database will support whatever application he may launch. Of course, the application should gracefully handle any absence or deficiency of data.
CGNS conventions do not specify the following:
The tree structure also makes it possible for applications to ignore data for which they have no use. (In fact, they cannot even discover the data's existence without a specific inquiry.) Therefore, it is permissible for an file containing a CGNS database to contain additional nodes not specified by the mapping. Such nodes will be disregarded by software not prepared to use them. However, if data essential to the CFD process is stored in a manner not consistent with CGNS conventions, that data becomes invisible and therefore useless to other applications.
Note that the SIDS serve not only to facilitate the mapping of data onto the file structure but also to standardize the meaning of the recorded data. Thus there are two kinds of conventions operative within CGNS. Adherence to the File Mapping conventions guarantees that the software will be able to find and read the data. Adherence to the SIDS guarantees uniformity of meaning among users and between applications. The SIDS File Mapping document establishes the context of CGNS for a database manager; the SIDS define the nomenclature, content, and meaning of the stored data.
The File Mapping generally avoids the storage of redundant data. Sometimes an application may require an alternate (but intellectually equivalent) form of the data; in such cases it is recommended that the alternate form be prepared at the time of use and kept separate from the CGNS data. This avoids habitual reliance on the alternate form, which would invalidate the standard.
The CGNS software was originally developed around ADF (Advanced Data Format) as it's database manager, thus much of the concepts and structures of CGNS originated from there.
In version 2.4 of the CGNS software, HDF5 (Hierarchical Data Format was introduced as an alternative database manager. At that time, either ADF or HDF5 (but not both) was selectable at build time.
It should be noted that because of HDF5's parallel and compression capability as well as its support, the CGNS Steering Committee has made the decision to slowly transition (beginning in 2005) to HDF5 as the official data storage mechanism. However, ADF will continue to be available for use, with the CGNS mid-level library capable of (1) using either format and (2) translating back and forth between the two.
Beginning with CGNS version 3.0, both ADF and HDF5 are supported concurrently and transparently by CGNS. To facilitate this, a new set of core routines, described in the CGIO User's Guide, have been developed as a replacement to the individual ADF and HDF5 core routines. These allow general access to the low-level I/O, irrespective of the underlying database manager.
The CGNS Mid-Level Library, or Applications Programming Interface (API), is one of the most directly visible parts of CGNS, and it is of particular interest to applications code developers. It consists of a set of routines that are designed to allow applications to access CGNS data according to the role of the data in CFD. Unlike the ADF (or HDF5) Core, routines in the CGNS Mid-Level Library "understand" the SIDS-defined CFD data structures and the File Mapping. This enables applications developers to insert CGNS I/O into their applications without having detailed knowledge of the File Mapping. For instance, an application might use CGNS mid-level calls to retrieve all boundary conditions for a given zone.
The CGNS Mid-Level Library document contains complete descriptions and usage instructions for all mid-level routines. All calls are provided in both C and Fortran.
The CGNS elements described above are documented individually, and are available as follows:
In addition, the following documentation is also recommended:
Prospective users are presumably unfamiliar with CGNS. They will probably wish to begin with the current Overview document, or, if they require more detailed information, the AIAA papers listed above. Beyond that, most will find a quick read of the SIDS File Mapping Manual (or enlightening as to the logical form of the contents of CGNS files. Browsing the figures in the File Mapping Manual, as well as the SIDS itself, will provide some feel for the scope of the system. The User's Guide to CGNS, and the CGNS Mid-Level Library document, should give an indication of what might be required to implement CGNS in a given application. Prospective users should probably not concern themselves with the details of ADF or HDF5.
The end user is the practitioner of CFD who generates the grids, runs the flow codes and/or analyzes the results. For this user, a scan of this Overview document will sufficiently explain the overall workings of the system. This includes end user responsibilities for matters not governed by CGNS, such as the maintenance of files and directories. The end user will also find useful the User's Guide to CGNS, as well as those portions of the SIDS which deal with standard data names. The AIAA papers listed above may also be useful if more details about the capabilities of CGNS are desired.
The applications code developer builds or maintains code to support the various sub-processes encountered in CFD, e.g., grid generation, flow solution, post-processing, or flow visualization. The code developer must be able to install CGNS compliant I/O. The most convenient method for doing so is to utilize the CGNS Mid-Level Library. The User's Guide to CGNS is the starting point for learning to use the Mid-Level Library to create and use CGNS files. The CGNS Mid-Level Library document itself should also be considered essential. This library of routines will perform the most common I/O operations in a CGNS-compliant manner. However, even when the Mid-Level Library suffices to implement all necessary I/O, an understanding of the file mapping and SIDS will be useful. It will likely be necessary to consult the SIDS to determine the precise meaning of the nomenclature.
Applications code developers wishing to read or write data that isn't supported by the Mid-Level Library, will need to use the CGIO low-level routines to access the underlying database manager directly. The CGIO User's Guide documents these routines in detail.
CGNS System development can be kept somewhat compartmentalized. Developers responsible for the maintenance or building of supplements to the ADF Core, need not concern themselves with documentation other than the ADF User Guide. (Development and maintenance of HDF5 is under the purview of NCSA, so has no relevance here.) System developers wishing to add to the CGNS Mid-Level Library will need all the documents. Theoretical developments, such as extensions to the SIDS, may possibly be undertaken with a knowledge of the SIDS alone, but such contributions must also be added to the SIDS File Mapping before they can be implemented.