Grid SpecificationΒΆ

CGNS Mid-Level Library - Grid Specification

Grid Specification

  • Zone Grid Coordinates
    • cg_grid_write - Create a GridCoordinates_t node
    • cg_ngrids - Get number of GridCoordinates_t nodes
    • cg_grid_read - Get name of a GridCoordinates_t node
    • cg_grid_bounding_box_read - Get bounding box associated to a GridCoordinates_t node
    • cg_grid_bounding_box_write - Write bounding box associated to a GridCoordinates_t node
    • cg_coord_write - Write grid coordinates
    • cg_coord_partial_write - Write subset of grid coordinates
    • cg_coord_general_write - Write shaped array to a subset of grid coordinates
    • cg_ncoords - Get number of coordinate arrays
    • cg_coord_info - Get info about a coordinate array
    • cg_coord_read - Read grid coordinates
    • cg_coord_general_read - Read subset of grid coordinates to a shaped array
  • Element Connectivity
    • cg_section_write - Write fixed size element data
    • cg_poly_section_write - Write element data
    • cg_section_general_write - Write section data without element data
    • cg_section_initialize - Initialize element data for not fixed size elements
    • cg_section_partial_write - Write subset of element data
    • cg_elements_partial_write - Write element data for a fixed size element section
    • cg_poly_elements_partial_write - Write element data for an element section
    • cg_elements_general_write - Write element data for a fixed size element section
    • cg_poly_elements_general_write - Write element data for an element section
    • cg_parent_data_write - Write parent info for an element section
    • cg_parent_data_partial_write - Write subset of parent info for an element section
    • cg_nsections - Get number of element sections
    • cg_section_read - Get info for an element section
    • cg_ElementDataSize - Get size of element connectivity data array
    • cg_ElementPartialSize - Get size of element connectivity data array for partial read
    • cg_elements_read - Read fixed size element data
    • cg_elements_partial_read - Read subset of fixed size element data
    • cg_elements_general_read - Read subset of fixed size element data to a typed array
    • cg_poly_elements_read - Read element data
    • cg_poly_elements_partial_read - Read subset of element data
    • cg_poly_elements_general_read - Read subset of element data to typed arrays
    • cg_parent_elements_general_read - Read parent info for an element section
    • cg_parent_elements_position_general_read - Read parent position info for an element section
    • cg_npe - Get number of nodes for an element type
  • Axisymmetry
    • cg_axisym_write - Create axisymmetry data
    • cg_axisym_read - Read axisymmetry data
  • Rotating Coordinates
    • cg_rotating_write - Create rotating coordinates data
    • cg_rotating_read - Read rotating coordinates data

Zone Grid Coordinates

Node: GridCoordinates_t (SIDS, File Mapping)

GridCoordinates_t nodes are used to describe grids associated with a particular zone. The original grid must be described by a GridCoordinates_t node named GridCoordinates. Additional GridCoordinates_t nodes may be used, with user-defined names, to store grids at multiple time steps or iterations. In addition to the discussion of the GridCoordinates_t node in the SIDS and File Mapping manuals, see the discussion of the ZoneIterativeData_t and ArbitraryGridMotion_t nodes in the SIDS manual.

Functions Modes
ier = cg_grid_write(int fn, int B, int Z, char *GridCoordName,
      int *G);
- w m
ier = cg_ngrids(int fn, int B, int Z, int *ngrids); - w m
ier = cg_grid_read(int fn, int B, int Z, int G,
      char *GridCoordName);
r - m
ier = cg_grid_bounding_box_write(int fn, int B, int Z, int G,
      DataType_t datatype, void *bbox_array);
- w m
ier = cg_grid_bounding_box_write(int fn, int B, int Z, int G,
      DataType_t datatype, void *bbox_array);
r - m
call cg_grid_write_f(fn, B, Z, GridCoordName, G, ier) - w m
call cg_ngrids_f(fn, B, Z, ngrids, ier) - w m
call cg_grid_read_f(fn, B, Z, G, GridCoordName, ier) r - m
call cg_grid_bounding_box_write_f(fn, B, Z, G, datatype, bbox_array, ier)
- w m
call cg_grid_bounding_box_read_f(fn, B, Z, G, datatype, bbox_array, ier)
r - m

Input/Output

    fn   CGNS file index number.
