Improved "broken line" and "normal transport" algorithms and refactored API

[hdrake]

Major changes

• Improved the MOM6_normal_transport function by generalizing it and renaming it to convergent_transport. Made the "normal transport" function unambiguous by adding an orientation (by default counterclockwise=True) as well as a sign convention (positive if northward becomes positive if convergent). This is well-defined for both open sections (as in OSNAP West/East) and closed sections (as in a section that includes OSNAP West but surrounds the entire Labrador Sea). The default behavior for a west-to-east section is unchanged; northward transport across the section is equivalent to convergent transport in the counterclockwise sense.

• Improved the infer_broken_line algorithm and renamed it infer_grid_path to better reflect what it does. A fundamental flaw with the old algorithm was that it was path-dependent because of the memory of the ijflip flag, and therefore was also non-symmetric (the broken lines were different if the section was defined from west-to-east versus east-to-west). Another major flaw was that it did not necessarily follow the shorted path between the two end points (a straight line) as closely as possible. The new algorithm accomplishes this by predicting a target point along that straightest path and finding the next increment that gets the closest to the predicted point. However, it still finds the shortest path between two points in index space; a future improvement would be to use the accurate geo coordinates to determine each of the steps along the grid.

• Refactored the API.

  • Made function names accurate,
  • Removed ad-hoc offset arguments in favor of correct symmetric/non-symmetric conventions
  • Consolidated some redundant functions,
  • Vectorized operations in some places (could improve performance and readability by doing this a lot more), and
  • Removed obsolete / incorrect / untested functions

• Updated examples. Improved existing examples with more explanatory text and figures that illustrate key features of the package. Included two new notebooks that demonstrate new features:

  • Convergent transports within a closed region
  • Support for sections that cross the periodic x-boundary

[hdrake]

@MDTocean, I am working on merging your function for adding grid cell widths (and accumulating the distance along a section), but I think it makes sense to just add this functionality directly into the convergent_transport and extract_tracer functions, possibly as an optional kwarg.

[hdrake]

As I've mentioned to you both in person (@raphaeldussin and @MDTocean), I think it is worth making some breaking changes now and trying to solidify an API around just a few core functions (esp. infer_grid_path, create_section, convergent_transport, and extract_tracer).

I am more than happy to work with you do update any scripts / notebooks to use the new API. The breaking changes are pretty straightforward to accomodate, mostly just changing function names and adding some arguments (e.g. symmetric) and setting optional keyword arguments (although I've tried to set their defaults to be consistent with the old API).

[hdrake]

The last commit (a2e8392) is a first pass at merging @MDTocean's method for computing the widths of cells along the section and aggregating them to give an along-section distance coordinate as well.

I still need to add in functionality for the cell-thickness and the cell-area (product of width and thickness), which are needed to compute the average velocities (as opposed to just transports) across the section. As mentioned in this comment, I think we are better off explicitly using the thkcello diagnostic to do this accurately regardless of the vertical coordinate of the diagnostics.

[hdrake]

@raphaeldussin, I think in cfedb2b9da1b482f2ee66a90648ee3a0e7bef101 I fixed the small bug in the new normal_transport algorithm that you had previously mentioned. I was able to exactly reproduce the results of my implementation of the old_algo (indexing point by point within a for loop) with the new xarray-enabled one.

[hdrake]

Closing in favor of https://github.com/raphaeldussin/sectionate/pull/19, which includes all of these changes.