Skip navigation links
(CGNS Documentation Home Page) (Steering Committee Charter) (Overview and Entry-Level Document) (A User's Guide to CGNS) (Standard Interface Data Structures) (SIDS-to-ADF File Mapping Manual) (SIDS-to-HDF File Mapping Manual) (Mid-Level Library) (ADF User's Guide) (CGNS Tools and Utilities)

(General Remarks) (File Operations) (Navigating a CGNS File) (Error Handling) (Structural Nodes) (Descriptors) (Physical Data) (Location and Position) (Auxiliary Data) (Grid Specification) (Solution Data) (Grid Connectivity) (Boundary Conditions) (Equation Specification) (Families) (Time-Dependent Data) (Links)

General Remarks

Language

The CGNS Mid-Level Library is written in C, but each function has a Fortran counterpart. All function names start with "cg_". The Fortran functions have the same name as their C counterpart with the addition of the suffix "_f".

Character Strings

All data structure names and labels in CGNS are limited to 32 characters. When reading a file, it is advised to pre-allocate the character string variables to 32 characters in Fortran, and 33 in C (to include the string terminator). Other character strings, such as the CGNS file name or descriptor text, are unlimited in length. The space for unlimited length character strings will be created by the Mid-Level Library; it is then the responsibility of the application to release this space by a call to cg_free.

Error Status

All C functions return an integer value representing the error status. All Fortran functions have an additional parameter, ier, which contains the value of the error status. An error status different from zero implies that an error occured. The error message can be printed using the error handling functions of the CGNS library. The error codes are coded in the C and Fortran include files cgnslib.h and cgnslib_f.h.

Typedefs

Several types of variables are defined using typedefs in the cgnslib.h file. These are intended to facilitate the implementation of CGNS in C. These variable types are defined as an enumeration of key words admissible for any variable of these types. The file cgnslib.h must be included in any C application programs which use these data types.

In Fortran, the same key words are defined as integer parameters in the include file cgnslib_f.h. Such variables should be declared as integer in Fortran applications. The file cgnslib_f.h must be included in any Fortran application using these key words.

The list of supported values (key words) for each of these variable types (typedefs) are:

    ZoneType_t   Structured, Unstructured
 
ElementType_t NODE, BAR_2, BAR_3, TRI_3, TRI_6, QUAD_4, QUAD_8, QUAD_9, TETRA_4, TETRA_10, PYRA_5, PYRA_14, PENTA_6, PENTA_15, PENTA_18, HEXA_8, HEXA_20, HEXA_27, MIXED, NGON_n
 
DataType_t Integer, RealSingle, RealDouble, Character
 
DataClass_t Dimensional, NormalizedByDimensional, NormalizedByUnknownDimensional, NondimensionalParameter, DimensionlessConstant
 
MassUnits_t Null, UserDefined, Kilogram, Gram, Slug, PoundMass
 
LengthUnits_t Null, UserDefined, Meter, Centimeter, Millimeter, Foot, Inch
 
TimeUnits_t Null, UserDefined, Second
 
TemperatureUnits_t Null, UserDefined, Kelvin, Celsius, Rankine, Fahrenheit
 
AngleUnits_t Null, UserDefined, Degree, Radian
 
ElectricCurrentUnits_t Null, UserDefined, Ampere, Abampere, Statampere, Edison, auCurrent
 
SubstanceAmountUnits_t Null, UserDefined, Mole, Entities, StandardCubicFoot, StandardCubicMeter
 
LuminousIntensityUnits_t Null, UserDefined, Candela, Candle, Carcel, Hefner, Violle
 
GoverningEquationsType_t Null, UserDefined, FullPotential, Euler, NSLaminar, NSTurbulent, NSLaminarIncompressible, NSTurbulentIncompressible
 
