NetCDF User's Guide for Fortran 90: Dimensions

Unidata - To provide the data services, tools, and cyberinfrastructure leadership that advance Earth system science, enhance educational opportunities, and broaden participation.

DataToolsCommunityDownloadsSupportProjectsAbout Us

•

[Next] [Previous] [Top] [Contents] [Index] [netCDF Home Page] [Unidata Home Page]

6 Dimensions

Dimensions for a netCDF dataset are defined when it is created, while the netCDF dataset is in define mode. Additional dimensions may be added later by reentering define mode. A netCDF dimension has a name and a length. At most one dimension in a netCDF dataset can have the unlimited length, which means variables using this dimension can grow along this dimension.

There is a suggested limit (512) to the number of dimensions that can be defined in a single netCDF dataset. The limit is the value of the constant NF90_MAX_DIMS. The purpose of the limit is to make writing generic applications simpler. They need only provide an array of NF90_MAX_DIMS dimensions to handle any netCDF dataset. The implementation of the netCDF library does not enforce this advisory maximum, so it is possible to use more dimensions, if necessary, but netCDF utilities that assume the advisory maximums may not be able to handle the resulting netCDF datasets.

Ordinarily, the name and length of a dimension are fixed when the dimension is first defined. The name may be changed later, but the length of a dimension (other than the unlimited dimension) cannot be changed without copying all the data to a new netCDF dataset with a redefined dimension length.

A netCDF dimension in an open netCDF dataset is referred to by a small integer called a dimension ID. In the Fortran 90 interface, dimension IDs are 1, 2, 3, ..., in the order in which the dimensions were defined.

Operations supported on dimensions are:

Create a dimension, given its name and length.
Get a dimension ID from its name.
Get a dimension's name and length from its ID.
Rename a dimension.

6.1 Create a Dimension: NF90_DEF_DIM

The function NF90_DEF_DIM adds a new dimension to an open netCDF dataset in define mode. It returns (as an argument) a dimension ID, given the netCDF ID, the dimension name, and the dimension length. At most one unlimited length dimension, called the record dimension, may be defined for each netCDF dataset.

Usage
 function nf90_def_dim(ncid, name, len, dimid)
   integer,             intent( in) :: ncid
   character (len = *), intent( in) :: name
   integer,             intent( in) :: len
   integer,             intent(out) :: dimid
   integer                          :: nf90_def_dim
ncid

NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE.

name

