Falwa

Issue to release 1.3: 116

Major changes

Major changes 1, 2 and 4 below lead to small changes in output values of `QGField` compared to the previous release. Users may compare the plots on example jupyter notebooks over different releases to gauge the magnitude of difference.

1. User can put in already interpolated (on evenly-spaced vertical grid) fields from hybrid coordinate interpolation by setting `data_on_evenly_spaced_pseudoheight_grid=True` to avoid interpolating twice - vertical interpolation is delegated to `scipy` instead of fortran modules. The old interpolation f2py modules is renamed `compute_qgpv` (as this is its sole duty now). (See 94 for the discussion.)
2. Compute Static Stability in *original* vertical coordinates (*before* vertical interpolation) with `UnivariateSpline` and its `derivative` to reduce the numerical error, leading to a smoother field
3. The behavior of `QGField.compute_reference_state` is modified such that even when `Uref` cannot be computed, users won't get an error and can still access `Qref` computed. A boolean parameter `QGField.nonconvergent_uref` is added to indicate whether `Uref` is properly computed. If `False`, `compute_lwa_and_barotropic_fluxes` cannot be called.
4. Added `QGField.compute_lwa_only` to provide users with a choice of computing solely LWA from `Qref`. That way, even if `Uref` cannot be solved for purely numerical reason, LWA can still be calculated from `Qref`. This method is available in `QGDataset` too.

Additional utilities
1. Added "Plot Utilities" (for plots presented in POD contribution to MDTF), "Statistics Utilities" (to compute covariance between `<LWA>` and `<U>`) and "netCDF Utilities"
2. Added "Preprocessing" module which include gridfill function used in MDTF with documentation
3. Included `developers/run_through_notebooks.sh` to run through notebooks for each release

Minor fixes
- Fixed the build test in Git Workflow
- Fixed Sphinx build on ReadTheDoc
- Fixed misformed link in documentation

This is fixing the issue reported in 108 that the barotropic component of zonal wind in southern hemisphere was wrongly computed using the data in the northern hemisphere. Other barotropic quantities computed were not affected.

Thanks chpolste for figuring out the fix.

**Important:** This release fix a bug in computing the reference states 102 : the differential area to compute reference states, $a^2 \cos\phi \Delta\phi \Delta\lambda$ , was miscomputed as $a^2 \cos\phi (\Delta\phi)^2$ . This has not caused issues in results presented in our previous publications because we have been using ERA5 datasets with $\Delta\phi = \Delta\lambda$. Great thanks to Pragallva Barpanda for fixing the issue and also sharing her working example to preprocess model output for consumption of `QGField` downstream.

Summary of changes:
1. $\Delta\phi$ and $\Delta\lambda$ are precomputed in `QGField` object and passed into the F2PY modules as parameters
2. Pragallva has included an example in `scripts/pre_process_data_in_hybrid_coordinates/` how to preprocess climate model output in hybrid coordinate for consumption of `QGField` downstream by (1) transforming the fields to pressure coordinates, and (2) do gridfill over underground" gridpoints using poisson solver (as [how Clare did in MDTF project](https://github.com/csyhuang/MDTF-diagnostics/blob/finite_amplitude_wave_diag/diagnostics/finite_amplitude_wave_diag/finite_amplitude_wave_diag_zonal_mean.py))
3. Added `CONTRIBUTING.md` to include instructions for potential contributors.

Bug being fixed

This release fix the bug occuring in `QGField`/`QGDataset` when processing latitude grid with even number of grid points - the dimension of latitude grid is recorded inconsistently, leading the code to crash. With this fix, computed variables are returned with original dimension (or original dimension / 2 if `northern_hemisphere_results_only=False`).

Additional unit tests

There are two additional unit tests demostrating the fix:
- `tests/test_output_results.py::test_offgrid_data_input`
- `tests/test_output_results.py::test_offgrid_data_input_xarrayinterface`

Corresponding changes

See code comparison: https://github.com/csyhuang/hn2016_falwa/compare/v1.0.0...v1.1.0

1. The python package is renamed from `hn2016_falwa` to `falwa` 91
2. There is a fix in code for zonal advective flux computation. The correction done in release 0.7.2 happens to be an over-correction. See 92 for mathematical details. Thanks Christopher Polster for spotting the error. The fix requires re-compilation of fortran modules.
3. QGDataset now supports dataset with even number of latitude gridpoints 85
4. User can delay the return of variable from methods in QGField/QGDataset by the boolean parameter `return_named_tuple`.
5. Cartopy is replacing Basemap (deprecated) in all the visualization examples 87
6. The GitHub workflow has been updated and run successfully 82

The changes can be found in this pull request: 93

This pre-release includes the changes mentioned in 75 , namely,
- Code fix for zonal advective flux computation, see 92 for details.
- Python package name change from `hn2016_falwa` to `falwa` 91
- QGDataset now also supports data input with even number of latitude gridpoints 85
- Used Cartopy instead of Basemap (deprecated) in all the visualization examples 87
- Fixed GitHub action 82