3 Conventions

• 3.1 Data Structure Notation Conventions
• 3.2 Structured Grid Notation and Indexing Conventions
• 3.3 Unstructured Grid Element Numbering Conventions
  • 3.3.1 1-D (Line) Elements
  • 3.3.2 2-D (Surface) Elements
  • 3.3.3 3-D (Volume) Elements
  • 3.3.4 Unstructured Grid Example
• 3.4 Multizone Interfaces

3.1 Data Structure Notation Conventions

The intellectual content of the CGNS database is defined in terms of C-like notation including typedefs and structures. The database is made up of entities, and each entity has a type associated with it. Entities include such things as the dimensionality of the grid, an array of grid coordinates, or a zone that contains all the data associated with a given region. Entities are defined in terms of types, where a type can be an integer or a collection of elements (a structure) or a hierarchy of structures or other similar constructs.

The terminology "instance of an entity" is used to refer to an entity that has been assigned a value or whose elements have been assigned values. The terminology "specific instance of a structure" is also used in the following sections. It is short for an instance of an entity whose type is a structure.

Names of entities and types are constructed using conventions typical of Mathematica [Mathematica 3.0, Wolfram Research, Inc. , Champaign, IL (1996)]. Names or identifiers contain no spaces and capitalization is used to distinguish individual words making up a name; names are case-sensitive. The character "/" should be avoided in names, as well as the names "." and "..", as these have special meaning when referencing elements of a structure entity. An entity name cannot exceed 32 characters.

The following notational conventions are employed:

	!		comment to end of line
	_t		suffix used for naming a type
	;		end of a definition, declaration, assignment or entity instance
	=		assignment (takes on the value of)
	:=		indicates a type definition (typedef)
	[ ]		delimiters of an array
	{ }		delimiters of a structure definition
	{{ }}		delimiters of an instance of a structure entity
	< >		delimiters of a structure parameter list
	int		integer
	real		floating-point number
	char		character
	bit		bit
	Enumeration( )		indicates an enumeration type
	Data( )		indicates an array of data, which may be multidimensional
	List( )		indicates a list of entities
	Identifier( )		indicates an entity identifier
	LogicalLink( )		indicates a logical link
	/		delimiter for element of a structure entity
	../		delimiter for parent of a structure entity
	(r)		designation for a required structure element
	(o)		designation for an optional structure element
	(o/d)		designation for an optional structure element with default if absent

An enumeration type is a set of values identified by names; names of values within a given enumeration declaration must be unique. An example of an enumeration type is the following:

  Enumeration( Dog, Cat, Bird, Frog ) 

Data() identifies an array of given dimensionality and size in each dimension, whose elements are all of a given data type. It is written as,

  Data( DataType, Dimension, DimensionValues[] ) ;

A typedef establishes a new type and defines it in terms of previously defined types. Types are identified by the suffix "_t", and the symbol ":=" is used to establish a type definition (or typedef). For example, the above enumeration example can be used in a typedef:

  Pet_t := Enumeration( Dog, Cat, Bird, Frog ) ;

  Pet_t MyFavoritePet ;

A structure is a type that can contain any number of elements, including elements that are also structures. An example of a structure type definition is:

  Sample_t :=
    {
    int Dimension ;                                      (r)

    real[4] Vector ;                                     (o)

    Pet_t ObnoxiousPet ;                                 (o)
    } ;

  Sample_t Sample1 = 
    {{
    Dimension = 3 ;
    Vector = [1.0, 3.45, 2.1, 5.4] ;
    ObnoxiousPet = Dog ;
    }} ;

Some structure type definitions contain arbitrarily long lists of other structures or types. These lists will be identified by the notation,

  List( Sample_t Sample1 ... SampleN ) ;

In the CGNS database it is sometimes necessary to reference the name or identifier of a structure entity. References to entities are denoted by Identifier(), whose single argument is a structure type. For example,

  Identifier(Sample_t) SampleName ;

