netCDF in NOClim PT5

INTRO

Download the present archive file:
  netCDF_NOClim_v3.1.tar.gz
        Download previous versions:
          netCDF_NOClim_v3.0.tar.gz
          netCDF_NOClim_v2.1.tar.gz
          netCDF_NOClim_v2.01.tar.gz
          netCDF_NOClim_v2.0.tar.gz
          netCDF_NOClim_v1.1.tar.gz
          netCDF_NOClim_v1.0.tar.gz

The archive contains the following files:

 README			- this file
 regular/
  add_nc_climate.f	- subroutine for creating netCDF headers for
			  climatology variables
  write_all_nc_headers.f
                        - subroutine for creating a full netCDF header
  write_header.f	- source code for the "skeleton" program
  write_nc_attrib.f	- subroutines for writing netCDF attributes
  write_one_nc_header.f	- subroutine for including a new variable,
                          and several attributes, on a netCDF file
  id.inc		- declaration of netCDF identifiers to the
			  various variables
  name.inc		- variable names and attributes
  specs.inc		- users' specification for the netCDF header
  specs_COADS_SST.inc	- sample specification (for COADS SST)
  write_header.make	- "make-file" for the "skeleton" program
   + soft links to the following files in the "utilities/" directory:
  nc_errors.f
  strings.f
  err_codes.inc
  missing_values.inc
  stats_texts.inc

 irregular/
  ok_name_drifter.f	- function that checks if a specific variable
			  is implemented in the present version
  write_drifter_tst.f	- source code for a test program
  write_nc_attrib_drifter.f
			- subroutines for writing netCDF attributes
  write_nc_drifter.f	- subroutine for writing data from one drifter 
			  on a netCDF file
  id_drifter.inc	- declaration of netCDF identifiers to the
			  various variables
  name_drifter.inc	- short names of variables (without the
			  drifter no. extension), and some more
  specs_drifter.inc	- users' specification for netCDF global
			  attributes
  specs_drifter_tst.inc	- sample specification
  write_drifter.make	- "make-file" for the test program
   + soft links to the following files in the "utilities/" directory:
  nc_errors.f
  strings.f
  missing_values.inc

 utilities/
  check_nc_dims.f	- subroutines and functions that are useful
			  for testing Fortran source code declarations 
			  vs. information on existing netCDF headers
  convert_int_float.f	- subroutines that convert variables/vectors/arrays
			  between (4 byte) integers (w/ offset and
			  scaling) and floating point numbers
  convert_short_float.f	- subroutines that convert variables/vectors/arrays
			  between "short" integers (2 byte) (w/ offset
			  and scaling) and floating point numbers
  convert_string_date.f - subroutines for conversion of dates in
			  netCDF strings (e.g. '2000-10-26  21:00:00.0')
			  and numbers (e.g., 2000, 10, 26, 21, 0, 0.0)
  dates.f		- subroutines and functions for manipulation
			  of dates, such as finding the interval between
			  two dates, and adding a time offset to a date;
			  with support for calendar years and "climate 
			  years" (12 30-day months)
  end_dates.f		- subroutine which updates the earliest and
			  latest date
  err_codes.f           - program which create the file 'err_codes.inc'
			  based on the local implementation of the
			  netCDF library
  lonlat2dxdy.f		- subroutine which computes the size of grids
			  when their positions are known in latitude
			  and longitude
  nc_errors.f		- subroutines for output of netCDF error messages
  nc_rename_attr.f	- source code for renaming an attribute
			  (of a variable, or global)
  nc_rename_dim.f	- source code for renaming a dimension
  nc_rename_var.f	- source code for renaming a variable
  nc_reset_attr.f	- source code for changing the value of an
			  attribute
  nc_reset_value.f	- ource code for changing a prescribed value (or
			  a range of values) for a variable, to a new
                          value
			  (NOTE! use "nc_reset_value.sh"!
			   NOTE! no attributes such as "missing_value"
				  will be changed, use "nc_reset_attr"
			          for this purpose)
  nc_var_dims.f		- source code for reading the dimensional sizes
			  of a particular variable, and writing this to
			  the include-file "nc_var_dims.inc"
  short2short.f		- subroutine for conversion of 2D array of type
			  "short" (2 byte integers), due to different
			  scale factors, different offsets and/or
			  different missing values
  strings.f		- three functions for examination of strings
  err_codes.inc		- list of (a few) netCDF error codes used in
			  the software in this distribution
  missing_values.inc	- list of special values that should be used for
			  missing values, dry nodes etc.
  stats_texts.inc	- strings used in headers for climatology
	                  variables
  err_codes.make	- "make-file" for "err_codes"
  nc_rename_attr.make	- "make-file" for "nc_rename_attr"
  nc_rename_dim.make	- "make-file" for "nc_rename_dim"
  nc_rename_var.make	- "make-file" for "nc_rename_var"
  nc_reset_attr.make	- "make-file" for "nc_reset_attr"
  nc_reset_value.make	- "make-file" for "nc_reset_value"
  nc_var_dims.make	- "make-file" for "nc_var_dims"
  err_codes.sh		- script for compilation and execution of
			  "make-file" for 'err_codes'
  nc_reset_value.sh	- script for changing a prescribed value (or
			  a range of values) for a variable, to a new
                          value; type the script name with no arguments
			  to view the syntax

 climate/
  check_climate.f	- subroutines for checking existence and
			  dimensional sizes of climatological variables
  nc_bymonth.f		- program which computes grid-by-grid monthly
			  means from "high-frequency" input (e.g., daily)
  nc_climatology.f	- program which adds monthly climatology for a
			  specific variable to a netCDF file
  nc_dims.f		- program which writes dimensional sizes and a
			  switch for use/non-use of spherical coordinates
			  to the include file "nc_dims.inc"
  nc_month_routines.f   - misc. subroutines called by "nc_bymonth.f"
  nc_bymonth.make.make	- "make file" for "nc_bymonth"
  nc_climatology.make	- "make-file" for "nc_climatology"
  nc_dims.make		- "make-file" for "nc_dims"
  nc_bymonth.sh		- script for compilation and execution of
			  programs that computes grid-by-grid monthly
			  means and writes the result to an "empty"
			  netCDF file
  nc_climatology.sh	- script for compilation and execution of
			  programs that adds monthly climatology for a
			  specific variable to a netCDF file
  sample_list1, sample_list2
			- sample file lists, for "nc_climatology.sh"
  sample_month_list	- sample file list, for "nc_bymonth.sh"
   + soft links to the following files in the "utilities/" directory:
  check_nc_dims.f
  convert_int_float.f
  convert_short_float.f
  convert_string_date.f
  dates.f
  end_dates.f
  nc_errors.f
  strings.f
  missing_values.inc
  stats_texts.inc

