Variables

Variable is a core component of a netCDF file representing an array of data values organized along one or more dimensions, with associated metadata in the form of attributes. An instance of class pnetcdf.Variable represents a NetCDF variable stored in the file. The class methods provide I/O operations to read and write the data and metadata of a NetCDF variable.

Reading and writing a subarray of a variable can be done through either explicit function-call style methods or Python indexer-style (numpy-like) syntax.

class pnetcdf.Variable

Bases: object

A PnetCDF variable is used to read and write netCDF data. They are analogous to numpy arrays. See Variable.__init__() for more details.

Note

Variable instances should be created using the File.def_var() method of a File() instance, not using this class constructor directly.

__init__(self, file, name, datatype, dimensions=(), fill_value=None, **kwargs)

The constructor for pnetcdf.Variable.

Parameters:

varname (str) – Name of the new variable.
datatype –
The data type of the new variable. It can be a string that describes a numpy dtype object, a numpy dtype object, or one of PnetCDF data type constant, as shown below.
- pnetcdf.NC_CHAR or S1 for 1-character string
- pnetcdf.NC_BYTE or i1 for 1-byte integer
- pnetcdf.NC_SHORT or i2 for 2-byte signed integer
- pnetcdf.NC_INT or i4 for 4-byte signed integer
- pnetcdf.NC_FLOAT or f4 for 4-byte floating point number
- pnetcdf.NC_DOUBLE or f8 for 8-byte real number in double precision
The following additional data types are available for CDF-5 format.
- pnetcdf.NC_UBYTE or u1 for unsigned 1-byte integer
- pnetcdf.NC_USHORT or u2 for unsigned 2-byte integer
- pnetcdf.NC_UINT or u4 for unsigned 4-byte integer
- pnetcdf.NC_INT64 or i8 for signed 8-byte integer
- pnetcdf.NC_UINT64 or u8 for unsigned 8-byte integer
dimensions (tuple of str or pnetcdf.Dimension instances) – [Optional] The dimensions of the new variable. Can be either dimension names or dimension class instances. Default is an empty tuple which means the variable is a scalar (and therefore has no dimensions).
fill_value –
[Optional] The fill value of the new variable. Accepted values are shown below.
- None to use the default netCDF fill value for the given data type.
- False to turn off the fill mode.
- If specified with other value, the default netCDF _FillValue (the value that the variable gets filled with before any data is written to it) is replaced with this value.

Returns:

The created variable

Return type:

pnetcdf.Variable

Example:

A example is available in examples/put_var.py

# Define dimensions
dim_y = f.def_dim("Y", global_ny)
dim_x = f.def_dim("X", global_nx)

# Define a 2D variable of integer type, using :meth:`File.def_var`.
var = f.def_var("var", pnetcdf.NC_INT, (dim_y, dim_x))

# Or equivalently, using :meth:`File.createVariable`.
var = f.createVariable("var", pnetcdf.NC_INT, (dim_y, dim_x))

bput_var(self, data, start=None, count=None, stride=None, imap=None, bufcount=None, buftype=None)

Method to post a nonblocking, buffered write request to write to the netCDF variable. The syntax is the same as Variable.put_var(). For the argument usage, please refer to Variable.put_var_all(). This method returns a request ID that can be used in File.wait_all() or File.wait(). The posted write request may not be committed until File.wait_all() or File.wait() is called.

Note

Note that this method requires a numpy array (data) as a write buffer from caller prepared for writing returned array values when File.wait_all() or File.wait() is called. Unlike Variable.iput_var(), the write data is buffered (cached) internally by PnetCDF and will be flushed to the file at the time of calling File.wait_all() or File.wait(). Once the call to this method returns, the caller is free to change the contents of write buffer. Prior to calling this method, make sure File.attach_buff() is called to allocate an internal buffer for accommodating the write requests.

Returns:: The request ID, which can be used in a successive call to File.wait_all() or File.wait() for the completion of the nonblocking operation.
Return type:: int
Operational mode:: This method can be called while the file is in either collective or independent data mode.