It is sometimes convenient to directly identify an element of a specific structure entity. It is also convenient to indicate that two entities with different names are actually the same entity. We borrow UNIX conventions to indicate both these features, and make the analogy that a structure entity is a UNIX directory and its elements are UNIX files. An element of an entity is designated by "/"; an example is Sample1/Vector). The structure entity that a given element belongs to is designated "../". A UNIX-like logical link that specifies the sameness of two apparently different entities is identified by LogicalLink(); it has one argument. An example of a logical link is as follows: Suppose a specific instance of a structure entity contains two elements that are of type Sample_t; call them SampleA and SampleB. The statement that SampleB is actually the same entity as SampleA is,

  SampleB = LogicalLink(../SampleA) ;

Structure type definitions include three additional syntactic/semantic notions. These are parameterized structures, structure-related functions, and the identification of required and optional fields within a structure.

As previously stated, one of our design objectives is to minimize duplication of information within the CGNS database. To meet this objective, information is often stored in only one location of the hierarchy; however, that information is typically used in other parts of the hierarchy. A consequence of this is that it may not be possible to decipher all the information associated with a given entity in the hierarchy without knowledge of data contained in higher level entities. For example, the grid size of a zone is stored in one location (in Zone_t), but is needed in many substructures to define the size of grid and solution-data arrays.

This organization of information must be reflected in the language used to describe the database. First, parameterized structures are introduced to formalize the notion that information must be passed down the hierarchy. A given structure type is defined in terms of a list of parameters that precisely specify what information must be obtained from the structure's parent. These structure-defining parameters play a similar role to subroutine parameters in C or FORTRAN and are used to define fields within the structure; they are also passed onto substructures. Parameterized structures are also loosely tied to templates in C++.

Parameterized structures are identified by the delimiters < > enclosing the list of parameters. Each structure parameter in a structure-type definition consists of a type and an identifier. Examples of parameterized structure type definitions are:

  NewSample_t< int Dimension, int Fred > :=
    {
    int[Dimension] Vector ;                              (o)

    Pet_t ObnoxiousPet ;                                 (o)

    Stuff_t<Fred> Thingy ;                               (o)
    } ;

  Stuff_t< int George > :=
    {
    real[George] IrrelevantStuff ;                       (r)
    } ;

A second language feature required to cope with the cascade of information within the hierarchy is structure-related functions. For example, the size of an array within a given structure may be a function of one or more of the structure-defining parameters, or the array size may be a function of an optional field within the structure. No new syntax is provided to incorporate structure-related functions; they are instead described in terms of their return values, dependencies, and functionality.

An additional notation used in structure typedefs is that each element or field within a structure definition is identified as required, optional, or optional with a default if absent; these are designated by "(r)", "(o)", and "(o/d)", respectively, in the right margin of the structure definition. These designations are included to assist in implementation of the data structures into an actual database and can be used to guide mapping of data as well as error checking. "Required" fields are those essential to the interpretation of the information contained within the data structure. "Optional" fields are those that are not necessary but potentially useful, such as documentation. "Defaulted-optional" fields are those that take on a known default if absent from the database.

In the example of Sample_t above, only the element Dimension is required. Both elements Vector and ObnoxiousPet are optional. This means that in any specific instance of the structure, only Dimension must be present. An alternative instance of the entity Sample1 shown above is the following:

  Sample_t Sample1 = 
    {{
    Dimension = 4 ;
    }} ;

None of the entities and types defined in the above examples are actually used in the definition of the SIDS. As a final note, the reader should be aware that the SIDS is a conceptual description of the form of the data. The actual location of data in the file is determined by the file mapping, defined by the appropriate File Mapping Manual.

3.2 Structured Grid Notation and Indexing Conventions

