1. Docs
  2. Standard Specification
  3. CGNS/MLL - An API for C and Fortran applications
  4. CGNS/PMLL documentation

CGNS/PMLL documentationΒΆ

Parallel CGNS User's Guide - Routines

Parallel CGNS Routines

  • Miscellaneous Routines
    • cgp_mpi_comm - Set the MPI communicator
    • cgp_mpi_info - Set the MPI info object
    • cgp_pio_mode - Set the parallel IO mode
    • BINDING DEPRECATED, Deprecated since CGNS-3.3.0 cgp_queue_set - Enable/Disable queued output
    • BINDING DEPRECATED, Deprecated since CGNS-3.3.0 cgp_queue_flush - Flush the output queue
    • cgp_error_exit - Exit with error message
  • File Operations
    • cgp_open - Open a file for parallel IO
    • cgp_close - Close a file
  • Grid Coordinate Data
    • cgp_coord_write - Create a coordinate data node
    • cgp_coord_write_data - Write coordinate data in parallel
    • cgp_coord_general_write_data - Write shaped array to a subset of grid coordinates in parallel
    • cgp_coord_read_data - Read coordinate data in parallel
    • cgp_coord_general_read_data - Read subset of grid coordinates to a shaped array in parallel
  • Element Connectivity Data
    • cgp_section_write - Create a section data node
    • cgp_poly_section_write - Create a section data node
    • cgp_elements_write_data - Write element data in parallel
    • cgp_poly_elements_write_data - Write element data in parallel
    • cgp_elements_read_data - Read element data in parallel
  • Solution Data
    • cgp_field_write - Create a solution field data node
    • cgp_field_write_data - Write field data in parallel
    • cgp_field_general_write_data - Write shaped array to a subset of flow solution field in parallel
    • cgp_field_read_data - Read field data in parallel
    • cgp_field_general_read_data - Read subset of flow solution field to a shaped array in parallel
  • Array Data
    • cgp_array_write - Create an array data node
    • cgp_array_write_data - Write array data in parallel
    • cgp_array_general_write_data - Write shaped array to a subset of data array in parallel
    • cgp_array_read_data - Read array data in parallel
    • cgp_array_general_read_data - Read subset of data array to a shaped array in parallel

Miscellaneous Routines

Functions Modes
ier = cgp_mpi_comm(int mpicomm); r w m
ier = cgp_mpi_info(MPI_Info info); r w m
ier = cgp_pio_mode(PIOmode_t mode); r w m
BINDING DEPRECATED, Deprecated since CGNS-3.3.0 ier = cgp_queue_set(int use_queue); - w m
BINDING DEPRECATED, Deprecated since CGNS-3.3.0 ier = cgp_queue_flush(); - w m
void cgp_error_exit(); r w m
call cgp_mpi_comm_f(mpicomm, ier) r w m
call cgp_mpi_info_f(info, ier) r w m
call cgp_pio_mode_f(mode, ier) r w m
BINDING DEPRECATED, Deprecated since CGNS-3.3.0 call cgp_queue_set_f(use_queue, ier) - w m
BINDING DEPRECATED, Deprecated since CGNS-3.3.0 call cgp_queue_flush_f(ier) - w m
call cgp_error_exit_f() r w m

Input/Output
(Note that for Fortran calls, all integer arguments are integer*4 in 32-bit mode and integer*8 in 64-bit mode. See 64-bit Fortran Portability and Issues.)

    mpicomm   The MPI communicator to be used by the CGNS library.
    mode   Parallel input/output mode.
use_queue enable or disables queued output.
ier Error status.

The routine cgp_mpi_comm sets the MPI communicator for parallel operations by the CGNS library. The default value is MPI_COMM_WORLD.

The routine cgp_mpi_info passes the MPI info object for parallel operations to the CGNS library. Notes for Fortran: the data type for info is an INTEGER.

The routine cgp_pio_mode sets the mode for parallel data reads and writes. The default value is CGP_COLLECTIVE, which allows any number of processes to access the data. When set to CGP_COLLECTIVE, all processes must access the data.

If cgp_queue_set is called with a non-zero argument, then output data will not be written to the file, but rather stored in a queue. The queued data will then be written out when cgp_queue_flush is called.

Note: The data array to be written is NOT duplicated in the queue. Rather a pointer to the data is stored. Thus, the data must be persistent within the user's program until cgp_queue_flush is called.

The routine cgp_error_exit is similar to cg_error_exit in that the process will exit with an error message. However, it will also print the process rank, and call MPI_Abort with an exit code of 1.

File Operations

Functions Modes
ier = cgp_open(char *filename, int mode, int *fn); r w m
ier = cgp_close(int fn); r w m
call cgp_open_f(filename, mode, fn, ier) r w m
call cgp_close_f(fn, ier) r w m

Input/Output
(Note that for Fortran calls, all integer arguments are integer*4 in 32-bit mode and integer*8 in 64-bit mode. See 64-bit Fortran Portability and Issues.)

    filename   Name of the CGNS file, including path name if necessary. There is no limit on the length of this character variable.