bput_varn(self, data, num, starts, counts=None, bufcount=None, buftype=None)

This method call is the nonblocking, buffered counterpart of Variable.put_varn(). For the argument usage, please refer to method Variable.put_varn_all(). This method returns a request ID that can be used in File.wait_all() or File.wait(). The posted write request may not be committed until File.wait_all() or File.wait() is called.

Note

Unlike Variable.iput_varn(), the write data is buffered (cached) internally by PnetCDF and will be flushed to the file at the time of calling File.wait_all() or File.wait(). Once the call to this method returns, the caller is free to change the contents of write buffer. Prior to calling this method, make sure File.attach_buff() is called to allocate an internal buffer for accommodating the write requests.

Returns:: The request ID, which can be used in a successive call to File.wait_all() or File.wait() for the completion of the nonblocking operation.
Return type:: int

def_fill(self, int no_fill, fill_value = None)

Sets the fill mode for a variable. This API must be called while the file is in the define mode, and after the variable is defined.

Parameters:

no_fill (int) – Set no_fill mode for a variable. 1 for on (not to fill) and 0 for off (to fill).
fill_value (any) – Sets the customized fill value. Must be the same type as the variable. This will be written to a _FillValue attribute, created for this purpose. If None, this argument will be ignored and the default fill value is used.

Example:

A example is available in examples/fill_mode.py

# set the variable's fill mode to NC_FILL with PnetCDF default fill value
var.def_fill(no_fill = 0)

# enable the variable's fill mode and use a customized value
fill_value = np.int32(-1)
var.def_fill(no_fill = 0, fill_value = fill_value)

# Equivalently this can be done by setting the PnetCDF pre-defined attribute "_FillValue"
var._FillValue = fill_value

del_att(self, name, value)

Delete a netCDF variable attribute.

Parameters:: name (str) – Name of the attribute
Operational mode:: This method must be called while the associated netCDF file is in define mode.

file(self)

Return the netCDF file instance that the variable is contained in.

Return type:: pnetcdf.File

fill_rec(self, int rec_no)

Fills a record of a record variable with predefined or user-defined fill values.

Parameters:: rec_no (int) – the index of the record to be filled

get_att(self, name, encoding='utf-8')

Retrieve an attribute of a netCDF variable.

Parameters:

name (str) – Name of the attribute.
encoding – specify the character encoding of a string attribute (default is utf-8).

Return type:

str or numpy.ndarray

Operational mode:

This method can be called while the file is in either define or data mode (collective or independent).

Example:

A example is available in examples/get_var.py

# Get attribute named "foo_attr"
str_att = v.get_att("foo_attr")

# Equivalently, uses python dictionary way
str_att = v.foo_attr

get_dims(self)

Returns:: a tuple of Dimension instances associated with this variable.
Return type:: tuple of Dimension

get_var(self, data, start=None, count=None, stride=None, imap=None, bufcount=None, buftype=None)

Method to read in parallel from the netCDF variable in the independent I/O mode. For the argument usage, please refer to method Variable.get_var_all(). The only difference is this method is a independent operation.

Operational mode:: This method must be called while the file is in independent data mode.

get_var_all(self, data, start=None, count=None, stride=None, imap=None, bufcount=None, buftype=None)

Method to read in parallel from the netCDF variable in the collective I/O mode. The behavior of the method varies depends on the pattern of provided optional arguments - start, count, stride, and imap. The method requires a empty array (data) as a read buffer from caller to store returned array values.

data - Read an entire variable.
Read all the values from a netCDF variable of an opened netCDF file. This is the simplest interface to use for reading the value of a scalar variable or when all the values of a multidimensional variable can be read at once.

Note

