This section contains miscellaneous structure types for describing reference states, convergence history, discrete field data, integral or global data, families, and user-defined data.
ReferenceState_t describes a reference state, which is a list of geometric or flow-state quantities defined at a common location or condition. Examples of typical reference states associated with CFD calculations are freestream, plenum, stagnation, inlet and exit. Note that providing a ReferenceState description is particularly important if items elsewhere in the CGNS database are NormalizedByUnknownDimensional.
ReferenceState_t :=
{
Descriptor_t ReferenceStateDescription ; (o)
List( Descriptor_t Descriptor1 ... DescriptorN ) ; (o)
List( DataArray_t<DataType, 1, 1> DataArray1 ... DataArrayN ) ; (o)
DataClass_t DataClass ; (o)
DimensionalUnits_t DimensionalUnits ; (o)
List( UserDefinedData_t UserDefinedData1 ... UserDefinedDataN ) ; (o)
} ;
Notes
Data-name identifiers associated with ReferenceState are shown in
the table below.
| Data-Name Identifier | Description | Units | ||
|---|---|---|---|---|
| Mach | Mach number, M = q/c | - | ||
| Mach_Velocity | Velocity scale, q | L/T | ||
| Mach_VelocitySound | Speed of sound scale, c | L/T | ||
| Reynolds | Reynolds number, Re = VLR / ν | - | ||
| Reynolds_Velocity | Velocity scale, V | L/T | ||
| Reynolds_Length | Length scale, LR | L | ||
| Reynolds_ViscosityKinematic | Kinematic viscosity scale, ν | L2/T | ||
| LengthReference | Reference length, L | L | ||
In addition, any flowfield quantities (such as Density, Pressure, etc.) can be included in the ReferenceState.
The reference length L (LengthReference) may be necessary for NormalizedByUnknownDimensional databases, to define the length scale used for nondimensionalizations. It may be the same or different from the Reynolds_Length used to define the Reynolds number.
Because of different definitions for angle of attack and angle of yaw, these quantities are not explicitly defined in the SIDS. Instead, the user can unambigouosly denote the freestream velocity vector direction by giving VelocityX, VelocityY, and VelocityZ in ReferenceState, (with the reference state denoting the freestream).
Care should be taken when defining the reference state quantities to ensure consistency. (See the discussion in the section on Nondimensional Data Normalized by Unknown Dimensional Quantities.) For example, if velocity, length, and time are all defined, then the velocity stored should be length/time. If consistency is not followed, different applications could interpret the resulting data in different ways.
DataClass defines the default for the class of data contained in the reference state. If any reference state quantities are dimensional, DimensionalUnits may be used to describe the system of dimensional units employed. If present, these two entities take precedence over all corresponding entities at higher levels of the hierarchy, following the standard precedence rules.
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.
We recommend using the ReferenceStateDescription entity to document the flow conditions. The format of the documentation is currently unregulated.
An example is presented in this section of a reference state entity that contains dimensional data. An additional example of a nondimensional reference state is provided in the Structured Two-Zone Flat Plate Example.
A freestream reference state where all data quantities are dimensional. Standard atmospheric conditions at sea level are assumed for static quantities, and all stagnation variables are obtained using the isentropic relations. The flow velocity is 200 m/s aligned with the x-axis. Dimensional units of kilograms, meters, and seconds are used. The data class and system of units are specified at the ReferenceState_t level rather than attaching this information directly to the DataArray_t entities for each reference quantity. Data-name identifiers are provided in the section Conventions for Data-Name Identifiers.
ReferenceState_t ReferenceState =
{{
Descriptor_t ReferenceStateDescription =
{{
Data(char, 1, 45) = "Freestream at standard atmospheric conditions" ;
}} ;
DataClass_t DataClass = Dimensional ;
DimensionalUnits_t DimensionalUnits =
{{
MassUnits = Kilogram ;
LengthUnits = Meter ;
TimeUnits = Second ;
TemperatureUnits = Kelvin ;
AngleUnits = Radian ;
}} ;
DataArray_t<real, 1, 1> VelocityX =
{{
Data(real, 1, 1) = 200. ;
}} ;
DataArray_t<real, 1, 1> VelocityY = {{ 0. }} ;
DataArray_t<real, 1, 1> VelocityZ = {{ 0. }} ;
DataArray_t<real, 1, 1> Pressure = {{ 1.0132E+05 }} ;
DataArray_t<real, 1, 1> Density = {{ 1.226 }} ;
DataArray_t<real, 1, 1> Temperature = {{ 288.15 }} ;
DataArray_t<real, 1, 1> VelocitySound = {{ 340. }} ;
DataArray_t<real, 1, 1> ViscosityMolecular = {{ 1.780E-05 }} ;
DataArray_t<real, 1, 1> PressureStagnation = {{ 1.2806E+05 }} ;
DataArray_t<real, 1, 1> DensityStagnation = {{ 1.449 }} ;
DataArray_t<real, 1, 1> TemperatureStagnation = {{ 308.09 }} ;
DataArray_t<real, 1, 1> VelocitySoundStagnation = {{ 351.6 }} ;
DataArray_t<real, 1, 1> PressureDynamic = {{ 0.2542E+05 }} ;
}} ;
Note that all DataArray_t
entities except VelocityX have been abbreviated.
Flow solver convergence history information is described by the ConvergenceHistory_t structure. This structure contains the number of iterations and a list of data arrays containing convergence information at each iteration.
ConvergenceHistory_t :=
{
Descriptor_t NormDefinitions ; (o)
List( Descriptor_t Descriptor1 ... DescriptorN ) ; (o)
int Iterations ; (r)
List( DataArray_t<DataType, 1, Iterations>
DataArray1 ... DataArrayN ) ; (o)
DataClass_t DataClass ; (o)
DimensionalUnits_t DimensionalUnits ; (o)
List( UserDefinedData_t UserDefinedData1 ... UserDefinedDataN ) ; (o)
} ;
Notes
Iterations identifies the number of iterations for which convergence information is recorded. This value is also passed into each of the DataArray_t entities, defining the length of the data arrays.
DataClass defines the default for the class of data contained in the convergence history. If any convergence-history data is dimensional, DimensionalUnits may be used to describe the system of dimensional units employed. If present, these two entities take precedence over all corresponding entities at higher levels of the hierarchy, following the standard precedence rules.
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.
Measures used to record convergence vary greatly among current flow-solver implementations. Convergence information typically includes global forces, norms of equation residuals, and norms of solution changes. Attempts to systematically define a set of convergence measures within the CGNS project have been futile. For global parameters, such as forces and moments, a set of standardized data-array identifiers is used. For equations residuals and solution changes, no such standard list exists. It is suggested that data-array identifiers for norms of equations residuals begin with RSD, and those for solution changes begin with CHG. For example, RSDMassRMS could be used for the L2-norm (RMS) of mass conservation residuals. It is also strongly recommended that NormDefinitions be utilized to describe the convergence information recorded in the data arrays. The format used to describe the convergence norms in NormDefinitions is currently unregulated.
DiscreteData_t provides a description of generic discrete data (i.e., data defined on a computational grid); it is identical to FlowSolution_t except for its type name. This structure can be used to store field data, such as fluxes or equation residuals, that is not typically considered part of the flow solution. DiscreteData_t contains a list for data arrays, identification of grid location, and a mechanism for identifying rind-point data included in the data arrays. All data contained within this structure must be defined at the same grid location and have the same amount of rind-point data.
DiscreteData_t< int CellDimension, int IndexDimension,
int VertexSize[IndexDimension],
int CellSize[IndexDimension] > :=
{
List( Descriptor_t Descriptor1 ... DescriptorN ) ; (o)
GridLocation_t GridLocation ; (o/d)
IndexRange<IndexDimension> PointRange ; (o)
IndexArray<IndexDimension, ListLength[], int> PointList ; (o)
Rind_t<IndexDimension> Rind ; (o/d)
List( DataArray_t<DataType, IndexDimension, DataSize[]>
DataArray1 ... DataArrayN ) ; (o)
DataClass_t DataClass ; (o)
DimensionalUnits_t DimensionalUnits ; (o)
List( UserDefinedData_t UserDefinedData1 ... UserDefinedDataN ) ; (o)
} ;
Notes
DiscreteData_t requires four structure parameters; CellDimension identifies the dimensionality of cells or elements, IndexDimension identifies the dimensionality of the grid size arrays, and VertexSize and CellSize are the number of core vertices and cells, respectively, in each index direction, excluding rind points. For structured zones, core vertices and cells begin at [1,1,1] (in 3-D) and end at VertexSize and CellSize, respectively. For unstructured zones, IndexDimension is always 1.
The arrays of discrete data are stored in the list of DataArray_t entities. The field GridLocation specifies the location of the data with respect to the grid; if absent, the data is assumed to coincide with grid vertices (i.e., GridLocation = Vertex). All data within a given instance of DiscreteData_t must reside at the same grid location.
For structured grids, the value of GridLocation alone specifies the location and indexing of the discrete. Vertices are explicity indexed. Cell centers and face centers are indexed using the minimum of the connecting vertex indices, as described in the section Structured Grid Notation and Indexing Conventions.
For unstructured grids, the value of GridLocation alone specifies location and indexing of discrete data only for vertex and cell-centered data. The reason for this is that element-based grid connectivity provided in the Elements_t data structures explicitly indexes only vertices and cells. For data stored at alternate grid locations (e.g., edges), additional connectivity information is needed. This is provided by the optional fields PointRange and PointList; these refer to vertices, edges, faces or cell centers, depending on the values of CellDimension and GridLocation. The following table shows these relations.
| CellDimension | GridLocation | |||
|---|---|---|---|---|
| Vertex | EdgeCenter | *FaceCenter | CellCenter | |
| 1 | vertices | - | - | cells (line elements) |
| 2 | vertices | edges | - | cells (area elements) |
| 3 | vertices | edges | faces | cells (volume elements) |
Note: In the table, *FaceCenter stands for the possible types: IFaceCenter, JFaceCenter, KFaceCenter, or FaceCenter.
Although intended for edge or face-based discrete data for unstructured grids, the fields PointRange/List may also be used to (redundantly) index vertex and cell-centered data. In all cases, indexing of flow solution data corresponds to the element numbering as defined in the Elements_t data structures.
Rind is an optional field that indicates the number of rind planes (for structured grids) or rind points or elements (for unstructured grids) included in the data. Its purpose and function are identical to those described for the GridCoordinates_t structure. Note, however, that the Rind in this structure is independent of the Rind contained in GridCoordinates_t. They are not required to contain the same number of rind planes or elements. Also, the location of any flow-solution rind points is assumed to be consistent with the location of the core flow solution points (e.g., if GridLocation = CellCenter, rind points are assumed to be located at fictitious cell centers).
DataClass defines the default for the class of data contained in the DataArray_t entities. For dimensional data, DimensionalUnits may be used to describe the system of dimensional units employed. If present, these two entities take precedence over all corresponding entities at higher levels of the hierarchy, following the standard precedence rules.
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.
DiscreteData_t requires the structure function ListLength, which is used to specify the number of entities (e.g. vertices) corresponding to a given PointRange or PointList. If PointRange is specified, then ListLength is obtained from the number of points (inclusive) between the beginning and ending indices of PointRange. If PointList is specified, then ListLength is the number of indices in the list of points. In this situation, ListLength becomes a user input along with the indices of the list PointList. By user we mean the application code that is generating the CGNS database.
The function DataSize[] is the size of discrete-data arrays. It is identical to the function DataSize[] defined for FlowSolution_t.
IntegralData_t provides a description of generic global or integral data that may be associated with a particular zone or an entire database. In contrast to DiscreteData_t, integral data is not associated with any specific field location.
IntegralData_t :=
{
List( Descriptor_t Descriptor1 ... DescriptorN ) ; (o)
List( DataArray_t<DataType, 1, 1> DataArray1 ... DataArrayN ) ; (o)
DataClass_t DataClass ; (o)
DimensionalUnits_t DimensionalUnits ; (o)
List( UserDefinedData_t UserDefinedData1 ... UserDefinedDataN ) ; (o)
} ;
Notes
DataClass defines the default class for data contained in the DataArray_t entities. For dimensional data, DimensionalUnits may be used to describe the system of units employed. If present, these two entities take precedence over all corresponding entities at higher levels of the hierarchy, following the standard precedence rules.
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.
Geometric associations need to be set through one layer of indirection. That is, rather than setting the geometry data for each mesh entity (nodes, edges, and faces), they are associated to intermediate objects. The intermediate objects are in turn linked to nodal regions of the computational mesh. We define a CFD family as this intermediate object. This layer of indirection is necessary since there is rarely a 1-to-1 connection between mesh regions and geometric entities.
The Family_t data structure holds the CFD family data. Each mesh surface is linked to the geometric entities of CAD databases by a name attribute. This attribute corresponds to a family of 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. A Family_t data structure may be included in the CGNSBase_t structure for each CFD family of the model.
A hierarchy of Family_t nodes can be build by adding a Family_t node as child of an existing Family_t node. One can mimic an existing CAD hierarchy or add another hierarchy for special application purpose.
In case of a tree of Family_t, the actual reference to a family in the tree should follow the pattern as described in Base Level Families.
The Family_t structure contains all information pertinent to a CFD family. This information includes the name attribute or family name, the boundary conditions applicable to these mesh regions, and the referencing to the CAD databases.
Family_t :=
{
List( Descriptor_t Descriptor1 ... DescriptorN ) ; (o)
FamilyBC_t FamilyBC ; (o)
List( GeometryReference_t
GeometryReference1 ... GeometryReferenceN ) ; (o)
RotatingCoordinates_t RotatingCoordinates ; (o)
List( Family_t Family1 ... FamilyN ) ; (o)
List( FamilyName_t FamilyName1 ... FamilyNameN ) ; (o)
List( UserDefinedData_t UserDefinedData1 ... UserDefinedDataN ) ; (o)
int Ordinal ; (o)
} ;
Notes
Rotation of the CFD family may be defined using the RotatingCoordinates_t data structure.
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.
The standard interface data structure identifies the CAD systems used to generate the geometry, the CAD files where the geometry is stored, and the geometric entities corresponding to the family. The GeometryReference_t structures contain all the information necessary to associate a CFD family to the CAD databases. For each GeometryReference_t structure, the CAD format is recorded in GeometryFormat, and the CAD file in GeometryFile. The geometry entity or entities within this CAD file that correspond to the family are recorded under the GeometryEntity_t nodes.
GeometryReference_t :=
{
List( Descriptor_t Descriptor1 ... DescriptorN ) ; (o)
GeometryFormat_t GeometryFormat ; (r)
GeometryFile_t GeometryFile ; (r)
List (GeometryEntity_t GeometryEntity1 ... GeometryEntityN) ; (o/d)
List( UserDefinedData_t UserDefinedData1 ... UserDefinedDataN ) ; (o)
} ;
The GeometryFormat is an enumeration type that identifies the CAD system used to generate the geometry.
GeometryFormat_t := Enumeration(
GeometryFormatNull,
GeometryFormatUserDefined,
NASA-IGES,
SDRC,
Unigraphics,
ProEngineer,
ICEM-CFD ) ;
Notes
One of the main advantages of the concept of a layer of indirection (called a family here) is that the mesh density and the geometric entities may be modified without altering the association between nodes and intermediate objects, or between intermediate objects and geometric entities. This is very beneficial when handling boundary conditions and properties. Instead of setting boundary conditions directly on mesh entities, or on CAD entities, they may be associated to the intermediate objects. Since these intermediate objects are stable in the sense that they are not subject to mesh or geometric variations, the boundary conditions do not need to be redefined each time the model is modified. Using the concept of indirection, the boundary conditions and property settings are made independent of operations such as geometric changes, modification of mesh topology (i.e., splitting into zones), mesh refinement and coarsening, etc.
The FamilyBC_t data structure contains the boundary condition type. It is envisioned that it will be extended to hold both material and volume properties as well.
FamilyBC_t :=
{
BCType_t BCType; (r)
List( FamilyBCDataSet_t<ListLength> BCDataSet1 ... BCDataSetN ) ; (o)
} ;
Notes
BCType specifies the boundary-condition type, which gives general information on the boundary-condition equations to be enforced. Boundary conditions are to be applied at the locations specified by the BC_t structure(s) associated with the CFD family.
The FamilyBC_t structure provides for a list of boundary-condition data sets. In general, the proper FamilyBCDataSet_t instance to impose on the CFD family is determined by the BCType association table. The mechanics of determining the proper data set to impose is described in the section Matching Boundary Condition Data Sets.
For a few boundary conditions, such as a symmetry plane or polar singularity, the value of BCType completely describes the equations to impose, and no instances of FamilyBCDataSet_t are needed. For "simple" boundary conditions, where a single set of Dirichlet and/or Neumann data is applied, a single FamilyBCDataSet_t will likely appear (although this is not a requirement). For "compound" boundary conditions, where the equations to impose are dependent on local flow conditions, several instances of FamilyBCDataSet_t will likely appear; the procedure for choosing the proper data set is more complex as described in the section Matching Boundary Condition Data Sets.
FamilyBCDataSet_t contains Dirichlet and Neumann data for a single set of boundary-condition equations. Its intended use is for simple boundary-condition types, where the equations imposed do not depend on local flow conditions.
FamilyBCDataSet_t :=
{
List( Descriptor_t Descriptor1 ... DescriptorN ) ; (o)
BCTypeSimple_t BCTypeSimple ; (r)
BCData_t<1> DirichletData ; (o)
BCData_t<1> NeumannData ; (o)
ReferenceState_t ReferenceState ; (o)
DataClass_t DataClass ; (o)
DimensionalUnits_t DimensionalUnits ; (o)
List( UserDefinedData_t UserDefinedData1 ... UserDefinedDataN ) ; (o)
} ;
Notes
BCTypeSimple specifies the boundary-condition type, which gives general information on the boundary-condition equations to be enforced. BCTypeSimple is also used for matching boundary condition data sets as discussed in the section Matching Boundary Condition Data Sets.
Boundary-condition data is separated by equation type into Dirichlet and Neumann conditions. Dirichlet boundary conditions impose the value of the given variables, whereas Neumann boundary conditions impose the normal derivative of the given variables. The mechanics of specifying Dirichlet and Neumann data for boundary conditions is covered in section Boundary Condition Specification Data.
The substructures DirichletData and NeumannData contain boundary-condition data defined as globally constant over the family.
Reference quantities applicable to the set of boundary-condition data are contained in the ReferenceState structure. DataClass defines the default for the class of data contained in the boundary condition data. If the boundary conditions contain dimensional data, DimensionalUnits may be used to describe the system of dimensional units employed. If present, these three entities take precedence over all corresponding entities at higher levels of the hierarchy, following the standard precedence rules.
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.
Note that FamilyBCDataSet_t is similar to the data structure BCDataSet_t. The primary difference is that FamilyBCDataSet_t only allows for globally constant Dirichlet and Neumann data.
Since the needs of all CGNS users cannot be anticipated, UserDefinedData_t provides 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.
UserDefinedData_t :=
{
List( Descriptor_t Descriptor1 ... DescriptorN ) ; (o)
GridLocation_t GridLocation ; (o/d)
IndexRange_t<IndexDimension> PointRange ; (o)
IndexArray_t<IndexDimension, ListLength, int> PointList ; (o)
List( DataArray_t<> DataArray1 ... DataArrayN ) ; (o)
DataClass_t DataClass ; (o)
DimensionalUnits_t DimensionalUnits ; (o)
FamilyName_t FamilyName ; (o)
List( AdditionalFamilyName_t AddFamilyName1 ... AddFamilyNameN ) ; (o)
List( UserDefinedData_t UserDefinedData1 ... UserDefinedDataN ) ; (o)
int Ordinal ; (o)
} ;
Notes
The Gravity_t data structure may be used to define the gravitational vector.
Gravity_t :=
{
List( Descriptor_t Descriptor1 ... DescriptorN ) ; (o)
DataArray_t<real, 1, PhysicalDimension> GravityVector ; (r)
DataClass_t DataClass ; (o)
DimensionalUnits_t DimensionalUnits ; (o)
List( UserDefinedData_t UserDefinedData1 ... UserDefinedDataN ) ; (o)
} ;
Notes
The only required field under the Gravity_t data structure is GravityVector, which contains the components of the gravity vector in the coordinate system being used.
DataClass defines the default class for data contained in the DataArray_t entity. For dimensional data, DimensionalUnits may be used to describe the system of units employed. If present, these two entities take precedence over the corresponding entities at higher levels of the CGNS hierarchy, following the standard precedence rules.
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.