NetCDF Example Programs

Table of Contents

• The simple_xy Example
• The sfc_pres_temp Example
• The pres_temp_4D Example
• The simple_nc4 Example
• The simple_xy_nc4 Example
• The filter example

The netCDF example programs show how to use netCDF.

In the netCDF distribution, the “examples” directory contains examples in C and CDL. The examples create, and then read, example data files of increasing complexity.

There are three sets of netCDF classic example programs; corresponding examples are included with the netCDF Fortran and C++ APIs.

• The simple_xy Example
• The sfc_pres_temp Example
• The pres_temp_4D Example

Additionally, there is a example program demonstrating how to use the filter API. This is C only and only accessible when built with automake currently.

• The filter example

Any existing netCDF applications can be converted to generate netCDF-4/HDF5 files. Simply change the file creation call to include the correct mode flag.

In one of the netCDF classic examples which write a data file, change the nc_create() call so that NC_NETCDF4 is one of the flags set on the create.

The corresponding read example will work without modification; netCDF will notice that the file is a NetCDF-4/HDF5 file, and will read it automatically, just as if it were a netCDF classic format file.

In the example in this section we show some of the advanced features of netCDF-4.

• The simple_nc4 Example
• The simple_xy_nc4 Example

The examples are built and run with the “make check” command. (See building).

The corresponding examples in each language create identical netCDF data files. For example, the C program sfc_pres_temp_wr.c produces the same data file as the Fortran 77 program sfc_pres_temp_wr.f.

The simple_xy Example

This example is an unrealistically simple netCDF file, to demonstrate the minimum operation of the netCDF APIs. Users should seek to make their netCDF files more self-describing than this primitive example.

• simple_xy_wr.c
• simple_xy_rd.c

As in all the netCDF tutorial examples, this example file can be created by C and by ncgen, which creates it from a CDL script. Both ncgen and the C example create identical files, “simple_xy.nc.”

The simple_xy.nc data file contains two dimensions, “x” and “y”, and one netCDF variable, “data.”

The CDL for this example is shown below. For more information on ncdump and ncgen see NetCDF Utilities.

netcdf simple_xy {
dimensions:
   x = 6 ;
   y = 12 ;
variables:
   int data(x, y) ;
data:
 
 data =
  0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
  12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23,
  24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35,
  36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47,
  48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59,
  60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71 ;
}

The sfc_pres_temp Example

This example has been constructed for the meteorological mind.

Suppose you have some data you want to write to a netCDF file. For example, you have one time step of surface temperature and surface pressure, on a 6 x 12 latitude longitude grid.

To store this in netCDF, create a file, add two dimensions (latitude and longitude) and two variables (pressure and temperature).

• sfc_pres_temp_wr.c
• sfc_pres_temp_rd.c

In this example we add some netCDF attributes, as is typical in scientific applications, to further describe the data. In this case we add a units attribute to every netCDF variable.

In this example we also add additional netCDF variables to describe the coordinate system. These “coordinate variables” allow us to specify the latitudes and longitudes that describe the data grid.

The CDL version of the data file, generated by ncdump, is shown below (see The NetCDF Utilities).

netcdf sfc_pres_temp {
dimensions:
   latitude = 6 ;
   longitude = 12 ;
variables:
   float latitude(latitude) ;
       latitude:units = "degrees_north" ;
   float longitude(longitude) ;
       longitude:units = "degrees_east" ;
   float pressure(latitude, longitude) ;
       pressure:units = "hPa" ;
   float temperature(latitude, longitude) ;
       temperature:units = "celsius" ;
data:
 
 latitude = 25, 30, 35, 40, 45, 50 ;
 
 longitude = -125, -120, -115, -110, -105, -100, -95, -90, -85, -80, -75, -70 ;
 
 pressure =
  900, 906, 912, 918, 924, 930, 936, 942, 948, 954, 960, 966,
  901, 907, 913, 919, 925, 931, 937, 943, 949, 955, 961, 967,
  902, 908, 914, 920, 926, 932, 938, 944, 950, 956, 962, 968,
  903, 909, 915, 921, 927, 933, 939, 945, 951, 957, 963, 969,
  904, 910, 916, 922, 928, 934, 940, 946, 952, 958, 964, 970,
  905, 911, 917, 923, 929, 935, 941, 947, 953, 959, 965, 971 ;
 
 temperature =
  9, 10.5, 12, 13.5, 15, 16.5, 18, 19.5, 21, 22.5, 24, 25.5,
  9.25, 10.75, 12.25, 13.75, 15.25, 16.75, 18.25, 19.75, 21.25, 22.75, 24.25,
    25.75,
  9.5, 11, 12.5, 14, 15.5, 17, 18.5, 20, 21.5, 23, 24.5, 26,
  9.75, 11.25, 12.75, 14.25, 15.75, 17.25, 18.75, 20.25, 21.75, 23.25, 24.75,
    26.25,
  10, 11.5, 13, 14.5, 16, 17.5, 19, 20.5, 22, 23.5, 25, 26.5,
  10.25, 11.75, 13.25, 14.75, 16.25, 17.75, 19.25, 20.75, 22.25, 23.75,
    25.25, 26.75 ;
}

The pres_temp_4D Example

