CGNS Tutorial

Introduction CFD General Notation System (CGNS)

Christopher L. Rumsey NASA Langley Research Center Outline • Introduction • Overview of CGNS – What it is – History – How it works, and how it can help – The future • Basic usage – Getting it and making it work for you – Simple example – Aspects for data longevity

2 Introduction

• CGNS provides a general, portable, and extensible standard for the description, storage, and retrieval of CFD analysis data • Principal target is data normally associated with computed solutions of the Navier-Stokes equations & its derivatives • But applicable to computational field physics in general (with augmentation of data definitions and storage conventions)

3 What is CGNS? • Standard for defining & storing CFD data – Self-descriptive – Machine-independent – Very general and extendable – Administered by international steering committee • AIAA recommended practice (AIAA R-101A-2005) • Free and open software • Well-documented • Discussion forum: [email protected] • Website: http://www.cgns.org

4 History

• CGNS was started in the mid-1990s as a joint effort between NASA, Boeing, and McDonnell Douglas – Under NASA’s Advanced Subsonic Technology (AST) program • Arose from need for common CFD data format for improved collaborative analyses between multiple organizations – Existing formats, such as PLOT3D, were incomplete, cumbersome to share between different platforms, and not self-descriptive (poor for archival purposes) • Initial development was heavily influenced by McDonnell Douglas’ “Common File Format”, which had been in use since 1989 • Version 1.0 of CGNS released in May 1998

5 History, cont’d

• After AST funding ended in 1999, CGNS steering committee was formed – Voluntary public forum – International members from government, industry, academia – Formally became a sub-committee of AIAA Committee on Standards in 2000 • Initial efforts by Boeing to make CGNS an international ISO-STEP standard (1999-2002) – Stalled due to lack of funding – Instead, the existing ISO standard AP209 (finite element solid mechanics) is being rewritten to include CGNS as well as an integrated engineering analysis framework (headed by Lockheed-Martin)

6 Steering committee

• CGNS Steering committee is a public forum • Responsibilities include (1) maintaining software, documentation, and website, (2) ensuring free distribution, and (3) promoting acceptance • Current steering committee make-up (22 members): ADAPCO ONERA ANSYS-CFX Pointwise ANSYS-ICEM CFD Pratt & Whitney Airbus Pratt & Whitney – Rocketdyne Boeing – IDS/PW Rolls-Royce Allison Boeing Commercial Stanford University Boeing IDS Stony Brook University Concepts NREC Tecplot Intelligent Light TTC Technologies NASA Glenn U.S. Air Force / AEDC NASA Langley Utah State University 7 CGNS main features

• Standard Interface Data Structures (SIDS) is the core of CGNS – defines the intellectual content • Hierarchical data structure : quickly traversed and sorted, no need to process irrelevant data • Layered so that many of the data structures are optional • HDF5 (or ADF) database: universal and self- describing • Data may encompass multiple files through the use of symbolic links • Portable ANSI C software, with complete Fortran, C, Python, and Matlab interfaces • Architecture-independent application programming interface (API) – written as a mid-level library (MLL) 8 CGNS File Layout

root node

Name Name Label Label Data Data (link)

Name Name Name Name Label Label Label Label Data Data Data Data

Name Name Label Label Data Data

9 How CGNS works

• Users must download the CGNS software – This includes ADF software (basic I/O operations in binary format) – Also includes MLL software (for ease of implementation) – As of Version 3, HDF5 is automatically included in download. Users wishing to use ADF instead of HDF5 may do so (MLL will work with either ADF or HDF5) • Users are encouraged to use the MLL to read and write their data (helps ensure CGNS-compatibility) • Files are portable across computer platforms • Tools (such as adfviewer) allow user to “see” what is in the CGNS file • Many commercial pre- and post-processing software support CGNS format 10 Typical view of CGNS file using adfviewer

11 Typical CGNS file

Root node

CGNSLibraryVersion_t CGNSBase_t

Zone 1 Zone 2 ConvergenceHistory_t ReferenceState_t Zone_t Zone_t

Elements_t GridCoordinates_t ZoneBC_t FlowSolution_t ZoneGridConnectivity_t

ElementConnectivity CoordinateX CoordinateY GridLocation Density Pressure DataArray_t DataArray_t DataArray_t GridLocation_t DataArray_t DataArray_t

12 Cons and Pros • Cons – Although there are rules, there are also many options and a certain amount of freedom • Example: GridLocation = Vertex vs. CellCenter • Example: data can be stored dimensional or nondimensional • Example: optional use of Rind cells – This flexibility places more responsibility on the CGNS reader to figure out how to make use of what is in the file – Attempted balance between too rigid and too flexible • Pros – As more people use it, more tools get developed to handle the flexibility – Can be as simple as storing only “grid + flow solution”, or as complex as storing everything needed to run/describe a case – Longevity and infinite extensibility

13 How CGNS can help you • Improves longevity (archival quality) of data – Self-descriptive (more on this later) – Machine-independent • Easy to share data files between sites – Eliminates need to translate between different data formats – Rigorous standard means less ambiguity about what the data means – For example, CGNS being used in part for AIAA Drag Prediction Workshop (DPW) • Saves time and money – For example, easy to set-up CFD runs because files include grid coordinates, connectivity, and BC information • Easily extendible to include additional types of data – Solver-specific or user-specific data can easily be written & read – file remains CGNS-compliant (others can still read it!)

