# read_cgns

### Synopsis

> The read_cgns user macro reads CGNS format files. CGNS files are used for the storage and retrieval of CFD data. More information about CGNS can be found at www.cgns.org.

> #### Parameters

> ##### CgnsParams

> Name | Type | Description | UI Control
> filename | string | Name of CGNS file to read. | File Dialog
> load | int | Triggers loading of selected data from CGNS file. | Button
> status | string | Reports any error during file loading. | Text Box

> ##### CgnsOutputParams

> Name | Type | Description | UI Control
> currentBase | int | Selected Base. | Menu
> currentActiveZones[] | int[] | Specifies which zones should be read. | Check Boxes
> currentSolution[] | int[] | Specifies which solution should be read for each zone. | Menus

> ##### Other Parameters

> Name | Type | Description
> BaseInfo | group | Base information read from CGNS file.
> ZoneInfo | group | Zone information read from CGNS file.

> #### Output Ports

> Name | Type | Description
> Multi Block | Multi Block | Structured zones read from CGNS file.
> unstr_field[] | Field[] | Unstructured zones read from CGNS file.

### Description

> The read_cgns user macro reads a CGNS file. The CGNS file format is used for the storage and retrieval of CFD data. CGNS is a fully supported file format of Fluent (version 5.5 or later),Computational Dynamics STAR-CD and other major CFD software vendors. More information on CGNS and a complete list of implementations can be found on the CGNS web site (www.cgns.org).

> The read_cgns macro takes a filename, reads the CGNS file and outputs a Multi_Block group that contains structured Zones and an array of fields that contains the unstructured Zones. The user interface allows the user to select which Base to read. It also allows the user to select which Zones to read and which Solution to read for each Zone. Two shortcut buttons are provided so that the user can easily select or deselect all zones.

> The data output by the read_cgns macro can be processed by the macros and modules found in the Accessories->Array of Fields library. The structured Multi_Block output can be processed by the multiblock modules or can be converted into an array of fields. The unstructured array of fields output can be processed by any of the `ARR` modules (i.e. `extract_cell_component_ARR`).

### Installation

> Internally this project uses the CGNS library to read CGNS files. This means that as well as installing the project in the normal way the CGNS library must also be installed onto your system. On Windows systems a pre-built binary version of this library is included. For other platforms pre-built binary versions of the CGNS library and the source code can be downloaded from the CGNS web-site. The instructions below detail how these files should be installed.

#### Windows Installation

> The ReadCgns project comes with a pre-built binary version of the CGNS library that is compiled for VC++. This binary will be automatically linked with Express when the ReadCgns project is compiled. Normally you will not need to do anything extra to the normal IAC installation process.

> The only exception to this is if you want to use a different version of the CGNS library. In this case you will have to recompile the library from the source code available on the CGNS web-site. This is because the pre-built binaries available from the web-site have been linked with different runtime libraries than those used by AVS/Express. To change this the CFLAGS line of the Makefile.win40 file will have to be altered so that it reads:

>     CFLAGS = -c -nologo /MDd /Zi /Op -I.. -I$(CTOOLS)/include -W1 -DWINNT -D_WIN32

> Once this is done the library should be recompiled and the resultant `libcgns.lib` file should be placed into the iac_proj\rd_cgns directory.

#### Other Platforms Installation

> For all other platforms a pre-built library is not supplied with the ReadCgns project. Instead a copy of the library must be downloaded from the CGNS web-site. Fortunately the pre-built binaries available do work with AVS/Express on platforms other than Windows. The downloaded library file and header file(cgnslib.h) can be placed into the iac_proj/rd_cgns project directory. Alternatively they can be placed into the appropriate lib and include directories on your system. In this case you should delete the cgnslib.h file in iac_proj/rd_cgns project directory.

### Parameters

#### CgnsParams

> filename

> String parameter that specifies which CGNS file should be read. The filename string should contain the full path name of the file and can contain any of the AVS/Express environment variables (e.g. $XP_PATH<1>)

> load

> Integer parameter that triggers the loading of the selected data from the CGNS file. Whenever this parameter is altered the selected Zones are read from the specified CGNS file.

> status

> String parameter that reports any errors that occurred whilst loading the CGNS file. This parameter is intended to be used only as an output from the low-level module and should not be altered.

#### CgnsOutputParams

> currentBase

> Integer parameter that specifies which base is currently selected. The value of this parameter is set by the Base drop-down list in the user interface. When the data is read from the CGNS file only that data associated with the current base is loaded.

> currentActiveZones[]

> Integer array that specifies which Zones have been selected. The values of this array are set by the Active checkbox in each zone panel of the user interface. Each element in the array is used as a boolean value. If an element is true then the respective Zone is read.

> currentSolution[]

> Integer array that specifies which Solution should be read for each Zone. The values of this array are set by the Solution drop-down list in each zone panel of the user interface. If the zone is not active then changing the selected solution will have no affect.

#### Other Parameters

> BaseInfo