Be careful when using this simplest form to read a record variable when you don’t specify how many records are to be read. If you try to read all the values of a record variable into an array but there are more records in the file than you assume, more data will be read than you expect, which may cause a segmentation violation.
data, start - Read a single data value (a single element).
Put a single array element specified by start from a variable of an opened netCDF file that is in data mode. For example, start = [0,5] would specify the following position in a 4 * 10 two-dimensional variable (“-” means skip).
- - - - - a - - - - - - - - - - - - - - -> a - - - - - - - - - - - - - - - - - - - -
data, start, count - Read a subarray of values.
The part of the netCDF variable to read is specified by giving a corner index and a vector of edge lengths that refer to an array section of the netCDF variable. For example, start = [0,5] and count = [2,2] would specify the following array section in a 4 * 10 two-dimensional variable (“-” means skip).
- - - - - a b - - - - - - - - c d - - - a b - - - - - - - - - - -> c d - - - - - - - - - -
data, start, count, stride - Read a subarray of values with strided space.
The part of the netCDF variable to read is specified by giving a corner, a vector of edge lengths and stride vector that refer to a subsampled array section of the netCDF variable. For example, start = [0,2], count = [2,4] and stride = [1,2] would specify the following array section in a 4 * 10 two-dimensional variable (“-” means skip).
- - a - b - c - d - - - e - f - g - h - a b c d - - - - - - - - - - -> e f g h - - - - - - - - - -
data, start, count, stride, imap - Read a mapped array of values.
The mapped array section is specified by giving a corner, a vector of counts, a stride vector, and an index mapping vector. The index mapping vector (imap) 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. For example, imap = [3,8], start = [0,5] and count = [2,2] would specify the following section in read butter and array section in a 4 * 10 two-dimensional variable (“-” means skip).
- - - - - a c - - - a - - b a c - - - - - b d - - - - - - - <= b d <= - - - - - - - - - - c - - d - - - - - - - - - - distance from a to b is 3 in buffer => imap[0] = 3 distance from a to c is 8 in buffer => imap[1] = 8

Parameters:

data (numpy.ndarray) – the numpy array that stores array values to be read from the file, which serves as a read buffer. The datatype should match with the variable’s datatype. Note this numpy array read buffer can be in any shape as long as the number of elements (buffer size) is matched.
start (numpy.ndarray) – [Optional] Only relevant when reading a array of values, a subsampled array, a mapped array or a list of subarrays. An array of integers specifying the index in the variable where the first of the data values will be written. The elements of start must correspond to the variable’s dimensions in order. Hence, if the variable is a record variable, the first index would correspond to the starting record number for reading the data values.
count (numpy.ndarray) – [Optional] Only relevant when reading a array of values, a subsampled array, a mapped array or a list of subarrays. An array of integers specifying the edge lengths along each dimension of the block of data values to be read. The elements of count must correspond to the variable’s dimensions in order. Hence, if the variable is a record variable, the first index would correspond to the starting record number for reading the data values.
stride (numpy.ndarray) – [Optional] Only relevant when reading a subsampled array or a mapped array. An array of integers specifying the sampling interval along each dimension of the netCDF variable. The elements of the stride vector correspond, in order, to the netCDF variable’s dimensions.
imap (numpy.ndarray) – [Optional] Only relevant when reading a subsampled array or a mapped array. An array of integers the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. The elements of the index mapping vector correspond, in order, to the netCDF variable’s dimensions. Each element value of imap should equal the memory location distance in read buffer between two adjacent elements along the corresponding dimension of netCDF variable.
bufcount (int) – [Optional] Optional for all types of reading patterns. An integer indicates the number of MPI derived data type elements in the read buffer to store data read from the file.
buftype (mpi4py.MPI.Datatype) – [Optional] An MPI derived data type that describes the memory layout of the read buffer.

Operational mode:

This method must be called while the file is in collective data mode.

Example:

A example is available in examples/get_var.py

# allocate read buffer
r_buf = np.empty(tuple(count), v.dtype)

# Read a subarray in collective mode
v.get_var_all(r_buf, start = start, count = count)

# Equivalently, below uses python index style
end = [start[i] + count[i] for i in range(2)]
r_bufs = v[start[0]:end[0], start[1]:end[1]]

