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	edhill	1.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.