Documentation of CGNS is found in a number of related publications. These are maintained separately for several reasons. First, they describe logically independent aspects of the CGNS system. Second, many users will find that a subset of the documentation is sufficient for their needs. And last, some portions of the system can be viewed as independent entities useful outside the context of CGNS.
The main documents currently available are:
In order to make the current document as self-contained as possible, basic information regarding all components of the CGNS standard has been included. However, the reader should be aware of the documents describing these other components. These should be regarded as the authoritative and complete descriptions of their respective components of CGNS. Each of these documents is described briefly in this section.
This is an introductory document which provides an overall view of the purpose and components of CGNS. The Overview is intended as an entry point into CGNS. Prospective users completely unfamiliar with CGNS should consult the Overview to determine whether CGNS provides the capabilities they seek.
The User's Guide to CGNS has been written to aid users in the implementation of CGNS. It is intended as a tutorial: light in content, but heavy in examples, advice, and guidelines. The guide provides a concise overview of many of the most commonly-used features of the SIDS, and gives coding examples using the CGNS Mid-Level Library to write and read simple CGNS files.
The CGNS Mid-Level Library document describes a set of routines which store and retrieve the CFD data objects defined in the SIDS. Their purpose is to provide CGNS compliant I/O without the need for detailed programming in the ADF or HDF Core. These "mid-level routines" are designed to be inserted directly into applications codes, such as flow solvers and grid generators.
The Standard Interface Data Structures, usually abbreviated as "SIDS," define the "intellectual content" of CFD data. They detail the data which must be stored to completely characterize each CFD entity. They describe, for example, what exactly is meant by a "grid" or a "boundary condition". They also establish a system of nomenclature which gives standard meaning to certain names, such as "Density" and "SubsonicInflow".
The SIDS description of the CFD data is hierarchical in nature, in that complex entities are built up out of simpler ones. In the SIDS document, this is reflected in a syntax which uses C-like structures to define the various entities. The result is a tree-like structure which maps naturally onto the ADF format. Consequently, the File Mapping described by the current document exactly parallels the SIDS. Thus in terms of basic structure, the Mapping itself summarizes the SIDS. However, there are many conventions regarding the nomenclature and meaning of data which are not summarized in the current document, and for these the SIDS is the authoritative document.
It is worth emphasizing that the SIDS may be regarded as a stand-alone definition of the data associated with CFD, and that these data could be stored in any sufficiently general format, given a mapping onto that format.
The SIDS File Mapping Manual specifies the exact manner in which, under CGNS conventions, CFD data structures (the SIDS) are to be stored in, i.e., mapped onto, the file structure provided by a database manager. Adherence to the mapping conventions guarantees uniform meaning and location of CFD data within database files, and thereby allows the construction of universal software to read and write the data.
The CGIO User's Guide describes the interface between the SIDS File Mapping and an underlying database manager. It also documents the low-level routines that provide this functionality as used in the Mid-Level Library. This is the preferred way to access the database directly if additional requirements beyond those provided by the MLL are needed.
The ADF Implementation describes one of the underlying database managers, ADF (Advanced Data Format), which may be used to create CGNS files. ADF is a binary format, based on a simple tree structure. In principal, nearly any kind of data could be stored in ADF format. ADF was, however, especially designed for the storage of large quantities of scientific data in a platform-independent and randomly-accessible manner. The "ADF Core" is a set of portable routines which store and retrieve data in ADF format. These routines are written in C, but Fortran versions are also provided. The ADF User's Guide describes both the ADF format and the ADF Core routines in detail.
Because the CGNS File Mapping depends intimately on the format of the underlying database manager, a summary of ADF data structures is provided.
It should be emphasized that ADF, with its Core routines, constitutes a very general stand-alone database manager which is not directly related to CFD. It can therefore be used to store any kind of data once it has been specified where to place that data within the ADF format. This File Mapping document describes the CGNS conventions governing that placement for CFD-specific data.
HDF5 (Hierarchical Data Format) is another underlying database manager
that may be used to create CGNS files, and is developed and maintained
by the National Center for
Supercomputing Applications
at the University of
Illinois at Urbana-Champaign.
Documentation for HDF5 is available at the
HDF5 Home Page
.
Like ADF, HDF5 is a binary format, based on a tree structure, designed for the storage of large quantities of scientific data in a platform-independent and randomly-accessible manner. Also like ADF, HDF5 can be used to store any kind of data. The HDF5 Implementation document describes the CGNS conventions governing the placement of CFD-specific data within the HDF5 format.
The document describes the node level system, whereas the Mid-Level Library can be understood as the tree level system. A description is given for every Mid-Level Library type, or sub-tree, in terms of sets of atomic nodes. Moreover, it specifies the exact manner in which, under CGNS conventions, CFD data structures (the SIDS) are to be mapped onto the data structures provided by the low level layer (HDF5).
Some system-specific mechanisms, such as link management are detailed. [Please note that only the final representation of these links are relevant, in other words the sequence of HDF5 calls required to obtain such a representation is not important.]
Adherence to the mapping conventions guarantees uniform meaning and location of CFD data within HDF5 files, and thereby allows the construction of universal software to read and write the data.
Ideally, all users of the CGNS system will want to have all the documents available for reference. However, many will find it possible to begin to use the system effectively without reading all the documents beforehand. In fact, since the CGNS system is intended to minimize interaction with underlying data structures, some users will find they need very little knowledge of the system's internal workings. We distinguish four classes of users who may wish to consult the CGNS Documentation.
Prospective users are presumably unfamiliar with CGNS. They will probably wish to begin with the Overview, or, if they require more detailed information, one or more of the various papers that have been written describing CGNS. Beyond that, most will find a quick read of this file mapping document enlightening as to the logical form of the contents of CGNS files. Browsing the figures in this document, 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 HDF.
The end user is the practitioner of CFD who generates the grids, runs the flow codes and/or analyzes the results. For this user, CGNS provides a mechanism for accumulating the output of the various processes related to CFD, e.g., grid generation and flow solution, and for making this output available to subsequent processes or for archiving final results. For this user, a scan of the Overview 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 nomenclature. AIAA 98-3007 may also be useful if more details about the capabilities of CGNS are desired.
The end user is, by definition, not involved in the building of CGNS-compliant applications code.
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 CGNS Library suffices to implement all necessary I/O, an understanding of the SIDS and the SIDS File mapping will be useful. It will likely be necessary to consult the SIDS to determine the precise meaning of the nomenclature. In the unlikely case that the MLL does not provide all the functionality needed by the application, the CGIO User's Guide may be consulted for information on the low-level access to the CGNS database.
CGNS System development can be kept somewhat compartmentalized.
Developers responsible for the maintenance or building of supplements
to the ADF or HDF Core, need not concern themselves with documentation
other than the ADF User Guide or
the HDF5 documentation
.
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.
Those wishing to do more than simply browse this document will find that the detailed information begins with the the General File Mapping Concepts. The detailed textual node descriptions in are more useful as reference than as sequential literature. The best overall technical view of the layout of CGNS files can be acquired by reference to the figures.