get_varn(self, data, num, starts, counts=None, bufcount=None, buftype=None): This method call is the same as method Variable.get_varn_all(), except it is an independent call and can only be called while the file in the independent I/O mode. Please refer to Variable.get_varn_all() for its argument usage.

get_varn_all(self, data, num, starts, counts=None, bufcount=None, buftype=None)

Method to read multiple subarrays of a netCDF variables from the file. This a collective I/O call and can only be called when the file is in the collective I/O mode. This method is equivalent to making multiple calls to Variable.get_var(). Note, combining multiple get_var calls into one can achieve a better performance.

data, num,`starts`, counts - Write multiple subarrays of values.

The part of the netCDF variable to read is specified by giving multiple subarrays and each subarray is specified by a corner and a vector of edge lengths that refer to an array section of the netCDF variable. The example code and diagram below illustrates a 4 subarray section in a 4 * 10 two-dimensional variable (“-” means skip).

num = 4

starts[0][0] = 0; starts[0][1] = 5; counts[0][0] = 1; counts[0][1] = 2
starts[1][0] = 1; starts[1][1] = 0; counts[1][0] = 1; counts[1][1] = 1
starts[2][0] = 2; starts[2][1] = 6; counts[2][0] = 1; counts[2][1] = 2
starts[3][0] = 3; starts[3][1] = 0; counts[3][0] = 1; counts[3][1] = 3

                     -  -  -  -  -  a  b  -  -  -
a b c d e f g h  <-  c  -  -  -  -  -  -  -  -  -
                     -  -  -  -  -  -  d  e  -  -
                     f  g  h  -  -  -  -  -  -  -

Parameters:

data (numpy.ndarray) – the numpy array that stores array values to be read, which serves as a read buffer. When reading a single data value, it can also be a single numeric (e.g. np.int32) python variable. The datatype should match with the variable’s datatype. Note this numpy array read buffer can be in any shape as long as the number of elements (buffer size) is matched. If the in-memory type of data values differs from the netCDF variable type defined in the file, type conversion will automatically be applied.
num (int) – An integer specifying the number of subarrays.
starts (numpy.ndarray) – A 2D array of integers containing starting array indices of num number of subarrays. The first dimension of starts should be of size num, indicating the number of subarrays of the variable to be read. The second dimension is of size equal to the number dimensions of the variable. For example, when num = 3 and the variable defined in the file is a 2D array, starts should be a 3x2 array. Each of the subarray starting indices identify the indices in the variable where the first of the data values will be read. Each starts[i] is a vector specifying the index in the variable where the first of the data values will be read. The elements of starts[i][*] must correspond to the variable’s dimensions in order. Hence, if the variable is a record variable, the first index, starts[i][0] would correspond to the starting record number for reading the data values.
counts (numpy.ndarray) – [Optional] A 2D array of integers specifying the lengths along each dimension of num number of subarrays to be read. The first dimension of counts should be of size num, indicating the number of subarrays of the variable to be read. The second dimension is of size equal to the number dimensions of the variable. For example, when num = 3 and the variable defined in the file is a 2D array, counts should be a 3x2 array. Each of the subarray counts[i] is a vector specifying the lengths along each dimension of the block of data values to be read and must correspond to the variable’s dimensions in order. When this argument is not supplied, it is equivalent to providing counts of all 1s.
bufcount (int) – [Optional] An integer indicates the number of MPI derived data type elements in the read buffer to store data read from the file.
buftype (mpi4py.MPI.Datatype) – [Optional] An MPI derived data type that describes the memory layout of the write buffer.

Example:

an example code fragment is given below.

num_reqs = 4
starts = np.zeros((num_reqs, NDIMS), dtype=np.int64)
counts = np.zeros((num_reqs, NDIMS), dtype=np.int64)
starts[0][0] = 0; starts[0][1] = 5; counts[0][0] = 1; counts[0][1] = 2
starts[1][0] = 1; starts[1][1] = 0; counts[1][0] = 1; counts[1][1] = 1
starts[2][0] = 2; starts[2][1] = 6; counts[2][0] = 1; counts[2][1] = 2
starts[3][0] = 3; starts[3][1] = 0; counts[3][0] = 1; counts[3][1] = 3

