Introduction to netCDF

From Geos-chem
Jump to: navigation, search

Previous | Next | Guide to netCDF in GEOS-Chem

  1. Introduction to netCDF
  2. Check if netCDF is already installed on your system
  3. Use Spack to install netCDF on your system
  4. The COARDS netCDF conventions for earth science data
  5. Working with netCDF data files
  6. Creating netCDF data files for GEOS-Chem
  7. Other libraries used by GEOS-Chem

On this page (and the following pages), we provide useful information about the netCDF file format, and the software library that allows GEOS-Chem to create and read netCDF files.

What is netCDF and why does GEOS-Chem need it?

GEOS-Chem reads and writes data using the netCDF file format. But in order for GEOS-Chem to be able to create and read netCDF files, it needs to be able to call certain routines from the netCDF software library.

The netCDF file format

NetCDF is a self-describing file format that can store data fields as well as the relevant "metadata", or information about the contents of the file. Types of metadata include descriptive names, units, horizontal and vertical, coordinates, file creation date/time, file history, etc.

The netCDF frequently asked questions (FAQ) guide gives this short overview of netCDF:

NetCDF (network Common Data Form) is a set of interfaces for array-oriented data access and a freely distributed collection of data access libraries for C, Fortran, C++, Java, and other languages. The netCDF libraries support a machine-independent format for representing scientific data. Together, the interfaces, libraries, and format support the creation, access, and sharing of scientific data.

NetCDF data is:

  • Self-Describing. A netCDF file includes information about the data it contains.
  • Portable. A netCDF file can be accessed by computers with different ways of storing integers, characters, and floating-point numbers.
  • Scalable. A small subset of a large dataset may be accessed efficiently.
  • Appendable. Data may be appended to a properly structured netCDF file without copying the dataset or redefining its structure.
  • Sharable. One writer and multiple readers may simultaneously access the same netCDF file.
  • Archivable. Access to all earlier forms of netCDF data will be supported by current and future versions of the software.

The netCDF software library

The netCDF sofware library is an Application Program Interface (API), which is a set of compiled utility routines meant to be called from a software program such as GEOS-Chem. These utility routines allow software programs that are written in either the C or Fortran languages to read from or write to netCDF files.

A netCDF library installation contains:

  1. Library files (ending in .a)
  2. Header files (ending in *.h or .inc)
  3. Various utility scripts (such as ncdump, nc-config, and nf-config)

There are two commonly-used major versions of netCDF in use today:

  1. netCDF-3, aka "netCDF classic".
  2. netCDF-4

The major difference between the two versions is that netCDF-4 relies on the HDF5 library "under the hood" whereas netCDF-3 does not. For this reason, netCDF-4 can be used to store more data per file than netCDF-3.

In netCDF-4.1 and prior versions, the C-language library file (libnetcdf.a) and the Fortran-language library file (libnetcdff.a) were always installed into the same folder by default. But starting with netCDF-4.2, the netCDF Fortran libraries now must be built from a separate distribution package. Because of this new configuration, you might find that the libnetcdff.a (Fortran) and libnetcdf.a (C) library files are stored in separate folders on your system. Ask your IT staff for more information about how netCDF is installed on your system. See this section below for more information.

For more information

For more information about the netCDF library, please see these references:

netCDF 4.2 and later versions require a separate netCDF-Fortran installation

In all netCDF versions up to 4.1.3, the library files for the C-language interface (stored in library file libnetcdf.a) and the Fortran-language interface (stored in library file libnetcdff.a) were always stored in the same folder. But in netCDF 4.2.0 (circa 2010) and later versions, the Fortran-language interface to netCDF was moved to a completely separate distribution, with its own version numbering system. Therefore, if you are using a netCDF package greater than 4.2.0, you have to install netCDF-Fortran as a completely separate library.

Long story short:

  1. If you are using netCDF-4.2.0 and later (which are the most recent versions of netCDF), look for a separate netCDF-Fortran installation.
  2. If you are using netCDF-4.1.3 and prior, then there is no separate netCDF-Fortran installation

GEOS-Chem is designed to work with any version of netCDF, regardless if the netCDF-Fortran installation is separate or not.

--Bob Yantosca (talk) 14:05, 13 June 2019 (UTC)

Previous | Next | Guide to netCDF in GEOS-Chem