[mandli]

This PR ties together and tries to address a lot of the confusion around the new windows into files, especially the netCDF files. Much of the language should apply to the ASCII files as well as netCDF, so I may have missed some of those. The diagram is also editable if someone wants to make it more clear.

---

Stacked on #763, which is stacked on #762. Please review only the commits
after 86bc5002:

• 140f52e0 adds the failing tests.
• 2b8d3c9e is the fix.
• d6e579f8 adds the design doc and diagram.

This PR will be rebased as #762 and #763 land.

This answers @rjleveque's question about crop_bounds versus crop_extent
in topo.data. It is PR A of the plan in
dev/design/topo_input_roadmap.md §2.8. Start with the new reference page
dev/design/topo_crop_windows.md. It names every crop "window" (file extent,
crop_extent, each entry's window in the file, the window actually loaded,
the array extent, and the domain), gives each one's coordinate frame, and has a
diagram for a netCDF crop across the antimeridian.

What was wrong

• crop_bounds was not a duplicate of crop_extent. It was each
  topo.data entry's crop in that file's own coordinates. It differs from
  crop_extent when a crop is split at the antimeridian, and Fortran used it
  in place of crop_extent.
• netCDF and ASCII cropped in different frames when x_shift/y_shift was
  set. ASCII applied the crop after the shift, as documented. netCDF applied
  it before the shift, in both Python and Fortran. With x_shift = 10 and
  crop_extent = [0, 20, …], ASCII loaded [0, 20] and netCDF loaded
  [10, 30], so a run on [0, 20] stopped with "topo arrays do not cover
  domain".
• Python and Fortran could drop different edge columns. Python compared crop
  edges exactly, while Fortran allowed 1e-6·dx. For example, crop
  [-99.5, -99.0] on a 0.1° grid written by Topography.write gave Python 5
  points and Fortran 6. Over 1,905 crop edges on grid lines, the two disagreed
  on 1,017.

What changes

• crop_extent is in domain coordinates (after x_shift/y_shift) for every
  topo type, in Python and in Fortran.
• topo.data no longer has crop_bounds for topo, dtopo or met. Fortran gets
  each entry's window from crop_extent − lon_wrap_offset − shift and clips it
  to the file. A hand-built [4, path, TopoMetadata] entry whose crop exists
  only in its metadata now has it written as crop_extent.
• One round-off allowance, CROP_TOL = 1e-6 of the grid spacing, is shared by
  Python (coordinate_tools.CROP_TOL) and Fortran (topo_module.f90). It
  guards round-off only and does not move crop edges.

Behavior changes (for release notes)

• netCDF topography cropped with x_shift/y_shift now selects the
  documented region. The old window was the crop moved by the shift.
• An old topo.data that contains a crop_bounds line stops with
  "Regenerate topo.data with 'make data'". Without that stop, an old file
  whose crop was only in crop_bounds would load the wrong window silently.
• A crop edge within 1e-6·dx of a grid point now keeps that point in Python,
  matching Fortran.

Verification

• New failing-first tests:
  • tests/test_topo_crop_frame.py: types 2/3/4 under a shift, for read and
    for the write-time coverage check.
  • test_shifted_crop_is_in_domain_coordinates in
    tests/regression/topo_crop: an end-to-end Fortran run. Every cell's
    topography matches an exact linear field to 1e-8, using the cos(latitude)
    area weighting of the spherical cell average.
  • tests/test_crop_tolerance.py: Python and Fortran use the same constant;
    on the 1,905-edge sweep Python picks the same points as Fortran's index
    formula; the -99.5 case keeps 6 points. With the constant set to 0,
    5 of these fail.
  • A regression test that an old topo.data with crop_bounds stops.
• Existing suites:
  • Python tests/: 661 passed.
  • tests/regression, bowl-slosh-netcdf (including coarsened),
    dtopo, chile2010: 43 passed, 1 expected failure (marked xfail).
    chile2010 includes lon_360, which builds topo_entries() entries by
    hand with a −360 offset.

Not in this PR

• Wrapping on read in Python, so one Topography can be plotted across the
  antimeridian (§2.8 PR A2).
• The value =: key notation for topo.data (§2.8 PR B).
• User docs. They overlap Document new fetch_remote_topo and deprecation of read_netcdf and etopo1_download rjleveque/doc#5, so they will follow it.
• Topography.write stores cellsize from x[1] - x[0]; the met reader's
  crop comparison is still exact. Both are recorded in §2.8.