# Detailed CGNS Node Descriptions¶

This section, together with the CGNS File Mapping Figures , constitutes a complete description of the CGNS database structure, together with detailed descriptions of the contents of each attribute of each node. It is intended to be suitable as a reference for anyone implementing CGNS within their own database manager or using the CGIO Core Routines. It should also be of interest to those wishing to understand exactly where information is stored within a CGNS database.

Note that it is the advertised purpose of the CGNS Mid-Level Library to store and retrieve information in conformity with the mapping herein described. Therefore, anyone accessing a CGNS database through the CGNS routines alone does not need a detailed understanding of the file mapping per se. However, this document should still prove useful in ascertaining the meaning of some of the arguments which must be supplied to the Library routines. Further, it will be necessary to consult the SIDS themselves to determine some of the naming conventions.

The node descriptions in this section are closely coupled to and cross-referenced with the CGNS File Mapping Figures, which show all the nodes defined in the SIDS that have child nodes. In the current section, the “Children:” entry in the list of Node Attributes is a link to the figure showing that node with its children. The “Label:” entry (or, in some cases, the “Name:” entry) is a link to the definition of the node’s data structure in the SIDS.

The nodal hierarchy of the CGNS database directly reflects that of the SIDS . Certain sections of the SIDS, notably Building-Block Structure Definitions , Data-Array Structure Definitions , and Miscellaneous Data Structures , describe basic data structures which appear repeatedly as children of nodes representing more complex structures. In order to simplify the presentation and avoid the introduction of undefined terms, this section has been divided into two parts. The first defines a number of basic types which recur often in the structure, and the second describes higher level nodes of more specific function built from the basic nodes

## Basic CGNS Nodes¶

In this section we describe CGNS nodes which hold fundamental types of information. Their structure and function, which are the same everywhere, are described here. However, the meaning of the data they hold at any particular point in a CGNS database depends on the context, i.e., the parent node. Therefore, where necessary, any special context-dependent meaning is elaborated in the paragraph devoted to the parent.

### Descriptor Group¶

These are user-assigned nodes designed to further describe the user’s intent. Their data is meant for human perusal or other user-designated purposes.

#### Descriptor_t¶

The purpose of a node of type Descriptor_t is to store textual data. It is not intended to be read by any system software, except to return the text for human examination.

The intent of the Descriptor_t node is to hold comment sufficient to allow someone other than the originator to understand what the node contains. This may consist of a problem description, reference documents, personal notes, etc.

Any node may have zero to many Descriptor_t children, with the uses differentiated by the Name field. At this time, there are no conventions for these names or for the form of the associated text. It is expected that a standard set such as README , TimeStamp , etc. will evolve as a matter of practice.

Name: User defined Descriptor_t C1 1 Length of string to be stored, including any carriage control or null bytes. String - Since line terminators can be stored within the data, the user could conceptually store an entire document in this area, read it into a program and then print it out. For example, an entire PostScript document describing the problem (and maybe results) could be stored in the Data field, read by a program and then sent to a printer. None 0, N

#### Ordinal_t¶

Because there is no notion of order among children, there is occasionally a desire to order children in a way that survives from one opening of a CGNS database to another. The current CGNS Library provides means of doing this. However, another early method was to place the node “number” in a child of type Ordinal_t .

Like Descriptor_t , the Ordinal_t node is completely under the control of the user, who takes full responsibility for its content. Unlike Descriptor_t , CGNS conventions do not encourage the use of Ordinal_t , as it usually encodes information which is redundant with the name. It is not read or written by standard CGNS software, and so there is no assurance that sibling nodes will be differently, consecutively, or consistently numbered by Ordinal_t . Clearly, if Ordinal_t must be used, no node should have more than one Ordinal_t child, and no two siblings should have Ordinal_t children containing the same data.

It is worth noting that, if consistent numbering is desired, one way of achieving it is to make the desired integer either the name or part of the name. In fact, if, for example, individual zones are left unnamed, the default convention will provide names of Zone1 , Zone2 , etc. Alternatively, the character strings “1 “, “2 “, …, are legal names. The CGNS software, of course, will return these as strings. This may necessitate type conversion or parsing before the names can be used as integer indices.

Name: Ordinal Ordinal_t I4 1 1 The user-defined ordinal number (an integer). None 0,1

### Physical Data Group¶

#### DataClass_t¶

A DataClass_t node specifies the dimensional nature of the data in and below its parent. It overrides any DataClass_t information higher up in the tree. There are six recognized string values. It is necessary to consult the SIDS to determine the precise meaning.

Name: DataClass DataClass_t C1 1 The length of the string One of: DataClassNull , DataClassUserDefined , Dimensional , NormalizedByDimensional , NormalizedByUnknownDimensional , NondimensionalParameter , or DimensionlessConstant None 0,1

#### DimensionalUnits_t¶

A DimensionalUnits_t node specifies dimensional units which apply to data in and below its parent. It overrides any DimensionalUnits_t information higher up in the tree. There are five strings to specify, corresponding, respectively, to units for mass, length, time, temperature, and angular measure. The number of recognized string values varies with the physical property.

Units for three additional types of data are specified in a child node, AdditionalUnits_t .

Node Attributes

Name:

DimensionalUnits

Label:

DimensionalUnits_t

DataType:

C1

Dimension:

2

Dimension Values:

(32,5)

Data:

 For mass, one of: MassUnitsNull , MassUnitsUserDefined , Kilogram , Gram , Slug , Pound-Mass For length, one of: LengthUnitsNull , LengthUnitsUserDefined , Meter , Centimeter , Millimeter , Foot , Inch For time, one of: TimeUnitsNull , TimeUnitsUserDefined , Second For temperature, one of: TemperatureUnitsNull , TemperatureUnitsUserDefined , Kelvin , Celsius , Rankine , Fahrenheit For angles, one of: AngleUnitsNull , AngleUnitsUserDefined , Degree , Radian

