NetCDF Getting Started

I. Overview
NETCDF is all called the network Common data format, the Chinese translation method is "The net Common Information Form",
For programmers, it is similar to a zip, JPEG, BMP file format and is a standard for file formats. netCDF
The purpose of the file is to store data in meteorological science, which is now a generating file for many data acquisition software.
The format.
Mathematically, the data stored by NETCDF is a single-valued function of a multi-argument. In the formula, it's
f (x, Y, z,...) =value, the function of the independent variable x, y, Z, etc. in NETCDF called Dimension (dimension)
or an axis (AXIX), the value of the function is called a variable (Variables) in NETCDF. Independent variables and function values
Some of the properties of physics, such as the Unit of measure (dimension), the name of physics, etc.
In netCDF, it is called the attribute (Attributes).

Second, the download of NETCDF
NETCDF is the official website for http://www.unidata.ucar.edu/software/netcdf/.
In this article, we mainly discuss the use of the NETCDF Software Library on the Windows platform. We're going to go from this site
Download the following resources
⑴NETCDF source code, the current address is
Ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/netcdf-beta.tar.gz
⑵NETCDF pre-compiled DLLs on the Windows platform, with the address
Ftp://ftp.unidata.ucar.edu/pub/netcdf/contrib/win32/netcdf-3.6.1-win32.zip
After decompression, there are the following things
Netcdf.dll for compiled DLLs
Ncgen.exe as a tool for generating NETCDF files
Ncdump.exe as a tool for reading NETCDF files
Netcdf.lib and Netcdf.exp will be used when programming, and will be spoken later.
⑶NETCDF related documents, including
①NETCDF's user manual for Http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.pdf
②NETCDF's Introductory tutorial for Http://www.unidata.ucar.edu/software/netcdf/docs/netcdf-tutorial.pdf
③NETCDF's C Interface API manual for Http://www.unidata.ucar.edu/software/netcdf/docs/netcdf-c.pdf
Let's look at the specific contents of the netCDF file.