B Base index number, where 1 ≤ Bnbases.
Z Zone index number, where 1 ≤ Znzones.
G Grid index number, where 1 ≤ Gngrids.
ngrids Number of GridCoordinates_t nodes for zone Z.
GridCoordinateName Name of the GridCoordinates_t node. Note that the name "GridCoordinates" is reserved for the original grid and must be the first GridCoordinates_t node to be defined.
datatype Data type of the bounding box array written to the file or read. Admissible data types for a coordinate bounding box are RealSingle and RealDouble.
bbox_array Data Array with bounding box values.
ier Error status.

The above functions are applicable to any GridCoordinates_t node.
When reading a bounding box, if the information is missing from the file, the bbox_array will remain untouched, and a warning is emitted.
The CGNS MLL relies on the user to compute the bounding box and ensure that the bounding box being stored is coherent with the coordinates under GridCoordinates_t node.

Functions Modes
ier = cg_coord_write(int fn, int B, int Z, DataType_t datatype,
      char *coordname, void *coord_array, int *C);
- w m
ier = cg_coord_partial_write(int fn, int B, int Z,
      DataType_t datatype, char *coordname, cgsize_t *range_min,
      cgsize_t *range_max, void *coord_array, int *C);
- w m
ier = cg_coord_general_write(int fn, int B, int Z, char *coordname,
      DataType_t datatype, cgsize_t *range_min, cgsize_t *range_max,
      DataType_t mem_datatype, int mem_rank, cgsize_t *mem_dimensions,
      cgsize_t *mem_range_min, cgsize_t *mem_range_max,
      void *coord_array, int *C);
- w m
ier = cg_ncoords(int fn, int B, int Z, int *ncoords); r - m
ier = cg_coord_info(int fn, int B, int Z, int C,
      DataType_t *datatype, char *coordname);
r - m
ier = cg_coord_read(int fn, int B, int Z, char *coordname,
      DataType_t mem_datatype, cgsize_t *range_min, cgsize_t *range_max,
      void *coord_array);
r - m
ier = cg_coord_general_read(int fn, int B, int Z, char *coordname,
      cgsize_t *range_min, cgsize_t *range_max,
      DataType_t mem_datatype, int mem_rank, cgsize_t *mem_dimensions,
      cgsize_t *mem_range_min, cgsize_t *mem_range_max, void *coord_array);
r - m
call cg_coord_write_f(fn, B, Z, datatype, coordname, coord_array,
     C, ier)
- w m
call cg_coord_partial_write_f(fn, B, Z, datatype, coordname,
     range_min, range_max, coord_array, C, ier)
- w m
call cg_coord_general_write_f(fn, B, Z, coordname, datatype,
     range_min, range_max, mem_datatype, mem_rank, mem_dimensions,
     mem_range_min, mem_range_max, coord_array, C, ier);
- w m
call cg_ncoords_f(fn, B, Z, ncoords, ier) r - m
call cg_coord_info_f(fn, B, Z, C, datatype, coordname, ier) r - m
call cg_coord_read_f(fn, B, Z, coordname, mem_datatype,
     range_min, range_max, coord_array, ier)
r - m
call cg_coord_general_read_f(fn, B, Z, coordname,
     range_min, range_max, mem_datatype, mem_rank, mem_dimensions,
     mem_range_min, mem_range_max, coord_array, ier);
r - m

Input/Output

    fn   CGNS file index number.
B Base index number, where 1 ≤ Bnbases.
Z Zone index number, where 1 ≤ Znzones.
C Coordinate array index number, where 1 ≤ Cncoords.
ncoords Number of coordinate arrays for zone Z.
datatype Data type of the coordinate array written to the file. Admissible data types for a coordinate array are RealSingle and RealDouble.
coordname Name of the coordinate array. It is strongly advised to use the SIDS nomenclature conventions when naming the coordinate arrays to insure file compatibility.
range_min Lower range index in file (eg., imin, jmin, kmin).
range_max Upper range index in file (eg., imax, jmax, kmax).
mem_datatype Data type of an array in memory. Admissible data types for a coordinate array are RealSingle and RealDouble..
mem_rank Number of dimensions of array in memory.
mem_dimensions Dimensions of array in memory.
mem_range_min Lower range index in memory (eg., imin, jmin, kmin).
mem_range_max Upper range index in memory (eg., imax, jmax, kmax).
coord_array Array of coordinate values.
ier Error status.

