Libcf – A CF Convention Library for NetCDF

Ed HartnettUnidata Program Center

Boulder ColoradoJune 11, 2007

Unidata

Mission : To provide data, tools, and community leadership for enhanced Earth-

system education and research.

NetCDF/libcf Development in C/C++/Fortran at Unidata

NetCDF 3.6.2 released March, 2007 NetCDF 4.0 beta1 released April 2007 Libcf alpha4 released November 2006

The NetCDF Classic Model

The netCDF classic data model: files, dimensions, variables, attributes, 6 data types.

The expanded netCDF-4 data model adds: groups, additional atomic and user-defined data types, additional unlimited dimensions.

Create netCDF-4/HDF5 files which conform to the classic model with a flag at create time.

Goals for libcf

Make using CF Convetions easier for readers and writers of data.

Reduce duplication of effort. Ensure CF conforming files. Provide a geo-science API for netCDF. Provide some of the advanced features

developed for netCDF-Java. Work with both netCDF-3 and

netCDF-4/HDF5 files.

Limitations of libcf

Handles classic model netCDF only. Lightly tested. Doesn't handle indirect coordinates. Does not check standard name table. Alpha release - Functions in the API may

change a little.

Current Status of libcf

Available in alpha release from libcf web page at Unidata: http://www.unidata.ucar.edu/software/libcf/

Nightly build/test cycle. C and F77 APIs are provided. Seeking feedback and test cases from CF

users.

Other Software Efforts

Climate Model Output Rewritter (CMOR). CFIO from NASA/GMAO. Brian Ermold (ACRF Development) DOD

project (just discovered).

Libcf and NetCDF-4

File Level Functions

Mark file as CF-1.0 Does file follow CF-

1.0 Write or read CF

recommended global attributes (title, history, institution, source, etc.)

nccf_def_convention nccf_inq_convention nccf_def_file nccf_add_history

Variable Functions

Define or read CF recommended variable attributes (units, fill_value, institution, etc.)

nccf_def_var nc_inq_var nccf_def_var_missing nc_inq_var_missing nccf_def_notes nccf_inq_notes

Lat/Lon Functions

Write and read simple latitude and longitude coordinate variables.

Currently handles simple situations only.

nc_def_latitude nc_inq_latitude nc_def_longitude nc_inq_longitude

Vertical Dimensions, First Try

A vertical coordinate API, done like the lat/long API, proves more complex.

int nccf_def_lvl(int ncid, const char *name, size_t len, nc_type xtype, const char *units, int positive_up, const char *standard_name, const char *formula_terms, int cdm_axis_type, int *lvl_dimidp, int *lvl_varidp);

int nccf_inq_lvl(int ncid, char *name, size_t *lenp, nc_type *xtypep, size_t *ft_lenp, char *formula_terms, int *positive_upp, int *lvl_dimidp, int *lvl_varidp);

Vertical Dimensions, Second Try

Functions to handle the vertical coordinates in appendix D of the CF 1.0 document.

NetCDF define mode considerations make the situation more complex.

nccf_def_lvl_sigma/nccf_def_ft_sigma nccf_inq_sigma Similarly for atmosphere_ln_pressure_coordinate,

atmosphere_hybrid_height_coordinate, atmosphere_sleve_coordinate, etc.

Time Dimension

Write and read time coordinate variable information.

nc_def_time nc_inq_time

Geographic Subsetting

Recent addition to libcf. Does not yet handle complex cases.

int nccf_get_vara(int ncid, int varid, float *lat_range, int *nlat, float *lon_range, int *nlon, int lvl_index, int timestep, void *data);

An Example if (nc_create(FILE_NAME_SIMPLE_SIGMA, 0, &ncid)) ERR;

if (nccf_def_file(ncid, TITLE, HISTORY)) ERR;

/* Create coordinates. */

if (nccf_def_latitude(ncid, NLATS, NC_INT, &lat_did,

&lat_vid)) ERR;

if (nccf_def_longitude(ncid, NLONS, NC_INT, &lon_did,

&lon_vid)) ERR;

if (nccf_def_lvl_sigma(ncid, "sigma", NC_FLOAT, NLVLS,

&lvl_did, &lvl_vid)) ERR;

if (nccf_def_time(ncid, "time", NC_UNLIMITED, NC_FLOAT, TIME_UNITS, "time", &time_did, &time_vid)) ERR;

<snip>

/* Save the ps and ptop info in formula terms attribute. */

if (nccf_def_ft_sigma(ncid, lvl_vid, ps_vid, ptop_vid)) ERR;

Website and Documentation

Daily Snapshots and Testing

Future of libcf

Better geographic subsetting. More testing on more sample files. Continued integration and borrowing of

functionality from other CF efforts. More convenience functions. Optional standard name table checking. Optional UDUNITS checking. CF Conventions 2.0 and beyond. F90 and C++ APIs.

How to Contribute

Send CF example data files to ed@unidata.ucar.edu

Download and try the libcf library. Let us know of any additional parallel

efforts.

Annual NetCDF Bike Rides

Celebrate your favorite data format with a bike ride!

Wednesday afternoon, rain or shine.

Route to be determined – bike paths if possible!