A grid is defined by its vertices. In a 3-D structured grid, the volume is the ensemble of cells, where each cell is the hexahedron region defined by eight nearest neighbor vertices. Each cell is bounded by six faces, where each face is the quadrilateral made up of four vertices. An edge links two nearest-neighbor vertices; a face is bounded by four edges.

In a 2-D structured grid, the notation is more ambiguous. Typically, the quadrilateral area composed of four nearest-neighbor vertices is referred to as a cell. The sides of each cell, the line linking two vertices, is either a face or an edge. In a 1-D grid, the line connecting two vertices is a cell.

A structured multizone grid is composed of multiple regions called zones, where each zone includes all the vertices, cells, faces, and edges that constitute the grid in that region.

Indices describing a 3-D grid are ordered (i,j,k); (i,j) is used for 2-D and (i) for 1-D.

Cell centers, face centers, and edge centers are indexed by the minimum i, j, and k indices of the connecting vertices. For example, a 2-D cell center (or face center on a 3-D grid) would have the following convention:

A zone may contain grid-coordinate or flow-solution data defined at a set of points outside the zone itself. These are referred to as "rind" or ghost points and may be associated with fictitious vertices or cell centers. They are distinguished from the vertices and cells making up the grid within the zone (including its boundary vertices), which are referred to as "core" points. The following is a 2-D zone with a single row of rind vertices at the minimum and maximum i-faces. The grid size (i.e., the number of core vertices in each direction) is 5×4. Core vertices are designated by a bullet, and rind vertices by "×". Default indexing is also shown for the vertices.

For a zone, the minimum faces in each coordinate direction are denoted i-min, j-min and k-min; the maximum faces are denoted i-max, j-max and k-max. These are the minimum and maximum core faces. For example, i-min is the face or grid plane whose core vertices have minimum i index (which if using default indexing is 1).

3.3 Unstructured Grid Element Numbering Conventions

The major difference in the way structured and unstructured grids are recorded is the element definition. In a structured grid, the elements can always be recomputed easily using the computational coordinates, and therefore they are usually not written in the data file. For an unstructured grid, the element connectivity cannot be easily built, so this additional information is generally added to the data file. The element information typically includes the element type or shape, and the list of nodes for each element.

In an unstructured zone, the nodes are ordered from 1 to N, where N is the number of nodes in the zone. An element is defined as a group of one or more nodes, where each node is represented by its index. The elements are indexed from 1 to M within a zone, where M is the total number of elements defined for the zone.

CGNS supports eight element shapes - points, lines, triangles, quadrangles, tetrahedra, pentahedra, pyramids, and hexahedra. Elements describing a volume are referred to as 3-D elements. Those defining a surface are 2-D elements. Line and point elements are called 1-D and 0-D elements, respectively.

In a 3-D unstructured mesh, the cells are defined using 3-D elements, while the boundary patches may be described using 2-D elements. The complete element definition may include more than just the cells.

Each element shape may have a different number of nodes, depending on whether linear, quadratic, or cubic interpolation is used. Therefore the name of each type of element is composed of two parts; the first part identifies the element shape, and the second part the number of nodes. The following table summarizes the element types supported in CGNS.

The ordering of the nodes within an element is important. Since the nodes in each element type could be ordered in multiple ways, it is necessary to define numbering conventions. The following sections describe the element numbering conventions used in CGNS.

Like a structured zone, an unstructured zone may contain grid-coordinates or flow-solution data at points outside of the zone itself, through the use of ghost or "rind" points and elements. However, unlike for structured zones, rind data for unstructured zones cannot be defined implicitly (i.e., via indexing conventions alone). In other words, when using rind with unstructured zones, the rind grid points and their element connectivity information should always be given.

3.3.1 1-D (Line) Elements

1-D elements represent geometrically a line (or bar). The linear form, BAR_2, is composed of two nodes at each extremity of the line. The quadratic form, BAR_3, has an additional node located at the middle of the line. The cubic form of the line, BAR_4, contains two nodes interior to the endpoints. The quartic form of the line, BAR_5, contains three nodes interior to the endpoints.