Children:

Cardinality:

0,1

#### AdditionalUnits_t¶

An AdditionalUnits_t node specifies dimensional units for additional types of data. To maintain compatibility with earlier CGNS versions, this is an optional child node of DimensionalUnits_t . The specified units apply to data in and below the parent of the corresponding DimensionalUnits_t node, and override any AdditionalUnits_t information higher up in the tree. There are three strings to specify, corresponding, respectively, to units for electric current, substance amount, and luminous intensity. The number of recognized string values varies with the physical property.

Node Attributes

Name:

AdditionalUnits

Label:

AdditionalUnits_t

DataType:

C1

Dimension:

2

Dimension Values:

(32,3)

Data:

 For electric current, one of: ElectricCurrentUnitsNull, ElectricCurrentUnitsUserDefined , Ampere , Abampere , Statampere , Edison , auCurrent For substance amount, one of: SubstanceAmountUnitsNull, SubstanceAmountUnitsUserDefined , Mole , Entities , StandardCubicFoot , StandardCubicMeter For luminous intensity, one of: LuminousIntensityUnitsNull, LuminousIntensityUnitsUserDefined , Candela , Candle , Carcel , Hefner , Violle

Children:

None

Cardinality:

0,1

#### DataConversion_t¶

A DataConversion_t node specifies a non-homogeneous linear function which converts non-dimensional data in its parent to raw dimensional data. Although in principle it overrides any DataConversion_t information higher up in the tree, it is generally not meaningful for it to apply to more than one kind of physical data. Therefore, CGNS specifies its use only as a child of a node which actually contains a single type of real data.

There are two values to specify, corresponding to the scale factor and offset. The SIDS contain the exact conversion formula.

Name: DataConversion DataConversion_t R4 or R8 1 2 ConversionScale , ConversionOffset None 0,1

#### DimensionalExponents_t¶

A DimensionalExponents_t node specifies the powers of mass, length, time, temperature, and angular measure which characterize dimensional data in its parent. Although in principle it overrides any DimensionalExponents_t information higher up in the tree, it is generally not meaningful for it to apply to more than one kind of physical data. Therefore, CGNS specifies its use only as a child of a node which actually contains a single type of real data. There are five values to specify, corresponding to the five types of units specified using DimensionalUnits_t . The data type is real, not integer.

Exponents for three additional types of data are specified in a child node, AdditionalExponents_t .

Name: DimensionalExponents DimensionalExponents_t R4 or R8 1 5 MassExponent , LengthExponent , TimeExponent , TemperatureExponent , AngleExponent 0,1

#### AdditionalExponents_t¶

An AdditionalExponents_t node specifies the powers of the units for additional types of data, which characterize the corresponding dimensional data. There are three values to specify, corresponding to the three types of units specified using AdditionalUnits_t . The data type is real, not integer.

Name: AdditionalExponents AdditionalExponents_t R4 or R8 1 3 ElectricCurrentExponent, SubstanceAmountExponent, LuminousIntensityExponent None 0,1

#### DataArray_t¶

A DataArray_t node is a very general type of node meant to hold large arrays of data, such as grids and flowfields. Often, some of the attributes of a DataArray_t node depend on the context in which the node is found; that is, they are structure parameters.

For example, the SIDS specify that the Data Type of DataArray_t is a structure parameter, “DataType”, which may assume any of the values “In”, “Rn”, or “Cn”.

The other two attributes of DataArray_t , Dimensions and DataSize , also depend on the context where they are being used. Dimensions is a function of the underlying dimensionality of the data being described (often IndexDimension , defined in the CGNSBase_t node), and the DataSize may be inferred from detailed descriptions of the grid.

A node may have any number of DataArray_t children. The meaning of their contents is differentiated by Name, often according to conventions specified by the SIDS. SIDS names are usually precise and descriptive, such as CoordinateTheta or EnergyInternal . (See the SIDS for a current list of sanctioned names .) Conversely, quantities not specified by the SIDS can be stored in DataArray_t nodes, but should be given names other than those specified in the SIDS. In other words, to comply with the SIDS requires that one give a quantity the SIDS-defined name if and only if it is one of the SIDS-defined quantities.

Name: Context dependent DataArray_t Context dependent Context dependent Context dependent The array of data values 0, N DataType, dimension of the data, size of the data

#### Integer Arrays¶

Integer array nodes perform the same function as nodes of type DataArray_t , but store integer instead of real arrays. They are always of type int[] or cgsize_t[] , with the dimensions and values given either explicitly in the appropriate fields, or as parameters or functions. The cgsize_t data type is used wherever there is the potential of exceeding the size limit for a 32-bit integer (I4 ), such as PointList , PointRange , and ElementRange .

Name: Context dependent int , int[IndexDimension] , int[2*IndexDimension] , or int[1 + ... + IndexDimension] I4 or cgsize_t 1 1, IndexDimension , 2*IndexDimension , or (1 + ... + IndexDimension) The array of integer values 0,1 None IndexDimension or none (context dependent)

### Location and Position Group¶

#### GridLocation_t¶

A GridLocation_t node specifies the physical location, with respect to the underlying grid, with which the field data below its parent is associated. The value (data field) is a character string of enumeration type, i.e., it must take one of a number of predefined values. These values are: Vertex , CellCenter , FaceCenter , IFaceCenter , JFaceCenter , KFaceCenter , or EdgeCenter . The strings are case sensitive, and an exact match is required. The GridLocation_t node is optional, and the default is Vertex .