mode Mode used for opening the file. The modes currently supported are CG_MODE_READ, CG_MODE_WRITE, and CG_MODE_MODIFY.
fn CGNS file index number.
ier Error status.

The routines cgp_open and cgp_close are similar to cg_open and cg_close, and call those routines. The differences are that cgp_open explicitly sets an internal CGNS flag to indicate parallel access.

Grid Coordinate Data

Functions Modes
ier = cgp_coord_write(int fn, int B, int Z, DataType_t datatype,
      char *coordname, int *C); 		- w m
ier = cgp_coord_write_data(int fn, int B, int Z, int C,
      cgsize_t *range_min, cgsize_t *range_max, void *coord_array); 		- w m
ier = cgp_coord_general_write_data(int fn, int B, int Z, int C,
      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);
ier = cgp_coord_read_data(int fn, int B, int Z, int C,
      cgsize_t *range_min, cgsize_t *range_max, void *coord_array);
ier = cgp_coord_general_read_data(int fn, int B, int Z, int C,
      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 cgp_coord_write_f(fn, B, Z, datatype, coordname, C, ier) - w m
call cgp_coord_write_data_f(fn, B, Z, C, range_min, range_max, coord_array, ier) - w m
call cgp_coord_read_data_f(fn, B, Z, C, range_min, range_max, coord_array, ier) r - m

Input/Output
(Note that for Fortran calls, all integer arguments are integer*4 in 32-bit mode and integer*8 in 64-bit mode. See 64-bit Fortran Portability and Issues.)

    fn   CGNS file index number.
B Base index number, where 1 ≤ B ≤ nbases.
Z Zone index number, where 1 ≤ Z ≤ nzones.
C Coordinate array index number, where 1 ≤ C ≤ ncoords.
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 for the range prescribed.
ier Error status.

The above functions are used to read and write grid coordinate data by multiple processes in a parallel fashion. To write the data in parallel, first call cgp_coord_write to create an empty data node. This call is identical to cg_coord_write with coord_array set to NULL (no data written). The actual data is then written to the node in parallel using either cgp_coord_write_data or cgp_coord_general_write_data where range_min and range_max specify the subset of coordinate data to be written by a given process. The routines cgp_coord_read_data and cgp_coord_general_read_data perform the same function for reading the coordinate data in parallel.

Note: The routines cgp_coord_general_write_data and cgp_coord_general_read_data perform data conversions if datatype is different from mem_datatype. For other routines, it is the responsibility of the application to ensure that the data type for the coordinate data matches that as defined in the file; no conversions are done.

Element Connectivity Data

Functions Modes
ier = cgp_section_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 = cgp_poly_section_write(int fn, int B, int Z,
      char *ElementSectionName, ElementType_t type, cgsize_t start,
      cgsize_t end, cgsize_t MaxOffset, int nbndry, int *S); 		- w m
ier = cgp_elements_write_data(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, cgsize_t *Elements); 		- w m
ier = cgp_poly_elements_write_data(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, cgsize_t *Elements, cgsize_t *Offsets); 		- w m
ier = cgp_elements_read_data(int fn, int B, int Z, int S,
      cgsize_t start, cgsize_t end, cgsize_t *Elements); 		r - m
call cgp_section_write_f(fn, B, Z, ElementSectionName, type,
     start, end, nbndry, S, ier)
 - w m
call cgp_elements_write_data_f(fn, B, Z, S, start,
     end, Elements, ier)
 - w m
call cgp_elements_read_data_f(fn, B, Z, S, start,
     end, Elements, ier)
 r - m

Input/Output
(Note that for Fortran calls, all integer arguments are integer*4 in 32-bit mode and integer*8 in 64-bit mode. See 64-bit Fortran Portability and Issues.)

    fn   CGNS file index number.
B Base index number, where 1 ≤ B ≤ nbases.
Z Zone index number, where 1 ≤ Z ≤ nzones.
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.
S Element section index, where 1 ≤ S ≤ nsections.
Elements Element connectivity data.
Offsets Element connectivity offsets data.
MaxOffset Maximum data size that should be reserved for Element connectivity data.
ier Error status.

Note: These routines only work for constant sized elements, since it is not possible to compute file offsets for variable sized elements without knowledge of the entire element connectivity data.

The above functions are used to read and write element connectivity data by multiple processes in a parallel fashion. To write the element data in parallel, first call cgp_section_write to create an empty data node. This call is identical to cg_section_write with Elements set to NULL (no data written). The actual element data is then written to the node in parallel using cgp_element_write_data where start and end specify the range of the elements to be written by a given process. The routine cgp_element_read_data performs the same function for reading the solution data in parallel.

Note: It is the responsibility of the application to ensure that cgsize_t in the application is the same size as that defined in the file; no conversions are done.

Solution Data

Functions Modes
ier = cgp_field_write(int fn, int B, int Z, int S,
      DataType_t datatype, char *fieldname, int *F); 		- w m
ier = cgp_field_write_data(int fn, int B, int Z, int S, int F,
      cgsize_t *range_min, cgsize_t *range_max, void *solution_array); 		- w m
ier = cgp_field_general_write_data(int fn, int B, int Z, int S, int F,
      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 *solution_array);
ier = cgp_field_read_data(int fn, int B, int Z, int S, int F,
      cgsize_t *range_min, cgsize_t *range_max, void *solution_array); 		r - m
ier = cgp_field_general_read_data(int fn, int B, int Z, int S, int F,
      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 *solution_array);
call cgp_field_write_f(fn, B, Z, S, datatype, fieldname, F, ier) - w m
call cgp_field_write_data_f(fn, B, Z, S, F,
      range_min, range_max, solution_array, ier) 		- w m
call cgp_field_read_data_f(fn, B, Z, S, F,
      range_min, range_max, solution_array, ier) 		r - m

Input/Output
(Note that for Fortran calls, all integer arguments are integer*4 in 32-bit mode and integer*8 in 64-bit mode. See 64-bit Fortran Portability and Issues.)

    fn   CGNS file index number.
B Base index number, where 1 ≤ B ≤ nbases.
Z Zone index number, where 1 ≤ Z ≤ nzones.
S Flow solution index number, where 1 ≤ S ≤ nsols.
F Solution array index number, where 1 ≤ F ≤ nfields.
datatype Data type of the solution array written to the file. Admissible data types for a solution array are Integer, LongInteger, RealSingle, and RealDouble.
fieldname Name of the solution array. It is strongly advised to use the SIDS nomenclature conventions when naming the solution 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 solution array are Integer, LongInteger, 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).
solution_array Array of solution values for the range prescribed.
ier Error status.

