4.19 Read a Subsampled Array of Values: ncmpi_get_vars_<type>

The ncmpi_get_vars_<type> family of functions read a subsampled (strided) array section of values from a netCDF variable of an opened netCDF file. The subsampled array section is specified by giving a corner, a vector of edge lengths, and a stride vector. The values are read with the last dimension of the netCDF variable varying fastest.

Data types

Operational Mode

These API must be called while the file is in data mode.

Collective I/O

The corresponding collective APIs have the suffix name "_all" and must be called in collective data mode.

Usage

int ncmpi_get_vars_<type>     (int                  ncid,
                                int                 varid,
                                const MPI_Offset    start[],
                                const MPI_Offset    count[],
                                const MPI_Offset    stride[],
                                <C type>           *buf);

int ncmpi_get_vars             (int                 ncid,
                                int                 varid,
                                const MPI_Offset    start[],
                                const MPI_Offset    count[],
                                const MPI_Offset    stride[],
                                void               *buf,
                                MPI_Offset          bufcount,
                                MPI_Datatype        buftype);

int ncmpi_get_vars_<type>_all (int                  ncid,
                                int                 varid,
                                const MPI_Offset    start[],
                                const MPI_Offset    count[],
                                const MPI_Offset    stride[],
                                <C type>           *buf);

int ncmpi_get_vars_all         (int                 ncid,
                                int                 varid,
                                const MPI_Offset    start[],
                                const MPI_Offset    count[],
                                const MPI_Offset    stride[],
                                void               *buf,
                                MPI_Offset          bufcount,
                                MPI_Datatype        buftype);

ncid

NetCDF ID, from a previous call to ncmpi_open or ncmpi_create.

varid

Variable ID. Different MPI processes may use different variable IDs.

start

A vector of MPI_Offset integers specifying the index in the variable where the first of the data values will be read. The indices are relative to 0, so for example, the first data value of a variable would have index (0, 0, ... , 0). The elements of start correspond, in order, to the variable’s dimensions. Hence, if the variable is a record variable, the first index corresponds to the starting record number for reading the data values.

count

A vector of MPI_Offset integers specifying the number of indices selected along each dimension. To read a single value, for example, specify count as (1, 1, ... , 1). The elements of count correspond, in order, to the variable’s dimensions. Hence, if the variable is a record variable, the first element of count corresponds to a count of the number of records to read.

stride

A vector of MPI_Offset integers specifying, for each dimension, the interval between selected indices. The elements of the stride vector correspond, in order, to the variable’s dimensions. A value of 1 accesses adjacent values of the netCDF variable in the corresponding dimension; a value of 2 accesses every other value of the netCDF variable in the corresponding dimension; and so on. A NULL stride argument is treated as (1, 1, ... , 1).

buf

Pointer to a block of contiguous locations in memory into which the data values are read. If the type of data value differs from the netCDF variable type, type conversion will occur.

bufcount

An integer indicates the number of MPI derived data type elements in the buf to be read from the file.

buftype

An MPI derived data type that describes the memory layout of buf. Starting from PnetCDF version 1.6.0, buftype can be MPI_DATATYPE_NULL. In this case, bufcount is ignored and the buf’s data type must match the type of the variable defined in the file - no data conversion will be done.

Layout Illustration for Read Buffer in Memory and Data Read from File

Return Error Codes

ncmpi_get_vars_<type> returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

• NC_EBADID: The specified netCDF ID does not refer to an opened netCDF file.
• NC_ENOTVAR: The variable ID is invalid for the specified netCDF file.
• NC_EGLOBAL: NC_GLOBAL is considered invalid for these APIs.
• NC_EINVALCOORDS: The specified corner indices were out of range for the rank of the specified variable. For example, a negative index, or an index that is larger than the corresponding dimension length will cause an error.
• NC_EEDGE: The specified edge lengths added to the specified corner would have referenced data out of range for the rank of the specified variable. For example, an edge length that is larger than the corresponding dimension length minus the corner index will cause an error.
• NC_ERANGE: One or more elements of the external variable are out of the range of values representable by the internal data type of read buffer, buf. (Does not apply to the ncmpi_get_vars() and ncmpi_get_vars_all()).
• NC_EINDEFINE: Operation not allowed in define mode.
• NC_ECHAR: Attempt to convert numerical values to or from text data.
• NC_ENOMEM: Out of memory.
• NC_EINDEP: Attempt collective I/O operations in independent data mode.
• NC_ENOTINDEP: Attempt independent I/O operations in collective data mode.
• NC_EIOMISMATCH: The number of variable elements requested in (bufcount, buftype) mismatches the one calculated from count. This error may only occur for flexible APIs.
• NC_ENOTSUPPORT: Flexible APIs for NetCDF-4 files is not yet supported.

Example

Here is an example of using ncmpi_get_vars_float_all to read every other point of a netCDF variable named rh in parallel which is described by the C declaration float rh[4][6] (note the size of the dimensions). In this example, we assume there are 4 MPI processes running. The parallel read reads the entire 4x6 array.

#include <pnetcdf.h>
   ... 
#define NDIM 2                    /* rank of netCDF variable */
int ncid;                         /* netCDF ID */
int status;                       /* error status */
int rhid;                         /* variable ID */
MPI_Offset start[NDIM];           /* netCDF variable start point: first element */
MPI_Offset count[NDIM] = {2, 3};  /* size of internal array: entire (subsampled) netCDF variable */
MPI_Offset stride[NDIM] = {2, 2}; /* variable subsampling intervals: access every other netCDF element */
float rh[2][3];                   /* note subsampled sizes for netCDF variable dimensions */
   ... 
/* open the file in read-only mode */
status = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_NOWRITE, MPI_INFO_NULL, &ncid);
if (status != NC_NOERR) handle_error(status);
   ... 
/* inquire variable ID */
status = ncmpi_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
   ... 
/* set the starting indices and read lengths for this process */
MPI_Comm_rank(MPI_COMM_WORLD, &rank);
if (rank == 0) {
    start[0] = 0;
    start[1] = 0;                 /* read locations by process rank IDs:
} else if (rank == 1) {              0 1 0 1 0 1
    start[0] = 0;                    2 3 2 3 2 3
    start[1] = 1;                    0 1 0 1 0 1
} else if (rank == 2) {              2 3 2 3 2 3
    start[0] = 1;                  */
    start[1] = 0;
} else if (rank == 3) {
    start[0] = 1;
    start[1] = 1;
}
   ... 
/* collectively read the variable */
status = ncmpi_get_vars_float_all(ncid, rhid, start, count, stride, rh);
if (status != NC_NOERR) handle_error(status);