CGNS Mid-Level Library - Auxiliary Data

(CGNS Documentation Home Page) (Steering Committee Charter) (Overview and Entry-Level Document) (A User's Guide to CGNS) (Mid-Level Library) (Standard Interface Data Structures) (SIDS File Mapping Manual) (CGIO User's Guide) (Parallel CGNS User's Guide) (ADF Implementation) (HDF5 Implementation) (Python Implementation) (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)

Auxiliary Data

Reference State
- cg_state_write - Create ReferenceState_t node
- cg_state_size - Get length of reference state description string.
- cg_state_read - Read text description of reference state.
Gravity
- cg_gravity_write - Create Gravity_t node
- cg_gravity_read - Read Gravity_t node
Convergence History
- cg_convergence_write - Create ConvergenceHistory_t node
- cg_convergence_read - Read ConvergenceHistory_t node
Integral Data
- cg_integral_write - Create IntegralData_t node
- cg_nintegrals - Get number of IntegralData_t nodes
- cg_integral_read - Get name of an IntegralData_t node
User-Defined Data
- cg_user_data_write - Create UserDefinedData_t node
- cg_nuser_data - Get number of UserDefinedData_t nodes
- cg_user_data_read - Get name of an UserDefinedData_t node
Freeing Memory
- cg_free - Release library-allocated memory

Reference State

Node: ReferenceState_t (SIDS, File Mapping)

Functions	Modes
`ier = cg_state_write(char *StateDescription);`	`- w m`
`ier = cg_state_read(char **StateDescription);`	`r - m`
`call cg_state_write_f(StateDescription, ier)`	`- w m`
`call cg_state_size_f(Size, ier)`	`r - m`
`call cg_state_read_f(StateDescription, ier)`	`r - m`

Input/Output

	`StateDescription`		Text description of reference state.
	`Size`		Number of characters in the `StateDescription` string (Fortran interface only) - integer.
	`ier`		Error status.

The function cg_state_write creates the ReferenceState_t node and must be called even if StateDescription is undefined (i.e., a blank string). The descriptors, data arrays, data class, and dimensional units characterizing the ReferenceState_t data structure may be added to this data structure after its creation.

The function cg_state_read reads the StateDescription of the local ReferenceState_t node. If StateDescription is undefined in the CGNS database, this function returns a null string. If StateDescription exists, the library will allocate the space to store the description string, and return the description string to the application. It is the responsibility of the application to free this space when it is no longer needed by a call to cg_free(StateDescription).

Gravity

Node: Gravity_t (SIDS, File Mapping)

Functions	Modes
`ier = cg_gravity_write(int fn, int B, float *GravityVector);`	`- w m`
`ier = cg_gravity_read(int fn, int B, float *GravityVector);`	`r - m`
`call cg_gravity_write_f(fn, B, GravityVector, ier)`	`- w m`
`call cg_gravity_read_f(fn, B, GravityVector, ier)`	`r - m`

Input/Output

	`fn`		CGNS file index number.
	`B`		Base index number, where 1 ≤ `B` ≤ `nbases`.
	`GravityVector`		Components of the gravity vector. The number of components must equal `PhysicalDimension`. (In Fortran, this is an array of Real*4 values.)
	`ier`		Error status.

Convergence History

Node: ConvergenceHistory_t (SIDS, File Mapping)

Functions	Modes
`ier = cg_convergence_write(int niterations, char *NormDefinitions);`	`- w m`
`ier = cg_convergence_read(int niterations, char *NormDefinitions);`	`r - m`
`call cg_convergence_write_f(niterations, NormDefinitions, ier)`	`- w m`
`call cg_convergence_read_f(niterations, NormDefinitions, ier)`	`r - m`

Input/Output

	`niterations`		Number of iterations for which convergence information is recorded.
	`NormDefinitions`		Description of the convergence information recorded in the data arrays.
	`ier`		Error status.

The function cg_convergence_write creates a ConvergenceHistory_t node. It must be the first one called when recording convergence history data. The NormDefinitions may be left undefined (i.e., a blank string). After creation of this node, the descriptors, data arrays, data class, and dimensional units characterizing the ConvergenceHistory_t data structure may be added.

The function cg_convergence_read reads a ConvergenceHistory_t node. If NormDefinitions is not defined in the CGNS database, this function returns a null string. If NormDefinitions exists, the library will allocate the space to store the description string, and return the description string to the application. It is the responsibility of the application to free this space when it is no longer needed by a call to cg_free(NormDefinitions).

Integral Data

Node: IntegralData_t (SIDS, File Mapping)

Functions	Modes
`ier = cg_integral_write(char *Name);`	`- w m`
`ier = cg_nintegrals(int *nintegrals);`	`r - m`
`ier = cg_integral_read(int Index, char *Name);`	`r - m`
`call cg_integral_write_f(Name, ier)`	`- w m`
`call cg_nintegrals_f(nintegrals, ier)`	`r - m`
`call cg_integral_read_f(Index, Name, ier)`	`r - m`

Input/Output

	`Name`		Name of the `IntegralData_t` data structure.
	`nintegrals`		Number of `IntegralData_t` nodes under current node.
	`Index`		Integral data index number, where 1 ≤ `Index` ≤ `nintegrals`.
	`ier`		Error status.

User-Defined Data

Node: UserDefinedData_t (SIDS, File Mapping)

Functions	Modes
`ier = cg_user_data_write(char *Name);`	`- w m`
`ier = cg_nuser_data(int *nuserdata);`	`r - m`
`ier = cg_user_data_read(int Index, char *Name);`	`r - m`
`call cg_user_data_write_f(Name, ier)`	`- w m`
`call cg_nuser_data_f(nuserdata, ier)`	`r - m`
`call cg_user_data_read_f(Index, Name, ier)`	`r - m`

Input/Output

	`nuserdata`		Number of `UserDefinedData_t` nodes under current node.
	`Name`		Name of the `UserDefinedData_t` node.
	`Index`		User-defined data index number, where 1 ≤ `Index` ≤ `nuserdata`.
	`ier`		Error status.

After accessing a particular UserDefinedData_t node using cg_goto, the Point Set functions may be used to read or write point set information for the node. The function cg_gridlocation_write may also be used to specify the location of the data with respect to the grid (e.g., Vertex or FaceCenter).

Multiple levels of UserDefinedData_t nodes may be written and retrieved by positioning via cg_goto. E.g.,

   ier = cg_goto(fn, B, "Zone_t", Z, "UserDefinedData_t", ud1, 
                 "UserDefinedData_t", ud2, "UserDefinedData_t", ud3, "end");

Freeing Memory

Functions	Modes
`ier = cg_free(void *data);`	`r w m`

Input/Output

	`data`		Data allocated by the Mid-Level Library.
	`ier`		Error status.

This function does not affect the structure of a CGNS file; it is provided as a convenience to free memory allocated by the Mid-Level Library. This isn't necessary in Fortran, and thus an equivalent Fortran function is not provided.

The functions that are used to allocate memory for return values are cg_descriptor_read, cg_convergence_read, cg_geo_read, cg_link_read, and cg_state_read. Each of these may allocate space to contain the data returned to the application. It is the responsibility of the application to free this data when it is no longer needed. Calling cg_free is identical to calling the standard C function free, however it is probably safer in that the memory is freed in the same module in which it is created, particularly when the Mid-Level Library is a shared library or DLL. The routine checks for NULL data and will return CG_ERROR in this case, otherwise it returns CG_OK.