NetCDF Field Import/Export

NetCDF (network Common Data Form) software was developed at the Unidata Program Center. NetCDF is an interface for array-oriented data access and a library that provides an implementation of the interface.

The new NetCDF macros, Read_Field and Write_Field will be placed in the NETCDF library. In the network Editor these macros can be found in Main->Data I/O with the names Rd_netCDF_Fld and Wr_netCDF_Fld.

To use NETCDF.Read_Field, enter a file name in a typein box in exactly the same manner as similar macros such as MODS.Read_Field. The UI will present a list of variables. The "title" and "history" global attributes are read, if they exist, they are presented. Then one or more variables are picked, which must have the same array dimensions. If the netCDF file has an unlimited dimension, the UI will present an option to extract a single time step. A slider allows the specification of the desired time step. The maximum value of the slider is adjusted to match the number of time steps found in the file. The slider will be ignored if the "Extract time step" toggle is not checked. The toggle and slider will be hidden if the netCDF file does not have an unlimited dimension.

When the user is done picking variables and optionally specifying a time step, the user must click on the "Read Field" button. The button will be initially disabled, but will be enabled when the user picks a variable. The need for an explicit button click to trigger reading in the netCDF file is so that picking multiple variables does not trigger repetitive re-reading of the file (and triggering of downstream computations) as the user clicks to add variables one-by-one. At that point the netCDF file will be read in to the output field. Error messages may be generated if the netCDF file is invalid somehow or if the user has picked variables that cannot be placed into a single field. Further details can be found below with the discussion for NCread_field. A special loophole has been created with respect to the "Read Field" button and time steps. Once a netCDF file has been read in, then it is possible to advance to the next time step by clicking on the time step slider without clicking on the "Read Field" button. NETCDF.Read_Field attempts to determine if the netCDF file is best represented as a uniform field, a rectilinear field, or a structured/irregular field. Most "standard" netCDF files will be mapped into a rectilinear field. A manual override is provided to control the field type. New users should leave the field type menu set to "Unspecified", which is the default, but experienced users can force a netCDF file to be read in as a user-specified field type. The most common use of this would be to force a nominally rectilinear field to be read in as a uniform field. For NETCDF.Read_Field to recognize a structured/irregular field, there needs to be some AVS/Express-specific additions to the netCDF file. For a structured/irregular field, AVS/Express needs to have source of coordinate information. The simplest way to see how this is done is to write out a structured field using NETCDF.Write_Field and examine the resulting netCDF file using the netCDF utility 'ncdump'.

Also in the NETCDF library, are the low-level modules

NClist_vars
NCread_array
NCread_field
NCwrite_field

NClist_vars is a utility module that is used by the NETCDF.Read_Field UI. It reads in the netCDF file and generates a list of possible variables. The variable list is filtered a bit by this module. Variables of type 'char' are excluded, as are 0D and 1D variables. NetCDF 'coordinate variables' are also excluded. The "title" and "history" attributes are also read, if present, for use by the UI. If an unlimited dimension is present, then the current size of the unlimited dimension is read and output, also for use by the UI.

NCread_array extracts a single variable from a netCDF file and outputs into a single AVS/Express array. Most users will want to stick with NETCDF.Read_Field and NCread_field, but NCread_array can be used as a building block to build custom networks to handle non-standard situations.

NCread_field is the module at the center of this package. It takes in a netCDF filename, a list of variables, an optional field type (which defaults to "Unspecified"), and an optional time step. The time step default is -1, which tells NCread_field to not attempt to extract a time step. As discussed above, NCread_field then attempts to read in the netCDF file into an AVS/Express field, mapping each netCDF variable into a node data component. The dimensions of each netCDF variable are extracted and used to construct the dimensions of the field. If time stepping is used, then the dimensionality of the AVS/Express field will be one less than the dimensionality of the netCDF variable (e.g. 3D becomes 2D, etc.). As already mentioned, if multiple variables are read in, the dimensions of the variables must match so that the variables can be placed together in a single field.

The netCDF global attributes "title" and "history" are read, if present, and placed into the field as supplemental information. Additionally, the netCDF dimension names are also added to the field as supplemental information. For each netCDF variable, the "_FillValue" variable attribute is used to set the corresponding node data component's null value and null value flag. The name of each netCDF variable used to set the label string of the corresponding node data component. The "units" netCDF variable attribute is used to set the units string. The "long_name" netCDF variable attribute is also read and is added to the field as supplemental information.

For a field to be recognized as a structured/irregular field, it must have a netCDF global attribute "XP_CLASS" that contains the string "Struct". It must also have a float variable "XP_COORDINATES" that provides the coordinate information. If the global attribute "XP_CLASS" contains the string "Unif" or "Rect", then the field's type will be forced to uniform or rectilinear, respectively.

NCwrite_field is essentially the inverse of NCread_field. Each node data component is written out as a separate netCDF variable. If the special dimension name information (an array of strings that is added to the field) is found, it is used for the netCDF dimension names. If the dimension name information is not found, it generates the names "dim0", "dim1", etc. For all fields it writes out the special global attribute "XP_CLASS", which will help NCread_field read it back in correctly. For structured fields, it also writes out the special variable "XP_COORDINATES". The node data component's label string is used as the netCDF variable name. If the label string is not present, NCwrite_field generates the names "var0", "var1", etc. NCwrite_field supports all the netCDF attributes mentioned above in the discussion of NCread_field, including "title", "_FillValue, "units", and "long_name".