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_DBL( myThid, fname, atname, len, dval ) |
44 |
MNC_FILE_ADD_ATTR_REAL(myThid, fname, atname, len, rval ) |
45 |
MNC_FILE_ADD_ATTR_INT( myThid, fname, atname, len, ival ) |
46 |
MNC_FILE_ADD_ATTR_ANY( myThid, fname, atname, atype, cs,len,dv,rv,iv ) |
47 |
... |
48 |
MNC_FILE_READ_HEADER( myThid, fname ) |
49 |
|
50 |
MNC_DIM_INIT( myThid, dname, dunits, dlen ) |
51 |
MNC_DIM_REMOVE( myThid, dname ) |
52 |
|
53 |
MNC_GRID_INIT( myThid, fname, gname, ndim, dnames ) |
54 |
MNC_GRID_SET_LL( myThid, fname, gname, type, lats, lons ) |
55 |
|
56 |
MNC_VAR_INIT_DBL( myThid, fname, gname, vname, units ) |
57 |
MNC_VAR_INIT_REAL( myThid, fname, gname, vname, units ) |
58 |
MNC_VAR_INIT_INT( myThid, fname, gname, vname, units ) |
59 |
MNC_VAR_INIT_ANY( myThid, fname, gname, vname, units, type ) |
60 |
MNC_VAR_ADD_ATTR_STR( myThid, fname, vname, atname, nv, sval ) |
61 |
MNC_VAR_ADD_ATTR_DBL( myThid, fname, vname, atname, nv, dval ) |
62 |
MNC_VAR_ADD_ATTR_REAL( myThid, fname, vname, atname, nv, rval ) |
63 |
MNC_VAR_ADD_ATTR_INT( myThid, fname, vname, atname, nv, ival ) |
64 |
MNC_VAR_ADD_ATTR_ANY( myThid, fname, vname, atname, atype, cs,len,dv,rv,iv ) |
65 |
MNC_VAR_WRITE_DBL( myThid, fname, vname, var ) |
66 |
MNC_VAR_WRITE_REAL( myThid, fname, vname, var ) |
67 |
MNC_VAR_WRITE_INT( myThid, fname, vname, var ) |
68 |
MNC_VAR_WRITE_ANY( myThid, fname, vname, vtype, dv, rv, iv ) |
69 |
... |
70 |
MNC_VAR_READ( myThid, fname, vname, var ) |
71 |
|
72 |
MNC_FILE_CLOSE( myThid, fname ) |
73 |
|
74 |
The above interface is powerful yet easy to use (easier than the |
75 |
entire NetCDF interface) since it helps the user keep track of the |
76 |
associations between files, "grids", variables, and dimensions. |
77 |
|
78 |
|
79 |
To-Do: |
80 |
====== |
81 |
|
82 |
1) CNH pointed out that grid interpolation needs to be handled |
83 |
"on-the-fly" since pre-processing would result in overly large |
84 |
input files. We need an interpolation API... |
85 |
|
86 |
2) AM described her "diags" (or "myDiags" or "mDiags") interface |
87 |
which should use MNC for output. The data storage idea is similar |
88 |
to the MNC tables-of-indicies approach but also includes one huge |
89 |
double-precision "accumulator" to hold all the temporary values |
90 |
(eg. partial sums for averages, current max/mins): |
91 |
|
92 |
vname ( ni ) |
93 |
vlen ( ni ) |
94 |
vind ( ni ) -----+ |
95 |
| |
96 |
|
97 |
vij_diag ( i, j, [...] ) w/ lat/lon indicies |
98 |
vgl_diag ( [...] ) wo/ lat/lon indicies (global) |