Name: GridLocation GridLocation_t C1 1 Length of the string value Vertex , CellCenter , FaceCenter , IFaceCenter , JFaceCenter , KFaceCenter , or EdgeCenter None 0,1

#### Rind_t¶

The presence of a Rind_t node indicates that field data stored below its parent includes values associated with a spatial extent beyond that of the basic underlying grid. Such data often arise from the use of ghost cells, or from the copying of information from adjacent zones.

Within a single zone, the size of the basic grid is found in the data field of the Zone_t node . The data field of a Rind_t node contains integers specifying the number of planes (for structured grids) or number of rind points or elements (for unstructured grids) of included extra data. The planes for structured grids correspond to the low and high values in the i -direction, low and high values in the j -direction, and low and high values in the k -direction (if needed), in that order. Note that the actual size of the field data, which is stored in a DataArray_t sibling node, is a DataSize structure parameter which depends on the basic grid size, the GridLocation , and the Rind .

The Rind_t node is optional, and the default is no rind.

Name: Rind Rind_t I4 1 2*IndexDimension Number of planes of extra data in low i , high i , low j , high j , etc., (for structured grids) or number of points or elements of extra data (for unstructured grids) None 0,1 IndexDimension

#### IndexRange_t¶

An IndexRange_t node describes a subregion of a zone. This may be, for example, a sub-block or a portion of a face of a zone. It may be used to describe the locations of boundary condition patches and holes for overset grids.

Name: PointRange , PointRangeDonor , ElementRange , or user defined IndexRange_t cgsize_t 2 IndexDimension , 2 First indices, last indices None Context dependent IndexDimension

#### IndexArray_t¶

An IndexArray_t node describes a general subregion of a zone. Unlike IndexRange_t , it lists all the elements of the subregion, rather then only the first and last ones. Its use is similar to IndexRange_t .

Name: PointList , PointListDonor , CellListDonor , or InwardNormalList IndexArray_t cgsize_t , or (for InwardNormalList ) R4 or R8 2 IndexDimension , number of items in the list; or (for InwardNormalList ) PhysicalDimension , number of items in the list Index coordinates of each point or element in the list, or (for InwardNormalList ) physical-space normal vectors at each point or element in the list None 0,1 IndexDimension , either PointListSize or ListLength , and DataType ; or (for InwardNormalList ) PhysicalDimension , ListLength , and DataType

### ReferenceState_t¶

The appearance of a ReferenceState_t node is optional. It is used to specify the values of flow quantities at reference conditions, e.g., at freestream or stagnation. This is typically done for the whole database, in which case the ReferenceState_t node is a child of the CGNSBase_t node.

ReferenceState_t nodes follow the usual convention that information specified lower in the tree overrides higher level specifications. Such overrides are therefore specified if a ReferenceState_t node appears as a child of a Zone_t , ZoneBC_t , or BCDataSet_t node.

The actual values are stored in one or more DataArray_t children whose names identify the quantities being stored. If present, the units specified in the DimensionalUnits_t child apply to all DataArray_t children, subject to the usual override convention. ( I.e., if one of the DataArray_t children itself has a DimensionalUnits_t child, it takes precedence over the higher level specification.)

Name: ReferenceState ReferenceState_t MT 0,1

#### ConvergenceHistory_t¶

ConvergenceHistory_t nodes are intended for the storage of lists of quantities accumulated during calculations associated with either the entire CGNS database or with a single zone.

In the former case, they are called Global convergence histories, and appear as children of the CGNSBase_t node. In the latter, they are called Local and stored below, with the zones to which they correspond.

Each ConvergenceHistory_t node is a parent of a collection of one-dimensional DataArray_t nodes, each of which contains a list of values of a quantity defined by the user. These quantities are differentiated by their user-assigned Names. User definitions of the names are recorded in a Descriptor_t child node with Name NormDefinitions . Children of types DataClass_t and DimensionalUnits_t modify the meaning of the DataArray_t children in the usual manner.

Name: GlobalConvergenceHistory if under a CGNSBase_t node; ZoneConvergenceHistory if under a Zone_t node ConvergenceHistory_t I4 1 1 Number of iterations 0,1

#### IntegralData_t¶

IntegralData_t nodes are intended for the storage of integrated flow quantities such as mass flows, forces and moments. These are kept in DataArray_t children just as in the ConvergenceHistory_t nodes, except that these nodes hold only one real number each.

Name: User defined IntegralData_t MT 0, N

#### UserDefinedData_t¶

UserDefinedData_t nodes are intended as a means of storing arbitrary user-defined data in Descriptor_t and DataArray_t children without the restrictions or implicit meanings imposed on these node types at other node locations.

Multiple Descriptor_t and DataArray_t children may be stored below a UserDefinedData_t node, and the DataArray_t children may be of any dimension and size.

Name: User defined UserDefinedData_t MT 0, N

#### Gravity_t¶

An optional Gravity_t node may be used to define the gravitational vector.

Name: Gravity Gravity_t MT 0,1

## Specialized Nodes¶

In this section we describe nodes whose use is specialized to certain types of CFD-related data. Although these nodes may appear in multiple places in a CGNS DataBase, they play a single role in the description of the data.

### Grid Specification¶

CGNS recognizes the notion of a collection of subdomains called zones, within each of which there is a single structured or unstructured grid. Mathematically, the grid is an assignment of a location in physical space to each element in a discrete computational space. An essential feature of the grid is the connection structure it inherits from the underlying computational space.

