This section presents the structure-type definitions for the top levels of the CGNS hierarchy. As stated in the SIDS design philosophy, the hierarchy is topologically based, where the overall organization is by zones. All information pertaining to a given zone, including grid coordinates, flow solution, and other related data, is contained within that zone’s structure entity. This section describes the CGNS version number, defines the CGNS database entry level structure and the zone structure, and concludes with a discussion of globally applicable data.
CGNS is an evolving standard. Although great care is taken to make CGNS databases backward-compatible with previous versions whenever possible, new nodes and new features are still being added that make them non-forward-compatible. To address this issue, each new version of the standard is labeled with a version number that should be written in the file. This version number corresponds to the version of the SIDS and is an essential part of the file containing the CGNS database. The file can not be interpreted properly without knowledge of this version number.
Physically, this version number is located directly under the root node of the file. The SIDS File Mapping Manual defines this location more precisely.
Historically, the version number was used to describe the version of the Mid-Level Library used to write or modify the file. The corresponding node was thus named CGNSLibraryVersion_t. With the advent of new libraries that can read and write CGNS databases, the node is now defined as the version of the CGNS standard. The Mid-Level Library modifies its interpretation of node data according to the CGNS version number, and other libraries should also.
CGNSBase_t¶The highest level structure in a CGNS database is CGNSBase_t. This top level entity is designed to be self-contained, a complete CFD computation can be archived and reproduced using the data defined in the CGNSBase. However a CGNS tree can contain more than one base, these can be related to the same CFD case or not. The behavior of a multi-base CGNS tree is application dependent, even if inter-base relationships are authorized in three cases:
A reference to another base’s zone name (including its sub-nodes’ names) as defined in the multi-zone connectivities (see Multizone Interface Connectivity and time-dependant pointers Time-Dependent Flow);
A reference to another base’s family name (see Family Data Structure Definition:
Family_t) as asFamilyName_tdata;A LogicalLink() from one base to another on any kind of node;
Care must be taken on precedence rules and scope in the case of parsing multiple CGNS bases (see Precedence Rules and Scope Within the Hierarchy).
The CGNS Base contains the cell dimension and physical dimension of the computational grid and lists of zones and families making up the domain. Globally applicable information, including a reference state, a set of flow equations, dimensional units, time step or iteration information, and convergence history are also attached. In addition, structures for describing or annotating the database are also provided; these same descriptive mechanisms are provided for structures at all levels of the hierarchy.
CGNSBase_t :=
{
List( Descriptor_t Descriptor1 ... DescriptorN ) ; (o)
int CellDimension ; (r)
int PhysicalDimension ; (r)
BaseIterativeData_t BaseIterativeData ; (o)
List( Zone_t<CellDimension, PhysicalDimension> Zone1 ... ZoneN ) ; (o)
List( ParticleZone_t<PhysicalDimension> Particles1 ... ParticlesN ) ; (o)
ReferenceState_t ReferenceState ; (o)
Axisymmetry_t Axisymmetry ; (o)
RotatingCoordinates_t RotatingCoordinates ; (o)
Gravity_t Gravity ; (o)
SimulationType_t SimulationType ; (o)
DataClass_t DataClass ; (o)
DimensionalUnits_t DimensionalUnits ; (o)
FlowEquationSet_t<CellDimension> FlowEquationSet ; (o)
ConvergenceHistory_t GlobalConvergenceHistory ; (o)
List( IntegralData_t IntegralData1... IntegralDataN ) ; (o)
List( Family_t Family1... FamilyN ) ; (o)
List( UserDefinedData_t UserDefinedData1 ... UserDefinedDataN ) ; (o)
} ;
Note
Default names for the Descriptor_t, Zone_t, ParticleZone_t, IntegralData_t, Family_t and UserDefinedData_t lists are as shown;
users may choose other legitimate names. Legitimate names must be unique at this level and shall not include the names Axisymmetry, :sidskey:` BaseIterativeData`, DataClass, DimensionalUnits, FlowEquationSet, GlobalConvergenceHistory, Gravity, ReferenceState, RotatingCoordinates or SimulationType.
The number of entities of type Zone_t defines the number of zones in the domain.
CellDimension and PhysicalDimension are the only required fields. The Descriptor_t, Zone_t and IntegralData_t lists may be empty, and all other optional fields absent.
Note that we make the distinction between the following:
|
Number of different indices required to reference a node (e.g., 1 = \(i\), 2 = \(i,j\), 3 = \(i,j,k\)) |
|
Dimensionality of the cell in the mesh (e.g., 3 for a volume cell, 2 for a face cell) |
|
Number of coordinates required to define a node position (e.g., 1 for 1-D, 2 for 2-D, 3 for 3-D) |
These three dimensions may differ depending on the mesh. For example, an unstructured triangular surface mesh representing the wet surface of an aircraft will have:
IndexDimension= 1 (always for unstructured)
CellDimension= 2 (face elements)
PhysicalDimension= 3 (needs \(x\), \(y\), \(z\) coordinates since it is a 3D surface)
For a structured zone, the quantities IndexDimension and CellDimension are always equal. For an unstructured zone, IndexDimension always equals 1. Therefore, storing CellDimension at the CGNSBase_t level will automatically define the IndexDimension value for each zone.
On the other hand we assume that all zones of the base have the same CellDimension, e.g. if CellDimension is 3, all zones must be composed of 3D cells within the CGNSBase_t.
If the base contains only particles (no mesh), then CellDimension carries no meaning. It remains required for compatibility purposes and must best set to 0.
We need IndexDimension for both structured and unstructured zones in order to use original data structures such as GridCoordinates_t, FlowSolution_t, DiscreteData_t, etc.
CellDimension is necessary to express the interpolants in ZoneConnectivity with an unstructured zone (mismatch or overset connectivity). When the cells are bidimensional, two interpolants per node are required, whereas when the cells are tridimensional, three interpolants per node must be provided. PhysicalDimension becomes useful when expressing quantities such as the InwardNormalList in the BC_t data structure. It’s possible to have a mesh where IndexDimension = 2 but the normal vectors still require \(x\), \(y\), \(z\) components in order to be properly defined. Consider, for example, a structured surface mesh in the 3D space.
Information about the number of time steps or iterations being recorded, and the time and/or iteration values at each step, may be contained in the BaseIterativeData structure.
Data specific to each zone in a multizone case is contained in the list of Zone_t structure entities.
The ParticleZone_t node allows to store sets of particles.
Reference data applicable to the entire CGNS database is contained in the ReferenceState structure; quantities such as Reynolds number and freestream Mach number are contained here (for external flow problems).
Axisymmetry may be used to specify the axis of rotation and the circumferential extent for an axisymmetric database.
If a rotating coordinate system is being used, the rotation center and rotation rate vector may be specified using the RotatingCoordinates structure.
Gravity may be used to define the gravitational vector.
SimulationType is an enumeration type identifying the type of simulation. The default value is SimulationTypeNull.
SimulationType_t := Enumeration (
SimulationTypeNull,
SimulationTypeUserDefined,
TimeAccurate,
NonTimeAccurate ) ;
DataClass describes the global default for the class of data contained in the CGNS database. If the CGNS database contains dimensional data (e.g., velocity with units of \(m/s\)), DimensionalUnits may be used to describe the system of units employed.
FlowEquationSet contains a description of the governing flow equations associated with the entire CGNS database. This structure contains information on the general class of governing equations (e.g., Euler or Navier-Stokes), equation sets required for closure, including turbulence modeling and equations of state, and constants associated with the equations.
DataClass, DimensionalUnits, ReferenceState, and FlowEquationSet have special function in the CGNS hierarchy. They are globally applicable throughout the database, but their precedence may be superseded by local entities (e.g., within a given zone). The scope of these entities and the rules for determining precedence are treated in the section on Precedence Rules and Scope Within the Hierarchy.
Globally relevant convergence history information is contained in GlobalConvergenceHistory. This convergence information includes total configuration forces, moments, and global residual and solution-change norms taken over all the zones.
Miscellaneous global data may be contained in the IntegralData_t list. Candidates for inclusion here are global forces and moments.
The Family_t data structure is used to record geometry reference data.
It may also include boundary conditions linked to geometry patches. For the purpose of defining material properties, families may also be defined for groups of elements.
The family-mesh association is defined under the Zone_t, the ZoneSubRegion_t and BC_t data structures by specifying the family name corresponding to a zone or a boundary patch. The familyname can refer to a Family_t defined in a CGNSBase_t other than the referring Zone_t, the ZoneSubRegion_t or BC_t.
In this case, the actual name of the Family_t has to be prefixed by the CGNSBase_t name.
The pattern is then BaseName/FamilyName, only one single / character is allowed, and neither of BaseName nor FamilyName should be empty. This Family_t node can be a direct child of the CGNSBase_t or a child of another Family_t.
The actual family name has the pattern /<CGNSBase_t>/<FamilyName1>/<FamilyName2>/.../<FamilyNameN>.
The family-mesh association is defined under the Zone_t, ZoneSubRegion_t and BC_t data structures by specifying the family name corresponding to a zone, a zone sub-region or a boundary patch in a FamilyName_t node. If the value of the FamilyName_t node does not have a / character in it, then the name refers to a family being a direct child of its CGNS base. Otherwise, if this value has at least one / in it, the pattern /<CGNSBase_t>/<FamilyName1>/<FamilyName2>/.../<FamilyNameN> is mandatory.
The UserDefinedData_t data structure allows arbitrary user-defined data to be stored in Descriptor_t and DataArray_t children without the restrictions or implicit meanings imposed on these node types at other node locations.
Zone_t¶The Zone_t structure contains all information pertinent to an individual zone. This information includes the zone type, the number of cells and vertices making up the grid in that zone, the physical coordinates of the grid vertices, grid motion information, the family, the flow solution, zone interface connectivity, boundary conditions, and zonal convergence history data. Zonal data may be recorded at multiple time steps or iterations. In addition, this structure contains a reference state, a set of flow equations and dimensional units that are all unique to the zone. For unstructured zones, the element connectivity may also be recorded.
ZoneType_t := Enumeration(
ZoneTypeNull,
ZoneTypeUserDefined,
Structured,
Unstructured ) ;
Zone_t< int CellDimension, int PhysicalDimension > :=
{
List( Descriptor_t Descriptor1 ... DescriptorN ) ; (o)
ZoneType_t ZoneType ; (r)
int[IndexDimension] VertexSize ; (r)
int[IndexDimension] CellSize ; (r)
int[IndexDimension] VertexSizeBoundary ; (o/d)
List( GridCoordinates_t<IndexDimension, VertexSize>
GridCoordinates MovedGrid1 ... MovedGridN ) ; (o)
List( Elements_t Elements1 ... ElementsN ) ; (o)
List( RigidGridMotion_t RigidGridMotion1 ... RigidGridMotionN ) ; (o)
List( ArbitraryGridMotion_t<IndexDimension, VertexSize, CellSize>
ArbitraryGridMotion1 ... ArbitraryGridMotionN ) ; (o)
FamilyName_t FamilyName ; (o)
List( AdditionalFamilyName_t AddFamilyName1 ... AddFamilyNameN ) ; (o)
List( FlowSolution_t<CellDimension, IndexDimension, VertexSize, CellSize>
FlowSolution1 ... FlowSolutionN ) ; (o)
List( DiscreteData_t<CellDimension, IndexDimension, VertexSize, CellSize>
DiscreteData1 ... DiscreteDataN ) ; (o)
List( IntegralData_t IntegralData1 ... IntegralDataN ) ; (o)
List( ZoneGridConnectivity_t<IndexDimension, CellDimension>
ZoneGridConnectivity1 ... ZoneGridConnectivityN ) ; (o)
List( ZoneSubRegion_t<IndexDimension, VertexSize, CellSize>
ZoneSubRegion1 ... ZoneSubRegionN ) ; (o)
ZoneBC_t<CellDimension, IndexDimension, PhysicalDimension> ZoneBC ;(o)
ZoneIterativeData_t<NumberOfSteps> ZoneIterativeData ; (o)
ReferenceState_t ReferenceState ; (o)
RotatingCoordinates_t RotatingCoordinates ; (o)
DataClass_t DataClass ; (o)
DimensionalUnits_t DimensionalUnits ; (o)
FlowEquationSet_t<CellDimension> FlowEquationSet ; (o)
ConvergenceHistory_t ZoneConvergenceHistory ; (o)
List( UserDefinedData_t UserDefinedData1 ... UserDefinedDataN ) ; (o)
int Ordinal ; (o)
} ;
Note
Default names for the Descriptor_t, Elements_t, FlowSolution_t, DiscreteData_t, IntegralData_t, and UserDefinedData_t lists are as shown; users may choose other legitimate names. Legitimate names must be unique within a given instance of Zone_t and shall not include the names DataClass, DimensionalUnits, FamilyName, FlowEquationSet, GridCoordinates, Ordinal, ReferenceState, RotatingCoordinates, ZoneBC, ZoneConvergenceHistory, ZoneGridConnectivity, ZoneIterativeData, or ZoneType.
The original grid coordinates should have the name GridCoordinates. Default names for the remaining entities in the GridCoordinates_t list are as shown; users may choose other legitimate names, subject to the restrictions listed in the previous note.
ZoneType, VertexSize, and CellSize are the only required fields within the Zone_t structure.
Zone_t requires the parameters CellDimension and PhysicalDimension. CellDimension, along with the type of zone, determines IndexDimension; if the zone type is Unstructured, IndexDimension = 1, and if the zone type is Structured, IndexDimension = CellDimension. These three structure parameters identify the dimensionality of the grid-size arrays. One or more of them are passed on to the grid coordinates, flow solution, interface connectivity, boundary condition and flow-equation description structures.
VertexSize is the number of vertices in each index direction, and CellSize is the number of cells in each direction. For example, for structured grids in 3-D, CellSize = VertexSize - [1,1,1], and for unstructured grids in 3-D, CellSize is simply the total number of 3-D cells. VertexSize is the number of vertices defining “the grid” or the domain (i.e., without rind points); CellSize is the number of cells on the interior of the domain. These two grid-size arrays are passed onto the grid-coordinate, flow-solution and discrete-data substructures.
If the nodes are sorted between internal nodes and boundary nodes, then the optional parameter VertexSizeBoundary must be set equal to the number of boundary nodes. If the nodes are sorted, the grid coordinate vector must first include the boundary nodes, followed by the internal nodes. By default, VertexSizeBoundary equals zero, meaning that the nodes are unsorted. This option is only useful for unstructured zones. For structured zones, VertexSizeBoundary always equals 0 in all index directions.
The GridCoordinates_t structure defines “the grid”; it contains the physical coordinates of the grid vertices, and may optionally contain physical coordinates of rind or ghost points. The original grid is contained in GridCoordinates. Additional GridCoordinates_t data structures are allowed, to store the grid at multiple time steps or iterations.
When the grid nodes are sorted, the DataArray_t in GridCoordinates_t lists first the data for the boundary nodes, then the data for the internal nodes.
The Elements_t data structure contains unstructured elements data such as connectivity, element type, parent elements, etc.
The RigidGridMotion_t and ArbitraryGridMotion_t data structures contain information defining rigid and arbitrary (i.e., deforming) grid motion.
FamilyName identifies to which family a zone belongs. Families may be used to define material properties. Where multiple families are desired, AdditionalFamilyName nodes may be used to specify them. Both FamilyName and AdditionalFamilyName should refer to a CGNSBase_t level Family_t, in the parent base of the zone or in another sibbling base (see Base Level Families).
Flow-solution quantities are contained in the list of FlowSolution_t structures. Each instance of the FlowSolution_t structure is only allowed to contain data at a single grid location (vertices, cell-centers, etc.); multiple FlowSolution_t structures are provided to store flow-solution data at different grid locations, to record different solutions at the same grid location, or to store solutions at multiple time steps or iterations. These structures may optionally contain solution data defined at rind points.
Miscellaneous discrete field data is contained in the list of DiscreteData_t structures. Candidate information includes residuals, fluxes and other related discrete data that is considered auxiliary to the flow solution. Likewise, miscellaneous zone-specific global data, other than reference-state data and convergence history information, is contained in the list of IntegralData_t structures. It is envisioned that these structures will be seldom used in practice but are provided nonetheless.
The ZoneSubRegion_t node allows flowfield or other information to be specified over a subset of the entire zone.
For unstructured zones only, the node-based DataArray_t vectors (GridLocation = Vertex) in FlowSolution_t or DiscreteData_t must follow exactly the same ordering as the GridCoordinates vector. If the nodes are sorted (VertexSizeBoundary is non-zero), the data on the boundary nodes must be listed first, followed by the data on the internal nodes.
Note that the order in which the node-based data are recorded must follow exactly the node ordering in GridCoordinates_t, to be able to associate the data to the correct nodes.
For element-based data (GridLocation = CellCenter), the FlowSolution_t or DiscreteData_t data arrays must list the data values for each element, in the same order as the elements are listed in ElementConnectivity.
All interface connectivity information, including identification of overset-grid holes, for a given zone is contained in ZoneGridConnectivity.
All boundary condition information pertaining to a zone is contained in ZoneBC_t.
The ZoneIterativeData_t data structure may be used to record pointers to zonal data at multiple time steps or iterations.
Reference-state data specific to an individual zone is contained in the ReferenceState structure.
RotatingCoordinates may be used to specify the rotation center and rotation rate vector of a rotating coordinate system.
DataClass defines the zonal default for the class of data contained in the zone and its substructures. If a zone contains dimensional data, DimensionalUnits may be used to describe the system of dimensional units employed.
If a set of flow equations are specific to a given zone, these may be described in FlowEquationSet. For example, if a single zone within the domain is inviscid, whereas all other are turbulent, then this zone-specific equation set could be used to describe the special zone.
DataClass, DimensionalUnits, ReferenceState, and FlowEquationSet have special function in the hierarchy. They are applicable throughout a given zone, but their precedence may be superseded by local entities contained in the zone’s substructures. If any of these entities are present within a given instance of Zone_t, they take precedence over the corresponding global entities contained in database’s CGNSBase_t entity. These precedence rules are further discussed in the section on Precedence Rules and Scope Within the Hierarchy
Convergence history information applicable to the zone is contained in ZoneConvergenceHistory; this includes residual and solution-change norms.
The UserDefinedData_t data structure allows arbitrary user-defined data to be stored in Descriptor_t and DataArray_t children without the restrictions or implicit meanings imposed on these node types at other node locations.
Ordinal is user-defined and has no restrictions on the values that it can contain. It is included for backward compatibility to assist implementation of the CGNS system into applications whose I/O depends heavily on the numbering of zones. Since there are no restrictions on the values contained in Ordinal (or that Ordinal is even provided), there is no guarantee that the zones in an existing CGNS database will have sequential values from 1 to N without holes or repetitions. Use of Ordinal is discouraged and is on a user-beware basis.
The dependence of a structure entity’s information on data contained at higher levels of the hierarchy is typically explicitly expressed through structure parameters. For example, all arrays within Zone_t depend on the dimensionality of the computational grid. This dimensionality is passed down to a Zone_t entity through a structure parameter in the definition of Zone_t.
We have established an alternate dependency for a limited number of entities that is not explicitly stated in the structure type definitions. These special situations include entities for describing data class, system of dimensional units, reference states, flow equation sets and particle equation sets. At each level of the hierarchy (where appropriate), entities for describing this information are defined, and if present they take precedence over all corresponding information existing at higher levels of the CGNS hierarchy. Essentially, we have established globally applicable data with provisions for recursively overriding it with local data.
Specifically, the entities that follow this alternate dependency are:
FlowEquationSet_tFlowEquationSet,
ParticleEquationSet_tParticleEquationSet,
ReferenceState_tReferenceState,
DataClass_tDataClass,
DimensionalUnits_tDimensionalUnits.
FlowEquationSet contains a description of the governing flow equations;
ParticleEquationSet contains a description of the governing particle equations;
ReferenceState describes a set of reference state flow conditions;
DataClass defines the class of data (e.g., dimensional or nondimensional);
and DimensionalUnits specifies the system of units used for dimensional data.
All of these entities may be defined within the highest level CGNSBase_t structure, and if present in a given database, establish globally applicable information; these may also be considered to be global defaults. Each of these four entities may also be defined within the Zone_t or ParticleZone_t structure (FlowEquationSet may not be defined in the ParticleZone_t and ParticleEquationSet may not be defined in Zone_t). If present in a given instance of Zone_t or ParticleZone_t, they supersede the global data and establish new defaults that apply only within that zone or particle zone.
For example, if a different set of flow equations is solved within a given zone than is solved in the rest of the flowfield, then this can be conveyed through FlowEquationSet. In this case, one FlowEquationSet entity would be placed within CGNSBase_t to state the globally applicable flow equations, and a second FlowEquationSet entity would be placed within the given zone (within its instance of Zone_t); this second FlowEquationSet entity supersedes the first only within the given zone.
In addition to its presence in CGNSBase_t and Zone_t, ReferenceState may also be defined within the boundary-condition structure types to establish reference states applicable to one or more boundary-condition patches. Actually, ReferenceState entities can be defined at several levels of the boundary-condition hierarchy to allow flexibility in setting the appropriate reference state conditions.
DataClass and DimensionalUnits are used within entities describing data arrays. They classify the data and specify its system of units if dimensional. If these entities are absent from a particular instance of DataArray_t, the information is derived from appropriate global data. DataClass and DimensionalUnits are also declared in all intermediate structure types that directly or indirectly contain DataArray_t entities. Examples include GridCoordinates_t, FlowSolution_t, BC_t, and ReferenceState_t. The same precedence rules apply - lower-level entities supersede higher-level entities.
It is envisioned that in practice, the use of globally applicable data will be the norm rather than the exception. It provides a measure of economy throughout the CGNS database in many situations. For example, when creating a database where the vast majority of data arrays are dimensional and use a consistent set of units, DataClass and DimensionalUnits can be set appropriately at the CGNSBase_t level and thereafter omitted when outputting data.
With a multiple-bases CGNS tree, some nodes defined at the base level may lead to an inconsistent CGNS set of data. In that case it is up to the application using the CGNS tree to define its own understanding of the data. In particular, the following nodes are not required to be the same in all bases of a CGNS tree, thus inter-base references may lead to inconsistency:
CellDimensionandPhysicalDimension
ReferenceState
Axisymmetry
RotatingCoordinates
Gravity
SimulationType
DataClass
DimensionalUnits
FlowEquationSet
ParticleEquationSet
Family_t
The application has to take into account the corresponding base definition for the referred-to node.