PNETCDF(3f90) LIBRARY FUNCTIONS PNETCDF(3f90)NAME
PnetCDF - Parallel library for accessing files in Network Common Data
Form (CDF, CDF-2 and CDF-5 formats)
SYNOPSIS
use pnetcdf
Most Systems:
mpif90 ... -lpnetcdf
CRAY PVP Systems:
f90 -dp -i64 ... -lpnetcdf
LIBRARY VERSION
This document describes Parallel netCDF APIs for the Fortran-90 pro‐
gramming language.
character*80 nf90mpi_inq_libvers()
character(len=80) :: nf90mpi_inq_libvers
Returns a string identifying the version of the PnetCDF library, and
when it was built, like: "1.6.1 of 01 Jun 2015".
The RCS ident(1) command will find a string like "$Id: @(#) PnetCDF li‐
brary version 1.6.1 of 01 Jun 2015 $" in the library. The SCCS what(1)
command will find a string like "PnetCDF library version 1.6.1 of 01
Jun 2015".
ROUTINE DESCRIPTIONS
All PnetCDF functions (except nf90mpi_inq_libvers() and nf90mpi_str‐
error()) return an integer status. This behavior replaces the rcode
argument used in previous versions of the library. If this returned
status value is not equal to nf90_noerr (zero), it indicates that an
error occurred. The possible status values are defined in the module
pnetcdf.
function nf90mpi_strerror(ncerr)
integer, intent(in) :: ncerr
character(len=80) :: nf90mpi_strerror
Returns a string textual translation of the ncerr value, like
"Attribute or variable name contains illegal characters" or "No
such file or directory".
function nf90mpi_create(comm, path, cmode, info, ncid)
integer, intent(in) :: comm
character(len=*), intent(in) :: path
integer, intent(in) :: cmode
integer, intent(in) :: info
integer, intent(out) :: ncid
integer :: nf90mpi_create
Creates a new netCDF dataset at path collectively by a group of
MPI processes specified by comm, returning a netCDF ID in ncid.
The argument cmode may include the bitwise-or of the following
flags: nf90_noclobber to protect existing datasets (default is
nf90_clobber, silently blows them away), nf90_share for stronger
metadata data consistency control, nf90_64bit_offset to create a
file in the 64-bit offset format (CDF-2), as opposed to classic
format, the default, or nf90_64bit_data to create a file in the
64-bit data format (CDF-5). Use either nf90_64bit_offset or
nf90_64bit_data. The 64-bit offset format allows the creation
of very large files with far fewer restrictions than netCDF
classic format, but can only be read by the netCDF library ver‐
sion 3.6 or greater. Users are cautioned that files that use the
64-bit offset format will not be recognized by netCDF applica‐
tions linked to an earlier version of the netCDF library than
3.6. Applications linked to version 3.6 or later will be able
to transparently access either the classic format or 64-bit off‐
set format. The 64-bit data format allows the creation of very
large array variables. CDF-5 files currently will not be recog‐
nized by netCDF 3 or 4 library.
The argument cmode must be consistent among all MPI processes
that collectively create the file. The argument info is an MPI
info object. Users can use it to supply the file access hints
further performance improvement. The hints include existing
MPI-IO hints as well as hints defined and used in PnetCDF.
When a netCDF dataset is created, it is opened in nf90_write
mode. When this function returns, the new netCDF dataset is in
define mode.
function nf90mpi_open(comm, path, mode, info, ncid)
integer, intent(in) :: comm
character(len=*), intent(in) :: path
integer, intent(in) :: mode
integer, intent(in) :: info
integer, intent(out) :: ncid
integer :: nf90mpi_open
Opens an existing netCDF dataset at path collectively by a group
of MPI processes specified by comm, returning a netCDF ID in
ncid. The type of access is described by the mode parameter,
which may include the bitwise-or of the following flags:
nf90_write for read-write access (default read-only), nf90_share
for stronger metadata data consistency control.
The argument mode must be consistent among all MPI processes
that collectively open the file. The argument info is an MPI
info object. Users can use it to supply the file access hints
further performance improvement. The hints include existing
MPI-IO hints as well as hints defined and used in PnetCDF.
function nf90mpi_redef(ncid)
integer, intent(in) :: ncid
integer :: nf90mpi_redef
Puts an open netCDF dataset into define mode, so dimensions,
variables, and attributes can be added or renamed and attributes
can be deleted.
function nf90mpi_enddef(ncid)
integer, intent(in) :: ncid
integer :: nf90mpi_enddef
Takes an open netCDF dataset out of define mode. The changes
made to the netCDF dataset while it was in define mode are
checked and committed to disk if no problems occurred. After a
successful call, variable data can be read or written to the
dataset.
function nf90mpi_sync(ncid)
integer, intent(in) :: ncid
integer :: nf90mpi_sync
Unless the nf90_share bit is set in nf90mpi_open() or
nf90mpi_create(), data written by PnetCDF APIs may be cached by
local file system on each compute node. This API flushes cached
data by calling MPI_File_sync.
function nf90mpi_abort(ncid)
integer, intent(in) :: ncid
integer :: nf90mpi_abort
You don't need to call this function. This function is called
automatically by nf90mpi_close() if the netCDF dataset was in
define mode and something goes wrong with the commit. If the
netCDF dataset isn't in define mode, then this function is
equivalent to nf90mpi_close(). If it is called after
nf90mpi_redef(), but before nf90mpi_enddef(), the new defini‐
tions are not committed and the dataset is closed. If it is
called after nf90mpi_create() but before nf90mpi_enddef(), the
dataset disappears.
function nf90mpi_close(ncid)
integer, intent(in) :: ncid
integer :: nf90mpi_close
Closes an open netCDF dataset. If the dataset is in define
mode, nf90mpi_enddef() will be called before closing. After a
dataset is closed, its ID may be reassigned to another dataset.
function nf90mpi_inquire(ncid, ndims, nvars, natts, unlimdimid, nfor‐
mat)
integer, intent(in) :: ncid
integer, optional, intent(out) :: ndims, nvars
integer, optional, intent(out) :: natts, unlimdimid
integer, optional, intent(out) :: nformat
integer :: nf90mpi_inquire
Inquire about an open netCDF dataset. ncid is the netCDF ID of
the open dataset. Upon successful return, ndims will contain
the number of dimensions defined for this netCDF dataset, nvars
will contain the number of variables, natts will contain the
number of attributes, and unlimdimid will contain the dimension
ID of the unlimited dimension if one exists, or 0 otherwise.
nformat will contain the format version number, rarely needed
because the library detects the format version and behaves ap‐
propriately.
function nf90mpi_def_dim(ncid, name, len, dimid)
integer, intent(in) :: ncid
character(len=*), intent(in) :: name
integer, intent(in) :: len
integer, intent(out) :: dimid
integer :: nf90mpi_def_dim
Adds a new dimension to an open netCDF dataset, which must be in
define mode. name is the dimension name. len is the size of
the new dimension or nf90mpi_unlimited to define the unlimited
dimension. On return, dimid will contain the dimension ID of
the newly created dimension.
function nf90mpi_inq_dimid(ncid, name, dimid)
integer, intent(in) :: ncid
character(len=*), intent(in) :: name
integer, intent(out) :: dimid
integer :: nf90mpi_inq_dimid
Given an open netCDF dataset and dimension name, returns the di‐
mension ID of the netCDF dimension in dimid.
function nf90mpi_inquire_dimension(ncid, dimid, name, len)
integer, intent(in) :: ncid, dimid
character(len=*), optional, intent(out) :: name
integer, optional, intent(out) :: len
integer :: nf90mpi_inquire_dimension
Inquire about a dimension. name should be big enough
(nf90_max_name) to hold the dimension name as the name will be
copied into your storage. The length return parameter, len will
contain the size of the dimension. For the unlimited dimension,
the returned length is the current maximum value used for writ‐
ing into any of the variables which use the dimension.
function nf90mpi_rename_dim(ncid, dimid, name)
integer, intent(in) :: ncid
character(len=*), intent(in) :: name
integer, intent(in) :: dimid
integer :: nf90mpi_rename_dim
Renames an existing dimension in an open netCDF dataset. If the
new name is longer than the old name, the netCDF dataset must be
in define mode. You cannot rename a dimension to have the same
name as another dimension.
function nf90mpi_def_var(ncid, name, xtype, dimids, varid)
integer, intent(in) :: ncid
character(len=*), intent(in) :: name
integer, intent(in) :: xtype
integer, optional, dimension(:), intent(in) :: dimids
integer :: nf90mpi_def_var
Adds a new variable to a netCDF dataset. The netCDF must be in
define mode. name will be the name of the netCDF variable.
xtype is the external, netCDF type of the variable and should be
one of nf90_byte, nf90_char, nf90_short, nf90_int, nf90_float,
or nf90_double for CDF-1 and CDF-2 file formats. CDF-5 defines
additional external types: nf90_ubyte, nf90_ushort, nf90_uint,
nf90_int64, and nf90_uint64. The optional dimids argument con‐
tains the dimension ID-s of the domain of the netCDF variable
and, consequently, determines the rank of the created variable:
if dimids is omitted, then the netCDF variable will be a scalar;
if dimids is a scalar, then the netCDF variable will be 1 dimen‐
sional; and if dimids is a vector, then the netCDF variable will
have rank equal to the number of elements in dimids. varid will
be set to the netCDF variable ID.
function nf90mpi_inq_varid(ncid, name, varid)
integer, intent(in) :: ncid
character(len=*), intent(in) :: name
integer, intent(out) :: varid
integer :: nf90mpi_inq_varid
Returns the ID of a netCDF variable in varid given an open
netCDF dataset and the name of the variable.
function nf90mpi_inquire_variable(ncid, varid, name, xtype, ndims,
dimids, natts)
integer, intent(in) :: ncid, varid
character(len=*), optional, intent(out) :: name
integer, optional, intent(out) :: xtype, ndims
integer, dimension(*), optional, intent(out) :: dimids
integer, optional, intent(out) :: natts
integer :: nf90mpi_inquire_variable
Inquire about a netCDF variable in an open netCDF dataset, given
its variable ID. On return, name will contain the name of the
variable and should be capacious enough (nf90_max_name). xtype
will contain the external, netCDF type of the variable. ndims
will contain the dimensionality of the netCDF variable: if the
variable is a scalar, then size(ndims) will be zero; otherwise,
size(ndims) will be the rank of the variable and ndims will con‐
tain the dimension ID-s of the netCDF dimensions that constitute
the domain of the variable. natts will contain the number of
attributes associated with the netCDF variable.
function nf90mpi_rename_var(ncid, varid, name)
integer, intent9in) :: ncid, varid
character(len=*), intent(in) :: newname
integer :: nf90mpi_rename_var
Changes the name of a netCDF variable. If the new name is
longer than the old name, the netCDF must be in define mode.
You cannot rename a variable to have the name of any existing
variable.
function nf90mpi_put_var(ncid, varid, values, start, stride, imap)
integer, intent(in) :: ncid, varid
<<whatever>>, intent(in) :: values
integer, dimension(:), optional, intent(in) :: start
integer, dimension(:), optional, intent(in) :: stride
integer, dimension(:), optional, intent(in) :: imap
integer :: nf90mpi_put_var
Writes a value or values to a netCDF variable. The netCDF
dataset must be open and in data mode. values contains the val‐
ue(s) what will be written to the netCDF variable identified by
ncid and varid; it may be a scalar or an array and must be of
type character, integer(kind=OneByteInt), inte‐
ger(kind=TwoByteInt), integer(kind=FourByteInt), inte‐
ger(kind=EightByteInt), real(kind=FourByteReal), or re‐
al(kind=EightByteReal). All values are converted to the exter‐
nal type of the netCDF variable, if possible; otherwise, an
nf90_erange error is returned. The optional argument start
specifies the starting index in the netCDF variable for writing
for each dimension of the netCDF variable. The optional argu‐
ment stride specifies the sampling stride (the interval between
accessed values in the netCDF variable) for each dimension of
the netCDF variable (see COMMON ARGUMENT DESCRIPTIONS below).
The optional argument imap specifies the in-memory arrangement
of the data values (see COMMON ARGUMENT DESCRIPTIONS below).
function nf90mpi_get_var(ncid, varid, values, start, stride, imap)
integer, intent(in) :: ncid, varid
<<whatever>>, intent(out) :: values
integer, dimension(:), optional, intent(in) :: start
integer, dimension(:), optional, intent(in) :: stride
integer, dimension(:), optional, intent(in) :: imap
integer :: nf90mpi_get_var
Reads a value or values from a netCDF variable. The netCDF
dataset must be open and in data mode. values will receive the
value(s) what will be read from the netCDF
variable identified by ncid and varid; it may be a scalar or an
array and must be of type character, integer(kind=OneByteInt),
integer(kind=TwoByteInt), integer(kind=FourByteInt), inte‐
ger(kind=EightByteInt), real(kind=FourByteReal), or re‐
al(kind=EightByteReal). All values are converted from the ex‐
ternal type of the netCDF variable, if possible; otherwise, an
nf90_erange error is returned. The optional argument start
specifies the starting index in the netCDF variable for reading
for each dimension of the netCDF variable. The optional argu‐
ment stride specifies the sampling stride (the interval between
accessed values in the netCDF variable) for each dimension of
the netCDF variable (see COMMON ARGUMENT DESCRIPTIONS below).
The optional argument imap specifies the in-memory arrangement
of the data values (see COMMON ARGUMENT DESCRIPTIONS below).
function nf90mpi_inquire_attribute(ncid, varid, name, xtype, len, at‐
tnum)
integer, intent(in) :: ncid, varid
character(len=*), intent(in) :: name
integer, optional, intent(out) :: xtype, len, attnum
integer :: nf90mpi_inquire_attribute
Inquires about the netCDF attribute named name, of variable
varid, in the open netCDF dataset ncid. xtype will contain the
external, netCDF type of the variable. len will contain the
number of elements in the attribute. attnum will contain the
attribute number.
function nf90mpi_inq_attname(ncid, varid, attnum, name)
integer, intent(in) :: ncid, varid, attnum
character(len=*), intent(out) :: name
integer :: nf90mpi_inq_attname
Gets the name of an attribute, given its variable ID and at‐
tribute number. This function is useful in generic applications
that need to get the names of all the attributes associated with
a variable because attributes are accessed by name rather than
number in all other attribute functions (the number of an at‐
tribute is more volatile than the name because it can change
when other attributes of the same variable are deleted). The
attributes for each variable are numbered from 1 (the first at‐
tribute) to natts, where natts is the number of attributes for
the variable, as returned from a call to nf90mpi_inquire_vari‐
able().
function nf90mpi_put_att(ncid, varid, name, values)
integer, intent(in) :: ncid, varid
character(len=*), intent(in) :: name
<<whatever>>, intent(in) :: values
integer :: nf90mpi_put_att
Unlike variables, attributes do not have separate functions for
defining and writing values. This function defines a new at‐
tribute with a value or changes the value of an existing at‐
tribute. If the attribute is new, or if the space required to
store the attribute value is greater than before, the netCDF
dataset must be in define mode. values contains the attribute
values to be written; it may be a scalar or a vector and must be
of type character, integer(kind=OneByteInt), inte‐
ger(kind=TwoByteInt), integer(kind=FourByteInt), inte‐
ger(kind=EightByteInt), real(kind=FourByteReal), or re‐
al(kind=EightByteReal).
function nf90mpi_get_att(ncid, varid, name, fIvalues)
integer, intent(in) :: ncid, varid
character(len=*), intent(in) :: name
<<whatever>>, intent(out) :: values
integer :: nf90mpi_get_att
Gets the value(s) of a netCDF attribute, given its variable ID
and name. The values are returned in values, which must be of
type character, integer(kind=OneByteInt), inte‐
ger(kind=TwoByteInt), integer(kind=FourByteInt), inte‐
ger(kind=EightByteInt), real(kind=FourByteReal), or re‐
al(kind=EightByteReal). Converts from the external type to the
type of the receiving variable, if possible; otherwise returns
an nf90_erange error. All values of the attribute are returned,
so you must allocate enough space to hold them. If you don't
know how much space to reserve, call nf90mpi_inquire_attribute()
first to find out the length of the attribute.
function nf90mpi_copy_att(ncid_in, varid_in, name, ncid_out, varid_out)
integer, intent(in) :: ncid_in, varid_in
character(len=*), intent(in) :: name
integer, intent(in) :: ncid_out, varid_out
integer :: nf90mpi_copy_att
Copies an attribute from one netCDF dataset to another. It can
also be used to copy an attribute from one variable to another
within the same netCDF dataset. ncid_in is the netCDF ID of an
input netCDF dataset from which the attribute will be copied.
varid_in is the ID of the variable in the input netCDF dataset
from which the attribute will be copied, or nf90_global for a
global attribute. name is the name of the attribute in the in‐
put netCDF dataset to be copied. ncid_out is the netCDF ID of
the output netCDF dataset to which the attribute will be copied.
It is permissible for the input and output netCDF ID's to be the
same. The output netCDF dataset should be in define mode if the
attribute to be copied does not already exist for the target
variable, or if it would cause an existing target attribute to
grow. varid_out is the ID of the variable in the output netCDF
dataset to which the attribute will be copied, or nf90_global to
copy to a global attribute.
function nf90mpi_rename_att(ncid, varid, name, newname)
integer, intent(in) :: ncid, varid
character(len=*), intent(in) :: name, newname
integer :: nf90mpi_rename_att
Changes the name of an attribute. If the new name is longer
than the original name, the netCDF must be in define mode. You
cannot rename an attribute to have the same name as another at‐
tribute of the same variable. name is the original attribute
name. newname is the new name to be assigned to the specified
attribute. If the new name is longer than the old name, the
netCDF dataset must be in define mode.
function nf90mpi_del_att(ncid, varid, name)
integer, intent(in) :: ncid, varid
character(len=*), intent(in) :: name
integer :: nf90mpi_del_att
Deletes an attribute from a netCDF dataset. The dataset must be
in define mode.
COMMON ARGUMENT DESCRIPTIONS
In this section we define some common arguments which are used in the
"FUNCTION DESCRIPTIONS" section.
integer ncid
is the netCDF ID returned from a previous, successful call to
nf90mpi_open() or nf90mpi_create()
character(len=*) name
is the name of a dimension, variable, or attribute. It shall
begin with an alphabetic character, followed by zero or more al‐
phanumeric characters including the underscore (_) or hyphen
(-). Case is significant. The maximum allowable number of
characters is nf90_max_name. Names that begin with an under‐
score (_) are reserved for use by the netCDF and PnetCDF inter‐
faces.
integer xtype
specifies the external data type of a netCDF variable or at‐
tribute and is one of the following: nf90_byte, nf90_char,
nf90_short, nf90_int, nf90_float, or nf90_double. These are
used to specify 8-bit integers, characters, 16-bit integers,
32-bit integers, 32-bit IEEE floating point numbers, and 64-bit
IEEE floating-point numbers, respectively.
integer dimids
is a vector of dimension ID's and defines the shape of a netCDF
variable. The size of the vector shall be greater than or equal
to the rank (i.e. the number of dimensions) of the variable
(ndims). The vector shall be ordered by the speed with which a
dimension varies: dimids(1) shall be the dimension ID of the
most rapidly varying dimension and dimids(ndims) shall be the
dimension ID of the most slowly varying dimension. The maximum
possible number of dimensions for a variable is given by the
symbolic constant nf90_max_var_dims.
integer dimid
is the ID of a netCDF dimension. netCDF dimension ID's are al‐
located sequentially from the positive integers beginning with
1.
integer ndims
is either the total number of dimensions in a netCDF dataset or
the rank (i.e. the number of dimensions) of a netCDF variable.
The value shall not be negative or greater than the symbolic
constant nf90_max_var_dims.
integer varid
is the ID of a netCDF variable or (for the attribute-access
functions) the symbolic constant nf90_global, which is used to
reference global attributes. netCDF variable ID's are allocated
sequentially from the positive integers beginning with 1.
integer natts
is the number of global attributes in a netCDF dataset for the
nf90mpi_inquire() function or the number of attributes associat‐
ed with a netCDF variable for the nf90mpi_varinq() function.
integer(kind=MPI_OFFSET) start
specifies the starting point for accessing a netCDF variable's
data values in terms of the indicial coordinates of the corner
of the array section. The indices start at 1; thus, the first
data value of a variable is (1, 1, ..., 1). The size of the
vector shall be at least the rank of the associated netCDF vari‐
able and its elements shall correspond, in order, to the vari‐
able's dimensions.
integer(kind=MPI_OFFSET) stride
specifies 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 (stride(1)) gives
the sampling interval along the most rapidly varying dimension
of the netCDF variable). Sampling intervals are specified in
type-independent units of elements (a value of 1 selects consec‐
utive elements of the netCDF variable along the corresponding
dimension, a value of 2 selects every other element, etc.).
integer(kind=MPI_OFFSET) imap
specifies the mapping between the dimensions of a netCDF vari‐
able 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 (imap gives the distance be‐
tween elements of the internal array corresponding to the most
rapidly varying dimension of the netCDF variable). Distances
between elements are specified in type-independent units of ele‐
ments (the distance between internal elements that occupy adja‐
cent memory locations is 1 and not the element's byte-length as
in netCDF 2).
VARIABLE PREFILLING
PnetCDF does not support data filling.
ENVIRONMENT VARIABLES
PNETCDF_SAFE_MODE
Set to 1 to enable metadata consistency check. Warning messages
will be printed to stdout if any inconsistency is detected.
MAILING-LISTS
A mailing list is available for discussion of the PnetCDF interface and
announcements about PnetCDF bugs, fixes, and enhancements. To sub‐
scribe or unsubscribe to the PnetCDF mailing list, visit
https://lists.mcs.anl.gov/mailman/listinfo/parallel-netcdf
SEE ALSOncmpidump(1), ncmpigen(1), ncmpidiff(1), ncmpivalid(1), pnetcdf(3f90).
PnetCDF User's Guide, published by Northwestern University and Argonne
National Laboratory. This document is adopted from the netCDF User's
Guide, developed at the Unidata Program Center, University Corporation
for Atmospheric Research, located in Boulder, Colorado.
PnetCDF home page at http://cucis.ece.northwest‐
ern.edu/projects/PnetCDF/.
Printed: 2024.04.28 2015-06-01 PNETCDF(3f90)