It is possible, given a grid, to create others from it, by translation to cell centers, for example. However, CGNS views these as new field structures associated with the original grid, and the File Mapping specifies that they be stored as FlowSolution_t or DiscreteData_t nodes .

#### GridCoordinates_t¶

A GridCoordinates_t node describes a grid associated with a single zone. For a structured zone, the connection structure of the underlying computational space is that of a rectangular array, and its dimension is the IndexDimension , that is, the number of integers required to identify a point in the grid. The physical dimension is the number of real coordinates assigned at each grid point and need not be the same. Thus CGNS can store a grid, for example, with IndexDimension equal to two and a physical dimension of three, that is, a structured grid on a curved surface.

IndexDimension is a zone dependent parameter. For an unstructured grid, it always equals one, meaning that a unique index is required to specified a node location. For a structured grid, IndexDimension varries with the CellDimension of the mesh. For a mesh composed of 3D cells, IndexDimension equals 3, while for a mesh composed of surface or shell elements, IndexDimension equals 2. The values of the physical coordinates of the grid points are stored in DataArray_t children of GridCoordinates_t . The names of the coordinates are stored in the Name field of the corresponding DataArray_t node. For common coordinate systems, i.e., Cartesian, polar, cylindrical, and spherical, the names are specified by the SIDS.

Unlike FlowSolution_t and DiscreteData_t nodes , GridCoordinates_t nodes are not permitted to have GridLocation_t children, because all grid points are at vertices by definition.

Coordinate arrays may also contain rind data. If they do, the GridCoordinates_t node must have a Rind_t child node describing the amount of rind. All DataArray_t nodes under GridCoordinates_t must have the same size. Because the number of field quantities to be stored depends on the number of rind, the actual dimension values are functions, specified in this document by the generic term DataSize[] .

Under each node of type Zone_t , the original grid is contained in a node named GridCoordinates . Additional GridCoordinates_t data structures are allowed, with user-defined names, to store the grid at multiple time steps or iterations.

Name: GridCoordinates or user defined GridCoordinates_t MT or R4 or R8 2 PhysicalDimension , 2 BoundingBox values 0, N IndexDimension , VertexSize , PhysicalDimension DataSize

#### Elements_t¶

The Elements_t data structure is required for unstructured zones, and contains the element connectivity data, the element type, the element range, the parent elements data, and the number of boundary elements.

Name: User defined Elements_t I4 1 2 ElementType value, ElementSizeBoundary 0, N

#### Axisymmetry_t¶

The Axisymmetry_t data structure may be included as a child of the CGNSBase_t node to record the axis of rotation and the angle of rotation around this axis for an axisymmetric database.

Name: Axisymmetry Axisymmetry_t MT 0,1

#### RotatingCoordinates_t¶

The RotatingCoordinates_t data structure may be included as a child of either the CGNSBase_t node or a Zone_t node to record the center of rotation and the rotation rate vector for a rotating coordinate system.

Name: RotatingCoordinates RotatingCoordinates_t MT 0,1

### Field Specification¶

The object of computational field physics is to compute fields of physical data associated with points in space.

#### FlowSolution_t¶

A FlowSolution_t node describes a field of physical data associated with the grid for a single zone. It is intended for the storage of computed flowfield data such as densities and pressures. There is no convention as to how many or what kind of quantities must or may be stored. In particular, it is not specified that the quantities need in any sense be either complete or non-redundant.

The data are stored in DataArray_t children of FlowSolution_t . These DataArray_t nodes are dimensioned by the same underlying IndexDimension parameter as the grid, and the order of storage within the DataArray_t nodes is presumed the same as it is for the grid. The names of the physical quantities are stored in the Name field of the corresponding DataArray_t node. For common fluid dynamic quantities the names are specified by the SIDS .

The relationship between the locations of the field quantities and the vertices of the grid is specified by a GridLocation_t child node. If this node is absent, the field quantities are assumed to be associated with the grid vertices. Field arrays may also contain rind data. If they do, the FlowSolution_t node must have a Rind_t child node describing the amount of rind. All DataArray_t nodes under a single FlowSolution_t must have the same size. Field arrays containing different numbers of rind must be stored under different FlowSolution_t nodes. There may be any number of nodes of type FlowSolution_t under a Zone_t .

Because the number of field quantities to be stored depends on the number of rind and on the location with respect to the grid, the actual dimension values are functions, specified in this document by the generic term DataSize[] .

The meaning of the field arrays is modified in the usual way by any DataClass_t or DimensionalUnits_t children of the FlowSolution_t node.

Name: User defined FlowSolution_t MT 0, N IndexDimension , VertexSize , CellSize DataSize

#### DiscreteData_t¶

DiscreteData_t nodes are identical to FlowSolution_t nodes, but are intended for the storage of fields of real data not usually identified as part of the field solution, such as cell-centered grids.

Name: User defined DiscreteData_t MT 0, N IndexDimension , VertexSize , CellSize DataSize

#### ZoneSubRegion_t¶

The ZoneSubRegion_t node allows for the ability to give flowfield or other information over a subset of the entire zone in a CGNS file. This subset may be over a portion of a boundary, or it may be over a portion of the entire field.

Name: User defined ZoneSubRegion_t I4 1 1 RegionCellDimension 0, N IndexDimension , VertexSize , CellSize DataSize

### Connectivity Group¶

#### Transform Node¶

The Transform node is a node of type int[] which is identified by its name rather than its label. Thus the name must be “Transform “. It appears only as a child of a node of type GridConnectivity1to1_t .