Iii. contents of the netCDF file
The structure of a NETCDF file consists of the following objects:
1. Variables (Variables)
variables correspond to real physical data. For example, in our home meter, the readings displayed at each moment indicate the user's power consumption at that point.
This reading value can be represented by a variable in the NETCDF. It is a single value that takes time as an argument (or the number of arguments is one dimension)
Function. Another example in meteorology to make a pressure map, is "longitude xx degrees, latitude yy degrees of atmospheric pressure is the number of KPA", which is
A two-dimensional single-valued function, two-dimensional longitude and latitude, respectively. The function value is atmospheric pressure.
As can be seen from the above example, the variable in NETCDF is an n-dimensional array, and the dimension of the array is the number of arguments in the actual problem.
The value of the array is the observed physical value. Variables (array values) have six types of storage type in NETCDF, ASCII characters (char), Byte (byte), short Integer, Integer (int), floating point (float), double precision (doubles). Obviously these types are the same as those in C, and friends of C should be able to understand them very quickly.
2. Dimension (Dimension)
A dimension corresponds to an argument in a function, or an axis in a function image, which is an n-dimensional vector in linear algebra.
(This is also the origin of the name of the dimension). In netCDF, a dimension has a name and range (or length,
is a mathematically defined domain, which can be a discrete set of points or a continuous interval. In netCDF, the length of the dimension is basically limited,
There can be at most one dimension with an infinite length.
3. Attributes (Attribute)
Attribute comments or explanations of the specific physical meaning of the variable value and dimension. Because variables and dimensions are only dimensionless numbers in netCDF,
To make people understand the exact meaning of these numbers, you have to rely on the object of the attribute.
In netCDF, a property consists of a property name and a property value (typically a string). For example, in a CDL file
(The specific format of the CDL file is described in the next section) has such a snippet
Temperature:units = "Celsius";
The previous temperature is an already defined variable (Variable), that is, the temperature, the units after the colon is the property name,
Represents the physical unit, = The value behind the Units property, which is "Celsius", or Celsius, the whole line of code means
The unit of temperature for this physical quantity is Celsius, well understood.

III. Structure of the CDL
The CDL is all called the network Common data form Description Language, which is used to describe the netCDF file
A syntax format for the structure. It includes the specific definitions of the previous three NETCDF objects (variables, dimensions, attributes).
See a specific example (this example CDL file is from the NETCDF Tutorial in section 2.1 of the simple XY example)
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 above code defines a structure simple_xy that conforms to the NETCDF format.
This structure consists of three parts
1, the definition of the dimension, with dimensions: The beginning of the keyword
Dimensions
x = 6;
y = 12;
Defines two axes (or two dimensions), with names of X and Y,x axes (exactly the number of coordinate points) of 6,
The y-axis has a length of 12.
2. Definition of variables: Starting with variables:
Variables
int data (x, y);
A function data with the X and Y axes as arguments is defined, and the mathematical formula is f (x, y) =data;
Note that the order in which the dimensions appear is ordered, which determines the specific assignment results in the data segment.
3, the definition of data, the beginning
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;
This piece of data is =data by the mathematical function formula F (x, y).
is x=0,y=0, data = 0;
X=0,y=1, data = 1;


X=5,y=11 is, data=71;
It's important to note that
1. Order of assignment:
We give the CDL file in C format, so the order of assignment here is consistent with the C language, which is usually called "row assignment",
In Fortran, it is "column-valued", so in a Fortran file, the value order of the data segment is exactly
Row and column interchange.
2. Default values and coordinate variables for independent variables
If only the length of the dimension is given, then the value of the dimension starts from 0 and then automatically adds 1 to the (length-1) Stop,
In many cases we have to give our own coordinate values for each point, and we need to use the coordinate variables in the NETCDF.
"Coordinate varibles": Adds a unary function (independent variable) associated with a dimension and gives its range of values.
For example, the following CDL file (excerpt from the NETCDF tutorial 2.2 the SFC pres temp Example)
NETCDF Sfc_pres_temp {
Dimensions
latitude = 6; Latitude axis
longitude = 12; Longitude axis
Variables
Float latitude (latitude); Coordinate variables, storing specific latitude
Latitude:units = "Degrees_north";
float longitude (longitude); Coordinate variables, storing specific latitude
Longitude:units = "Degrees_east";
float pressure (latitude, longitude); Atmospheric pressure values for a point (intersection of longitude and latitude)
Pressure:units = "HPa"; The unit of atmospheric pressure is
float temperature (latitude, longitude); Temperature value of a point (intersection of longitude and latitude)
Temperature:units = "Celsius"; The unit of temperature is
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
For the above data, it is
Latitude = 25,longitude =-125, pressure = 900,temperature = 9;
Latitude = 25,longitude =-120, pressure = 906,temperature = 10.5;
And so on

Iv. reading and writing of NETCDF files
"Apply to the knowledge", the front is all netcdf of the basics, are for the core of this section-read and write files in NETCDF format
To pave the way, let's take a look at how to create a netcdf format file, and how to read its contents again.
1. Read and write netcdf files at the command line
⑴ Create a SIMPLE_XY.CDL file that is the first example in the previous section, "CDL Structure".
⑵ using the Ncgen.exe tool (see section II above) to create a netcdf file
① Add the Ncgen directory to the system path variable or copy the Ncgen.exe directly to the directory where SIMPLE_XY.CDL is located
② Execute ncgen-o simple_xy.nc simple_xy.cdl generate netcdf format file Simple_xy.nc
⑶ generated SIMPLE_XY.NC is a binary file, in order to restore data from this file information, you need to use the Ncdump tool
① Add the Ncdump directory to the system path variable or copy the Ncdump.exe directly to the directory where SIMPLE_XY.NC is located
② executes ncdump simple_xy.nc at the command line, and the output of the screen is exactly the same as the SIMPLE_XY.CDL content. Description
Our file read and write operations are correct.

2, programming read-write NETCDF file
Before we know how to manually build and read the Netddf file, let's look at how to implement the code in the program NETCDF
The establishment and analysis of documents. My programming environment is win2000+vc6.0 and the VC SP6 Patch pack is installed. Example code selected from
Section 2.1 of the NETCDF tutorial, the simple xy Example
⑴ NETCDF The source code to extract. We're going to use the libsrc/netcdf.h header file inside.
⑵ Create an empty Win32 console project in VC6. Named Simplexywrite, this project is used to create a NETCDF file
⑶ Copy the following files to the project directory
①NETCDF libsrc/netcdf.h header files in source code
②NETCDF the examples/c/simple_xy_wr.c file in the source code and renamed to Simple_xy_wr.cpp
③NETCDF netcdf.dll files and netcdf.lib files in a precompiled package
⑷ adding netcdf.h files and Simple_xy_wr.cpp to the project's file list
(Specific menu operation Project->add to Project->files)
⑸ add Netcdf.lib to the project's Lib list
(Specific menu operation Project->add to project->settings->link->object/library modules)
⑹ compiles and runs this project, it generates a SIMPLE_XY.NC file in the project directory, with the contents of our manually generated
The contents of the file are exactly the same.

The simple_xy_wr.c file is the C code that establishes the netCDF file, and the EXAMPLES/C/SIMPLE_XY_RD.C file is the analysis
NETCDF the code of the file, the reader can compile the file in VC6 with the steps similar to the one just described. The runtime puts the generated
SIMPLE_XY.NC copied to the project directory, if the file format is not wrong, will prompt
SUCCESS Reading example File simple_xy.nc!
Then exit.

3, automatically generate C code with ncgen command
  Given the simple_xy.cdl file, you can use
  ncgen-c  simple_xy.cdl
  command to output C code directly on the screen.
  However, this approach can only be used if the data of the CDL is relatively simple. For real projects,
  requires us to write the code ourselves.
  
V. Summary
  through the above content of the introduction, I believe that the reader has a general understanding of NETCDF. Overall, the core of
netCDF is to create a NETCDF format file through the CDL Description grammar. With this in mind, the
reader should continue to look deeper into NETCDF's other materials, and it shouldn't be much of a challenge. If so, the author's
purpose is achieved.

Vi. Appendices
For the convenience of the reader, the contents of several files used in this article are listed here
1. Contents of SIMPLE_XY.CDL File
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;
}
2. Contents of simple_xy-wr.c File
/* The NetCDF package.
Copyright 2006 University Corporation for atmospheric research/unidata.
See COPYRIGHT "File for conditions".

This was a very simple example which writes a 2D array of
Sample data. To handle this in NetCDF we create the shared
Dimensions, "x" and "Y", and a NetCDF variable, called "Data".

This example demonstrates the NetCDF C API. This was part of the
NetCDF tutorial, which can be found at:
Http://www.unidata.ucar.edu/software/netcdf/docs/netcdf-tutorial

Full documentation of the NetCDF C API can is found at:
Http://www.unidata.ucar.edu/software/netcdf/docs/netcdf-c

$Id: Simple_xy_wr.c,v 1.12 2007/02/14 20:59:21 Ed Exp $
*/
#include <stdlib.h>
#include <stdio.h>
#include <netcdf.h>

/* This is the name of the data file we'll create. */
#define FILE_NAME "Simple_xy.nc"

/* We are writing 2D data, a 6 x grid. */
#define NDIMS 2
#define NX 6
#define NY 12

/* Handle errors by printing an error message and exiting with a
* Non-zero status. */
#define ERRCODE 2
#define ERR (e) {printf ("Error:%s/n", Nc_strerror (e)); exit (Errcode);}

Int
Main ()
{
/* When we create NetCDF variables and dimensions, we get a
* ID for each one. */
int Ncid, X_dimid, Y_dimid, Varid;
int Dimids[ndims];

/* This is the data array we'll write. It'll be filled with a
* Progression of numbers for this example. */
int Data_out[nx][ny];

/* Loop indexes, and error handling. */
int x, y, retval;

/* Create some pretend data. If This wasn ' t A example program, we
* Would has some real data to write, for example, model
* Output. */
for (x = 0 × < NX; x + +)
for (y = 0; y < NY; y++)
Data_out[x][y] = x * NY + y;

/* Always check the return code of every NetCDF function call. Inch
* This example program, any retval which are not equal to Nc_noerr
* (0) would cause the program to print an error message and exit
* With a Non-zero return code. */

/* Create the file. The Nc_clobber parameter tells NetCDF to
* Overwrite this file, if it already exists.*/
if ((retval = Nc_create (file_name, Nc_clobber, &ncid)))
ERR (retval);

/* Define the dimensions. NetCDF would hand back a ID for each. */
if (retval = Nc_def_dim (Ncid, "X", NX, &x_dimid)))
ERR (retval);
if (retval = Nc_def_dim (ncid, "Y", NY, &y_dimid)))
ERR (retval);

