Skip navigation links
(CGNS Documentation Home Page) (Steering Committee Charter) (Overview and Entry-Level Document) (A User's Guide to CGNS) (Mid-Level Library) (Standard Interface Data Structures) (SIDS File Mapping Manual) (CGIO User's Guide) (Parallel CGNS User's Guide) (ADF Implementation) (HDF5 Implementation) (Python Implementation) (CGNS Tools and Utilities)

(Introduction) (Getting Started) (Additional Information) (Troubleshooting) (Frequently Asked Questions) (Example Computer Codes) (Overview of the SIDS) (Guideline for PLOT3D Variables)


This User's Guide (originally published as NASA/TM-2001-211236, October 2001) has been written to aid users in the implementation of CGNS (CFD General Notation System). It is intended as a tutorial: light in content, but heavy in examples, advice, and guidelines. Readers interested in additional details are referred to other documents, listed in the references, which are available from the CGNS website external link.

What is CGNS?

CGNS (CFD General Notation System) originated in 1994 as a joint effort between Boeing and NASA, and has since grown to include many other contributing organizations worldwide. It is an effort to standardize CFD input and output, including grid (both structured and unstructured), flow solution, connectivity, BCs, and auxiliary information. CGNS is also easily extensible, and allows for file-stamping and user-inserted-commenting. It employs ADF (Advanced Data Format) and/or HDF5 (Hierarchical Data Format) as a database manager which creates binary files that are portable across computer platforms. It provides a layer of software, the CGIO Interface which allows access to these database managers at a low-level, and a second layer of software known as the Mid-Level Library, or API (Application Programming Interface), which eases the implementation of CGNS into existing CFD codes.

In 1999, control of CGNS was completely transferred to a public forum known as the CGNS Steering Committee. This Steering Committee is made up of international representatives from government and private industry. All CGNS software is completely free and open to anyone (open source). The CGNS standard is also the object of an ISO standardization effort for fluid dynamics data, for release some time in the early to mid-2000's. [Poirier, D. M. A., Bush, R. H., Cosner, R. R., Rumsey, C. L., and McCarthy, D. R., "Advances in the CGNS Database Standard for Aerodynamics and CFD," AIAA Paper 2000-0681, January 2000.]


CGNS will eventually eliminate most of the translator programs now necessary when working between machines and between CFD codes. Also, it eventually may allow for the results from one code to be easily restarted using another code. It will hopefully therefore save a lot of time and money. In particular, it is hoped that future grid-generation software will generate grids with all connectivity and BC information included as part of a CGNS database, saving time and avoiding potential costly errors in setting up this information after-the-fact.

What is a CGNS File?

A CGNS file is an entity that is organized (inside the file itself) into a set of "nodes" in a tree-like structure, in much the same way as directories are organized in the UNIX environment. [Strictly speaking, because links may be used to store information in multiple files, there is no notion of a CGNS file, only of a CGNS database implemented within one or more files. However, throughout this document the two phrases are used interchangeably.] The top-most node is referred to as the "root node." Each node below the root node is defined by both a name and a label, and may or may not contain information or data. Each node can also be a "parent" to one or more "child" nodes. A node can also have as a child node a link to a node elsewhere in the file or to a node in a separate CGNS file altogether. Links are transparent to the user: the user "sees" linked children nodes as if they truly exist in the current tree. An example of a CGNS tree-like structure is shown below.

Figure showing file structure with root node, child nodes, and a link

Example CGNS tree-like structure.

In order for any user to be able to interpret a CGNS file, its nodes must be assembled according to particular rules. For example, the figure below shows a simple example of a tree-like structure that organizes some animals into categories according to rules that most of us are very familiar with. (Note that this figure is different from the previous figure in that no "Labels" or "Data" are used, only "Names.")

Figure showing file structure for categorizing animals

Simple tree-like structure that categorizes some animals.

The categories get narrower and narrower in their scope as you traverse lower in the tree. The broadest category here is "Animals," and the tree narrows all the way down to particular dogs (two "Fido"s, a "Spot," and a "Ginger"). Knowing ahead of time how this tree is organized allows you to quickly and easily access whatever particular information from the tree that you may be interested in. If someone else were to organize these same animals in a completely different way, according to different rules, then it would be difficult for you to access the desired information without spending a lot of time searching and studying the tree.

The particular rules for organizing CGNS files for aerodynamic data, which allow users to easily access desired information, are described in the Standard Interface Data Structures (SIDS) document. Because CGNS files are binary files, they cannot be viewed by the user with standard UNIX ASCII-editing tools. The utility CGNSview was created to allow users to easily view CGNS files.

How this User's Guide is Organized

The main content in this User's Guide is located in the Getting Started section, where several simple examples are given for both structured and unstructured grids. This section covers the basics that most users want or need to learn in order to get started using CGNS. It is recommended that the section on structured grids be read first, in its entirety, even if the user is only interested in unstructured grid applications. Some additional information is covered in the following section; these issues are felt to be important (i.e., most users will want to eventually include them), but they are not as crucial as the basic items covered under Getting Started. Sections are also included on troubleshooting and frequently asked questions.

Note that all of the codes and code segments given in this document are available as complete codes from the CGNS site external link. The names of these codes and their functions are also listed in this document. Also note that not all CGNS capabilities are covered in this document. It is meant to be a fairly simple introductory guide only.