Linear and Quadratic Elements

	BAR_2
	BAR_3

Cubic Elements

BAR_4

Quartic Elements

BAR_5

Note that nodes are uniformly spaced on all edges for all higher order elements.

3.3.2 2-D (Surface) Elements

2-D elements represent a surface in either 2-D or 3-D space. Note that in physical space, the surface need not be planar, but may be curved. In a 2-D mesh the elements represent the cells themselves; in a 3-D mesh they represent faces. CGNS supports two shapes of 2-D elements - triangles and quadrangles.

The normal vector of a 2-D element is computed using the cross product of a vector from the first to second node, with a vector from the first to third node. The direction of the normal is such that the three vectors (i.e., , , and ) form a right-handed triad.

3.3.2.1 Triangular Elements

Six types of triangular elements are supported in CGNS, TRI_3, TRI_6, TRI_9, TRI_10, TRI_12, and TRI_15. TRI_3 elements are composed of three nodes located at the three geometric corners of the triangle. TRI_6 elements have three additional nodes located at the middles of the three edges. The cubic forms of triangular elements, TRI_9 and TRI_10 contain two interior nodes along each edge, and an interior face node in the case of TRI_10. The quartic forms of triangular elements, TRI_12 and TRI_15 contain three interior nodes along each edge, and three interior face nodes in the case of TRI_15.

Linear and Quadratic Elements

TRI_3 and TRI_6

Cubic Elements

TRI_9 and TRI_10

Quartic Elements

	TRI_12
	TRI_15

3.3.2.2 Quadrilateral Elements

CGNS supports seven types of quadrilateral elements, QUAD_4, QUAD_8, QUAD_9, QUAD_12, QUAD_16, QUAD_P4_16, and QUAD_25. QUAD_4 elements are composed of four nodes located at the four geometric corners of the quadrangle. In addition, QUAD_8 and QUAD_9 elements have four mid-edge nodes, and QUAD_9 adds a mid-face node. The cubic forms of quadrilateral elements, QUAD_12 and QUAD_16 contain two interior nodes along each edge, and four interior face nodes in the case of QUAD_16. The quartic forms of quadrilateral elements, QUAD_P4_16 and QUAD_25 contain three interior nodes along each edge, and nine interior face nodes in the case of QUAD_25.

Linear and Quadratic Elements

	QUAD_4 and QUAD_8
	QUAD_9

Cubic Elements

	QUAD_12
	QUAD_16

Quartic Elements

	QUAD_P4_16
	QUAD_25

3.3.3 3-D (Volume) Elements

3-D elements represent a volume in 3-D space, and constitute the cells of a 3-D mesh. CGNS supports four different shapes of 3-D elements - tetrahedra, pyramids, pentahedra, and hexahedra.

3.3.3.1 Tetrahedral Elements

CGNS supports seven types of tetrahedral elements, TETRA_4, TETRA_10, TETRA_16, TETRA_20, TETRA_22, TETRA_34, and TETRA_35. TETRA_4 elements are composed of four nodes located at the four geometric corners of the tetrahedron. TETRA_10 elements have six additional nodes, at the middle of each of the six edges. The cubic forms of tetrahedral elements, TETRA_16 and TETRA_20 contain two interior nodes along each edge, and four interior face nodes in the case of TETRA_20. The quartic forms of tetrahedral elements, TETRA_22, TETRA_34, and TETRA_35 contain three interior nodes along each edge, twelve interior face nodes in the case of TETRA_34, and twelve interior face nodes plus one interior volume node in the case of TETRA_35.

Linear and Quadratic Elements

	TETRA_4
	TETRA_10

Cubic Elements

	TETRA_16
	TETRA_20

Quartic Elements

	TETRA_22
	TETRA_34
	TETRA_35