ModelType_t Null, UserDefined, Ideal, VanderWaals, Constant, PowerLaw, SutherlandLaw, ConstantPrandtl, EddyViscosity, ReynoldsStress, ReynoldsStressAlgebraic, Algebraic_BaldwinLomax, Algebraic_CebeciSmith, HalfEquation_JohnsonKing, OneEquation_BaldwinBarth, OneEquation_SpalartAllmaras, TwoEquation_JonesLaunder, TwoEquation_MenterSST, TwoEquation_Wilcox, CaloricallyPerfect, ThermallyPerfect, ConstantDensity, RedlichKwong, Frozen, ThermalEquilib, ThermalNonequilib, ChemicalEquilibCurveFit, ChemicalEquilibMinimization, ChemicalNonequilib, EMElectricField, EMMagneticField, EMConductivity, Voltage, Interpolated, Equilibrium_LinRessler, Chemistry_LinRessler
 
GridLocation_t Vertex, CellCenter, FaceCenter, IFaceCenter, JFaceCenter, KFaceCenter, EdgeCenter
 
GridConnectivityType_t Overset, Abutting, Abutting1to1
 
PointSetType_t PointList, PointRange, PointListDonor, PointRangeDonor, ElementList, ElementRange, CellListDonor
 
BCType_t Null, UserDefined, BCAxisymmetricWedge, BCDegenerateLine, BCExtrapolate, BCDegeneratePoint, BCDirichlet, BCFarfield, BCNeumann, BCGeneral, BCInflow, BCOutflow, BCInflowSubsonic, BCOutflowSubsonic, BCInflowSupersonic, BCOutflowSupersonic, BCSymmetryPlane, BCTunnelInflow, BCSymmetryPolar, BCTunnelOutflow, BCWallViscous, BCWall, BCWallViscousHeatFlux, BCWallInviscid, BCWallViscousIsothermal, FamilySpecified
 
BCDataType_t Dirichlet, Neumann
 
RigidGridMotionType_t Null, UserDefined, ConstantRate, VariableRate
 
ArbitraryGridMotionType_t Null, UserDefined, NonDeformingGrid, DeformingGrid
 
SimulationType_t TimeAccurate, NonTimeAccurate
 
WallFunctionType_t Generic
 
AreaType_t BleedArea, CaptureArea
 
AverageInterfaceType_t AverageAll, AverageCircumferential, AverageRadial, AverageI, AverageJ, AverageK

Note that these key words need to be written exactly as they appear here, including the use of upper and lower case, to be recognized by the library.

Character Names For Typedefs

The CGNS library defines character arrays which map the typedefs above to character strings. These are global arrays dimensioned to the size of each list of typedefs. To retrieve a character string representation of a typedef, use the typedef value as an index to the appropiate character array. For example, to retrieve the string "Meter" for the LengthUnits_t Meter typedef, use LengthUnitsName[Meter]. Functions are available to retrieve these names without the need for direct global data access. These functions also do bounds checking on the input, and if out of range, will return the string "<invalid>". An additional benefit is that these will work from within a Windows DLL, and are thus the recommended access technique. The routines have the same name as the global data arrays, but with a "cg_" prepended. For the example above, use "cg_LengthUnitsName(Meter)".

Acquiring the Software and Documentation

The CGNS Mid-Level Library may be downloaded from SourceForge external link. This manual, as well as the other CGNS documentation, is available in both HTML and PDF format from the CGNS documentation web site.

Organization of This Manual

The sections that follow describe the Mid-Level Library functions in detail. The first three sections cover some basic file operations (i.e., opening and closing a CGNS file, and some configuration options), accessing a specific node in a CGNS database, and error handling. The remaining sections describe the functions used to read, write, and modify nodes and data in a CGNS database. These sections basically follow the organization used in the "Detailed CGNS Node Descriptions" section of both the SIDS-to-ADF and SIDS-to-HDF file mapping manuals.

At the start of each sub-section is a Node line, listing the the applicable CGNS node label, with links to that node's description in the SIDS and SIDS-to-ADF File Mapping manuals.

Next is a table illustrating the syntax for the Mid-Level Library functions. The C functions are shown in the top half of the table, followed by the corresponding Fortran routines in the bottom half of the table. Input variables are shown in an upright blue font, and output variables are shown in a slanted red font. For each function, the right-hand column lists the modes (read, write, and/or modify) applicable to that function.

The input and output variables are then listed and defined.