Next: , Previous: , Up: Variables   [Index]


4.20 Read a Mapped Array of Values: ncmpi_get_varm_<type>

The ncmpi_get_varm_<type> family of functions reads a mapped array section of values from a netCDF variable of an opened netCDF file. The mapped array section is specified by giving a corner, a vector of edge lengths, a stride vector, and an index mapping vector. The index mapping vector is a vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. No assumptions are made about the ordering or length of the dimensions of the data array.

The most common use case for this API is to read a matrix-transposed array. See an example below.

Data types

<type > for API names <C type> for API arguments
text char
schar signed char
short short
int int
float float
double double
uchar unsigned char
ushort unsigned short
uint unsigned int
longlong long long
ulonglong unsigned longlong

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_varm_<type>     (int                  ncid,
                                int                 varid,
                                const MPI_Offset    start[],
                                const MPI_Offset    count[],
                                const MPI_Offset    stride[],
                                const MPI_Offset    imap[],
                                <C type>           *buf);

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

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

int ncmpi_get_varm_all         (int                 ncid,
                                int                 varid,
                                const MPI_Offset    start[],
                                const MPI_Offset    count[],
                                const MPI_Offset    stride[],
                                const MPI_Offset    imap[],
                                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).

imap

A vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. imap[0] gives the distance between elements of the internal array corresponding to the most slowly varying dimension of the netCDF variable. imap[n-1] (where n is the rank of the netCDF variable) gives the distance between elements of the internal array corresponding to the most rapidly varying dimension of the netCDF variable. Intervening imap elements correspond to other dimensions of the netCDF variable in the obvious way. Distances between elements are specified in type-independent units of elements (the distance between internal elements that occupy adjacent memory locations is 1 and not the element’s byte-length as in netCDF 2).

buf

Pointer to the location used for computing where the data values are read; the data should be of the type appropriate for the function called. 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

get_varm mapping

Return Error Codes

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

Example

The following imap vector maps in the trivial way a 4x3x2 netCDF variable and an internal array of the same shape:

float a[4][3][2];       /* same shape as netCDF variable */
MPI_Offset imap[3] = {6, 2, 1};
                        /* netCDF dimension       inter-element distance */
                        /* ----------------       ---------------------- */
                        /* most rapidly varying       1                  */
                        /* intermediate               2 (=imap[2]*2)     */
                        /* most slowly varying        6 (=imap[1]*3)     */

Using the imap vector above with ncmpi_get_varm_float_all obtains the same result as simply using ncmpi_get_var_float.

Here is an example of using ncmpi_get_varm_float_all to transpose a netCDF variable named rh which is described by the C declaration float rh[6][4] (note the size and order of the dimensions):

#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: */
                 = {0, 0};   /* first element */
MPI_Offset count[NDIM]       /* size of internal array: entire netCDF */
                 = {6, 4};   /* variable; order corresponds to netCDF */
                             /* variable -- not internal array */
MPI_Offset stride[NDIM]      /* variable subsampling intervals: */
                 = {1, 1};   /* sample every netCDF element */
MPI_Offset imap[NDIM]        /* internal array inter-element distances; */
                 = {1, 6};   /* would be {4, 1} if not transposing */
float rh[4][6];              /* note transposition of netCDF variable */
                             /* dimensions */
   ... 
status = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_WRITE, MPI_INFO_NULL,  &ncid);
if (status != NC_NOERR) handle_error(status);
   ... 
status = ncmpi_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
   ... 
status = ncmpi_get_varm_float_all(ncid, rhid, start, count, stride, imap, rh);
if (status != NC_NOERR) handle_error(status);

Here is another example of using ncmpi_get_varm_float_all to simultaneously transpose and subsample the same netCDF variable, by accessing every other point of the netCDF variable:

#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: */
                 = {0, 0};   /* first element */
MPI_Offset count[NDIM]       /* size of internal array: entire */
                 = {3, 2};   /* (subsampled) netCDF variable; order of */
                             /* dimensions corresponds to netCDF */
                             /* variable -- not internal array */
MPI_Offset stride[NDIM]      /* variable subsampling intervals: */
                 = {2, 2};   /* sample every other netCDF element */
MPI_Offset imap[NDIM]        /* internal array inter-element distances; */
                 = {1, 3};   /* would be {2, 1} if not transposing */
float rh[2][3];              /* note transposition of (subsampled) */
                             /* netCDF variable dimensions */
   ... 
status = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_WRITE, MPI_INFO_NULL,  &ncid);
if (status != NC_NOERR) handle_error(status);
   ... 
status = ncmpi_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
   ... 
status = ncmpi_get_varm_float_all(ncid, rhid, start, count, stride, imap, rh);
if (status != NC_NOERR) handle_error(status);

Next: , Previous: , Up: Variables   [Index]