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; /* 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 [email protected]

 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!