3.3.3.2 Pyramid Elements

CGNS supports nine types of pyramid elements, PYRA_5, PYRA_13, PYRA_14, PYRA_21, PYRA_29, PYRA_30, PYRA_P4_29, PYRA_50, and PYRA_55. PYRA_5 elements are composed of five nodes located at the five geometric corners of the pyramid. In addition, PYRA_13 and PYRA_14 elements have a node at the middle of each of the eight edges; PYRA_14 adds a node at the middle of the quadrilateral face. The cubic forms of pyramid elements, PYRA_21, PYRA_29, and PYRA_30 contain two interior nodes along each edge, eight interior face nodes in the case of PYRA_29 and PYRA_30, and an additonal interior volume node for PYRA_30. The quartic forms of pyramid elements, PYRA_P4_29, PYRA_50, and PYRA_55 contain three interior nodes along each edge, 21 interior face nodes in the case of PYRA_50, and 21 interior face nodes and five additonal interior volume nodes for PYRA_55.

Linear and Quadratic Elements

	PYRA_5
	PYRA_13
	PYRA_14

Cubic Elements

	PYRA_21
	PYRA_29
	PYRA_30

Quartic Elements

	PYRA_P4_29
	PYRA_50
	PYRA_55

NOTE: Prior to 5/21/2019, Face F1 was defined incorrectly in the table for PYRA_50 and PYRA_55.

3.3.3.3 Pentahedral Elements

CGNS supports nine types of pentahedral elements, PENTA_6, PENTA_15, PENTA_18, PENTA_24, PENTA_38, PENTA_40, PENTA_33, PENTA_66, and PENTA_75. PENTA_6 elements are composed of six nodes located at the six geometric corners of the pentahedron. In addition, PENTA_15 and PENTA_18 elements have a node at the middle of each of the nine edges; PENTA_18 adds a node at the middle of each of the three quadrilateral faces. The cubic forms of the pentahedral elements, PENTA_24, PENTA_38, and PENTA_40 contain two interior nodes along each edge, fourteen interior face nodes in the case of PENTA_38 and PENTA_40, and an additonal two interior volume nodes for PENTA_40. The quartic forms of the pentahedral elements, PENTA_33, PENTA_66, and PENTA_75 contain three interior nodes along each edge, 33 interior face nodes in the case of PENTA_66, and 33 interior face nodes and an additonal nine interior volume nodes for PENTA_75.

Linear and Quadratic Elements

	PENTA_6
	PENTA_15
	PENTA_18

Cubic Elements

	PENTA_24
	PENTA_38
	PENTA_40

Quartic Elements

	PENTA_33
	PENTA_66
	PENTA_75

NOTE: Prior to 5/21/2019, Face F4 was defined incorrectly in the table for PENTA_66 and PENTA_75.

3.3.3.4 Hexahedral Elements

CGNS supports nine types of hexahedral elements, HEXA_8, HEXA_20, HEXA_27, HEXA_32, HEXA_56, HEXA_64, HEXA_44, HEXA_98, and HEXA_125. HEXA_8 elements are composed of eight nodes located at the eight geometric corners of the hexahedron. In addition, HEXA_20 and HEXA_27 elements have a node at the middle of each of the twelve edges; HEXA_27 adds a node at the middle of each of the six faces, and one at the cell center. The cubic forms of the hexahedral elements, HEXA_32, HEXA_56, and HEXA_64 contain two interior nodes along each edge, 24 interior face nodes in the case of HEXA_56 and HEXA_64, and an additonal eight interior volume nodes for HEXA_64. The quartic forms of the hexahedral elements, HEXA_44, HEXA_98, and HEXA_125 contain three interior nodes along each edge, 54 interior face nodes in the case of HEXA_98, and 54 interior face nodes and an additonal 27 interior volume nodes for HEXA_125.