This node stores the transformation matrix relating the indices of two adjacent zones. Its data field contains a list of IndexDimension signed integers, each within the range [-IndexDimension, ..., +IndexDimension] , and no two of which have the same absolute value. Thus in 3-D allowed components are $$0$$, $$\pm 1$$, $$\pm 2$$, and $$\pm 3$$. Each component of the array shows the image in the adjacent zone of a positive index increment in the current zone. The SIDS contain complete details.

Name: Transform “int[IndexDimension] “ I4 1 IndexDimension Transformation matrix (shorthand) None 0,1 IndexDimension

#### GridConnectivityType_t¶

The purpose of this node is to describe the type of zone-to-zone connectivity specified by its parent, which is always a GridConnectivity_t node. The connectivity type is given in the data field as a character string which may take one of three specific values: Abutting , Abutting1to1 , or Overset .

There is a shorthand form of the GridConnectivity_t node, namely, GridConnectivity1to1_t , which incorporates the assumption that the connection is Abutting1to1 . Nodes of type GridConnectivity1to1_t do not have GridConnectivityType_t subnodes. However, GridConnectivity1to1_t nodes can only be used to specify zone-to-zone connections on rectangular subregions between two structured zones. So the use of GridConnectivityType_t subnodes to specify Abutting1to1 is required if the connecting regions are not rectangular, or if the connectivity involves a least one unstructured zone.

Name: GridConnectivityType GridConnectivityType_t C1 1 Length of string Abutting , Abutting1to1 , or Overset None 0,1

#### GridConnectivity1to1_t¶

This node is a shorthand format of GridConnectivity_t capable of describing only Abutting1to1 connections between two structured zones. The underlying subregion must have rectangular data structure.

Each GridConnectivity1to1_t node describes a subregion of a face of a zone whose vertices are coincident in a 1-to-1 fashion with those of a corresponding subregion of a face of another zone. Each ZoneGridConnectivity_t node may have as many GridConnectivity1to1_t (or GridConnectivity_t ) children as are required to describe the connection structure.

The location of the connected subregion of a face of the current zone is given in a single child of type IndexRange_t , whose name is specified by the mapping as “PointRange “. The location of the corresponding subregion on a face of the other zone is given in a single child of type IndexRange_t , whose name is specified by the mapping as “PointRangeDonor “. The first (i.e., beginning) points in these IndexRange_t nodes are presumed to be coincident. The specification of the correspondence is completed by the inclusion of a Transform child node which describes the relative orientation of the two systems of indices. The second (i.e., end) point of the PointRange subnode specifies the extant of the connection.

In general, the File Mapping seeks to avoid the storage of redundant data. However, there are two redundancies associated with GridConnectivity1to1_t . First, for the sake of symmetry, the information recorded here is duplicated (in reverse) in a corresponding node under the donor zone. It is expected that these two specifications will agree.

Second, the end point of the PointRangeDonor can be calculated from the other three points specified, along with the transform. However, the transform cannot be inferred from the four points. Therefore, the end point of the PointRangeDonor is considered to be redundant, and the three points and the transform are designated as the primary specification.

Name: User defined GridConnectivity1to1_t C1 1 Length of string ZoneDonorName 0, N IndexDimension

#### GridConnectivity_t¶

The GridConnectivity_t node is the most general format for describing grid connectivity. It can describe one-to-one, mismatched, and overset connectivity, and the underlying subregions of the connecting zones need not be rectangular.

Each GridConnectivity_t node describes a subregion of a zone which corresponds to a subregion of another zone. Each ZoneGridConnectivity_t node may have as many GridConnectivity_t (or GridConnectivity1to1_t ) children as are required to describe the connection structure.

The location of the connected subregion of the current zone is given in a single child of type either IndexRange_t or IndexArray_t , whose name is specified by the mapping as “PointRange ” or “PointList “, respectively.

If the grid connectivity is one-to-one, the corresponding subregion is defined with a single child of type IndexArray_t , whose name is specified by the mapping as “PointListDonor “. Otherwise, the corresponding subregion is defined by two child nodes, one defining the cells and the other the interpolation factors within the cells. See the SIDS for the complete description.

Name: User defined GridConnectivity_t C1 1 Length of string ZoneDonorName 0, N IndexDimension , CellDimension PointListSize

#### GridConnectivityProperty_t¶

An optional GridConnectivityProperty_t node may be used to record special properties associated with particular connectivity patches.

Name: GridConnectivityProperty GridConnectivityProperty_t MT 0,1

#### Periodic_t¶

A Periodic_t node may be used as a child of GridConnectivityProperty_t to record data associated with a periodic interface.

Name: Periodic Periodic_t MT 0,1

#### AverageInterface_t¶

An AverageInterface_t node is used as a child of GridConnectivityProperty_t when data at the current connectivity interface is to be averaged in some way prior to passing it to a neighboring interface.

Name: AverageInterface AverageInterface_t MT 0,1

#### OversetHoles_t¶

A node of type OversetHoles_t describes a region in a grid in which solution values are to be ignored because the data in the region is to be represented by values associated with other “overlapping” zones (equivalent to that specified by IBLANK = 0 in the PLOT3D format). Each ZoneGridConnectivity_t node may have as many OversetHoles_t children as are required to describe the affected region.

Each hole is described either by a single child of type IndexArray_t or by any number of children of type IndexRange_t . The latter is provided as a means of specifying holes which are unions of small numbers of logically rectangular subregions. However, if the region is irregular, the intent is that it should be specified by a single child of type IndexArray_t which lists the points.

Name: User defined OversetHoles_t MT 0, N IndexDimension

#### ZoneGridConnectivity_t¶

Each Zone_t node may have zero or more children of type ZoneGridConnectivity_t . It holds no data, but serves as the point below which all connectivity data associated with the zone can be found. Multiple ZoneGridConnectivity_t nodes may be used to specify time-dependent changes in the connectivity information.