– Once defined & agreed upon, new data standards can be 14 added Status/where CGNS is headed

• Latest version as of June 2009 is 2.5 • Version 3.0 (beta) almost ready for release • As of June 2009, the CGNSTalk mailing list had 278 participants from 22 different countries and 92 different organizations (sign up at: https://lists.nasa.gov/mailman/listinfo/cgnstalk) • Many people have expressed interest in CGNS from outside of the traditional aerodynamics community – E.g., computational physiology, electromagnetics • Parallel I/O (through HDF5) available soon as alpha release • CGNS is already in many widely-used commercial visualization products, e.g., Tecplot, Fieldview, ICEM-CFD, VisIt • Continuous process: approval and implementation of extensions for handling new capabilities

15 Getting CGNS

• Go to http://www.cgns.org and follow instructions – All documentation available here (in HTML or PDF) – You can get the official released version (currently 2.5), or use CVS to keep up with the latest fixes – Follow instructions in README file to compile • Also highly recommended (from same place): – cgnstools (tools for viewing/editing) – CGNS Users Guide (practical entry-level manual for getting started with CGNS – includes simple source codes)

16 Basics of using CGNS

• Simple example: opening, closing, writing, & reading Base • Aspects for data longevity – Boundary conditions – Convergence history – Descriptor nodes – Data & equation descriptions – Flowfield variables

17 Opening/closing file & writing Base • C cg_open(“grid.cgns”, CG_MODE_WRITE, &indexf); strcpy (basename,“Base”); icelldim=3; /* dimensionality of cell (3 for volume cell) */ iphysdim=3; /* number of coordinates (3 for 3-D) */ cg_base_write(indexf, basename, icelldim, iphysdim, &indexb); …….. cg_close(indexf); • Fortran call cg_open_f(‘grid.cgns’, CG_MODE_WRITE, indexf, ier) basename=‘Base’ icelldim=3 iphysdim=3 call cg_base_write_f(indexf, basename, icelldim, iphysdim, indexb, ier) …….. call cg_close_f(indexf, ierr) 18 What the file looks like…

Root node automatic

Name = CGNSLibraryVersion Name = Base Label = CGNSLibraryVersion_t Label = CGNSBase_t Data = 2.4 Data = 3, 3

automatic automatic user-defined

Notes: icelldim = dimensionality of cell (2 for face, 3 for volume) iphysdim = no. of coordinates required to define a node position (1 for 1-D, 2 for 2-D, 3 for 3-D)

19 What the file looks like in adfviewer…

20 Reading the Base

• C cg_open(“grid.cgns”, CG_MODE_READ, &indexf); cg_nbases(indexf, &nbases); for (i=1; i <= nbases; i++) {cg_base_read(indexf, i, basename, &icelldim, &iphysdim);} cg_close(indexf); • Fortran call cg_open_f(‘grid.cgns’, CG_MODE_READ, indexf, ier) call cg_nbases_f(indexf, nbases, ier) do i=1,nbases call cg_base_read_f(indexf, i, basename, icelldim, iphysdim, ier) enddo call cg_close_f(indexf, ier)

21 Aspects for data longevity boundary conditions • BCs are included in the CGNS file • Including BCs makes it easier for someone else to duplicate the same flow conditions • Eliminates doubt as to how the solution was run, when later looking at the file • BCs can be simple or have high level of detail – Minimum: list of points and their BC type (name) – Can also include Dirichlet or Neumann-type data

22 23 Aspects for data longevity convergence history • GlobalConvergenceHistory tracks history of residual(s), forces, moments, etc. • Part of a complete record of the flow solution, easily readable by others

24 25 Aspects for data longevity descriptor nodes

• Allow user to add notes, descriptions, important factors associated with the particular run, etc. • As part of the permanent record, descriptor nodes make the file potentially more useful/meaningful in the future • Full inclusion of flow solver input deck(s) is particularly useful • Eliminates doubt as to how the solution was run, when later looking at the file 26 27 28 Aspects for data longevity data & equation descriptions • Documents the dimensionality & units (or normalization) of the data • Reference state and flow solution method become part of permanent record • Eliminates doubt as to what the variables represent and how the solution was run, when later looking at the file

29 30 31 32 Aspects for data longevity flowfield variables • As many flowfield variables as desired can be stored; for example: – Conserved and/or primitive variables – Plus all turbulence quantities, eddy viscosity, distance functions, species mass fractions, or other flowfield quantities of interest • Eliminates having to go back and restart or reconstruct when you want to obtain non- standard quantities

33 Some final comments

• A CGNS file can be as full or as sparse as you want to make it – The fuller it is, the more complete and archival the file – Always easy to read only the parts you want • Easy to build CGNS into existing processes – Start by writing only the “basic” elements of CGNS file (e.g., grid, flow solution, connectivity, and BCs) as a postprocessing file for flow visualization – Gradually add to completeness of file – Eventually, CGNS file can replace your restart file, if desired – Self-contained package: everything you need to run a CFD case can be put in the CGNS file 34 Conclusions

• CGNS is a well-established, stable format with world- wide acceptance, use, and support • Provides seamless communication of data between applications, sites, and system architectures • Supported by many commercial visualization and CFD vendors • Extensible and flexible – easily adapted to other fields of computational physics through specification in the SIDS • Backward compatible with previous versions; forward compatible within major release numbers • Allows new software development to focus on important matters, rather than on time-consuming data I/O, storage, and compatibility issues 35