The above functions are used to read and write solution arrays by multiple processes in a parallel fashion. To write the data in parallel, first call cgp_field_write to create an empty data node. This call is identical to cg_field_write with solution_array set to NULL (no data written). The actual data is then written to the node in parallel using either cgp_field_write_data or cgp_field_general_write_data where range_min and range_max specify the subset of the solution data to be written by a given process. The routines cgp_field_read_data and cgp_field_general_read_data perform the same function for reading the solution data in parallel.

Note: The routines cgp_field_general_write_data and cgp_field_general_read_data perform data conversions if datatype is different from mem_datatype. For other routines, it is the responsibility of the application to ensure that the data type for the solution data matches that as defined in the file; no conversions are done.

Array Data

Functions Modes
ier = cgp_array_write(char *arrayname, DataType_t datatype,
      int rank, cgsize_t *dimensions, int *A); 		- w m
ier = cgp_array_write_data(int A, cgsize_t *range_min, cgsize_t *range_max, void *data); - w m
ier = cgp_array_general_write_data(int A,
      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 *data);
ier = cgp_array_read_data(int A, cgsize_t *range_min, cgsize_t *range_max, void *data); r - m
ier = cgp_array_general_read_data(int A,
      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 *data);
call cgp_array_write_f(arrayname, datatype, rank, dimensions, A, ier) - w m
call cgp_array_write_data_f(A, range_min, range_max, data, ier) - w m
call cgp_array_read_data_f(A, range_min, range_max, data, ier) r - m

Input/Output
(Note that for Fortran calls, all integer arguments are integer*4 in 32-bit mode and integer*8 in 64-bit mode. See 64-bit Fortran Portability and Issues.)

    A   Data array index, where 1 ≤ A ≤ narrays.
arrayname Name of the DataArray_t node.
datatype Type of data held in the DataArray_t node. The admissible types are Integer, LongInteger, RealSingle, RealDouble, and Character.
rank Number of dimensions of array in file.
dimensions Dimensions of array in file.
range_min Lower range index in file (eg., imin, jmin, kmin).
range_max Upper range index in file (eg., imax, jmax, kmax).
mem_datatype The type of data held in memory. The admissible types are Integer, LongInteger, RealSingle, RealDouble, and Character.
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).
data The data array.
ier Error status.

The above functions are used to read and write data arrays by multiple processes in a parallel fashion. To write the data in parallel, first call cg_goto to set the position for the DataArray_t node, then call cgp_array_write to create an empty data node. This call is similar to cg_array_write with Data set to NULL (no data written). This function will return the array index, A, which is used to write the actual data to the node in parallel using either cgp_array_write_data or cgp_array_general_write_data where range_min and range_max specify the subset of the array data to be written by a given process. The routines cgp_array_read_data and cgp_array_general_read_data perform the same function for reading the array data in parallel.

Note: The routines cgp_array_general_write_data and cgp_array_general_read_data perform data conversions if datatype is different from mem_datatype. For other routines, it is the responsibility of the application to ensure that the data type for the array data matches that as defined in the file; no conversions are done.

General Remarks
CGNS/PMLL examples
© Copyright 1991-2020, CGNS Steering Commmittee. Created using Sphinx.