/* The dimids array is used to pass the IDs of the dimensions of
* the variable. */
Dimids[0] = X_dimid;
DIMIDS[1] = Y_dimid;

/* Define the variable. The type of the variable in this case is
* Nc_int (4-byte integer). */
if (retval = Nc_def_var (ncid, "data", Nc_int, Ndims,
Dimids, &varid)))
ERR (retval);

/* End define mode. This tells NetCDF we is done defining
* Metadata. */
if ((retval = Nc_enddef (ncid)))
ERR (retval);

/* Write The pretend data to the file. Although NetCDF supports
* Reading and writing subsets of data, in this case we write all
* The data in one operation. */
if ((retval = Nc_put_var_int (Ncid, Varid, &data_out[0][0])))
ERR (retval);

/* Close the file. This frees to any internal NetCDF resources
* Associated with the file, and flushes any buffers. */
if ((retval = Nc_close (ncid)))
ERR (retval);

printf ("* * * * SUCCESS Writing example file simple_xy.nc!/n");
return 0;
}

3. Contents of SIMPLE_XY_RD.C File
/* The NetCDF package.
Copyright 2006 University Corporation for atmospheric research/unidata.
See COPYRIGHT "File for conditions".

Example which reads a small dummy array, which was
Written by SIMPLE_XY_WR.C. This was intended to illustrate the use
Of the NetCDF C API.

This program was part of the NetCDF tutorial:
Http://www.unidata.ucar.edu/software/netcdf/docs/netcdf-tutorial

Full documentation of the NetCDF C API can is found at:
Http://www.unidata.ucar.edu/software/netcdf/docs/netcdf-c

$Id: simple_xy_rd.c,v 1.9 2006/08/17 23:00:55 Russ Exp $
*/
#include <stdlib.h>
#include <stdio.h>
#include <netcdf.h>

