NCEPLIBS-ncio

This is a library used by NCEP GSI system to read the GFS forecast files for use in data assimilation. It is also used by enkf_chgres_recenter_nc, which will read in a template output file, an input file, and regrid the input file to the template output file resolution.

For more detailed documentation see https://noaa-emc.github.io/NCEPLIBS-ncio/.

NCEPLIBS-ncio is part of the NCEPLIBS project.

To submit bug reports, feature requests, or other code-related issues including installation and usage questions, please create a GitHub issue. For general NCEPLIBS inquiries, contact Edward Hartnett (secondary point of contact Alex Richert).

Authors

Jeff Whitaker, Cory Martin

Code manager: Edward Hartnett, Hang Lei

Prerequisites

This package requires:

• netcdf-c Library
• netcdf-fortran Library

Installing

mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=/path/to/install ..
make -j2
make install

Using

This library contains a module for reading/writing netcdf gridded data. API docs here.

Examples

• open a Dataset.

use module_ncio
type(Dataset) :: ds
ds = open_dataset('gfs.t00z.atmf240.nc')

• read an attribute.

real(4), allocatable, dimension(:) :: ak,bk
character(len=32) charatt
! ak,bk are allocated and filled.
call read_attribute(ds, 'ak', ak)
call read_attribute(ds, 'bk', bk)
! read character variable attribute
call read_attribute(ds, 'long_name', charatt, 'vgrd')

• read a variable.

real(4), allocatable, dimension(:) :: lats,lons
real(4), allocatable, dimension(:,:,:) :: psfc
! arrays must be of correct rank (but not necessarily
! the same type). They are allocated and filled.
! The entire variable is read at once.
call read_vardata(ds,'latitudes',lats)
call read_vardata(ds,'latitudes',lons)
call read_vardata(ds,'pressfc',psfc)

• create a new dataset from a template dataset.

type(Dataset) :: dso
! copy_vardata is optional, default .false. means just copy
! variables, dimensions and attributes and coordinate variable 
! data (don't copy all variable data).
dso = create_dataset('gfs.t00z.atmf240_copy.nc', ds, copy_vardata=.true.)

• write a variable.

real(8), allocatable, dimension(:) :: times
call read_vardata(dso, 'time', times)
! times is now allocated and filled with values from template dataset.
! now overwrite with new values and write back.
times = times + 6 ! add six hours.
call write_vardata(dso, 'time', times)

• quantize variable data before writing for better compression.

! Lossy compression controlled by parameter nbits (1-31).
! The floating point data is quantized to improve compression
! See doi:10.5194/gmd-10-413-2017.  The method employed
! here is identical to the 'scaled linear packing' method in
! that paper, except that the data are scaling into an arbitrary
! range (2**nbits-1 not just 2**16-1) and are stored as re-scaled floats
! instead of short integers. The zlib algorithm does almost as
! well packing the rescaled floats as it does the scaled
! integers, and this avoids the need for the client to apply the
! rescaling (plus it allows the ability to adjust the packing range).
data_save = data
nbits = 14
call quantize_data(data_save, data, nbits, compress_err)
! compress_err is the max abs compression error (can be saved
! as a variable attribute.

• write an attribute.

charatt = 'hours since 2016-01-04 06:00:00'
call write_attribute(dso, 'units', charatt, 'time')

• access Variable and Dimension derived data types.

type(Variable) :: var
type(Dimension) :: dim
! see module_ncio.f90 for type definitions.
! type members can be used to the call netcdf-fortran90 interface
! directly.
var = get_var(ds, 'ugrd')
dim = get_dim(ds, 'time')

• close a dataset.

call close_dataset(ds)
call close_dataset(dso)