1 |
edhill |
1.1 |
|
2 |
edhill |
1.2 |
API Discussions: |
3 |
|
|
================ |
4 |
|
|
|
5 |
edhill |
1.1 |
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 |
edhill |
1.8 |
2) MNC_INIT_VGRID('V_GRID_TYPE', nx, ny, nz, zc, zg) |
12 |
edhill |
1.1 |
|
13 |
edhill |
1.8 |
3) MNC_INIT_HGRID('H_GRID_TYPE', nx, ny, xc, yc, xg, yg) |
14 |
edhill |
1.1 |
|
15 |
edhill |
1.8 |
4) MNC_INIT_VAR('file', 'Vname', 'Vunits', 'H_GTYPE', 'V_GTYPE', PREC, FillVal) |
16 |
edhill |
1.1 |
|
17 |
edhill |
1.8 |
5) MNC_WRITE_VAR('file', 'Vname', var, bi, bj, myThid) |
18 |
edhill |
1.1 |
|
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 |
edhill |
1.8 |
MNC_INIT( myThid ) |
38 |
edhill |
1.1 |
|
39 |
edhill |
1.12 |
MNC_FILE_CREATE( fname, myThid ) |
40 |
|
|
MNC_FILE_OPEN( fname, itype, myThid ) |
41 |
|
|
MNC_FILE_ADD_ATTR_STR( fname, atname, sval, myThid ) |
42 |
|
|
MNC_FILE_ADD_ATTR_DBL( fname, atname, len, dval, myThid ) |
43 |
|
|
MNC_FILE_ADD_ATTR_REAL(fname, atname, len, rval, myThid ) |
44 |
|
|
MNC_FILE_ADD_ATTR_INT( fname, atname, len, ival, myThid ) |
45 |
|
|
MNC_FILE_ADD_ATTR_ANY( fname, atname, atype, cs,len,dv,rv,iv, myThid ) |
46 |
edhill |
1.1 |
... |
47 |
edhill |
1.12 |
MNC_FILE_READ_HEADER( fname, myThid ) |
48 |
edhill |
1.1 |
|
49 |
edhill |
1.12 |
MNC_DIM_INIT( fname, dname, dlen, myThid ) |
50 |
edhill |
1.1 |
|
51 |
edhill |
1.12 |
MNC_GRID_INIT( fname, gname, ndim, dnames, myThid ) |
52 |
edhill |
1.1 |
|
53 |
edhill |
1.12 |
MNC_VAR_INIT_DBL( fname, gname, vname, units, myThid ) |
54 |
|
|
MNC_VAR_INIT_REAL( fname, gname, vname, units, myThid ) |
55 |
|
|
MNC_VAR_INIT_INT( fname, gname, vname, units, myThid ) |
56 |
|
|
MNC_VAR_INIT_ANY( fname, gname, vname, units, type, myThid ) |
57 |
|
|
MNC_VAR_ADD_ATTR_STR( fname, vname, atname, sval, myThid ) |
58 |
|
|
MNC_VAR_ADD_ATTR_DBL( fname, vname, atname, nv, dval, myThid ) |
59 |
|
|
MNC_VAR_ADD_ATTR_REAL( fname, vname, atname, nv, rval, myThid ) |
60 |
|
|
MNC_VAR_ADD_ATTR_INT( fname, vname, atname, nv, ival, myThid ) |
61 |
|
|
MNC_VAR_ADD_ATTR_ANY( fname, vname, atname, atype, cs,len,dv,rv,iv, myThid ) |
62 |
|
|
MNC_VAR_WRITE_DBL( fname, vname, var, myThid ) |
63 |
|
|
MNC_VAR_WRITE_REAL( fname, vname, var, myThid ) |
64 |
|
|
MNC_VAR_WRITE_INT( fname, vname, var, myThid ) |
65 |
|
|
MNC_VAR_WRITE_ANY( fname, vname, vtype, dv, rv, iv, myThid ) |
66 |
edhill |
1.1 |
... |
67 |
edhill |
1.12 |
MNC_VAR_READ( fname, vname, var, myThid ) |
68 |
edhill |
1.1 |
|
69 |
edhill |
1.12 |
MNC_FILE_SYNC( fname, myThid ) |
70 |
|
|
MNC_FILE_CLOSE( fname, myThid ) |
71 |
edhill |
1.8 |
|
72 |
|
|
|
73 |
|
|
Heres a further "convenience wrapper" written on top of the above UI: |
74 |
|
|
|
75 |
edhill |
1.12 |
MNC_CW_INIT( Gtype, Htype, Hsub, Vtype, Ttype, wHalo, myThid ) |
76 |
edhill |
1.8 |
|
77 |
edhill |
1.9 |
with pre-defined - xy - - n |
78 |
|
|
combinations: U x c t y |
79 |
|
|
'Cen_xy_c_t_Hn' V y i |
80 |
|
|
'U_xy_i_t_Hn', Cen |
81 |
|
|
'Cor_x_-_-_Hy' Cor |
82 |
edhill |
1.8 |
|
83 |
edhill |
1.13 |
MNC_CW_SET_UDIM( fbname, udim, myThid ) |
84 |
edhill |
1.1 |
|
85 |
edhill |
1.13 |
MNC_CW_RX_W( 'R|D|I', fbname,bi,bj, vtype, indu, var, myThid ) |
86 |
|
|
MNC_CW_RX_R( 'R|D|I', fbname,bi,bj, vtype, indu, var, myThid ) |
87 |
|
|
| |
88 |
|
|
+-- RX = 'RL', 'RS', or 'I' |
89 |
edhill |
1.11 |
|
90 |
edhill |
1.12 |
MNC_COMP_VTYPE_VAR( ind_vt, ind_fv_ids, ires, myThid ) |
91 |
edhill |
1.2 |
|
92 |
|
|
|
93 |
|
|
To-Do: |
94 |
|
|
====== |
95 |
|
|
|
96 |
edhill |
1.7 |
1) NAMING -- We should (as much as possible) try to name variables so |
97 |
|
|
that they are in agreement with the CF naming conventions. |
98 |
|
|
|
99 |
|
|
2) UNITS -- as with the names we need to follow conventions |
100 |
edhill |
1.6 |
|
101 |
edhill |
1.7 |
3) AM described her "diags" (or "myDiags" or "mDiags") interface |
102 |
edhill |
1.6 |
which should use MNC for output. The data storage idea is similar |
103 |
|
|
to the MNC tables-of-indicies approach but also includes one huge |
104 |
|
|
double-precision "accumulator" to hold all the temporary values |
105 |
|
|
(eg. partial sums for averages, current max/mins): |
106 |
|
|
|
107 |
|
|
vname ( ni ) |
108 |
|
|
vlen ( ni ) |
109 |
edhill |
1.7 |
vind ( ni ) ------+ |
110 |
edhill |
1.8 |
| |
111 |
edhill |
1.6 |
|
112 |
|
|
vij_diag ( i, j, [...] ) w/ lat/lon indicies |
113 |
|
|
vgl_diag ( [...] ) wo/ lat/lon indicies (global) |
114 |
edhill |
1.7 |
|
115 |
|
|
4) CNH pointed out that grid interpolation needs to be handled |
116 |
|
|
"on-the-fly" since pre-processing would result in overly large |
117 |
|
|
input files. We need an interpolation API... |
118 |
edhill |
1.8 |
|
119 |
|
|
5) From the group meeting on 2004/01/21, we need to define |
120 |
|
|
"sub-grids" corresponding to: |
121 |
|
|
|
122 |
|
|
var_name HGRID VGRID TIME |
123 |
|
|
=========================================== |
124 |
|
|
u U_xy r_c t |
125 |
|
|
eta T_xy - t |
126 |
|
|
rac T_xy - - |
127 |
|
|
|
128 |
|
|
And write a convenience wrapper so that users can write variables |
129 |
|
|
using just two function calls. JMC and I worked out the |
130 |
|
|
following: |
131 |
|
|
|
132 |
edhill |
1.7 |
|