Name: ZoneGridConnectivity or user defined ZoneGridConnectivity_t MT 0,N IndexDimension , CellDimension

### Boundary Condition Group¶

Nodes in this group are used to specify the physical boundary conditions. Each boundary condition is associated with a subregion of a zone. For brevity below, we use the word “domain” to refer to the region on which a boundary condition is to be enforced.

The domain is usually, but not necessarily, a subregion of a face of the zone. The mapping is sufficiently general to permit the description of internal boundary conditions and boundary conditions which do not lie on a constant coordinate plane.

Mathematical boundary conditions are generally applied on subregions of physical dimension one less than the corresponding field problem. This condition, however, is neither defined nor enforced by the File Mapping.

A large number of standard boundary condition types are named by the SIDS. In addition, it is possible to define new types as collections of Dirichlet and Neumann conditions. It is not possible to describe the entire array of possibilities within this document, and the reader should consult the SIDS for a full description.

#### InwardNormalIndex¶

An InwardNormalIndex node is a node of type int[IndexDimension] which is identified by its Name. It applies to structured grids only, and its function is to specify on which side of the domain the condition is to be enforced.

InwardNormalIndex may have only one nonzero element, whose sign indicates the computational-coordinate direction of the boundary condition patch normal; this normal points into the interior of the zone. For example, if the domain lies on the face of a three-dimensional zone where the second index is a maximum, the inward normal index values are [0,-1,0].

The InwardNormalIndex node must apply to the entire domain of the boundary condition.

For a boundary condition on a face of a zone, the InwardNormalIndex can be calculated from other data and need not be specified. Its purpose is to define the normal direction for internal boundary conditions and other cases where the direction is ambiguous.

Name: InwardNormalIndex “int[IndexDimension] “ I4 1 IndexDimension Index of inward normal None 0,1 IndexDimension

#### InwardNormalList¶

An InwardNormalList node is a node of type IndexArray_t identified by its Name. Its data field contains an array of physical (real) vectors which point into the region on which the boundary condition is to be applied. It may be used for boundary conditions on complex domains for which InwardNormalIndex is not defined, or to store vectors orthogonal to the domain of the boundary condition where these are not easily calculated from the domain itself.

Name: InwardNormalList IndexArray_t R4 or R8 2 PhysicalDimension , ListLength Inward normal vectors None 0,1 PhysicalDimension , ListLength

#### BCData_t¶

When global or local Dirichlet or Neumann boundary conditions are defined, a node of type BCData_t is introduced to store the numerical data. For global data, this consists of a single quantity kept in a DataArray_t child. For local data, e.g., a pressure profile, it is a vector of quantities stored in an order corresponding to that defining the domain and kept in a child node of type DataArray_t .

Name: DirichletData or NeumannData BCData_t MT 0,1 ListLength

#### BCDataSet_t¶

The function of a BCDataSet_t node is to specify the equations to be applied at the boundary, including any actual data values which may be required. The type of the equation is specified by the SIDS and recorded in the data field. For some types, the data is implicit or empty. For others, the data is specified in BCData_t children.

If the locations at which the boundary conditions are to be applied are specified in BCDataSet_t , using PointRange or PointList , the structure function ListLength is used. Otherwise, the structure parameter ListLength is required.

Name: User defined BCDataSet_t C1 1 Length of string BCTypeSimple value 0, N ListLength ListLength

#### BC_t¶

A BC_t node specifies a single boundary condition to be applied on a single zone. It specifies the domain on which the condition is to be applied and the equations to be enforced. All the BC_t nodes for a single zone are found under that zone’s ZoneBC_t node. A ZoneBC_t node may have as many BC_t children as are required to describe the physical boundary conditions on the corresponding zone.

The domain on which the boundary condition is to be enforced is specified by a single node of type either IndexRange_t or IndexArray_t . The equations are specified in one or more BCDataSet_t children.

The type of the boundary condition, which may be either simple or compound, is specified in the data field. For a complete description, it is necessary to consult the SIDS.

Name: User defined BC_t C1 1 Length of string BCType value See BC_t figure 0, N IndexDimension , PhysicalDimension

#### ZoneBC_t¶

The ZoneBC_t node occurs at most once for each zone and serves as the location under which all boundary conditions on that zone are collected.

Name: ZoneBC ZoneBC_t MT 0,1 IndexDimension , PhysicalDimension

#### BCProperty_t¶

An optional BCProperty_t node may be used to record special properties associated with particular boundary condition patches.

Name: BCProperty BCProperty_t MT 0,1

#### WallFunction_t¶

A WallFunction_t node may be used as a child of BCProperty_t to record data associated with the use of wall function boundary conditions.

Name: WallFunction WallFunction_t MT 0,1

#### Area_t¶

An Area_t node may be used as a child of BCProperty_t to record data associated with area-related boundary conditions such as bleed.

Name: Area Area_t MT 0,1

### Equation Specification Group¶

Nodes in this group serve to identify the physical model associated with the data being recorded. Nearly always, the data is of enumeration type and is selected from a collection of terms defined in detail in the SIDS. The names are largely self explanatory, and the detailed definitions will not be repeated here. Numerical values associated with the physical model depend on the type of modeling being chosen and are generally stored in child nodes of type DataArray_t .

#### GoverningEquations_t¶

This node names the equation set being solved, for example, FullPotential or NSTurbulent . If Navier-Stokes, the diffusion terms retained may be specified in a DiffusionModel subnode.

Name: GoverningEquations GoverningEquations_t C1 1 Length of string GoverningEquationsType value 0,1 CellDimension