v.get_varn_all(r_buf, num = num_reqs, starts = starts, counts = counts)

iget_var(self, data, start=None, count=None, stride=None, imap=None, bufcount=None, buftype=None)

Method to post a nonblocking request to read from the netCDF variable. The syntax is the same as Variable.get_var(). For the argument usage, please refer to Variable.get_var_all(). This method returns a request ID that can be used in File.wait_all() or File.wait(). The posted read request may not be committed until File.wait_all() or File.wait() is called.

Note

Note that this method requires a empty array (data) as a read buffer from caller prepared for storing returned array values when File.wait_all() or File.wait() is called. User is expected to retain this buffer array handler (the numpy variable) until the read buffer is committed and the transaction is completed.

Returns:: The request ID, which can be used in a successive call to File.wait_all() or File.wait() for the completion of the nonblocking operation.
Return type:: int
Operational mode:: This method can be called in either define, collective, or independent data mode.

iget_varn(self, data, num, starts, counts=None, bufcount=None, buftype=None)

This method call is the nonblocking counterpart of Variable.get_varn(). The syntax is the same as Variable.get_varn(). For the argument usage, please refer to method Variable.get_varn_all(). This method returns a request ID that can be used in File.wait_all() or File.wait(). The posted write request may not be committed until File.wait_all() or File.wait() is called.

Note

Unlike Variable.get_varn(), the posted nonblocking read requests may not be committed until the time of calling File.wait_all() or File.wait(). Users should not alter the contents of the read buffer once the request is posted until the File.wait_all() or File.wait() is returned. Any change to the buffer contents in between will result in unexpected error.

Returns:: The request ID, which can be used in a successive call to File.wait_all() or File.wait() for the completion of the nonblocking operation.
Return type:: int

inq_fill(self)

Returns the fill mode settings of this variable. A tuple of two values representing no_fill mode and fill value.

Returns:

A tuple of two values which are no_fill mode and fill_value, respectively.

no_fill: 1 if no_fill mode is set (else 0).

fill_value: the fill value for this variable.

Return type:

tuple

inq_offset(self)

Returns:: The starting file offset of this netCDF variable.
Return type:: int64

iput_var(self, data, start=None, count=None, stride=None, imap=None, bufcount=None, buftype=None)

Method to post a nonblocking request to write to the netCDF variable. The syntax is the same as Variable.put_var(). For the argument usage, please refer to Variable.put_var_all(). This method returns a request ID that can This method returns a request ID that can be used in File.wait_all() or File.wait(). The posted write request may not be committed until File.wait_all() or File.wait() is called.

Note

Note that this method requires a numpy array (data) as a write buffer from caller prepared for writing returned array values when File.wait_all() or File.wait() is called. Users should not alter the contents of the write buffer once the request is posted until the File.wait_all() or File.wait() is returned. Any change to the buffer contents in between will result in unexpected error.

Returns:: The request ID, which can be used in a successive call to File.wait_all() or File.wait() for the completion of the nonblocking operation.
Return type:: int
Operational mode:: This method can be called while the file is in either collective or independent data mode.

iput_varn(self, data, num, starts, counts=None, bufcount=None, buftype=None)

This method call is the nonblocking counterpart of Variable.put_varn(). The syntax is the same as Variable.put_varn(). For the argument usage, please refer to method Variable.put_varn_all(). This method returns a request ID that can be used in File.wait_all() or File.wait(). The posted write request may not be committed until File.wait_all() or File.wait() is called.

Note

Unlike Variable.put_varn(), the posted nonblocking write requests may not be committed to the file until the time of calling File.wait_all() or File.wait(). Users should not alter the contents of the write buffer once the request is posted until the File.wait_all() or File.wait() is returned. Any change to the buffer contents in between will result in unexpected error.

Returns:: The request ID, which can be used in a successive call to File.wait_all() or File.wait() for the completion of the nonblocking operation.
Return type:: int