Dimension name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore (`_'). Case is significant.

len

Length of dimension; that is, number of values for this dimension as an index to variables that use it. This should be either a positive integer or the predefined constant NF90_UNLIMITED.

dimid

Returned dimension ID.

Errors

NF90_DEF_DIM returns the value NF90_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

The netCDF dataset is not in definition mode.
The specified dimension name is the name of another existing dimension.
The specified length is not greater than zero.
The specified length is unlimited, but there is already an unlimited length dimension defined for this netCDF dataset.
The specified netCDF ID does not refer to an open netCDF dataset.

Example

Here is an example using NF90_DEF_DIM to create a dimension named lat of length 18 and a unlimited dimension named rec in a new netCDF dataset named foo.nc:
 use netcdf
 implicit none
 integer :: ncid, status, LatDimID, RecordDimID
 ...
 status = nf90_create("foo.nc", nf90_noclobber, ncid) 
 if (status /= nf90_noerr) call handle_err(status)
 ...  
 status = nf90_def_dim(ncid, "Lat", 18, LatDimID) 
 if (status /= nf90_noerr) call handle_err(status)
 status = nf90_def_dim(ncid, "Record", nf90_unlimited, RecordDimID)
 if (status /= nf90_noerr) call handle_err(status)
6.2 Get a Dimension ID from Its Name: NF90_INQ_DIMID

The function NF90_INQ_DIMID returns (as an argument) the ID of a netCDF dimension, given the name of the dimension. If ndims is the number of dimensions defined for a netCDF dataset, each dimension has an ID between 1 and ndims.

Usage
 function nf90_inq_dimid(ncid, name, dimid)
   integer,             intent( in) :: ncid
   character (len = *), intent( in) :: name
   integer,             intent(out) :: dimid
   integer                          :: nf90_inq_dimid
ncid

NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE.

name

Dimension name, a character string beginning with a letter and followed by any sequence of letters, digits, or underscore (`_') characters. Case is significant in dimension names.

dimid

Returned dimension ID.

Errors

NF90_INQ_DIMID returns the value NF90_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

The name that was specified is not the name of a dimension in the netCDF dataset.
The specified netCDF ID does not refer to an open netCDF dataset.

Example

Here is an example using NF90_INQ_DIMID to determine the dimension ID of a dimension named lat, assumed to have been defined previously in an existing netCDF dataset named foo.nc:
 use netcdf
 implicit none
 integer :: ncid, status, LatDimID
 ...
 status = nf90_open("foo.nc", nf90_nowrite, ncid) 
 if (status /= nf90_noerr) call handle_err(status)
 ...  
 status = nf90_inq_dimid(ncid, "Lat", LatDimID) 
 if (status /= nf90_noerr) call handle_err(status)
6.3 Inquire about a Dimension: NF90_Inquire_Dimension

This function information about a netCDF dimension. Information about a dimension includes its name and its length. The length for the unlimited dimension, if any, is the number of records written so far.

Usage
 function nf90_Inquire_Dimension(ncid, dimid, name, len)
   integer,                       intent( in) :: ncid, dimid
   character (len = *), optional, intent(out) :: name
   integer,             optional, intent(out) :: len
   integer                                    :: nf90_Inquire_Dimension
ncid

NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE.

dimid

Dimension ID, for example from a previous call to NF90_INQ_DIMID or NF90_DEF_DIM.

name

Returned dimension name. The caller must allocate space for the returned name. The maximum possible length, in characters, of a dimension name is given by the predefined constant NF90_MAX_NAME.

len

Returned length of dimension. For the unlimited dimension, this is the current maximum value used for writing any variables with this dimension, that is the maximum record number.

Errors

These functions return the value NF90_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

The dimension ID is invalid for the specified netCDF dataset.
The specified netCDF ID does not refer to an open netCDF dataset.

Example

Here is an example using NF90_INQ_DIM to determine the length of a dimension named lat, and the name and current maximum length of the unlimited dimension for an existing netCDF dataset named foo.nc:
 use netcdf
 implicit none
 integer :: ncid, status, LatDimID, RecordDimID
 integer :: nLats, nRecords
 character(len = nf90_max_name) :: RecordDimName
 ...
 status = nf90_open("foo.nc", nf90_nowrite, ncid) 
 if (status /= nf90_noerr) call handle_err(status)
 ! Get ID of unlimited dimension
 status = nf90_Inquire(ncid, unlimitedDimId = RecordDimID)
 if (status /= nf90_noerr) call handle_err(status)
 ...  
 status = nf90_inq_dimid(ncid, "Lat", LatDimID) 
 if (status /= nf90_noerr) call handle_err(status)
 ! How many values of "lat" are there?
 status = nf90_Inquire_Dimension(ncid, LatDimID, len = nLats)
 if (status /= nf90_noerr) call handle_err(status)
 ! What is the name of the unlimited dimension, how many records are there?
 status = nf90_Inquire_Dimension(ncid, RecordDimID, &
                                 name = RecordDimName, len = Records)
 if (status /= nf90_noerr) call handle_err(status)
6.4 Rename a Dimension: NF90_RENAME_DIM

The function NF90_renames an existing dimension in a netCDF dataset open for writing. 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.

Usage
 function nf90_rename_dim(ncid, dimid, name)
   integer,             intent( in) :: ncid
   character (len = *), intent( in) :: name
   integer,             intent( in) :: dimid
   integer                          :: nf90_rename_dim
ncid

NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE.

dimid

Dimension ID, from a previous call to NF90_INQ_DIMID or NF90_DEF_DIM.

name

New name for the dimension.

Errors

NF90_RENAME_DIM returns the value NF90_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

The new name is the name of another dimension.
The dimension ID is invalid for the specified netCDF dataset.
The specified netCDF ID does not refer to an open netCDF dataset.
The new name is longer than the old name and the netCDF dataset is not in define mode.

Example

Here is an example using NF90_RENAME_DIM to rename the dimension lat to latitude in an existing netCDF dataset named foo.nc:
 use netcdf
 implicit none
 integer :: ncid, status, LatDimID
 ...
 status = nf90_open("foo.nc", nf90_write, ncid) 
 if (status /= nf90_noerr) call handle_err(status)
 ...  
 ! Put in define mode so we can rename the dimension
 status = nf90_redef(ncid) 
 if (status /= nf90_noerr) call handle_err(status)
 ! Get the dimension ID for "Lat"...
 status = nf90_inq_dimid(ncid, "Lat", LatDimID)
 if (status /= nf90_noerr) call handle_err(status)
 ! ... and change the name to "Latitude". 
 status = nf90_rename_dim(ncid, LatDimID, "Latitude")
 if (status /= nf90_noerr) call handle_err(status)
 ! Leave define mode
 status = nf90_enddef(ncid)
 if (status /= nf90_noerr) call handle_err(status)

ncid	NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE.
name	Dimension name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore (`_'). Case is significant.
len	Length of dimension; that is, number of values for this dimension as an index to variables that use it. This should be either a positive integer or the predefined constant NF90_UNLIMITED.
dimid	Returned dimension ID.

ncid	NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE.
name	Dimension name, a character string beginning with a letter and followed by any sequence of letters, digits, or underscore (`_') characters. Case is significant in dimension names.
dimid	Returned dimension ID.

ncid	NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE.
dimid	Dimension ID, for example from a previous call to NF90_INQ_DIMID or NF90_DEF_DIM.
name	Returned dimension name. The caller must allocate space for the returned name. The maximum possible length, in characters, of a dimension name is given by the predefined constant NF90_MAX_NAME.
len	Returned length of dimension. For the unlimited dimension, this is the current maximum value used for writing any variables with this dimension, that is the maximum record number.

ncid	NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE.
dimid	Dimension ID, from a previous call to NF90_INQ_DIMID or NF90_DEF_DIM.
name	New name for the dimension.

[Next] [Previous] [Top] [Contents] [Index] [netCDF Home Page] [Unidata Home Page]

				Unidata is a member of the UCAR Office of Programs, is managed by the University Corporation for Atmospheric Research, and is sponsored by the National Science Foundation.
				P.O. Box 3000 • Boulder, CO 80307-3000 USA • Tel: 303-497-8643 • Fax: 303-497-8690