#### GasModel_t¶

A node of type GasModel_t names the gas model used, for example, Ideal or VanderWaals .

Name: GasModel GasModel_t C1 1 Length of string GasModelType value 0,1

#### ViscosityModel_t¶

A node of type ViscosityModel_t names the molecular viscosity model used to relate the viscosity to the temperature, for example, PowerLaw or SutherlandLaw .

Name: ViscosityModel ViscosityModel_t C1 1 Length of string ViscosityModelType value 0,1

#### EquationDimension¶

A node named EquationDimension , of type int[] , gives the number of dependent variables required for a complete solution description, or the number of equations being solved. For example, for NSTurbulent with the $$k$$-$$\epsilon$$ turbulence model in three dimensions, it is 7.

Name: EquationDimension “int “ I4 1 1 EquationDimension value None 0,1

#### ThermalConductivityModel_t¶

A node of type ThermalConductivityModel_t names the model used to relate the thermal conductivity to the temperature, for example, ConstantPrandtl , PowerLaw , or SutherlandLaw . These closely parallel the viscosity model.

Name: ThermalConductivityModel ThermalConductivityModel_t C1 1 Length of string ThermalConductivityModelType value 0,1

#### TurbulenceClosure_t¶

A node of type TurbulenceClosure_t names the method of closing the Reynolds stress equations when the governing equations are turbulent, for example, EddyViscosity or ReynoldsStressAlgebraic .

Name: TurbulenceClosure TurbulenceClosure_t C1 1 Length of string TurbulenceClosureType value 0,1

#### TurbulenceModel_t¶

A node of type TurbulenceModel_t names the equation set used to model the turbulence quantities, for example, Algebraic_BaldwinLomax or OneEquation_SpalartAllmaras .

Name: TurbulenceModel TurbulenceModel_t C1 1 Length of string TurbulenceModelType value 0,1 CellDimension

#### ThermalRelaxationModel_t¶

A node of type ThermalRelaxationModel_t names the equation set used to model the thermal relaxation quantities, for example, Frozen or ThermalEquilib .

Name: ThermalRelaxationModel ThermalRelaxationModel_t C1 1 Length of string ThermalRelaxationModelType value 0,1

#### ChemicalKineticsModel_t¶

A node of type ChemicalKineticsModel_t names the equation set used to model the chemical kinetics quantities, for example, Frozen and ChemicalEquilibCurveFit .

Name: ChemicalKineticsModel ChemicalKineticsModel_t C1 1 Length of string ChemicalKineticsModelType value 0,1

#### EMElectricFieldModel_t¶

A node of type EMElectricFieldModel_t names the electric field model used for electromagnetic flows, for example, Constant or Voltage .

Name: EMElectricFieldModel EMElectricFieldModel_t C1 1 Length of string EMElectricFieldModelType value 0,1

#### EMMagneticFieldModel_t¶

A node of type EMMagneticFieldModel_t names the magnetic field model used for electromagnetic flows, for example, Constant or Interpolated.

Name: EMMagneticFieldModel EMMagneticFieldModel_t C1 1 Length of string EMMagneticFieldModelType value 0,1

#### EMConductivityModel_t¶

A node of type EMConductivityModel_t names the conductivity model used for electromagnetic flows, for example, Constant or Equilibrium_LinRessler .

Name: EMConductivityModel EMConductivityModel_t C1 1 Length of string EMConductivityModelType value 0,1

#### FlowEquationSet_t¶

A node of type FlowEquationSet_t appears either at the highest level of the tree (under CGNSBase_t ), to indicate the equation set whose solution is recorded throughout the database, or below a Zone_t node, to indicate the set of equations solved in that zone. The usual convention applies, i.e., specifications at the local (zone) level override global specifications.

Name: FlowEquationSet FlowEquationSet_t MT 0,1 CellDimension

### Family Group¶

Because there is rarely a 1-to-1 connection between mesh regions and geometric entities, it is often desirable to set geometric associations indirectly in a CGNS file. That is, rather than setting the geometry data for each mesh entity (nodes, edges, and faces), it’s useful to associate them with intermediate objects. The intermediate objects are in turn linked to nodal regions of the computational mesh. This intermediate object is defined as a CFD family .

Each mesh surface may linked to the geometric entities of one or more CAD databases by a user-defined CFD family name. The CFD family corresponds to one or more CAD geometric entities on which the mesh face is projected. Each one of these geometric entities is described in a CAD file and is not redefined within the CGNS file.

#### Family_t¶

This node, a child of a CGNSBase_t node or a Family_t node, contains the definition of a single CFD family. Multiple Family_t nodes are allowed.

Name: User defined Family_t MT 0, N

#### FamilyName_t¶

This node is used to identify a family to which a particular zone or boundary belongs. Note that the name of the family is defined by the “Name” of the Family_t node, and is stored as data in the FamilyName_t node.

Name: FamilyName or user defined FamilyName_t C1 1 Length of string Name of CFD family None 0,1

#### AdditionalFamilyName_t¶

This node is a supplement to the FamilyName_t node, and is used to identify additional families to which a particular zone or boundary belongs.

Name: user defined AdditionalFamilyName_t C1 1 Length of string Name of CFD family None 0,N

#### FamilyBC_t¶

This node contains a boundary condition type for a particular CFD family.

Name: FamilyBC FamilyBC_t C1 1 Length of string BCType value 0,1

#### FamilyBCDataSet_t¶

A FamilyBCDataSet_t node contains Dirichlet and Neumann data for a single set of boundary condition equations to be applied to a Family. It’s intended use is for simple boundary condition types, where the equations imposed do not depend on local flow conditions.