For more information about netCDF, see the netCDF home page:
  http://www.unidata.ucar.edu/packages/netcdf/

Download netCDF source code, manual and more from:
  ftp://ftp.unidata.ucar.edu/pub/netcdf/

4-STEP HOW-TO
-regular sets-

Step 1.
Set the paths in the "make-file"
  utilities/err_codes.make
correctly, and run the script
  utilities/err_codes.sh
to create a proper "include"-file for some netCDF error codes.

Step 2.
Edit the file
  regular/specs.inc
to suit your set of data and/or model results
(see regular/specs_COADS_SST.inc for an example).
The values for X_offset and X_scale are probably OK, with a possible exception for 'level_offset' and 'level_scale'.

Step 3.
Edit the "make-file"
  regular/write_header.make
so the paths are set correctly.

Step 4.
"make" the "make-file" and run the program
  regular/write_header
to create the header.

4-STEP HOW-TO
-monthly climatology-

Step 0 (preparations).
If the input that will be processed is distributed on more than one file, the climatology must be written to a file that is separate from the input files. Otherwise, the climatology may be written to the input file. The climatological fields must be defined in the output netCDF file before Step 2 and Step 3 below are performed. These headers may be added to an existing file as outlined by the HOWTO above, provided that "climatology_on" is set to 1 on the include file (in Step 2 above).

Step 1.
Edit a file that contains
  on the first line:
      no. of files
  on the following lines:
      file name(s) for input, and output of monthly climatology fields

Step 2.
Run the script
  climate/nc_climatology.sh /filelist/ /variable/ [ /firstyear/ ( /lastyear/ ) ]
to add climatology to the (last) file that is listed on /filelist/, for the requested /variable/. See "climate/sample_list1" and "climate/sample_list2" for /filelist/ samples. For an explanation of the command line arguments, run the script with no arguments.

