Libcf – A CF Convention Library for NetCDF Ed Hartnett Unidata Program Center Boulder Colorado June 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!