Re: netCDF F90, first iteration

> To: Russ Rew <address@hidden>
> From: Robert Pincus <address@hidden>
> Subject: netCDF F90, first iteration

Hi Robert,

> The semester has started and I'm up to my ears in juniors. I spent 
> some time this summer trying to add additional error checking to the 
> netCDF Fortan 90 interface and got tangled up in my own feet. I'm 
> therefore sending you an almost complete Fortran 90 API with the same 
> functionality as the C and F77 versions. I will ask you to use your 
> editor and macros to expand some ideas I've sketched out. Once you've 
> done this and sent the results back to me, I think we will be very 
> very close to finished.

Wow, thanks, I've saved the eleven f90 files you sent and hope to get a
chance to look at them more than superficially in the next week.  

> We'll make two modules. The first declares KIND parameters for the 
> integer, real, and character data types. The module also has a 
> function to try to determine if each of these is distinct, and 
> supported by the compiler. (typeSizes.f90).
>
> The second module is the netcdf information itself. I've currently 
> broken it up into several separate files which are "included" in one 
> main file. Things are easier to see this way, although I'm not sure 
> we'll want to package the distribution like this.
>
> The Fortran 90 interface is much smaller than the Fortran 77 
> interface while providing the same functionality. You can see the 
> list of nf_ API functions I'm calling in netcdf_externals.f90. In 
> contrast, only the functions named in netcdf_visibility.f90 are 
> available in the Fortran 90 interface. I accomplished this reduction 
> using two techniques. Most of the inquiry functions now have optional 
> arguments, meaning that a programmer can ask for exactly the 
> information he or she needs, and only that information. A bigger 
> reduction came by combing the optional arguments with overloading for 
> all the put and get functions for attributes and variables.

That's a great simplification, from 76 functions to 31!

> I've compiled the current version, but I haven't tested it in any 
> way. Do you have standard test cases you'd like me to work with?

No, though developing an extensive test for the f90 interface should
be simpler than what was required for testing the f77 interface, since
it has so many fewer functions to test.

> I made a few design decisions that you should review:
> --------
> Module elements are declared to be PRIVATE by default. Any module 
> entity that isn't explicitly declared as PUBLIC is not available to 
> users of the nf90_ API. This includes every function in the nf_ 
> interface, for example.

That seems fine to me.

> I guessed at the intent (in or out) of arguments to the create_mp and 
> open_mp functions in netcdf_file.f90. Can you tel me if I got these 
> right?

Looks right to me.  The input argument you have as "chunksizeint" is
more properly named "chunksizehint", since it is supposed to be a hint
about what chunk size to use, but I'll fix that.

> The attribute and variable functions accept six types of input: 
> character strings (fixed length Fortran character arrays); one, two, 
> and four byte integers; and four and eight byte real values.
>
> It seems to me that the fill values in the constants section should 
> correspond in type to these six data types, i.e. that nf90_fill_byte 
> should be an one byte integer. The current Fortran interface declares 
> this to be a standard integer, however. I left it the way it was; 
> should I change it?

I'm not sure, I'll have to look at this.  My first guess is a standard
integer was used because a one byte integer couldn't be used for f77
compilers that didn't have such a type, but there may be another
reason ...

> Variable put and get functions are now overloaded 48 ways: 8 
> possiblities for rank (scalars, and arrays from 1 to 7 dimensions) 
> and 6 possibilities for variable type. By default, a single value is 
> written to or read from the first element of the variable. 
> N-dimensional arrays passsed as the "values" argument are written or 
> read as from the first N dimensions starting at the origin.
>
> I made a guess about efficiency, namely that the biggest performance 
> hit comes from mapping variable dimensions from the file to the 
> array. Thus, the nf_put_varm_ is called if a map is provided, and 
> nf_put_vars_ is called otherwise. If there are other big performance 
> penalties (i.e. if nf_put_vars_ is much slower than nf_put_vara_ even 
> when every element of stride is 1) please let me know.

We don't worry much about nf_put_varm_ functions, because I suspect
no one actually uses them (I've never gotten a support question from
anyone asking about them).

I think using the stride functions rather than the simpler array
functions is fine because stride 1 is handled efficiently as a special
case in the C library.

> ------------
> I left two files that I'd like you to run your editor macros over. 
> These are the many versions of the variable put and get routines; 
> they're in netcdf_vars_expand_single.f90 and 
> netcdf_vars_expand_array.f90. I've provided you with a template and a 
> filled out example in each file.

OK, it looks pretty clear what is needed, but I'll have to figure out
how I want to automate the generation of these things, with a
combination of emacs macros and some editing scripts.  Don't expect
anything for a week or two, as I'm in the middle of something else
currently.

> Please let me know if you have questions. This has taken way way way 
> too long on my end, and I'd like to finish waht I told you I'd do. 
> Once you've generated the functions from the template, return the 
> files to me and I should be able to finish the routines in short 
> order.

I'm just grateful you figured out how to do this.  I'll try to get my
part done as soon as practical ...

--Russ

_____________________________________________________________________

Russ Rew                                         UCAR Unidata Program
address@hidden                     http://www.unidata.ucar.edu