Step 3.
If the file (set of files) holds more than one variable, repeat Step 2 for the remaining variables.

5-STEP HOW-TO
-monthly means-

Step 1.
Edit the file
  regular/specs_bymonth.inc
to suit your set of data and/or model results
(see regular/specs_Reynolds_SST_bymonth.inc for an example).
The values for X_offset and X_scale are probably OK, with possible exceptions for 'level_offset', 'level_scale' and 'ssh_scale'.

Step 2.
Edit the "make-file"
  regular/write_header.make
so the paths are set correctly.

Step 3.
"make" the "make-file" and run the program
  regular/write_header
to create the header.

Step 4.
Run the script
  climate/nc_bymonth.sh /filelist/ /variable/
to write monthly means to the last file that is listed on /filelist/, for the requested /variable/. See "climate/sample_month_list" for a /filelist/ sample. For an explanation of the command line arguments, run the script with no arguments.

Step 5.
If the file (set of files) holds more than one variable, repeat Step 4 for the remaining variables.

4-STEP HOW-TO
-irregular sets-

Step 1.
Edit the file
  irregular/specs_drifter.inc
to include proper definitions of global attributes
(see specs_drifter_tst.inc for a poor example).

Step 2.
Write a program
  irregular/write_drifter.f
which reads the original drifter data, and calls the subroutine "write_nc_drifter" once for each variable from all drifter tracks
(see irregular/write_drifter_tst.f for a simple example).

Step 3.
Edit the "make-file"
  irregular/write_drifter.make
so the paths are set correctly.

Step 4.
"make" the "make-file" and run the program
  irregular/write_drifter
to create the netCDF file.

KNOWN PROBLEMS

Use of strings with netCDF includes the use of the "null character", or end-of-string character. The Fortran specification of this character is potentially platform dependent. This version uses the representation '\0', which should work on SGI, SUN and DEC platforms. See the function "null_chrctr" on
  utilities/strings.f
for the implementation of this.

The subroutines in version 3.0 has been tested in various ways, (mostly for x,y,t-fields). Further testing, and use, of the included functions and subroutines may well reveal errors that have not yet been identified. Users are encouraged to report problems to the author.

