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/

Release v0.7.0: encapsulated calculations from Neal et al (2022)

Major changes in user interface

• Encapsulated the latitudinal boundary conditions and inversion algorithm used in Neal et al (2022, GRL) to QGFieldNHN22. The existing algorithm from Nakamura and Huang (2018, Science) is encapsulated in QGFieldNH18. Current QGField class is equivalent to QGFieldNH18 (for backward compatibility). These classes are also available in the xarray interface QGDataset (Thanks Christopher Polster!).
• Updated interfaces of F2PY modules to remove redundant arguments. Please recompile F2PY modules following instructions from README.md.
• Significant improvement in Documentation. In particular, with the use of nbsphinx, jupyter notebook examples are now available in the documentation. Great thanks to Christopher Polster for the enhancement.
• All jupyter notebook examples are fixed. Notebook examples are available for both QGFieldNH18 and QGFieldNHN22. They can be run with the sample data available in Dropbox folder (See Quick start in readme.md for details).
• Added new unit tests which enhance test coverage.

Migration guide from v0.6.x -> 0.7.0

• Now northern_hemisphere_results_only becomes an input argument for QGField. Please initialize this when creating QGField object and remove this argument from the methods (compute_reference_states and compute_lwa_and_barotropic_fluxes).
• eq_boundary_index is now an input arguemnt merely for QGFieldNHN22, but not QGFieldNH18. Remove it if you are using QGField/QGFieldNH18. You can refer to the jupyter notebook examples for the updated usage.

Release 0.6.6 - graph plot fix for GRL corrigendum

This minor release include a fix in graph plot procedure scripts/nhn_grl2022/graph_plot_module.py - the plotting script for the residual plot is fixed such that it produces the same plot on different machines.