Guideline for PLOT3D Variables

• Dimensional Data
• NormalizedByDimensional Data
• NormalizedByUnknownDimensional Data
• Notes

The broad scope of CGNS allows users to essentially put anything into a CGNS file. While this is useful from the perspective of extensibility, it also makes it more difficult to read someone else's CGNS file without an elaborate array of checks and translators. This is true not only because of the many choices of variables to output, but also because CGNS allows many forms of dimensional and nondimensional data.

Many people in the CFD community currently output structured-grids and corresponding flow field data in PLOT3D format [Walatka, P. P., Buning, P. G., Pierce, L., Elson, P. A., "PLOT3D User's Guide," NASA TM 101067, March 1990], particularly for use in postprocessing visualization programs. It has, in some sense, become a de facto standard for sharing structured CFD data. Because this format is so widely used, we give a guideline in this section for outputting and reading this type of data in a CGNS file. If you follow this guideline, then it is more likely that other users will be able to easily read and interpret your CGNS files.

The PLOT3D standard grid variables are (in 3-D) x, y, and z. These coordinates may be dimensional or nondimensional. To follow this guideline, the three coordinates CoordinateX, CoordinateY, and CoordinateZ (either dimensional or nondimensional) must be given. There also may be "iblank" information, associated with overset grids. If used, the list of overset holes is stored under OversetHoles_t nodes. This section does not cover the various dimensionalization and nondimensionalization options for the grid coordinates. By and large, from the point of view of portability, the issue of units and/or nondimensionalization for grid coordinates is not as crucial as it is for the "Q" variables, which is covered in great detail below. However, one should follow the SIDS standard and appropriately define within the CGNS file the grid's units or nondimensionalizations used.

The PLOT3D standard "Q" variables are (in 3-D):

	ρ / ρref		=		nondimensional density
	ρu / (ρref aref)		=		nondimensional x-momentum
	ρv / (ρref aref)		=		nondimensional y-momentum
	ρw / (ρref aref)		=		nondimensional z-momentum
	ρe0 / (ρref a2ref)		=		nondimensional total energy per unit volume

where a is the speed of sound and ref indicates a reference state. Standard PLOT3D Q files also specify a reference Mach number, Reynolds number, angle of attack, and time value. For the purposes of this discussion, the time value will not be addressed. CGNS does have the capability for storing time-accurate data if needed, but time-accurate data is not covered in this PLOT3D guideline. We include below the CGNS convention for storing Mach number, Reynolds number, and (indirectly) angle of attack.

Each of the 5 flow field variables above has a standard name, defined in the SIDS. They are, respectively: Density, MomentumX, MomentumY, MomentumZ, and EnergyStagnationDensity. To follow this guideline, these are the 5 variables that should be output to your CGNS file (in 3-D), and are also the ones that you should expect to read, given someone else's CGNS file, if they are following this guideline.

Multiple bases are allowed in CGNS, but, to further enhance portability of PLOT3D-like datasets, only one CGNSBase_t node is recommended under this guideline. In other words, multiple cases (such as different angles of attack) should be stored in separate CGNS files with single bases, rather than in a single file with multiple bases.

The three most common types of data that one may output in a CGNS file are:

   DataClass = Dimensional
   DataClass = NormalizedByDimensional
   DataClass = NormalizedByUnknownDimensional

The first category indicates that the data has dimensional units. The second category indicates that the data has been nondimensionalized by known reference values, which are specified in the CGNS file. The third category indicates that the data is nondimensional, but the reference values are unspecified or unknown. Because CGNS deals with each of these in a slightly different way, we will give the guideline for each of these three classes in separate subsections.

Dimensional Data

To output dimensional data:

1. Under CGNSBase_t, set DataClass = Dimensional.
   
   
2. Under CGNSBase_t, put a ReferenceState; and under ReferenceState, put the dimensional reference values of Density and VelocitySound. Under this guideline, the units of these must be consistent with one another and with the units of Density, MomentumX, MomentumY, MomentumZ, and EnergyStagnationDensity given under FlowSolution (e.g., all MKS units). Also under ReferenceState, put Mach, Reynolds, VelocityX, VelocityY, and VelocityZ.
   
   
3. Under FlowSolution, put the dimensional variables Density, MomentumX, MomentumY, MomentumZ, and EnergyStagnationDensity. Under this guideline, the units of these 5 variables must be consistent with one another and with the units of Density and VelocitySound in ReferenceState.

