pkg/mnc/README.txt


As discussed in our group meeting of 2003-12-17 (AJA, CNH, JMC, AM,
PH, EH3), the NetCDF interface should resemble the following FORTRAN
subroutines:

  1) "stubs" of the form:  MNC_WV_[G|L]2D_R[S|L] ()

  2) MNC_INIT_VGRID( 'V_GRID_TYPE', nx, ny, nz, zc, zg )
                                    1   1

  3) MNC_INIT_HGRID( 'H_GRID_TYPE', nx, ny, xc, yc, xg, yg )

  4) MNC_INIT_VAR( 'file', 'Vname', 'Vunits', 'H_GTYPE', 'V_GTYPE', PREC, FillVal )

  5) MNC_WRITE_VAR( 'file', 'Vname', var, bi, bj, myThid )

This is a reasonable start but its inflexible since it isn't easily
generalized to grids with dimensions other than [2,3,4] or grids with
non-horizontal orientations (eg. vertical slices).


Generalizing what we would like to write as "variables defined on 1-D
to n-D grids", one can imagine a small number of objects containing
all the relevant information:

  a dimension:   [ name, size, units ]
  a grid:        [ name, 1+ dim-ref ]
  a variable:    [ name, units, *1* grid-ref, data ]
  an attribute:  [ name, units, data ]
  a NetCDF file: [ name, 0+ attr, 0+ grid-ref, 0+ var-ref ]

which can then be manipulated (created, associated, destroyed, etc.)
using a simple interface such as:

  MNC_INIT(              myThid )

  MNC_FILE_OPEN(         myThid, fname, itype )
  MNC_FILE_ADD_ATTR_STR( myThid, fname, atname, sval )
  MNC_FILE_ADD_ATTR_INT( myThid, fname, atname, ival )
  MNC_FILE_ADD_ATTR_DBL( myThid, fname, atname, dval )
  ...
  MNC_FILE_READ_HEADER(  myThid, fname )

  MNC_DIM_INIT(          myThid, dname, dunits, dlen )

  MNC_GRID_INIT(         myThid, fname, gname, ndim, dnames )
  MNC_GRID_SET_XY_1DLL(  myThid, fname, gname, lats, lons )
  MNC_GRID_SET_XY_2DLL(  myThid, fname, gname, lats, lons )

  MNC_VAR_INIT_DBL(      myThid, fname, gname, vname, fillval )
  MNC_VAR_INIT_REAL(     myThid, fname, gname, vname, fillval )
  MNC_VAR_INIT_INT(      myThid, fname, gname, vname, fillval )
  MNC_VAR_ADD_ATTR_STR(  myThid, vname, name, sval )
  MNC_VAR_ADD_ATTR_INT(  myThid, vname, name, ival )
  MNC_VAR_ADD_ATTR_DBL(  myThid, vname, name, dval )
  MNC_VAR_WRITE(         myThid, vname, var )
  ...
  MNC_VAR_READ(          myThid, vname, var )

  MNC_FILE_CLOSE(        myThid, fname )

The above interface is powerful yet easy to use (easier than the
entire NetCDF interface) since it helps the user keep track of the
associations between files, "grids", variables, and dimensions.
1
2	As discussed in our group meeting of 2003-12-17 (AJA, CNH, JMC, AM,
3	PH, EH3), the NetCDF interface should resemble the following FORTRAN
4	subroutines:
5
6	1) "stubs" of the form: MNC_WV_[G\|L]2D_R[S\|L] ()
7
8	2) MNC_INIT_VGRID( 'V_GRID_TYPE', nx, ny, nz, zc, zg )
9	1 1
10
11	3) MNC_INIT_HGRID( 'H_GRID_TYPE', nx, ny, xc, yc, xg, yg )
12
13	4) MNC_INIT_VAR( 'file', 'Vname', 'Vunits', 'H_GTYPE', 'V_GTYPE', PREC, FillVal )
14
15	5) MNC_WRITE_VAR( 'file', 'Vname', var, bi, bj, myThid )
16
17	This is a reasonable start but its inflexible since it isn't easily
18	generalized to grids with dimensions other than [2,3,4] or grids with
19	non-horizontal orientations (eg. vertical slices).
20
21
22	Generalizing what we would like to write as "variables defined on 1-D
23	to n-D grids", one can imagine a small number of objects containing
24	all the relevant information:
25
26	a dimension: [ name, size, units ]
27	a grid: [ name, 1+ dim-ref ]
28	a variable: [ name, units, 1 grid-ref, data ]
29	an attribute: [ name, units, data ]
30	a NetCDF file: [ name, 0+ attr, 0+ grid-ref, 0+ var-ref ]
31
32	which can then be manipulated (created, associated, destroyed, etc.)
33	using a simple interface such as:
34
35	MNC_INIT( myThid )
36
37	MNC_FILE_OPEN( myThid, fname, itype )
38	MNC_FILE_ADD_ATTR_STR( myThid, fname, atname, sval )
39	MNC_FILE_ADD_ATTR_INT( myThid, fname, atname, ival )
40	MNC_FILE_ADD_ATTR_DBL( myThid, fname, atname, dval )
41	...
42	MNC_FILE_READ_HEADER( myThid, fname )
43
44	MNC_DIM_INIT( myThid, dname, dunits, dlen )
45
46	MNC_GRID_INIT( myThid, fname, gname, ndim, dnames )
47	MNC_GRID_SET_XY_1DLL( myThid, fname, gname, lats, lons )
48	MNC_GRID_SET_XY_2DLL( myThid, fname, gname, lats, lons )
49
50	MNC_VAR_INIT_DBL( myThid, fname, gname, vname, fillval )
51	MNC_VAR_INIT_REAL( myThid, fname, gname, vname, fillval )
52	MNC_VAR_INIT_INT( myThid, fname, gname, vname, fillval )
53	MNC_VAR_ADD_ATTR_STR( myThid, vname, name, sval )
54	MNC_VAR_ADD_ATTR_INT( myThid, vname, name, ival )
55	MNC_VAR_ADD_ATTR_DBL( myThid, vname, name, dval )
56	MNC_VAR_WRITE( myThid, vname, var )
57	...
58	MNC_VAR_READ( myThid, vname, var )
59
60	MNC_FILE_CLOSE( myThid, fname )
61
62	The above interface is powerful yet easy to use (easier than the
63	entire NetCDF interface) since it helps the user keep track of the
64	associations between files, "grids", variables, and dimensions.