Linear and Quadratic Elements

	HEXA_8
	HEXA_20
	HEXA_27

NOTE: Prior to 7/19/2019, there was a typo in F3 corner nodes definition for HEXA_8, HEXA_20, and HEXA_27.

Cubic Elements

	HEXA_32
	HEXA_56
	HEXA_64

NOTE: Prior to 7/19/2019, there was a typo in F3 corner nodes definition for HEXA_32, HEXA_56, and HEXA_64, and F5 mid-face nodes were mis-ordered in HEXA_56 and HEXA_64.

Notes

	N1,...,N64		Grid point identification number. Integer ≥ 0 or blank, and no two values may be the same. Grid points N1 ... N4 are in consecutive order about one quadrilateral face. Grid points N5 ... N8 are in order in the same direction around the opposite quadrilateral face.
	E1,...,E12		Edge identification number. The edges are oriented from the first to the second node. A negative edge (e.g., -E1) means that the edge is used in its reverse direction.
	F1,...,F6		Face identification number. The faces are oriented so that the cross product of a vector from its first to second node, with a vector from its first to third node, is oriented outward.

Quartic Elements

	HEXA_44
	HEXA_98
	HEXA_125

NOTE: Prior to 7/19/2019, there was a typo in F3 corner nodes definition for HEXA_44, HEXA_98, and HEXA_125, and F5 mid-face nodes were mis-ordered in HEXA_98 and HEXA_125.

NOTE: Prior to 5/21/2019, Face F1 was defined incorrectly in the table for HEXA_98 and HEXA_125.

3.3.4 Unstructured Grid Example

Consider an unstructured zone in the shape of a cube, with each edge of the zone having three nodes. The resulting unstructured grid has a total of 27 nodes, as illustrated in the exploded figure below.

Example Unstructured Cube (Exploded View)

This zone contains eight hexahedral cells, numbered 1 to 8, and the cell connectivity is:

In addition to the cells, the boundary faces could also be added to the element definition of this unstructured zone. There are 24 boundary faces in this zone, corresponding to element numbers 9 to 32. Each boundary face is of type QUAD_4. The table below shows the element connectivity of each boundary face, as well as the element number and face number of its parent cell.

3.4 Multizone Interfaces

1-to-1 Abutting Interface



Mismatched Abutting Interface



Overset Interface

Structured-Grid Multizone Interface Types

The above figure shows three types of multizone interfaces, shown for structured zones. The first type is a 1-to-1 abutting interface, also referred to as matching or C0 continuous. The interface is a plane of vertices that are physically coincident between the adjacent zones. For structured zones, grid-coordinate lines perpendicular to the interface are continuous from one zone to the next. In 3-D, a 1-to-1 abutting interface is usually a logically rectangular region.

The second type of interface is mismatched abutting, where two zones touch but do not overlap (except for vertices and cell faces on the grid plane of the interface). Vertices on the interface may not be physically coincident between the two zones. The figure identifies the vertices and face centers of the left zone that lay on the interface. Even for structured zones in 3-D, the vertices of a zone that constitute an interface patch may not form a logically rectangular region.

The third type of multizone interface is called overset and occurs when two zones overlap; in 3-D, the overlap is a 3-D region. For overset interfaces, one of the two zones takes precedence over the other; this establishes which solution in the overlap region to retain and which to discard. The region in a given zone where the solution is discarded is called an overset hole and the grid points outlining the hole are called fringe points. The figure depicts an overlap region between two zones. The right zone takes precedence over the left zone, and the points identified in the figure are the fringe points and overset-hole points for the left zone. In addition, for the zone taking precedence, any bounding points (i.e., vertices on the bounding faces) of the zone that lay within the overlap region must also be identified.

Overset interfaces may also include multiple layers of fringe points outlining holes and at zone boundaries.

For the mismatched abutting and overset interfaces in the above figure, the left zone plays the role of receiver zone and the right plays the role of donor zone.