The above functions are applicable only to the GridCoordinates_t node named GridCoordinates, used for the original grid in a zone. Coordinates for additional GridCoordinates_t nodes in a zone must be read and written using the cg_array_xxx functions.

When writing, the function cg_coord_write will automatically write the full range of coordinates (i.e., the entire coord_array). The functions cg_coord_partial_write and cg_coord_general_write may be used to write only a subset of coord_array. When using the partial write, any existing data as defined by range_min and range_max will be overwritten by the new values. All other values will not be affected.

The function cg_coord_read returns the coordinate array coord_array, for the range prescribed by range_min and range_max. The array is returned to the application in the data type requested in mem_datatype. This data type does not need to be the same as the one in which the coordinates are stored in the file. A coordinate array stored as double precision in the CGNS file can be returned to the application as single precision, or vice versa. The functions cg_coord_general_read and cg_coord_general_write allow for type conversion when both reading from and writing to the file.

In Fortran, when using cg_coord_read_f to read 2D or 3D coordinates, the extent of each dimension of coord_array must be consistent with the requested range. When reading a 1D solution, the declared size can be larger than the requested range. For example, for a 2D zone with 100 × 50 vertices, if range_min and range_max are set to (11,11) and (20,20) to read a subset of the coordinates, then coord_array must be dimensioned (10,10). If coord_array is declared larger (e.g., (100,50)) the indices for the returned coordinates will be wrong. These restrictions can be avoided by using cg_coord_general_read_f instead.

When using cg_coord_general_write and cg_coord_general_read, the lower core vertices in the file have index 1 for defining range_min and range_max; whereas for the array in memory, defined by mem_rank and mem_dimensions, the lower array vertices in memory have index 1 for defining mem_range_min and mem_range_max. The actual lower and upper bounds of the array in memory can be anything. For example, to fully read a two-dimensional 6 × 6 coordinate array with 1 rind plane on each side in the file to an 8 × 8 array in memory (mem_rank = 2 and mem_dimensions = (8,8)), set range_min and range_max to (0,0) and (7,7), and set mem_range_min and mem_range_max to (1,1) and (8,8).

Element Connectivity

Node: Elements_t (SIDS, File Mapping)

Functions Modes
ier = cg_section_write(int fn, int B, int Z,
      char *ElementSectionName, ElementType_t type, cgsize_t start,
      cgsize_t end, int nbndry, cgsize_t *Elements, int *S);
- w m
ier = cg_poly_section_write(int fn, int B, int Z,
      char *ElementSectionName, ElementType_t type, cgsize_t start,
      cgsize_t end, int nbndry, cgsize_t *Elements, cgsize_t *ConnectOffset,
      int *S);
- w m
ier = cg_section_general_write(int fn, int B, int Z,
      char *ElementSectionName, ElementType_t type, DataType_t ElementDataType,
      cgsize_t start, cgsize_t end, cgsize_t ElementDataSize, int nbndry,
      int *S);
- w m
ier = cg_section_initialize(int fn, int B, int Z, int S); - w m
ier = cg_section_partial_write(int fn, int B, int Z,
      char *ElementSectionName, ElementType_t type, cgsize_t start,
      cgsize_t end, int nbndry, int *S);
- w m
ier = cg_elements_partial_write(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, cgsize_t *Elements);
- w m
ier = cg_poly_elements_partial_write(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, cgsize_t *Elements,
      cgsize_t *ConnectOffset);
- w m
ier = cg_elements_general_write(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, DataType_t mem_datatype,
      void *Elements);
- w m
ier = cg_poly_elements_general_write(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, DataType_t mem_datatype,
      void *Elements, void *ConnectOffset);
- w m
ier = cg_parent_data_write(int fn, int B, int Z, int S,
      cgsize_t *ParentData);
- w m
ier = cg_parent_data_partial_write(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, cgsize_t *ParentData);
- w m
ier = cg_nsections(int fn, int B, int Z, int *nsections); r - m
ier = cg_section_read(int fn, int B, int Z, int S,
      char *ElementSectionName, ElementType_t *type, cgsize_t *start,
      cgsize_t *end, int *nbndry, int *parent_flag);
r - m
ier = cg_ElementDataSize(int fn, int B, int Z, int S,
      cgsize_t *ElementDataSize);
r - m
ier = cg_ElementPartialSize(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, cgsize_t *ElementDataSize);
r - m
ier = cg_elements_read(int fn, int B, int Z, int S, cgsize_t *Elements,
      cgsize_t *ParentData);