Name: User defined FamilyBCDataSet_t C1 1 Length of string BCTypeSimple value 0, N

#### GeometryReference_t¶

GeometryReference_t nodes are used to associate a CFD family with one or more CAD databases.

Name: User defined GeometryReference_t MT 0, N

#### GeometryFile_t¶

This node contains the name of the CAD geometry file.

Name: GeometryFile GeometryFile_t C1 1 Length of string Name of the CAD geometry file None 1

#### GeometryFormat_t¶

This enumeration node defines the format of the CAD geometry file.

Name: GeometryFormat GeometryFormat_t C1 1 Length of string Name of the CAD geometry format None 1

#### GeometryEntity_t¶

GeometryEntity_t nodes define the names of the entities in CAD geometry file that make up a CFD family.

Name: User defined GeometryEntity_t MT None 0, N

### Time-Dependent Group¶

Nodes in this section are used for information related to time-dependent flows, and include specification of grid motion and storage of time-dependent or iterative data.

#### BaseIterativeData_t¶

Located directly under the CGNSBase_t node, the BaseIterativeData_t node contains information about the number of time steps or iterations being recorded, and the time and/or iteration values at each step. In addition, it may include the list of zones and families for each step of the simulation, if these vary throughout the simulation.

Name: User defined BaseIterativeData_t I4 1 1 NumberOfSteps 0,1

#### ZoneIterativeData_t¶

The ZoneIterativeData_t node is a child of the Zone_t node, and is used to store pointers to zonal data for each recorded step of the simulation.

Name: User defined ZoneIterativeData_t MT 0,1 NumberOfSteps

#### RigidGridMotion_t¶

RigidGridMotion_t nodes are used to store data defining rigid translation and/or rotation of the grid coordinates. Multiple RigidGridMotion_t nodes may be associated with different iterations or time steps in the computation. This association is recorded under the ZoneIterativeData_t node.

Name: User defined RigidGridMotion_t C1 1 Length of string RigidGridMotionType value 0, N

#### ArbitraryGridMotion_t¶

ArbitraryGridMotion_t nodes are used to store grid velocities for each grid point in a zone (i.e., for deforming grids). Multiple ArbitraryGridMotion_t nodes may be associated with different iterations or time steps in the computation. This association is recorded under the ZoneIterativeData_t node.

Note that instantaneous grid coordinates at different iterations or time steps may be recorded using multiple GridCoordinates_t nodes under a Zone_t node.

Name: User defined ArbitraryGridMotion_t C1 1 Length of string ArbitraryGridMotionType value 0, N IndexDimension , VertexSize , CellSize DataSize

### Structural Nodes¶

In this section we describe the highest levels of the hierarchy. Nodes in this section store only quantities which refer to all the entities below them. Therir primary function is to provide organization to the data below.

#### Zone_t¶

Directly below the highest level node in the database, which is by definition of type CGNSBase_t , are found nodes of type Zone_t providing entry into the data specific to each zone. There are as many Zone_t nodes as there are zones. Their children, in turn, record grid, field, connectivity, and boundary conditions, and a variety of auxiliary data.

Name: User defined Zone_t cgsize_t 2 IndexDimension , 3 VertexSize[IndexDimension] , CellSize[IndexDimension] , VertexSizeBoundary[IndexDimension] 0, N CellDimension , PhysicalDimension

#### CGNSBase_t¶

The CGNSBase_t node is by definition the highest level node in the database, and is located directly below the database root node. It provides entry into all other data. Multiple CGNSBase_t nodes are allowed in a file. The particular database being accessed is determined by the name of the CGNSBase_t node.

The only data stored in the node itself are CellDimension , the dimensionality of a cell in the mesh (i.e., 3 for a volume cell and 2 for a face cell), and PhysicalDimension , the number of indices required to specify a unique physical location in the field data being recorded. However, a variety of global information concerning the entire database may be stored in children of the CGNSBase_t node. In particular, a Descriptor_t node at this level can store user commentary on the entire history of the development of the database.

Other information typically stored directly below the CGNSBase_t node includes convergence histories, reference states, dimensional units, integrated quantities, and information on the flow equations being solved.

Name: User defined CGNSBase_t I4 1 2 CellDimension , PhysicalDimension 0, N

#### SimulationType_t¶

This enumeration-type node is a child of the CGNSBase_t node, and specifies whether or not the data below CGNSBase_t is time-accurate.

Name: SimulationType SimulationType_t C1 1 Length of string TimeAccurate or NonTimeAccurate None 0,1

#### ZoneType_t¶

This enumeration-type node is a required child of the Zone_t node, and specifies whether the grid in that zone is structured or unstructured.

Name: ZoneType ZoneType_t C1 1 Length of string Structured or Unstructured None 1

#### CGNSLibraryVersion_t¶

A file containing a CGNS database also contains, directly below the root node, a CGNSLibraryVersion_t node. This node stores the version number of the CGNS standard with which the file is consistent, and is created automatically when the file is created or modified using the CGNS Mid-Level Library . Note that this node is not actually part of the CGNS database, since it is not located below a CGNSBase_t node.

Note that a file may contain multiple CGNS databases, but there is only one CGNSLibraryVersion_t node. It is assumed that the version number in the CGNSLibraryVersion_t node is applicable to all the CGNS databases in the file.

Note also that some CGNS nodes may actually be links to CGNS nodes in other files. In this case, it is assumed that the CGNSLibraryVersion_t node in the “top-level” file is applicable to the file(s) containing the linked nodes.

Name: CGNSLibraryVersion CGNSLibraryVersion_t R4` 1 1 CGNS version number None 1