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 Manual) (Parallel CGNS User's Guide) (ADF Implementation) (HDF5 Implementation) (Python Implementation) (CGNS Tools and Utilities)

(Summary Description of ADF) (ADF User's Guide)

Summary Description of ADF (Advanced Data Format)

The purpose of the current document is to describe the way in which CFD data is to be stored in an ADF file. To do this, it is necessary to first describe the structure of the ADF file itself in some detail. Therefore, a conceptual summary of ADF is given here in order to make the current document relatively independent, and to allow the reader to focus on those aspects of ADF which are essential to understanding the file mapping. The ADF User's Guide should be used as the authoritative reference to resolve any issues not covered by this summary.

General Description of ADF

The ADF, or Advanced Data Format, together with its access software known as the ADF Core, constitutes a general database manager particularly suited to the storage of numerical data. Its use is not restricted to data connected with CFD, and ADF contains no built-in references to concepts from CFD.

ADF Files and the ADF Core

Files created by the ADF Core are referred to as ADF files. These are binary files whose precise physical form on the external storage medium is completely controlled by the Core routines. ADF files are not intelligible or accessible except through the ADF Core routines, and their physical form is of interest only to ADF Core programmers.

The ADF Core routines perform typical operations on ADF files: open, close, create, delete, read, write, and so on. They are written in ANSI C and are thus themselves portable to any platform supporting an ANSI C compiler. Because the Core completely determines the physical form of the ADF files, the files themselves can be read on those platforms as well. [There are necessarily some issues relating to the retention of precision on platforms of varying word length.] In addition to portability, this arrangement provides integrity of data across both space and time. In particular, it is never necessary to know more about an ADF file (other than that it is one) in order to open it and find out what it contains.

The ADF Core implements the minimal set of procedures required to fully manipulate the database. The Core itself is written in C, but each Core call is also provided in Fortran. This enables the user to access ADF data from either of these languages.

The Conceptual Structure of ADF Files

Although the physical structure of an ADF file in storage is (or should be) of little concern to users of ADF, an understanding of its logical or conceptual structure is essential. This structure determines its suitability for the type of data at hand and is reflected in all of the ADF Core calling sequences.

An ADF file consists entirely of a collection of elements called nodes. These nodes are arranged in a tree structure which 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:

  1. Each node may have any number of child nodes.
  2. Except for one node, called the root, each node is the child of exactly one other node, called its parent.
  3. The root node has no parent.

Every node in an ADF file has exactly the same internal structure. Each node contains identifying information, pointers to any children, and, optionally, data.

When an ADF file is opened (by the appropriate Core routine), information is returned to the calling program which is sufficient to access the root node. It is then the responsibility of the program to search the tree for whatever information is required, or to add to the tree any information it wishes to store.

There is a special kind of node called a link, which serves as a pointer to a node in another ADF file, or in another part of the same ADF file. The tree structure at and below the node to which the link points is available as if that node were present instead of the link. This allows an ADF file to span multiple physical files, and also allows a portion of one ADF file to be referenced by several other ADF files.

The ADF Mid-Level Library (projected)

The ADF Core routines access the data at a very fundamental level. Since by definition the Core implements a minimum number of basic functions, it necessarily deals with the data at a very fundamental level. While skilled programmers may find this acceptable, most programs define higher level routines which coalesce oft-repeated sequences of Core calls. We envision that these routines will eventually be gathered into an ADF "Mid-Level" Library.

At this time, there are approximately four such routines. However, there has been no coordinated effort to gather, organize, or distribute such a Library.

(These remarks apply only to routines designed to access general ADF data. There does exist a set of higher level routines used to access CFD related data, namely, the CGNS Mid-Level Library.)

The Structure of an ADF Node

The File Mapping specifies not only the location of the node at which a particular kind of data is to be stored, but also how the internal structure of the node is to be used. Each node contains a number of fields into which data may be entered directly via ADF Core calls. They are:

In addition, two other entities associated with the nodes are managed by ADF itself. These are:

The Node ID

The node ID is a unique identifier assigned to each existing node by ADF when the file containing it is opened, and to new nodes as they are created. ADF Core inquiries generally return node IDs as a result and accept node IDs as input. By building a table of IDs, calling software can subsequently access specific nodes without further search. The Node ID is real and is not under user control.

The Node Name

The node Name is a 32-byte character field which is user controllable. Its general use is to distinguish among the children of a given node; consequently, no two children of the same parent may have the same Name.

The Label

The Label is a 32-byte character field which is user controllable. ADF assigns no formal role to the Label, but the intent was to identify the structure of the included data. It is common for the various children of a single parent to store different instances of the same structure. Therefore, there is no prohibition against more than one child of the same parent having the same Label.

The Data Type

The Data Type is a 32-byte character field which specifies the type and precision of any data which is stored in the data field. Types provided by ADF are:

    Data Type   Notation
No Data MT
Integer 32 I4
Integer 64 I8
Unsigned Integer 32 U4
Unsigned Integer 64 U8
Real 32 R4
Real 64 R8
Complex 64 X4
Complex 128 X8
Character C1
Byte B1
Link LK

If the data type is MT or LK, the node attributes which described the data may be left undefined.

The Number of Dimensions

The Data portion of a node is designed to store multi-dimensional arrays of data, each element of which is presumed to be of the Data Type specified. The Number of Dimensions specifies the number of integers required to reference a single datum within the array.

The Dimension Values

The Dimension Values are a list of integers expressing the actual sizes of the stored array in each of the dimensions specified.

The Data

The portion of the node holding the actual stored data array.

The Child Table

ADF maintains a table recording the number of, and pointers to, the children of each node. The table is adjusted when children are added or deleted by ADF Core calls.

Children may be identified by their names and labels, and, thence, by their node IDs once these have been determined. ADF provides no notion of order among children. In particular, the order of a list of children returned by ADF has nothing to do with the order in which they were inserted in the file. However, the order returned is consistent from call to call provided the file has not been closed and the node structure has not been modifed.

Note that there is no parent table; that is, a node has no direct knowledge of its parent. Since calling software must open the file from the root, it presumably cannot access a child without having first accessed the parent. It is the responsibility of the calling software to record the node ID of the parent if this information will be required.