ncattrs(self)

Returns:: all attribute names of this variable in a list.
Return type:: list

put_att(self, name, value)

Method add or change a variable attribute. If this attribute is new, or if the space required to store the attribute is greater than before, the netCDF file must be in define mode.

Parameters:

name (str) – Name of the attribute.
value (str or numpy.ndarray) – Value of the attribute.

Operational mode:

This method must be called while the associated netCDF file is in define mode.

Example:

A example is available in examples/put_var.py

str_att = "example attribute of type text."
var.put_att("foo_attr", str_att)

# Equivalently, uses python dictionary way
var.foo_attr = str_att

put_var(self, data, start=None, count=None, stride=None, imap=None, bufcount=None, buftype=None)

Method to write in parallel to the netCDF variable in the independent I/O mode. For the argument usage, please refer to method Variable.put_var_all(). The only difference is this method is a independent operation.

Operational mode:: This method must be called while the file is in independent data mode.

put_var_all(self, data, start=None, count=None, stride=None, imap=None, bufcount=None, buftype=None)

Method to write in parallel to the netCDF variable in the collective I/O mode. The behavior of the method varies depends on the pattern of provided optional arguments - start, count, stride, bufcount and buftype.

data - Write an entire variable.
Write a netCDF variable entirely of an opened netCDF file, i.e. calling this API with only argument data. This is the simplest interface to use for writing a value in a scalar variable or whenever all the values of a multidimensional variable can all be written at once.

Note

Be careful when using the simplest forms of this interface with record variables. When there is no record written into the file yet, calling this API with only argument data, nothing will be written. Similarly, when writing the entire record variable, one must take the number of records into account.

data, start - Write a single data value (a single element).

Put a single data value specified by start into a variable of an opened netCDF file. For example, start = [0,5] would specify the following position in a 4 * 10 two-dimensional variable (“-” means skip).

           -  -  -  -  -  a  -  -  -  -
a     ->   -  -  -  -  -  -  -  -  -  -
           -  -  -  -  -  -  -  -  -  -
           -  -  -  -  -  -  -  -  -  -

data, start, count - Write a subarray of values.
The part of the netCDF variable to write is specified by giving a corner index and a vector of edge lengths that refer to an array section of the netCDF variable. For example, start = [0,5] and count = [2,2] would specify the following array section in a 4 * 10 two-dimensional variable (“-” means skip).
- - - - - a b - - - a b -> - - - - - c d - - - c d - - - - - - - - - - - - - - - - - - - -
data, start, count, stride - Write a subarray of values with strided space.
The part of the netCDF variable to write is specified by giving a corner, a vector of edge lengths and stride vector that refer to a subsampled array section of the netCDF variable. For example, start = [0,2], count = [2,4] and stride = [1,2] would specify the following array section in a 4 * 10 two-dimensional variable (“-” means skip).
- - a - b - c - d - a b c d -> - - e - f - g - h - e f g h - - - - - - - - - - - - - - - - - - - -
data, start, count, stride, imap - Write a mapped array of values.
The mapped array section is specified by giving a corner, a vector of counts, a stride vector, and an index mapping vector. The index mapping vector (imap) 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. For example, imap = [3,8], start = [0,5] and count = [2,2] would specify the following section in write butter and array section in a 4 * 10 two-dimensional variable (“-” means skip).
- - - - - a c - - - a - - b a c - - - - - b d - - - - - - - -> b d -> - - - - - - - - - - c - - d - - - - - - - - - - distance from a to b is 3 in buffer => imap[0] = 3 distance from a to c is 8 in buffer => imap[1] = 8

Parameters:

data (numpy.ndarray) – the numpy array that stores array values to be written, which serves as a write buffer. When writing a single data value, it can also be a single numeric (e.g. np.int32) python variable. The datatype should match with the variable’s datatype. Note this numpy array write buffer can be in any shape as long as the number of elements (buffer size) is matched.
start (numpy.ndarray) – [Optional] Only relevant when writing a array of values, a subsampled array, a mapped array or a list of subarrays. An array of integers specifying the index in the variable where the first of the data values will be written. The elements of start must correspond to the variable’s dimensions in order. Hence, if the variable is a record variable, the first index would correspond to the starting record number for writing the data values. When writing to a list of subarrays, start is 2D array of size [num][ndims] and each start[i] is a vector specifying the index in the variable where the first of the data values will be written.
count (numpy.ndarray) – [Optional] Only relevant when writing a array of values, a subsampled array, a mapped array or a list of subarrays. An array of integers specifying the edge lengths along each dimension of the block of data values to be written. The elements of count must correspond to the variable’s dimensions in order. Hence, if the variable is a record variable, the first index would correspond to the starting record number for writing the data values. When writing to a list of subarrays, count is 2D array of size [num][ndims] and each count[i] is a vector specifying the edge lengths along each dimension of the block of data values to be written.
stride (numpy.ndarray) – [Optional] Only relevant when writing a subsampled array or a mapped array. An array of integers specifying the sampling interval along each dimension of the netCDF variable. The elements of the stride vector correspond, in order, to the netCDF variable’s dimensions.
imap (numpy.ndarray) – [Optional] Only relevant when writing a subsampled array or a mapped array. An array of integers the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. The elements of the index mapping vector correspond, in order, to the netCDF variable’s dimensions. Each element value of imap should equal the memory location distance in write buffer between two adjacent elements along the corresponding dimension of netCDF variable.
bufcount (int) – [Optional] Optional for all types of writing patterns. An integer indicates the number of MPI derived data type elements in the write buffer to be written to the file.
buftype (mpi4py.MPI.Datatype) – [Optional] An MPI derived data type that describes the memory layout of the write buffer.

Operational mode:

This method must be called while the file is in collective data mode.

Example:

A example is available in examples/put_var.py

var.put_var_all(buf, start = start, count = count)

# Equivalently, below uses python index style
end = [start[i] + count[i] for i in range(2)]
var[start[0]:end[0], start[1]:end[1]] = buf

put_varn(self, data, num, starts, counts=None, bufcount=None, buftype=None): This method call is the same as method Variable.put_varn_all(), except it is an independent call and can only be called in the independent I/O mode. Please refer to Variable.put_varn_all() for its argument usage.

put_varn_all(self, data, num, starts, counts=None, bufcount=None, buftype=None)

Method write multiple subarrays of a netCDF variable to the file. This an collective I/O call and can only be called when the file is in the collective I/O mode. This method is equivalent to making multiple calls to Variable.put_var(). Note, combining multiple put_var calls into one can achieve a better performance.

data, num, starts, counts - Write multiple subarrays of values.

The part of the netCDF variable to write is specified by giving multiple subarrays and each subarray is specified by a corner and a vector of edge lengths that refer to an array section of the netCDF variable. The example code and diagram below illustrates a 4 subarray section in a 4 * 10 two-dimensional variable (“-” means skip).

num = 4

starts[0][0] = 0; starts[0][1] = 5; counts[0][0] = 1; counts[0][1] = 2
starts[1][0] = 1; starts[1][1] = 0; counts[1][0] = 1; counts[1][1] = 1
starts[2][0] = 2; starts[2][1] = 6; counts[2][0] = 1; counts[2][1] = 2
starts[3][0] = 3; starts[3][1] = 0; counts[3][0] = 1; counts[3][1] = 3

                     -  -  -  -  -  a  b  -  -  -
a b c d e f g h  ->  c  -  -  -  -  -  -  -  -  -
                     -  -  -  -  -  -  d  e  -  -
                     f  g  h  -  -  -  -  -  -  -

Parameters:

data (numpy.ndarray) – the numpy array that stores array values to be written, which serves as a write buffer. When writing a single data value, it can also be a single numeric (e.g. np.int32) python variable. The datatype should match with the variable’s datatype. Note this numpy array write buffer can be in any shape as long as the number of elements (buffer size) is matched. If the in-memory type of data values differs from the netCDF variable type defined in the file, type conversion will automatically be applied.
num (int) – An integer specifying the number of subarrays.
starts (numpy.ndarray) – A 2D array of integers containing starting array indices of num number of subarrays. The first dimension of starts should be of size num, indicating the number of subarrays of the variable to be written. The second dimension is of size equal to the number dimensions of the variable. For example, when num = 3 and the variable defined in the file is a 2D array, starts should be a 3x2 array. Each of the subarray starting indices identify the indices in the variable where the first of the data values will be written. Each starts[i] is a vector specifying the index in the variable where the first of the data values will be written. The elements of starts[i][*] must correspond to the variable’s dimensions in order. Hence, if the variable is a record variable, the first index, starts[i][0] would correspond to the starting record number for writing the data values.
counts (numpy.ndarray) – [Optional] A 2D array of integers specifying the lengths along each dimension of num number of subarrays to be written. The first dimension of counts should be of size num, indicating the number of subarrays of the variable to be written. The second dimension is of size equal to the number dimensions of the variable. For example, when num = 3 and the variable defined in the file is a 2D array, counts should be a 3x2 array. Each of the subarray counts[i] is a vector specifying the lengths along each dimension of the block of data values to be written and must correspond to the variable’s dimensions in order. When this argument is not supplied, it is equivalent to providing counts of all 1s.
bufcount (int) – [Optional] An integer indicates the number of MPI derived data type elements in the write buffer to be written to the file.
buftype (mpi4py.MPI.Datatype) – [Optional] An MPI derived data type that describes the memory layout of the write buffer.

Example:

A example is available in examples/put_varn_int.py

num_reqs = 4
starts = np.zeros((num_reqs, NDIMS), dtype=np.int64)
counts = np.zeros((num_reqs, NDIMS), dtype=np.int64)
starts[0][0] = 0; starts[0][1] = 5; counts[0][0] = 1; counts[0][1] = 2
starts[1][0] = 1; starts[1][1] = 0; counts[1][0] = 1; counts[1][1] = 1
starts[2][0] = 2; starts[2][1] = 6; counts[2][0] = 1; counts[2][1] = 2
starts[3][0] = 3; starts[3][1] = 0; counts[3][0] = 1; counts[3][1] = 3

v.put_varn_all(w_buf, num = num_reqs, starts = starts, counts = counts)

rename_att(self, oldname, newname)

Rename a variable attribute named oldname to newname

Parameters:: oldname (str) – Old name of the attribute.
Operational mode:: If the new name is longer than the original name, the associated netCDF file must be in define mode. Otherwise, the netCDF file can be in either define or data mode.

set_auto_chartostring(self, chartostring)

Turn on or off automatic conversion of character variable data to and from numpy fixed length string arrays when the _Encoding variable attribute is set.

If chartostring is set to True, when data is read from a character variable (dtype = S1) that has an _Encoding attribute, it is converted to a numpy fixed length unicode string array (dtype = UN, where N is the length of the rightmost dimension of the variable). The value of _Encoding is the unicode encoding that is used to decode the bytes into strings.

When numpy string data is written to a variable it is converted back to indiviual bytes, with the number of bytes in each string equalling the rightmost dimension of the variable.

The default value of chartostring is True (automatic conversions are performed).

Read-only python fields of class pnetcdf.Variable

The following class fields are read-only and should not be modified directly by the user.

name

The string name of Variable instance

Type: str

dtype

A numpy data type of the variable.

Type: numpy.dtype

datatype

Same as Variable.dtype().

Type: numpy.dtype

shape

The shape of the variable, which is the current sizes of all variable dimensions

Type: tuple of ints

ndim

The number of variable dimensions.

Type: int

size

Return the number of stored elements

Type: int

dimensions

Return the variable’s dimension names

Type: list of str

chartostring

If True, data is automatically converted to/from character arrays to string arrays when the _Encoding variable attribute is set. Default is True, can be reset using Variable.set_auto_chartostring() method.

Type: bool