r - m
ier = cg_elements_partial_read(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, cgsize_t *Elements, cgsize_t *ParentData);
r - m
ier = cg_elements_general_read(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, DataType_t mem_datatype, void *Elements);
r - m
ier = cg_poly_elements_read(int fn, int B, int Z, int S, cgsize_t *Elements,
      cgsize_t *ConnectOffset, cgsize_t *ParentData);
r - m
ier = cg_poly_elements_partial_read(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, cgsize_t *Elements,
      cgsize_t *ConnectOffset, cgsize_t *ParentData);
r - m
ier = cg_poly_elements_general_read(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, DataType_t *mem_datatype,
      void *Elements, void *ConnectOffset);
r - m
ier = cg_parent_elements_general_read(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, DataType_t *mem_datatype,
      void *ParentElement);
r - m
ier = cg_parent_elements_position_general_read(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, DataType_t *mem_datatype,
      void *ParentFace);
r - m
ier = cg_npe(ElementType_t type, int *npe); r w m
call cg_section_write_f(fn, B, Z, ElementSectionName, type,
     start, end, nbndry, Elements, S, ier)

- w m
call cg_poly_section_write_f(fn, B, Z, ElementSectionName, type,
     start, end, nbndry, Elements, ConnectOffset, S, ier)

- w m
call cg_section_general_write_f(fn, B, Z, ElementSectionName, type,
     ElementDataType, start, end, ElementDataSize, nbndry, S, ier)

- w m
call cg_section_initialize_f(fn, B, Z, S)
- w m
call cg_section_partial_write_f(fn, B, Z, ElementSectionName, type,
     start, end, nbndry, S, ier)

- w m
call cg_elements_partial_write_f(fn, B, Z, S, start,
     end, Elements, ier)

- w m
call cg_poly_elements_partial_write_f(fn, B, Z, S, start,
     end, Elements, ConnectOffset, ier)

- w m
call cg_elements_general_write_f(fn, B, Z, S, start,
     end, mem_datatype, Elements, ier)

- w m
call cg_poly_elements_general_write_f(fn, B, Z, S, start,
     end, mem_datatype, Elements, ConnectOffset, ier)

- w m
call cg_parent_data_write_f(fn, B, Z, S, ParentData, ier)
- w m
call cg_parent_data_partial_write_f(fn, B, Z, S, start,
     end, ParentData, ier)

- w m
call cg_nsections_f(fn, B, Z, nsections, ier)
r - m
call cg_section_read_f(fn, B, Z, S, ElementSectionName, type,
     start, end, nbndry, parent_flag, ier)

r - m
call cg_ElementDataSize_f(fn, B, Z, S, ElementDataSize, ier)
r - m
call cg_ElementPartialSize_f(fn, B, Z, S, start, end, ElementDataSize, ier)
r - m
call cg_elements_read_f(fn, B, Z, S, Elements, ParentData, ier)
r - m
call cg_elements_partial_read_f(fn, B, Z, S, start, end, Elements,
     ParentData, ier)

r - m
call cg_poly_elements_read_f(fn, B, Z, S, Elements, ConnectOffset,
     ParentData, ier)

r - m
call cg_poly_elements_partial_read_f(fn, B, Z, S, start, end, Elements,
     ConnectOffset, ParentData, ier)

r - m
call cg_elements_general_read_f(fn, B, Z, S, start, end,
     mem_datatype, Elements, ier)

r - m
call cg_poly_elements_general_read_f(fn, B, Z, S, start, end,
     mem_datatype, Elements, ConnectOffset, ier)

r - m
call cg_parent_elements_general_read_f(fn, B, Z, S, start, end,
     mem_datatype, ParentElement, ier)

r - m
call cg_parent_elements_position_general_read_f(fn, B, Z, S, start, end,
     mem_datatype, ParentFace, ier)

r - m
call cg_npe_f(type, npe, ier) r w m

Input/Output

    fn   CGNS file index number.
