Particle Specification¶

CGNS Mid-Level Library - Particle Specification

Particle Specification

Particle Information
- cg_particle_write - Create and/or write to a particle node
- cg_nparticle_zones - Get number of particle nodes in base
- cg_particle_read - Read particle information
Particle Coordinates
- cg_particle_coord_node_write - Write a ParticleCoordinates_t node
- cg_particle_ncoord_nodes - Get number of ParticleCoordinates_t nodes
- cg_particle_coord_node_read - Get name of a ParticleCoordinates_t node
- cg_particle_bounding_box_read - Get bounding box associated to a ParticleCoordinates_t node
- cg_particle_bounding_box_write - Write bounding box associated to a ParticlesCoordinates_t node
- cg_particle_coord_write - Write particle coordinates
- cg_particle_coord_partial_write - Write subset of particle coordinates
- cg_particle_coord_general_write - Write shaped array to a subset of particle coordinates
- cg_particle_ncoords - Get number of particle coordinate arrays
- cg_particle_coord_info - Get info about a particle coordinate array
- cg_particle_coord_read - Read particle coordinates
- cg_particle_coord_general_read - Read subset of particle coordinates to a shaped array

Particle

Node: ParticleZone_t (SIDS, File Mapping)

Functions	Modes
`ier = cg_particle_write(int fn, int B, char particlename, int P);`	`- w m`
`ier = cg_nparticle_zones(int fn, int B, int P, int *nparticlezones);`	`- w m`
`ier = cg_particle_read(int fn, int B, int P, char *particlename);`	`r - m`
`call cg_particle_write_f(fn, B, P, particlename, ier)`	`- w m`
`call cg_nparticle_zones_f(fn, B, P, nparticlezones, ier)`	`- w m`
`call cg_particle_read_f(fn, B, P, particlename, ier)`	`r - m`

Input/Output

	`fn`		CGNS file index number.
	`B`		Base index number, where 1 ≤ `B` ≤ `nbases`.
	`P`		Particle index number, where 1 ≤ `P` ≤ `nparticlezones`.
	`particlename`		Name of the `ParticleZone_t` node.
	`ier`		Error status.

Note: When a CGNS file is opened via the cg_open() MLL function, the particle zones are sorted alphanumerically by name (the creation order is ignored/discarded). It is considered good standard practice to always choose particle names to be alphabetically increasing. For example, Particle0001, Particle0002, etc. is appropriate for up to 9999 particles.

Particle Coordinates

Node: ParticleCoordinates_t (SIDS, File Mapping)

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

Functions	Modes
`ier = cg_particle_coord_node_write(int fn, int B, int P, char pcoordname, int C);`	`- w m`
`ier = cg_particle_ncoord_nodes(int fn, int B, int P, int *ncoord_nodes);`	`- w m`
`ier = cg_particle_coord_node_read(int fn, int B, int P, int C, char *pcoordname);`	`r - m`
`ier = cg_particle_bounding_box_write(int fn, int B, int P, int C, DataType_t datatype, void *bbox_array);`	`- w m`
`ier = cg_particle_bounding_box_read(int fn, int B, int P, int C, DataType_t datatype, void *bbox_array);`	`r - m`
`call cg_particle_coord_node_write_f(fn, B, P, pcoodname, C, ier)`	`- w m`
`call cg_particle_ncoord_nodes_f(fn, B, P, ncoord_nodes, ier)`	`- w m`
`call cg_particle_coord_node_read_f(fn, B, P, C, pcoordname, ier)`	`r - m`
`call cg_particle_bounding_box_write_f(fn, B, P, C, datatype, bbox_array, ier)`	`- w m`
`call cg_particle_bounding_box_read_f(fn, B, P, C, datatype, bbox_array, ier)`	`r - m`

Input/Output

	`fn`		CGNS file index number.
	`B`		Base index number, where 1 ≤ `B` ≤ `nbases`.
	`P`		Particle index number, where 1 ≤ `P` ≤ `nparticlezones`.
	`C`		Location index number, where 1 ≤ `C` ≤ `ncoord_nodes`.
	`ncoord_nodes`		Number of `ParticleCoordinates_t` nodes for particle `P`.
	`pcoordname`		Name of the `ParticleCoordinates_t` node. Note that the name "`ParticleCoordinates`" is reserved for the original particle coord_node and must be the first `ParticleCoordinates_t` node to be defined.
	`ier`		Error status.

The above functions are applicable to any ParticleCoordinates_t node.

Functions	Modes
`ier = cg_particle_coord_write(int fn, int B, int P, DataType_t datatype, char coordname, void coord_array, int *C);`	`- w m`
`ier = cg_particle_coord_partial_write(int fn, int B, int P, DataType_t datatype, char coordname, cgsize_t range_min, cgsize_t range_max, void coord_array, int *C);`	`- w m`
`ier = cg_particle_coord_general_write(int fn, int B, int P, 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 P, int *ncoords);`	`r - m`
`ier = cg_particle_coord_info(int fn, int B, int P, int C, DataType_t datatype, char coordname);`	`r - m`
`ier = cg_particle_coord_read(int fn, int B, int P, char coordname, DataType_t mem_datatype, cgsize_t range_min, cgsize_t range_max, void coord_array);`	`r - m`
`ier = cg_particle_coord_general_read(int fn, int B, int P, 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_particle_coord_write_f(fn, B, Z, datatype, coordname, coord_array, C, ier)`	`- w m`
`call cg_particle_coord_partial_write_f(fn, B, Z, datatype, coordname, range_min, range_max, coord_array, C, ier)`	`- w m`
`call cg_particle_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_particle_coord_info_f(fn, B, Z, C, datatype, coordname, ier)`	`r - m`
`call cg_particle_coord_read_f(fn, B, Z, coordname, mem_datatype, range_min, range_max, coord_array, ier)`	`r - m`
`call cg_particle_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 ≤ `B` ≤ `nbases`.
	`P`		Particle index number, where 1 ≤ `P` ≤ `nparticlezones`.
	`C`		Coordinate array index number, where 1 ≤ `C` ≤ `ncoords`.
	`ncoords`		Number of coordinate arrays for particle `P`.
	`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.
	`range_max`		Upper range index in file.
	`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.
	`mem_range_max`		Upper range index in memory.
	`coord_array`		Array of coordinate values.
	`ier`		Error status.

The above functions are applicable only to the ParticleCoordinates_t node named ParticleCoordinates, used for the original particle positions in a ParticleZone_t node. Coordinates for additional ParticleCoordinates_t nodes in a ParticleZone_t node must be read and written using the cg_array_xxx functions.

When writing, the function cg_particle_coord_write will automatically write the full range of coordinates (i.e., the entire coord_array). The functions cg_particle_coord_partial_write and cg_particle_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_particle_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_particle_coord_general_read and cg_particle_coord_general_write allow for type conversion when both reading from and writing to the file.