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 )
                                    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_CREATE(       myThid, fname )
  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_DIM_REMOVE(        myThid, dname )

  MNC_GRID_INIT(         myThid, fname, gname, ndim, dnames )
  MNC_GRID_SET_LL(       myThid, fname, gname, type, 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.


To-Do:
======

 1) 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...
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	1 1
13
14	3) MNC_INIT_HGRID( 'H_GRID_TYPE', nx, ny, xc, yc, xg, yg )
15
16	4) MNC_INIT_VAR( 'file', 'Vname', 'Vunits', 'H_GTYPE', 'V_GTYPE', PREC, FillVal )
17
18	5) MNC_WRITE_VAR( 'file', 'Vname', var, bi, bj, myThid )
19
20	This is a reasonable start but its inflexible since it isn't easily
21	generalized to grids with dimensions other than [2,3,4] or grids with
22	non-horizontal orientations (eg. vertical slices).
23
24
25	Generalizing what we would like to write as "variables defined on 1-D
26	to n-D grids", one can imagine a small number of objects containing
27	all the relevant information:
28
29	a dimension: [ name, size, units ]
30	a grid: [ name, 1+ dim-ref ]
31	a variable: [ name, units, 1 grid-ref, data ]
32	an attribute: [ name, units, data ]
33	a NetCDF file: [ name, 0+ attr, 0+ grid-ref, 0+ var-ref ]
34
35	which can then be manipulated (created, associated, destroyed, etc.)
36	using a simple interface such as:
37
38	MNC_INIT( myThid )
39
40	MNC_FILE_CREATE( myThid, fname )
41	MNC_FILE_OPEN( myThid, fname, itype )
42	MNC_FILE_ADD_ATTR_STR( myThid, fname, atname, sval )
43	MNC_FILE_ADD_ATTR_INT( myThid, fname, atname, ival )
44	MNC_FILE_ADD_ATTR_DBL( myThid, fname, atname, dval )
45	...
46	MNC_FILE_READ_HEADER( myThid, fname )
47
48	MNC_DIM_INIT( myThid, dname, dunits, dlen )
49	MNC_DIM_REMOVE( myThid, dname )
50
51	MNC_GRID_INIT( myThid, fname, gname, ndim, dnames )
52	MNC_GRID_SET_LL( myThid, fname, gname, type, lats, lons )
53
54	MNC_VAR_INIT_DBL( myThid, fname, gname, vname, fillval )
55	MNC_VAR_INIT_REAL( myThid, fname, gname, vname, fillval )
56	MNC_VAR_INIT_INT( myThid, fname, gname, vname, fillval )
57	MNC_VAR_ADD_ATTR_STR( myThid, vname, name, sval )
58	MNC_VAR_ADD_ATTR_INT( myThid, vname, name, ival )
59	MNC_VAR_ADD_ATTR_DBL( myThid, vname, name, dval )
60	MNC_VAR_WRITE( myThid, vname, var )
61	...
62	MNC_VAR_READ( myThid, vname, var )
63
64	MNC_FILE_CLOSE( myThid, fname )
65
66	The above interface is powerful yet easy to use (easier than the
67	entire NetCDF interface) since it helps the user keep track of the
68	associations between files, "grids", variables, and dimensions.
69
70
71	To-Do:
72	======
73
74	1) CNH pointed out that grid interpolation needs to be handled
75	"on-the-fly" since pre-processing would result in overly large
76	input files. We need an interpolation API...