> Group parameter that stores all base information that is read from the CGNS file. It contains an array that specifies the name, cell dimensions and physical dimensions for each Base in the CGNS file. The BaseInfo group is used by the user interface to display information about each base. It is also used by the low-level module to store information between each stage of the reading process.

> ZoneInfo

> Group parameter that stores all zone information that is read from the CGNS file. It contains an array that specifies a number of properties for each Zone in the selected Base. The ZoneInfo group is used by the user interface to display information about each zone so that the user can make the appropriate choice. It is also used by the low-level module to store information between each stage of the reading process.

### Outputs

> Multi_Block

> This output group contains all of the structured data read from the selected zones in the CGNS file. Each active structured zone is output as a single element of the multiblock field array. The Multi_Block can be processed by a number of multiblock modules or can be converted into an array of fields by using the mblock_to_field module. Once this is done any of the `ARR` modules can be used to process the data.

> unstr_fields[]

> This output array contains all of the unstructured data read from the selected zones in the CGNS file. Each active unstructured zone is output as a single element of the field array. Any of the `ARR` modules can be used to process this data.

### Utility Macros

> The ReadCgnsFunc functional macro uses the low-level DVread_cgns module. The macro takes as input the two parameter blocks, CgnsParams and CgnsOutputParams. The macro outputs the data read from the CGNS file as structured multiblock data and unstructured array of field data. The macro also outputs the read BaseInfo and ZoneInfo.

> The ReadCgnsFunc functional macro and the ReadCgnsUI user interface macro are both used by the read_cgns user macro. All of these macros use the CgnsParams and CgnsOutputParams parameter block to communicate data. There are also two additional links between the ReadCgnsUI macro and ReadCgnsFunc functional macro to transfer the BaseInfo and ZoneInfo data.

### Example

> The project includes two example applications that demonstrates the use of the read_cgns macro. The ReadCgnsMultiBlockEg application uses the read_cgns macro to read a CGNS file containing structured zones. The ReadCgnsUnstructuredEg application use read_cgns macro to read a CGNS file containing unstructured zones.

> A sub-library of test case applications has also been included. These were used during development to ensure that the ReadCgns project could read certain unusual CGNS files. These have been included so that the end user can also assure themselves that project works properly. The included test cases are listed below:

> > TstMixed | Tests the simultaneous reading of structured and unstructured zones. Also tests reading of Sections with MIXED cell type and cells not defined in any order.
> > TstNGON | Tests the reading of NGON-n cells.
> > TstRind | Tests the reading of CGNS files containing Rind data.
> > TstUnsupported | Tests the reading of CGNS files that contain features that are not currently supported by the ReadCgns project. The test case reads a file containing non-Cartesian coordinates and GridPosition, both of which are unsupported.
> > TstCellTypes | Tests the reading of various base cell types.
> > Tst2DScndOrderCells | Tests the reading of two dimensional second order cells. These cell types are TRI_6, QUAD_8 and QUAD_9.
> > Tst3DScndOrderCells | Tests the reading of three dimensional second order cells. These cell types are TETRA_10, PYRA_14, PENTA_15, PENTA_18, HEXA_20 and HEXA_27.

### Files

> iac_proj/rd_cgns/cgnsmods.v contains the V definitions of the DVread_cgns module, BaseInfo and ZoneInfo groups and the CgnsParams and CgnsOutputParams parameter blocks.

> iac_proj/rd_cgns/cgnsmacs.v contains the V definitions of the ReadCgnsUI UI macro, the ReadCgnsFunc functional macro and the read_cgns user macro.

> iac_proj/rd_cgns/cgnsapps.v contains the V definitions of the ReadCgnsMultiBlockEg and ReadCgnsUnstructuredEg example applications, and the TestCases library containing the TstMixed, TstNGON, TstRind, TstUnsupported, TstCellTypes, Tst2DScndOrderCells and Tst3DScndOrderCells test cases.

### Prerequisites

> On all platforms this project requires the CGNS library to be used. On the Windows platform a pre-compiled binary version of the library is included with the project. On other platforms this project requires the CGNS library to be installed. The necessary files to do this can be downloaded from http://www.cgns.org. On this web-site you should be able to find pre-built binaries for a number of platforms. You can place the downloaded library file and header file (cgnslib.h) into the iac_proj/rd_cgns directory. Alternatively you can place the CGNS library files into the appropriate lib and include directories on your system.

### Other Notes

> The low-level ReadCgnsMods library containing the low-level module DVread_cgns does not specify a process. By default the `express` process will be used.

### Author

>     Ian Curington, AVS Inc.

### Modifications

>     Ma YingLiang, Manchester Visualization Centre

>     Andrew Dodd, International AVS Centre

### Contact

>     International AVS Centre
>     Manchester Visualization Centre
>     Manchester Computing
>     University of Manchester
>     Oxford Road
>     Manchester
>     United Kingdom
>     M13 9PL

### See Also

- CGNS home page.
- Fluent Inc. home page.
- Computational Dynamics Ltd. (STAR-CD) home page.