This example expands on the previous example by making our two-dimensional data into four-dimensional data, adding a vertical level axis and an unlimited time step axis.

• pres_temp_4D_wr.c
• pres_temp_4D_rd.c

Additionally, in this example the data are written and read one time step at a time, as is typical in scientific applications that use the unlimited dimension.

The sample data file created by pres_temp_4D_wr can be examined with the utility ncdump (see The NetCDF Utilities).

netcdf pres_temp_4D {
dimensions:
   level = 2 ;
   latitude = 6 ;
   longitude = 12 ;
   time = UNLIMITED ; // (2 currently)
variables:
   float latitude(latitude) ;
       latitude:units = "degrees_north" ;
   float longitude(longitude) ;
       longitude:units = "degrees_east" ;
   float pressure(time, level, latitude, longitude) ;
       pressure:units = "hPa" ;
   float temperature(time, level, latitude, longitude) ;
       temperature:units = "celsius" ;
data:
 
 latitude = 25, 30, 35, 40, 45, 50 ;
 
 longitude = -125, -120, -115, -110, -105, -100, -95, -90, -85, -80, -75, -70 ;
 
 pressure =
  900, 901, 902, 903, 904, 905, 906, 907, 908, 909, 910, 911,
  912, 913, 914, 915, 916, 917, 918, 919, 920, 921, 922, 923,
  924, 925, 926, 927, 928, 929, 930, 931, 932, 933, 934, 935,
  936, 937, 938, 939, 940, 941, 942, 943, 944, 945, 946, 947,
  948, 949, 950, 951, 952, 953, 954, 955, 956, 957, 958, 959,
  960, 961, 962, 963, 964, 965, 966, 967, 968, 969, 970, 971,
  972, 973, 974, 975, 976, 977, 978, 979, 980, 981, 982, 983,
  984, 985, 986, 987, 988, 989, 990, 991, 992, 993, 994, 995,
  996, 997, 998, 999, 1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007,
  1008, 1009, 1010, 1011, 1012, 1013, 1014, 1015, 1016, 1017, 1018, 1019,
  1020, 1021, 1022, 1023, 1024, 1025, 1026, 1027, 1028, 1029, 1030, 1031,
  1032, 1033, 1034, 1035, 1036, 1037, 1038, 1039, 1040, 1041, 1042, 1043,
  900, 901, 902, 903, 904, 905, 906, 907, 908, 909, 910, 911,
  912, 913, 914, 915, 916, 917, 918, 919, 920, 921, 922, 923,
  924, 925, 926, 927, 928, 929, 930, 931, 932, 933, 934, 935,
  936, 937, 938, 939, 940, 941, 942, 943, 944, 945, 946, 947,
  948, 949, 950, 951, 952, 953, 954, 955, 956, 957, 958, 959,
  960, 961, 962, 963, 964, 965, 966, 967, 968, 969, 970, 971,
  972, 973, 974, 975, 976, 977, 978, 979, 980, 981, 982, 983,
  984, 985, 986, 987, 988, 989, 990, 991, 992, 993, 994, 995,
  996, 997, 998, 999, 1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007,
  1008, 1009, 1010, 1011, 1012, 1013, 1014, 1015, 1016, 1017, 1018, 1019,
  1020, 1021, 1022, 1023, 1024, 1025, 1026, 1027, 1028, 1029, 1030, 1031,
  1032, 1033, 1034, 1035, 1036, 1037, 1038, 1039, 1040, 1041, 1042, 1043 ;
 
 temperature =
  9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
  21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32,
  33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44,
  45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56,
  57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68,
  69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80,
  81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92,
  93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104,
  105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116,
  117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128,
  129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140,
  141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152,
  9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
  21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32,
  33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44,
  45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56,
  57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68,
  69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80,
  81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92,
  93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104,
  105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116,
  117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128,
  129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140,
  141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152 ;
}

The simple_nc4 Example

This example, like the simple_xy netCDF-3 example above, is an overly simplified example which demonstrates how to use groups in a netCDF-4 file.

This example is only available in C for this version of netCDF-4. The example creates and then reads the file “simple_nc4.nc.”

The simple_xy.nc data file contains two dimensions, “x” and “y”, two groups, “grp1” and “grp2”, and two data variables, one in each group, both named: “data.” One data variable is an unsigned 64-bit integer, the other a user-defined compound type.

The example program simple_nc4_wr.c creates the example data file simple_nc4.nc. The example program simple_nc4_rd.c reads the data file.

• simple_nc4_wr.c
• simple_nc4_rd.c

The simple_xy_nc4 Example

This example, like the simple_xy netCDF-3 example above, is an overly simplified example. It is based on the simple_xy example, but used data chunking, compression, and the fletcher32 filter.

(These are all HDF5 features. For more information see http://hdfgroup.org/HDF5/).

This example is not yet available in C++. We hope to have the C++ example in a future release of netCDF.

The example creates and then reads the file “simple_xy_nc4.nc.”

The example program simple_xy_nc4_wr.c creates the example data file simple_xy_nc4.nc. The example program simple_xy_nc4_rd.c reads the data file.

• simple_xy_nc4_wr.c
• simple_xy_nc4_rd.c

The filter example

This example demonstrates how to write and read a variable that is compressed using, in this example, bzip2 compression.

• filter_example.c