pkg/mnc/README.txt


API Discussions:
================

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)

  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_CREATE(       myThid, fname )
  MNC_FILE_OPEN(         myThid, fname, itype )
  MNC_FILE_ADD_ATTR_STR( myThid, fname, atname, sval )
  MNC_FILE_ADD_ATTR_DBL( myThid, fname, atname, len, dval )
  MNC_FILE_ADD_ATTR_REAL(myThid, fname, atname, len, rval )
  MNC_FILE_ADD_ATTR_INT( myThid, fname, atname, len, ival )
  MNC_FILE_ADD_ATTR_ANY( myThid, fname, atname, atype, cs,len,dv,rv,iv )
  ...
  MNC_FILE_READ_HEADER(  myThid, fname )

  MNC_DIM_INIT(          myThid, fname, dname, dlen )

  MNC_GRID_INIT(         myThid, fname, gname, ndim, dnames )

  MNC_VAR_INIT_DBL(      myThid, fname, gname, vname, units )
  MNC_VAR_INIT_REAL(     myThid, fname, gname, vname, units )
  MNC_VAR_INIT_INT(      myThid, fname, gname, vname, units )
  MNC_VAR_INIT_ANY(      myThid, fname, gname, vname, units, type )
  MNC_VAR_ADD_ATTR_STR(  myThid, fname, vname, atname, sval )
  MNC_VAR_ADD_ATTR_DBL(  myThid, fname, vname, atname, nv, dval )
  MNC_VAR_ADD_ATTR_REAL( myThid, fname, vname, atname, nv, rval )
  MNC_VAR_ADD_ATTR_INT(  myThid, fname, vname, atname, nv, ival )
  MNC_VAR_ADD_ATTR_ANY(  myThid, fname, vname, atname, atype, cs,len,dv,rv,iv )
  MNC_VAR_WRITE_DBL(     myThid, fname, vname, var )
  MNC_VAR_WRITE_REAL(    myThid, fname, vname, var )
  MNC_VAR_WRITE_INT(     myThid, fname, vname, var )
  MNC_VAR_WRITE_ANY(     myThid, fname, vname, vtype, dv, rv, iv )
  ...
  MNC_VAR_READ(          myThid, fname, vname, var )

  MNC_FILE_CLOSE(        myThid, fname )


Heres a further "convenience wrapper" written on top of the above UI:

  MNC_UGRID_INIT(        myThid, ugname, Htype, Hsub, Vtype, Ttype )

    with pre-defined individual          -      xy    -      -
    types and combinations:              U      x     c      t
                                         V      y     i
    'U_xy_i_t' or 'Cor_x_-_-'            Cen
                                         Cor

  MNC_UGRID_W_VAR(       myThid, myIter, fbase,bi,bj, ugname, 'RX', var )


To-Do:
======

 1) NAMING -- We should (as much as possible) try to name variables so
    that they are in agreement with the CF naming conventions.

 2) UNITS -- as with the names we need to follow conventions

 3) AM described her "diags" (or "myDiags" or "mDiags") interface
    which should use MNC for output.  The data storage idea is similar
    to the MNC tables-of-indicies approach but also includes one huge
    double-precision "accumulator" to hold all the temporary values
    (eg. partial sums for averages, current max/mins):

      vname ( ni ) 
      vlen  ( ni ) 
      vind  ( ni ) ------+
                         |

      vij_diag ( i, j, [...] )  w/ lat/lon indicies
      vgl_diag ( [...] )        wo/ lat/lon indicies (global)

 4) CNH pointed out that grid interpolation needs to be handled
    "on-the-fly" since pre-processing would result in overly large
    input files.  We need an interpolation API...

 5) From the group meeting on 2004/01/21, we need to define
    "sub-grids" corresponding to:

         var_name       HGRID       VGRID       TIME
         ===========================================
         u              U_xy        r_c         t
         eta            T_xy        -           t
         rac            T_xy        -           -

    And write a convenience wrapper so that users can write variables
    using just two function calls.  JMC and I worked out the
    following:


1
2	API Discussions:
3	================
4
5	As discussed in our group meeting of 2003-12-17 (AJA, CNH, JMC, AM,
6	PH, EH3), the NetCDF interface should resemble the following FORTRAN
7	subroutines:
8
9	1) "stubs" of the form: MNC_WV_[G\|L]2D_R[S\|L] ()
10
11	2) MNC_INIT_VGRID('V_GRID_TYPE', nx, ny, nz, zc, zg)
12
13	3) MNC_INIT_HGRID('H_GRID_TYPE', nx, ny, xc, yc, xg, yg)
14
15	4) MNC_INIT_VAR('file', 'Vname', 'Vunits', 'H_GTYPE', 'V_GTYPE', PREC, FillVal)
16
17	5) MNC_WRITE_VAR('file', 'Vname', var, bi, bj, myThid)
18
19	This is a reasonable start but its inflexible since it isn't easily
20	generalized to grids with dimensions other than [2,3,4] or grids with
21	non-horizontal orientations (eg. vertical slices).
22
23
24	Generalizing what we would like to write as "variables defined on 1-D
25	to n-D grids", one can imagine a small number of objects containing
26	all the relevant information:
27
28	a dimension: [ name, size, units ]
29	a grid: [ name, 1+ dim-ref ]
30	a variable: [ name, units, 1 grid-ref, data ]
31	an attribute: [ name, units, data ]
32	a NetCDF file: [ name, 0+ attr, 0+ grid-ref, 0+ var-ref ]
33
34	which can then be manipulated (created, associated, destroyed, etc.)
35	using a simple interface such as:
36
37	MNC_INIT( myThid )
38
39	MNC_FILE_CREATE( myThid, fname )
40	MNC_FILE_OPEN( myThid, fname, itype )
41	MNC_FILE_ADD_ATTR_STR( myThid, fname, atname, sval )
42	MNC_FILE_ADD_ATTR_DBL( myThid, fname, atname, len, dval )
43	MNC_FILE_ADD_ATTR_REAL(myThid, fname, atname, len, rval )
44	MNC_FILE_ADD_ATTR_INT( myThid, fname, atname, len, ival )
45	MNC_FILE_ADD_ATTR_ANY( myThid, fname, atname, atype, cs,len,dv,rv,iv )
46	...
47	MNC_FILE_READ_HEADER( myThid, fname )
48
49	MNC_DIM_INIT( myThid, fname, dname, dlen )
50
51	MNC_GRID_INIT( myThid, fname, gname, ndim, dnames )
52
53	MNC_VAR_INIT_DBL( myThid, fname, gname, vname, units )
54	MNC_VAR_INIT_REAL( myThid, fname, gname, vname, units )
55	MNC_VAR_INIT_INT( myThid, fname, gname, vname, units )
56	MNC_VAR_INIT_ANY( myThid, fname, gname, vname, units, type )
57	MNC_VAR_ADD_ATTR_STR( myThid, fname, vname, atname, sval )
58	MNC_VAR_ADD_ATTR_DBL( myThid, fname, vname, atname, nv, dval )
59	MNC_VAR_ADD_ATTR_REAL( myThid, fname, vname, atname, nv, rval )
60	MNC_VAR_ADD_ATTR_INT( myThid, fname, vname, atname, nv, ival )
61	MNC_VAR_ADD_ATTR_ANY( myThid, fname, vname, atname, atype, cs,len,dv,rv,iv )
62	MNC_VAR_WRITE_DBL( myThid, fname, vname, var )
63	MNC_VAR_WRITE_REAL( myThid, fname, vname, var )
64	MNC_VAR_WRITE_INT( myThid, fname, vname, var )
65	MNC_VAR_WRITE_ANY( myThid, fname, vname, vtype, dv, rv, iv )
66	...
67	MNC_VAR_READ( myThid, fname, vname, var )
68
69	MNC_FILE_CLOSE( myThid, fname )
70
71
72	Heres a further "convenience wrapper" written on top of the above UI:
73
74	MNC_UGRID_INIT( myThid, ugname, Htype, Hsub, Vtype, Ttype )
75
76	with pre-defined individual - xy - -
77	types and combinations: U x c t
78	V y i
79	'U_xy_i_t' or 'Cor_x_-_-' Cen
80	Cor
81
82	MNC_UGRID_W_VAR( myThid, myIter, fbase,bi,bj, ugname, 'RX', var )
83
84
85
86
87	To-Do:
88	======
89
90	1) NAMING -- We should (as much as possible) try to name variables so
91	that they are in agreement with the CF naming conventions.
92
93	2) UNITS -- as with the names we need to follow conventions
94
95	3) AM described her "diags" (or "myDiags" or "mDiags") interface
96	which should use MNC for output. The data storage idea is similar
97	to the MNC tables-of-indicies approach but also includes one huge
98	double-precision "accumulator" to hold all the temporary values
99	(eg. partial sums for averages, current max/mins):
100
101	vname ( ni )
102	vlen ( ni )
103	vind ( ni ) ------+
104	\|
105
106	vij_diag ( i, j, [...] ) w/ lat/lon indicies
107	vgl_diag ( [...] ) wo/ lat/lon indicies (global)
108
109	4) CNH pointed out that grid interpolation needs to be handled
110	"on-the-fly" since pre-processing would result in overly large
111	input files. We need an interpolation API...
112
113	5) From the group meeting on 2004/01/21, we need to define
114	"sub-grids" corresponding to:
115
116	var_name HGRID VGRID TIME
117	===========================================
118	u U_xy r_c t
119	eta T_xy - t
120	rac T_xy - -
121
122	And write a convenience wrapper so that users can write variables
123	using just two function calls. JMC and I worked out the
124	following:
125
126