LOG OF CHANGES

 v3.1	- added a number of programs/script for easy manipulation of
	  names and values of variables and attributes, and for names
	  of dimensions
	- added the floating point function "decimal_year" in
	  "utilities/dates.f"
	- added flexibility in the interpretation of strings as dates
	  in "utilities/convert_string_date.f"
	- added more tranparency of use of upper- and lowercase
 v3.0	- added "climate/nc_bymonth.sh", software for computation of
	  monthly mean fields; the present version software does not use
	  weights, i.e., a value from April 30 2000 contributes solely
	  to the April 2000 mean (and not to the May 2000 mean)
	- added the utility "utilities/nc_rename" to rename a variable
	  on a netCDF file (to compile and link, make the file
	  "utilities/nc_rename.make"); run the program with no arguments
	  to view the syntax
	- added attribute 'min_defined' to some climatological
	  variables in "regular/add_nc_climate.f"
	- added some tranparency of use of upper- and lowercase variable
	  names (e.g. in "utilities/check_nc_dims.f", , notably for 'lat'
	  and 'lon', more work should be done on this topic)
	- minor modifications in "utilities/convert_string_date.f"
	  (mostly cosmetic)
 v2.1 	- included rough tests for out-of-bounds values when
	  converting from floating point numbers to (2 or 4 byte)
	  integers (in "utilities/convert_short_float.f" and in
	  "utilities/convert_int_float.f")
	- extended computations of climatology to include node-by-node
	  regression line coefficients (least squares fitted)
 v2.01	- removed bugs in the code on "regular/write_all_nc_headers.f"
	  and "regular/write_nc_attrib.f"
	- included option for requiring no missing values for wet
	  grids for all years for computation of climatology by
	  "climate/nc_climatology.sh", by specifying a negative number
	  of files in the list provided through the first argument 
	- changed use of intrinsic trigonometric functions to conform
	  with Fortran 77 standard
	- cosmetic changes in the shell scripts
	- changed syntax in "make"-files to conform with the standard
	- disbanded use of intrinsic functions "min" and "max" in
	  declarations in the "include"-files in the "regular/"-section
 v2.0	- added "climate/nc_climatology.sh"; software for computation of
	  monthly climatology
          (no. of values, mean value, standard deviation,
           overall minimum value, overall maximum value;
           all by month and grid no.),
	  the present version software does not use weights, i.e., a
          value from April 30 contributes solely to the April
	  climatology (and not to the May climatology)
	- included a number of additional subroutines in the
	  "utilities/"-section, on the files "end_dates.f",
	  "convert_int_float.f" and "convert_short_float.f"
	- in earlier versions, a mix of integers and logical
	  variables were used, and this is a potential for errors on
	  some platforms and/or compilers; in this version variables
	  remain either logical or integer throughout, note that
	  a number of "if-tests" has been modified accordingly
 v1.1   - added capabilities for modifications of existing netCDF
	  headers
	- rewritten much of the software in version 1.0 in order to
	  gain clarity in programming
	  ("regular/write_nc_header.f" in v. 1.0 corresponds to
	   "regular/write_all_nc_headers.f" in v. 1.1;
	   "regular/write_nc_intgr_header.f" in v. 1.0 corresponds to
	   one of the subroutines in "regular/write_one_nc_header.f"
	   in v. 1.1)
	- included new subroutines for creating variables for
	  climatological fields (means, standard deviations etc.), on
	  the file "regular/add_nc_climate.f"
	- added the switch 'climatology_on' on "regular/specs.inc"
	  for generation of climatological fields
	- added the switch 'climate_dates_on' on "regular/specs.inc"
	  for indication of time specification and calculation
	  (on/1: use 12 months of 30 days in each year,
	   off/0: use calendar years, including leap years)
	- added software for detection of netCDF error codes that are
	  utilized in the new software in v. 1.1; run the script
	  "utilities/err_codes.sh" after checking/altering the paths
	  in "utilities/err_codes.make"

 v1.0   - moved the file "utilities/str_len.f" to "utilities/strings.f";
	  included testing for null character; added new functions
	- corrected misspelt netCDF variable IDs, and included missing
	  IDs, on "regular/id.inc" and "regular/write_nc_header"
	- included transfer of netCDF variable ID from
	  "regular/write_nc_ingr_header" to "regular/write_nc_header"
	- included a substantial number of new functions and
	  subroutines in the "utilities/" directory; on the files
	  "chck_nc_dims.f", "convert_string_date.f", "dates.f",
	  "lonlat2dxdy.f" and "short2short.f"
	- introduced extensive and uniform "on-file" presentation for
	  all functions and subroutines in the "utilities/" directory

 v0.3	- restructured "regular/write_nc_header.f" by adapting a new
	  subroutine, on "regular/write_nc_intgr_header.f"
	- renamed directory "common/" to "utilities/"
	- renamed the file "common/utilities.f" to "utilities/str_len.f"
	- implemented different variables for the use of units Celsius 
	  and Kelvin for tempereature ('temp'/'temp_K'; 'sst'/'sst_K')
	- deleted vertical dimension for variables 'u_ice', 'v_ice'

 v0.2	- added support for irregular sets (drifter data)
	- included variable for layer thickness results on regular sets
	- typographical corrections

HISTORY

 v0.1   2000-09-28      Arne Melsom, DNMI       arne.melsom@dnmi.no
 v0.2   2000-10-06      Arne Melsom, DNMI       arne.melsom@dnmi.no
 v0.3   2000-10-17      Arne Melsom, DNMI       arne.melsom@dnmi.no
 v1.0   2000-10-27	Arne Melsom, DNMI	arne.melsom@dnmi.no
 v1.1   2000-12-20	Arne Melsom, DNMI	arne.melsom@dnmi.no
 v2.0   2001-02-23	Arne Melsom, DNMI	arne.melsom@dnmi.no
 v2.01  2001-03-22      Arne Melsom, DNMI       arne.melsom@dnmi.no
 v2.1   2001-09-07      Arne Melsom, DNMI       arne.melsom@dnmi.no
 v3.0   2001-10-31      Arne Melsom, DNMI       arne.melsom@dnmi.no
 v3.1   2001-12-21	Arne Melsom, DNMI	arne.melsom@dnmi.no

Arne Melsom
Last modified: Fri Dec 21 13:35:49 GMT 2001