B Base index number, where 1 ≤ Bnbases.
Z Zone index number, where 1 ≤ Znzones.
ElementSectionName Name of the Elements_t node.
type Type of element. See the eligible types for ElementType_t in the Typedefs section.
start Index of first element in the section.
end Index of last element in the section.
nbndry Index of last boundary element in the section. Set to zero if the elements are unsorted.
nsections Number of element sections.
S Element section index, where 1 ≤ Snsections.
parent_flag Flag indicating if the parent data are defined. If the parent data exist, parent_flag is set to 1; otherwise it is set to 0.
ElementDataType Data type of an array. Admissible data types are Integer and LongInteger.
ElementDataSize Number of element connectivity data values.
Elements Element connectivity data. The element connectivity order is given in Element Numbering Conventions.
ConnectOffset Element connectivity offset data. This is required for NGON_n, NFACE_n and MIXED according to Elements_t Structure Definition.
ParentData For boundary or interface elements, this array contains information on the cell(s) and cell face(s) sharing the element. If you do not need to read the ParentData when reading the ElementData, you may set the value to NULL.
ParentElement For boundary or interface elements, this array contains information on the cell(s) sharing the element.
ParentFace For boundary or interface elements, this array contains information on the cell face(s) sharing the element.
mem_datatype Data type of an array in memory. Admissible data types are Integer and LongInteger.
npe Number of nodes for an element of type type.
ier Error status.

It is important to note that each element under a given Zone_t - including all cells, faces, edges, boundary elements, etc. - must have a unique element index number. The numbering should be consecutive (i.e., no gaps). This global numbering system insures that each and every element within a zone is uniquely identified by its number.

If the specified Elements_t node doesn't yet exist, it may be created using either cg_section_write or cg_section_partial_write. MIXED, NGON_n, and NFACE_n element sets may be created using cg_poly_section_write or cg_poly_section_partial_write. The function cg_section_write writes the full range as indicated by start and end and supplied by the element connectivity array Elements. The cg_section_partial_write function will create the element section data for the range start to end with the element data intialized to 0. cg_poly_section_write and cg_poly_section_partial_write have a comparable behavior for MIXED, NGON_n, and NFACE_n. To add elements to the section, use cg_elements_partial_write or cg_poly_elements_partial_write and parent data (it it exists) using cg_parent_data_partial_write. These functions will replace the data for the range as indicated by start and end with the new values. In most cases, the data is not duplicated in the mid-level library and written directly from the user data to disk.The exception to this is in the case of MIXED, NGON_n, and NFACE_n element sets. Even if the size of the element connectivity array can be known through ConnectOffset, the MLL will keep a copy of the data in memory for the partial writes.

The functions cg_elements_read and cg_poly_elements_read returns all of the element connectivity and parent data. Specified subsets of the element connectivity and parent data may be read using cg_elements_partial_read or cg_poly_elements_partial_read (MIXED, NGON_n, NFACE_n).

Note : cg_elements_read, cg_elements_partial_read, cg_section_write and cg_element_partial_write functions only work with fixed size elements.

Axisymmetry

Node: Axisymmetry_t (SIDS, File Mapping)

Functions Modes
ier = cg_axisym_write(int fn, int B, float *ReferencePoint,
      float *AxisVector);
- w m
ier = cg_axisym_read(int fn, int B, float *ReferencePoint,
      float *AxisVector);
r - m
call cg_axisym_write_f(fn, B, ReferencePoint, AxisVector, ier) - w m
call cg_axisym_read_f(fn, B, ReferencePoint, AxisVector, ier) r - m

Input/Output

    fn   CGNS file index number.
B Base index number, where 1 ≤ Bnbases.
ReferencePoint Origin used for defining the axis of rotation. (In Fortran, this is an array of Real*4 values.)
AxisVector Direction cosines of the axis of rotation, through the reference point. (In Fortran, this is an array of Real*4 values.)
ier Error status.

This node can only be used for a bi-dimensional model, i.e., PhysicalDimension must equal two.

Rotating Coordinates

Node: RotatingCoordinates_t (SIDS, File Mapping)

Functions Modes
ier = cg_rotating_write(float *RotationRateVector,
      float *RotationCenter);
- w m
ier = cg_rotating_read(float *RotationRateVector,
      float *RotationCenter);
r - m
call cg_rotating_write_f(RotationRateVector, RotationCenter, ier) - w m
call cg_rotating_read_f(RotationRateVector, RotationCenter, ier) r - m

Input/Output

    RotationRateVector   Components of the angular velocity of the grid about the center of rotation. (In Fortran, this is an array of Real*4 values.)
RotationCenter Coordinates of the center of rotation. (In Fortran, this is an array of Real*4 values.)
ier Error status.