/* This is the name of the data file we'll read. */
#define FILE_NAME "Simple_xy.nc"

/* We are reading 2D data, a 6 x grid. */
#define NX 6
#define NY 12

/* Handle errors by printing an error message and exiting with a
* Non-zero status. */
#define ERRCODE 2
#define ERR (e) {printf ("Error:%s/n", Nc_strerror (e)); exit (Errcode);}

Int
Main ()
{
/* This is the NetCDF ID for the file and data variable. */
int Ncid, Varid;

int Data_in[nx][ny];

/* Loop indexes, and error handling. */
int x, y, retval;

/* Open the file. Nc_nowrite tells NetCDF we want read-only access
* to the file.*/
if ((retval = Nc_open (file_name, Nc_nowrite, &ncid)))
ERR (retval);

/* Get The Varid of the data variable, based on its name. */
if ((retval = Nc_inq_varid (ncid, "data", &varid)))
ERR (retval);

/* Read the data. */
if ((retval = Nc_get_var_int (Ncid, Varid, &data_in[0][0])))
ERR (retval);

/* Check the data. */
for (x = 0 × < NX; x + +)
for (y = 0; y < NY; y++)
if (data_in[x][y]! = x * NY + y)
return errcode;

/* Close The file, freeing all resources. */
if ((retval = Nc_close (ncid)))
ERR (retval);

printf ("* * * * SUCCESS Reading example file%s!/n", file_name);
return 0;
}

NetCDF Getting Started