1. Under ReferenceState (directly under CGNSBase_t), read Density, VelocitySound, Mach, and Reynolds. Also read VelocityX, VelocityY, and VelocityZ if an angle of attack of the reference state is needed.
   
   
2. Under FlowSolution, read Density, MomentumX, MomentumY, MomentumZ, and EnergyStagnationDensity.
   
   
3. To obtain the PLOT3D Q variables, do the following:
   
   

   	ρ / ρref		=		Density / Density(ref)
   	ρu / (ρref aref)		=		MomentumX / (Density(ref) * VelocitySound(ref))
   	ρv / (ρref aref)		=		MomentumY / (Density(ref) * VelocitySound(ref))
   	ρw / (ρref aref)		=		MomentumZ / (Density(ref) * VelocitySound(ref))
   	ρe0 / (ρref a2ref)		=		EnergyStagnationDensity / (Density(ref) * VelocitySound(ref)2)

NormalizedByDimensional Data

To output nondimensional data with known normalizations:

1. Under CGNSBase_t, set DataClass = NormalizedByDimensional.
   
   
2. Under CGNSBase_t, put a ReferenceState; and under ReferenceState, put Mach, Reynolds, VelocityX, VelocityY, and VelocityZ. Then put either:
   
   
   • The dimensional reference values of Density and VelocitySound. Under this guideline, the units of these must be consistent with one another and with the units of the raw (dimensional) data Density, MomentumX, MomentumY, MomentumZ, and EnergyStagnationDensity given under FlowSolution, prior to normalization.
     
     
   • The nondimensional reference values of Density and VelocitySound, along with their corresponding ConversionScale and ConversionOffset values. Under this guideline, the units of the raw (dimensional) Density and VelocitySound, prior to normalization using ConversionScale and ConversionOffset, must be consistent with one another and with the units of the raw (dimensional) data Density, MomentumX, MomentumY, MomentumZ, and EnergyStagnationDensity given under FlowSolution, prior to normalization.
   
   
3. Under FlowSolution, put the nondimensional variables Density, MomentumX, MomentumY, MomentumZ, and EnergyStagnationDensity, along with their corresponding ConversionScale and ConversionOffset values. Under this guideline, the units of the raw (dimensional) variables, prior to normalization using ConversionScale and ConversionOffset, must be consistent with one another and with the units of the raw (dimensional) Density and VelocitySound in ReferenceState.

