pkg/mnc/README.txt

a27dc5c859 Ed H*0001 API Discussions:
                0002 ================
                0003
4de8f8c098 Ed H*0004 As discussed in our group meeting of 2003-12-17 (AJA, CNH, JMC, AM,
                0005 PH, EH3), the NetCDF interface should resemble the following FORTRAN
                0006 subroutines:
                0007
                0008   1) "stubs" of the form:  MNC_WV_[G|L]2D_R[S|L] ()
                0009
75987013ac Ed H*0010   2) MNC_INIT_VGRID('V_GRID_TYPE', nx, ny, nz, zc, zg)
4de8f8c098 Ed H*0011
75987013ac Ed H*0012   3) MNC_INIT_HGRID('H_GRID_TYPE', nx, ny, xc, yc, xg, yg)
4de8f8c098 Ed H*0013
75987013ac Ed H*0014   4) MNC_INIT_VAR('file', 'Vname', 'Vunits', 'H_GTYPE', 'V_GTYPE', PREC, FillVal)
4de8f8c098 Ed H*0015
75987013ac Ed H*0016   5) MNC_WRITE_VAR('file', 'Vname', var, bi, bj, myThid)
4de8f8c098 Ed H*0017
                0018 This is a reasonable start but its inflexible since it isn't easily
                0019 generalized to grids with dimensions other than [2,3,4] or grids with
                0020 non-horizontal orientations (eg. vertical slices).
                0021
                0022
                0023 Generalizing what we would like to write as "variables defined on 1-D
                0024 to n-D grids", one can imagine a small number of objects containing
                0025 all the relevant information:
                0026
                0027   a dimension:   [ name, size, units ]
                0028   a grid:        [ name, 1+ dim-ref ]
                0029   a variable:    [ name, units, *1* grid-ref, data ]
                0030   an attribute:  [ name, units, data ]
                0031   a NetCDF file: [ name, 0+ attr, 0+ grid-ref, 0+ var-ref ]
                0032
                0033 which can then be manipulated (created, associated, destroyed, etc.)
                0034 using a simple interface such as:
                0035
75987013ac Ed H*0036   MNC_INIT(              myThid )
4de8f8c098 Ed H*0037
3f2ea2a4ed Ed H*0038   MNC_FILE_CREATE(       fname, myThid )
                0039   MNC_FILE_OPEN(         fname, itype, myThid )
                0040   MNC_FILE_ADD_ATTR_STR( fname, atname, sval, myThid )
                0041   MNC_FILE_ADD_ATTR_DBL( fname, atname, len, dval, myThid )
                0042   MNC_FILE_ADD_ATTR_REAL(fname, atname, len, rval, myThid )
                0043   MNC_FILE_ADD_ATTR_INT( fname, atname, len, ival, myThid )
                0044   MNC_FILE_ADD_ATTR_ANY( fname, atname, atype, cs,len,dv,rv,iv, myThid )
4de8f8c098 Ed H*0045   ...
3f2ea2a4ed Ed H*0046   MNC_FILE_READ_HEADER(  fname, myThid )
                0047
                0048   MNC_DIM_INIT(          fname, dname, dlen, myThid )
                0049
                0050   MNC_GRID_INIT(         fname, gname, ndim, dnames, myThid )
                0051
                0052   MNC_VAR_INIT_DBL(      fname, gname, vname, units, myThid )
                0053   MNC_VAR_INIT_REAL(     fname, gname, vname, units, myThid )
                0054   MNC_VAR_INIT_INT(      fname, gname, vname, units, myThid )
                0055   MNC_VAR_INIT_ANY(      fname, gname, vname, units, type, myThid )
                0056   MNC_VAR_ADD_ATTR_STR(  fname, vname, atname, sval, myThid )
                0057   MNC_VAR_ADD_ATTR_DBL(  fname, vname, atname, nv, dval, myThid )
                0058   MNC_VAR_ADD_ATTR_REAL( fname, vname, atname, nv, rval, myThid )
                0059   MNC_VAR_ADD_ATTR_INT(  fname, vname, atname, nv, ival, myThid )
                0060   MNC_VAR_ADD_ATTR_ANY(  fname, vname, atname, atype, cs,len,dv,rv,iv, myThid )
                0061   MNC_VAR_WRITE_DBL(     fname, vname, var, myThid )
                0062   MNC_VAR_WRITE_REAL(    fname, vname, var, myThid )
                0063   MNC_VAR_WRITE_INT(     fname, vname, var, myThid )
                0064   MNC_VAR_WRITE_ANY(     fname, vname, vtype, dv, rv, iv, myThid )
4de8f8c098 Ed H*0065   ...
3f2ea2a4ed Ed H*0066   MNC_VAR_READ(          fname, vname, var, myThid )
4de8f8c098 Ed H*0067
3f2ea2a4ed Ed H*0068   MNC_FILE_SYNC(         fname, myThid )
                0069   MNC_FILE_CLOSE(        fname, myThid )
75987013ac Ed H*0070
                0071
                0072 Heres a further "convenience wrapper" written on top of the above UI:
                0073
3f2ea2a4ed Ed H*0074   MNC_CW_INIT(  Gtype, Htype, Hsub, Vtype, Ttype, wHalo, myThid )
75987013ac Ed H*0075
e9b72f2bd9 Ed H*0076     with pre-defined           -      xy    -      -      n
                0077     combinations:              U      x     c      t      y
                0078     'Cen_xy_c_t_Hn'            V      y     i
                0079     'U_xy_i_t_Hn',             Cen
                0080     'Cor_x_-_-_Hy'             Cor
75987013ac Ed H*0081
3ca071fc35 Ed H*0082   MNC_CW_SET_UDIM( fbname, udim, myThid )
4de8f8c098 Ed H*0083
3ca071fc35 Ed H*0084   MNC_CW_RX_W( 'R|D|I', fbname,bi,bj, vtype, indu, var, myThid )
                0085   MNC_CW_RX_R( 'R|D|I', fbname,bi,bj, vtype, indu, var, myThid )
                0086           |
                0087           +--  RX = 'RL', 'RS', or 'I'
8ae258cf2c Ed H*0088
3f2ea2a4ed Ed H*0089   MNC_COMP_VTYPE_VAR( ind_vt, ind_fv_ids, ires, myThid )
a27dc5c859 Ed H*0090
                0091
5bc9611487 Ed H*0092
a27dc5c859 Ed H*0093 To-Do:
                0094 ======
                0095
dad4143247 Ed H*0096  1) NAMING -- We should (as much as possible) try to name variables so
                0097     that they are in agreement with the CF naming conventions.
1ac23013aa Ed H*0098
dad4143247 Ed H*0099  2) UNITS -- as with the names we need to follow conventions
                0100
5bc9611487 Ed H*0101  3) CNH pointed out that grid interpolation needs to be handled
dad4143247 Ed H*0102     "on-the-fly" since pre-processing would result in overly large
                0103     input files.  We need an interpolation API...
                0104
75987013ac Ed H*0105