Pre-release v2.1.0a: non-conservative force calculation included in QGField

This pre-release is made for the sake of generating a zenodo code to be included in Lubis et al. (in prep). Functionality to compute the contribution of diabatic heating in the wave activity budget equation is included. See documentation of QGField.compute_lwa_and_barotropic_fluxes for details. A formal release will be made once the manuscript is finalized.

Release 2.0.0: Migration of F2PY compilation from `numpy.disutils` to `meson`

To cope with the need to compile F2PY modules upon the deprecation of numpy.disutils in python 3.12, falwa switch to using meson. While the user interfaces remain the same, this release changes the installation mechanism of the package. The develop mode is not available anymore as both the compiled F2PY modules and python modules are stored in python site-package directory.

Please refer to the README section "Package Installation" for the updated installation procedures.

Great thanks to Christopher Polster for figuring out a timely and clean solution for migration to python 3.12. 👏 For details and references related to this migration, users can refer to Christopher's Pull request.

Release 1.3.0

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

Bugfix release v1.2.1 wrong values of u_baro in Southern Hemisphere

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.

Bugfix release v1.2.0: inconsistency in differential area computation in reference state calculation

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)
3. Added CONTRIBUTING.md to include instructions for potential contributors.

v1.1.0 Fix bug in processing input with even number of grid points

Release: falwa v1.1.0

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: v1.0.0...v1.1.0

v1.0.0 Release of python package `falwa` v1.0.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

Pre-release v1.0.0a0

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

Corrigendum for NHN22 and NH18: fix in nonlinear zonal advective flux calculation

This release requires recompilation of fortran modules.

Two weeks ago, we discovered that there is a mistake in the derivation of expression of nonlinear zonal advective flux term:
$$\frac{1}{a\cos\phi} \frac{\partial}{\partial \lambda} \int^{\Delta\phi}_0 u_e q_e \cos(\phi+\phi^\prime) d\phi^\prime$$

The correct definition of $u_e$ in the integral should be:

$$u_e(\lambda, \phi, \phi^\prime, z, t) \equiv \omega_e a \cos\phi = \frac{u(\lambda, \phi + \phi^\prime, z, t)\cos\phi}{\cos(\phi+\phi^\prime)} - u_{\text{REF}}(\phi, z, t)$$

where $\omega = \frac{u}{a\cos\phi}$ is the angular velocity (and $\phi^\prime \in [0, \Delta\phi]$).

The fix has been done in the following commit and will be published in release 0.7.2:

1995e1d#diff-7e797030d6c037af018d523e2e6a20f0d9f01c3dd8f41a2d7f044b4800684455

This error led to an underestimation of nonlinear component of advective flux ("ua2" in the code). Fixing this error indeed makes traffic jam mechanism (i.e. how waves are slowed down by the nonlinear effect that grows with wave amplitude) more robust.

We will submit corrigendums for Neal et al. (2022, GRL) and Nakamura and Huang (2018, Science) to update the numerical results. The correct derivation of the flux expression can be found in the corrected supplementary materials of NH18. There is no change in conclusions in any of the articles.

Please refer to Issue #83 for a preliminary comparison between originally published figures and updated figures.

Minor release v0.7.1

• Remove the use of setuptools in setup.py
• Dependencies in environment.yml matches MDTF
• Dependencies in setup.py changed (for the sake of MDTF incorporation)
• Deployment onto Conda channel (at least for Linux) is included in notes/developer/conda_deployment.md
• Deployment using pip (only include source code)
• Migrate completely to python 3.10 (TODO: fix GitHub workflow)
• Match MDTF package version requirements in pip
• Deployed on https://pypi.org/project/hn2016-falwa/0.7.1/