1. Under ReferenceState (directly under CGNSBase_t), read Density and VelocitySound. Also read their ConversionScale and ConversionOffset values if they are present. Additionally, read Mach and Reynolds. Also read VelocityX, VelocityY, and VelocityZ if an angle of attack of the reference state is needed.
   
   
2. Under FlowSolution, read Density, MomentumX, MomentumY, MomentumZ, and EnergyStagnationDensity. Also read each ConversionScale and ConversionOffset.
   
   
3. To obtain the PLOT3D Q variables, do the following. First, only if they were given as nondimensional quantities (indicated by a ' below), recover the raw (dimensional) reference values of Density and VelocitySound, via:
   
      Density(ref) = Density'(ref)*ConversionScale + ConversionOffset
      VelocitySound(ref) = VelocitySound'(ref)*ConversionScale + ConversionOffset
   
   Then do:
   
   

   	ρ / ρref		=		(Density*ConversionScale + ConversionOffset) / Density(ref)
   	ρu / (ρref aref)		=		(MomentumX*ConversionScale + ConversionOffset) / (Density(ref) * VelocitySound(ref))
   	ρv / (ρref aref)		=		(MomentumY*ConversionScale + ConversionOffset) / (Density(ref) * VelocitySound(ref))
   	ρw / (ρref aref)		=		(MomentumZ*ConversionScale + ConversionOffset) / (Density(ref) * VelocitySound(ref))
   	ρe0 / (ρref a2ref)		=		(EnergyStagnationDensity*ConversionScale + ConversionOffset) / (Density(ref) * VelocitySound(ref)2)

Note that it is possible that the conversion scale and offset for the PLOT3D Q variables may correspond to the reference conditions. This would imply that the variables could be directly output, without the above conversions needed. However, CGNS allows the variables to be normalized by properties independent of the reference conditions, so the above procedure is recommended to avoid ambiguity.

NormalizedByUnknownDimensional Data

To output nondimensional data with unknown normalizations:

1. Under CGNSBase_t, set DataClass = NormalizedByUnknownDimensional.
   
   
2. Under CGNSBase_t, put a ReferenceState; and under ReferenceState, put Density = 1 and VelocitySound = 1. Also, put Mach, Reynolds, VelocityX, VelocityY, and VelocityZ.
   
   
3. Under FlowSolution, put the nondimensional variables Density, MomentumX, MomentumY, MomentumZ, and EnergyStagnationDensity. These must be nondimensionalized as: ρ/ρ_ref, ρu/(ρ_ref a_ref), ρv/(ρ_ref a_ref), ρw/(ρ_ref a_ref), ρe₀/(ρ_ref a²_ref).

1. Check under ReferenceState (directly under CGNSBase_t), to be sure that Density = 1 and VelocitySound = 1. Then, read Mach and Reynolds. Also read VelocityX, VelocityY, and VelocityZ if an angle of attack of the reference state is needed.
   
   
2. Under FlowSolution, read Density, MomentumX, MomentumY, MomentumZ, and EnergyStagnationDensity.

Notes

1. In addition to the flow field variables Density, MomentumX, MomentumY, MomentumZ, and EnergyStagnationDensity (under FlowSolution), you may also output additional variables if desired, but be sure these 5 are present.
   
   
2. Other reference values may also be placed under ReferenceState (for example, LengthReference may be needed to define the reference length associated with the grid coordinates), but the use of Density and VelocitySound is sufficient to define the nondimensionalizations of the PLOT3D Q variables.
   
   
3. The quantities Mach, Reynolds, VelocityX, VelocityY, VelocityZ, Density, and VelocitySound (plus anything else) under ReferenceState must all represent the same reference state of the flow. For external aerodynamics, this is usually taken to be the free stream, but it does not have to be.
   
   
4. The velocity components are used, in the PLOT3D sense, solely to provide an angle of attack of the flow field at the reference state. The definition of angle of attack itself is non-unique in 3-D, so there is therefore no SIDS standard for it. For example, one possible set of angle definitions assumes that the z-direction is "up," and uses:
   
   

   	u		=		V cos β cos α
   	v		=		−V sin β
   	w		=		V cos β sin α

   
   where V = (u² + v² + w²)^1/2, α is angle of attack, and β is angle of sideslip. Thus, an angle of attack can be obtained using α = tan⁻¹(w/u), where u = VelocityX and w = VelocityZ.
   
   
5. When reading someone else's CGNS file, a low-level approach to interpret and/or use it appropriately would be the following. First, check to see that there is only one CGNSBase_t node. (As discussed above, multiple bases are allowed in general, but under this guideline only one base should exist.) Second, insure that the variables CoordinateX, CoordinateY, and CoordinateZ exist under each zone's GridCoordinates_t node, and that the variables Density, MomentumX, MomentumY, MomentumZ, and EnergyStagnationDensity exist under each zone's FlowSolution_t node. (Note: for time-accurate datasets there may be multiple GridCoordinates_t and FlowSolution_t nodes under each zone - see the section on time-dependent data - but this situation is not covered under the current PLOT3D guideline.) Then, search for the following characteristics in the file:
   
   
   • If DataClass = Dimensional, then ReferenceState (directly under CGNSBase_t) must contain Density, VelocitySound, Mach, and Reynolds. VelocityX, VelocityY, and VelocityZ are needed under ReferenceState only if a reference angle of attack is required.
     
     
   • If DataClass = NormalizedByDimensional, then ReferenceState (directly under CGNSBase_t) must contain Density, VelocitySound, Mach, and Reynolds. VelocityX, VelocityY, and VelocityZ are needed under ReferenceState only if a reference angle of attack is required. Furthermore, a ConversionScale and ConversionOffset must exist for each of the 5 flow field variables under FlowSolution. ConversionScale and ConversionOffset may or may not exist for the variables under ReferenceState.
     
     
   • If DataClass = NormalizedByUnknownDimensional, then ReferenceState (directly under CGNSBase_t) must contain Density = 1, VelocitySound = 1, as well as Mach, and Reynolds. VelocityX, VelocityY, and VelocityZ are needed under ReferenceState only if a reference angle of attack is required.
   
   If these conditions are met, then a low-level reader could assume that the guidelines outlined in the above subsections were followed, and the PLOT3D variables could easily be obtained using the procedures given. A more advanced reader would probably check for consistency in the dimensions and conversion scales, to ensure compliance with the guidelines.