Wish list: improvements to utils/matlab/cs_grid routines and cs/llc-related MITgcm doc

[jrscott]

cs_grid routines seem to fall into three categories; in each case, we only need to provide a few very simple examples rather than a comprehensive collection.
- plotting output (tile-by-tile, global), from cs/llc grids
- data processing: conversion to lat-lon, grid/tile format permutation, vector rotation, broken line routines
- diagnostics: zonal mean heat transport, MOC, barotropic streamfunction

One initial question: do we even need a directory of these (matlab) utilities, when there are well-documented python packages that are able to do all of this already? We (the MITgcm dev team) think so — we think it is important to have some simple, bare minimum routines available, that a modeler can peruse to see how such manipulations can be done, as a springboard to writing one’s own routines, or simply available just to understand how to work with data in these output formats. We would argue that the specific language used here is not so critical, rather the code should be clear enough to be easily translatable.

Below is a first pass at list of issues and todo items, trending from specific to these matlab directories toward relevant broader lack of proper MITgcm documentation:

1. Existing routines were collected from different users over many years; there is little consistency in general coding practices, and some no longer even work. Routines expect cs (or llc) grid data in different formats. There is functional duplication in some routines; suggestion would be to select one “best” routine, fix this up, and designate the other routines as “legacy”. Major cleanup needed.

2. All routines should have tested example steps outlined, e.g. working with the global cs32 verification. This does not have to be very long or elaborate (and in fact some already document a successful “use recipe”), but some are mysterious (to me at least) in how they should be used in practice.

3. The READMEs are missing descriptions for some routines. And a list of “legacy” unsupported routines could be kept here (or, maybe these unsupported routines put into a subdirectory).

4. Ideally, it would be nice if these routines all worked for both llc and cs grids., thus avoiding the separate subdirectory latloncap/.

5. Writing these routines as functions is best (and documented as such), although long, complicated argument lists should generally be avoided, if possible.

6. Best if all routines accept both “compact” and “original/old” formats

7. MITgcm doc: there is no documentation on compact/original formats, pkg EXCH2 doc needs a major overhaul (it is written somewhat as a programmer’s guide rather than a user’s guide). While there is useful scattered info in pkg EXCH2 code, (e.g. .h files), in EXCH2 doc, and also in (outdated) chap 6, this needs to be consolidated (somewhere) into a plainly written guide for newer users who want to work on either of these grids. (Note: global_ocean.cs32 does not actively turn on EXCH2 in data.pkg, so this pkg probably not best as the hub of all things cs and llc-related in the doc?)

8. The tried and true method for finding and then specifying blank tiles should also be added to the main MITgcm doc.

Open to comments and suggestions.

[dramauh]

I think it will be fantastic to add some functions. For instance, I wonder if it is possible to edit blank lines to cover any type of curvilinear grid. Currently, I think blank_lines only accepts cs grid configuration (nc*6 nc nr). It is quite troublesome to compare the MOC from ECCO (i.e. cs_grid) with other models such as NEMO or MOM.

[jm-c]

@dramauh Regarding using blank tiles:
There are 2 experiments that illustrate the use of blank-tiles, for which you need to compile and use pkg/exch2. The first one, adjustment.cs-32x32x1 , uses curvilinear grid (CS-32) and the second one, global_ocean.90x40x15, uses regular lat-long grid (usingSphericalPolarGrid=.TRUE.,). The list of experiments in the documentation (secion 4.15) mentions these 2 experiments as using blank-tiles.
And for the purpose of showing how to use blank-tiles, in both experiments, only the MPI setting uses blank-tiles (code/SIZE.h_mpi, input/data.exch2.mpi) whereas the non-MPI setting (SIZE.h, no data.exch2) does not. This way, by comparing the 2 setting, one can easily see what need to be changed to use use blank-tiles ; also easy to check which tiles are empty (running the non-MPI setting) and are candidate for blank-tile list.