hn2016_falwa - Release 2.2.0 - Layerwise LWA flux calculations

Summary of changes

• Xarray interface is included for diabatic heating calculation PR #135
• Significant refactoring of QGFieldBase and subclasses reduces branching of procedures. Now the two child classes QGFieldNH18 and QGFieldNHN22 are using the same code for Step I and Step III.
• Layerwise (on pressure levels) calculation of LWA fluxes are added. The computed fields can be access via QGFieldBase.layerwise_flux_terms_storage.
  • TODO for v2.2.1: create user interface analogous to the barotropic version.
• Bugfix: there was a sign error in the calculation of meridional divergence of eddy momentum flux in the Southern Hemisphere in QGFieldNH18. The calculation in the Northern Hemisphere has no such issue.
• Fixed inconsistent dates in sample MERRA2 test data.
• Added a new section "Citing this package" to README.md and documentation page as our software package paper has been published on the Geoscience Data Journal:

Huang, C. S. Y., Polster, C., & Nakamura, N. (2025). Falwa: Python Package to Implement Finite‐Amplitude Local Wave Activity Diagnostics on Climate Data. Geoscience Data Journal, 12(2), e70006.

- Jupyter Notebook
Published by csyhuang 9 months ago

hn2016_falwa - Release 2.1.0: diabatic heating calculation added to QGFieldNHN22

• Functionalities to calculate contribution of diabatic heating to vertical-averaged budget of local wave activity (LWA) is added to QGFieldNHN22 and QGDataset. Please refer to notebook examples in notebooks/lubis_et_al_2024/ and corresponding documentation for example of usage on MERRA2 data.
  • Note: The calculation of layerwise fluxes and diabatic heating will be included in v2.2.0 tentatively released in early April. See #133 for the plan of the next release.
• The basis function falwa.basis.lwa now supports partition of LWA into cyclonic and anti-cyclonic components (by setting parameter return_partitioned_lwa=True). See documentation for detailed instructions and notebook examples (notebooks/simple/Example_barotropic.ipynb and notebooks/simple/BarotropicField_example.ipynb).
• Additional integration tests are included to cover new functionalities.
• QGDataset has been updated to accommodate variable name change in ERA5 data downloaded from new CDS of ECMWF (2024/10/26 #132 - Thanks Christopher Polster for the update!).

- Jupyter Notebook
Published by csyhuang 11 months ago

hn2016_falwa - 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.

- Jupyter Notebook
Published by csyhuang over 1 year ago

hn2016_falwa - 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.

- Jupyter Notebook
Published by csyhuang over 1 year ago

hn2016_falwa - 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

- Jupyter Notebook
Published by csyhuang over 1 year ago

hn2016_falwa - 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.

- Jupyter Notebook
Published by csyhuang about 2 years ago

hn2016_falwa - 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.

- Jupyter Notebook
Published by csyhuang about 2 years ago

hn2016_falwa - 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: https://github.com/csyhuang/hn2016_falwa/compare/v1.0.0...v1.1.0

- Jupyter Notebook
Published by csyhuang about 2 years ago

hn2016_falwa - 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

- Jupyter Notebook
Published by csyhuang about 2 years ago

hn2016_falwa - 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

- Jupyter Notebook
Published by csyhuang over 2 years ago

hn2016_falwa - 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 ue q_e \cos(\phi+\phi^\prime) d\phi^\prime$$

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

$$ue(\lambda, \phi, \phi^\prime, z, t) \equiv \omegae 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:

https://github.com/csyhuang/hn2016_falwa/commit/1995e1dfcd422c61b0a6728d1d54a6fbb2f2cf58#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.

- Jupyter Notebook
Published by csyhuang over 2 years ago

hn2016_falwa - 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/

- Jupyter Notebook
Published by csyhuang over 2 years ago

hn2016_falwa - 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.

- Jupyter Notebook
Published by csyhuang over 2 years ago

hn2016_falwa - 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.

- Jupyter Notebook
Published by csyhuang almost 3 years ago

hn2016_falwa - Release 0.6.5 - setup.py fixes

This is a minor release that fixes the issues with setup.py that cannot locate the compiled fortran modules. Thanks @chpolste for fixing this!

The archive on PyPI has also been also fixed in v0.6.5.

- Jupyter Notebook
Published by csyhuang almost 3 years ago

hn2016_falwa - Release 0.6.4 - meridional flux correction

This release includes the fix for the calculation of meridional flux component. See the correction note for details. The corrigendum on Neal et al 2022, GRL corresponds to this release.

The main change in the calculation can be found in this commit: 38d95f6202f2b0d052263437a61124fe3ace0d65

Please remove all the compiled fortran modules on your machine and git pull the newest version of fortran codes for installation (python setup.py develop).

- Jupyter Notebook
Published by csyhuang about 3 years ago

hn2016_falwa - Resolution-dependent bugfix

There were resolution-dependent procedures which worked with the (360x181) grid we used for NHN2022, GRL. This bugfix enables the new inversion routine to take data of other grid sizes.

- Jupyter Notebook
Published by csyhuang over 3 years ago

hn2016_falwa - Release 0.6.1 - Xarray interface to implement QGField methods

Major update:

• Thanks Christopher Polster @chpolste for developing an xarray interface for the QGField object using the SOR solver to compute reference state as documented in Nakamura and Huang (2018, Science).
  • Sample code that use this interface: examples/nh2018_science/demo_script_for_nh2018_with_xarray.ipynb
  • Please refer to the corresponding xarray interface documentation page for details.

Minor update:

• Added .gitignore for this repo
• Fix documentation display on readthedocs.io
• Fortran code files are now moved to hn2016_falwa/f90_modules/ such that the compiled .so modules are located in hn2016_falwa/
• Cleaned up f2py modules and remove unused variables

Code change

Detailed change in the code can be viewed on this GitHub commit comparison page:

https://github.com/csyhuang/hn2016_falwa/compare/44fabe7..a656062

- Jupyter Notebook
Published by csyhuang over 3 years ago

hn2016_falwa - Release for publishing analysis code on Zenodo for GRL submission

There is an enhancement in the algorithm computing reference state in this release. In the past, and also the analysis in NH18 Science, we used equator as the latitudinal boundary. In this current version of the script (release 0.6.0), we use absolute vorticity at 5°N as boundary condition such that the solution is no longer sensitive to fields at the equator, which improves the quality of the analysis.

The analysis code to reproduce results in Neal et al. "The 2021 Pacific Northwest heat wave and associated blocking: Meteorology and the role of an upstream cyclone as a diabatic source of wave activity" (submitted to GRL) can be found in the directory scripts/nhn_grl2022/.

Zenodo badge:

- Jupyter Notebook
Published by csyhuang almost 4 years ago

hn2016_falwa - Fortran module optimization, package restructured and additional unit tests

• Great thanks to @chpolste for pull request #36 that optimizes the fortran code that computes LWA and fluxes. To incorporate the changes made, after pulling the changes, please re-compile the f2py modules. One way of doing this is: $ python setup.py develop -u $ git pull $ python setup.py develop
• The module hn2016_falwa/download_data.py, which downloads ERA-Interim data, has been removed.
• The module hn2016_falwa/beta_version.py has been moved to the legacy/ folder. This module is no longer maintained, and will be deprecated in the upcoming release.
• Added one unit test for the class BarotropicField.
• Instead of using Travis CI, now deployment test and code coverage test are implemented using GitHub workflow.

close #37

- Jupyter Notebook
Published by csyhuang over 4 years ago

hn2016_falwa - Bug fix in BarotropicField and include procedures to handle masked array

There are two fixes in this release: - The bugs in the class BarotropicField is fixed. Thanks @chpolste for the pull request. - Now QGField can handle masked arrays without raising an error. It converts masked array to numpy array with the fill_value stored in the masked array.

- Jupyter Notebook
Published by csyhuang over 5 years ago

hn2016_falwa - Calculations for Southern Hemisphere available now!

Enhancement in functionality

• The computation of LWA, reference state and vertically averaged fluxes in the Southern Hemisphere is now available in the QGField class!
• The computed variables can be accessed via the QGField class without calling any methods, e.g. the 3D wave activity can be retrieved from the QGField object qgfield by qgfield.lwa. See documentation/example for all the attributes.
• Added more sanity checks for the inputs of QGField.

Other changes

• The documentation page is fixed and now available at http://csyhuang.github.io/hn2016_falwa.
• Added test data and increase unit test coverage for QGField.

- Jupyter Notebook
Published by csyhuang almost 6 years ago

hn2016_falwa - Bugfix for interpolation procedure for even-number latitude grid

• Fixed a bug in the interpolation procedure when the input latitude grid is of even number of points
• Updated the notes regarding the equation solver for the reference state (in notes/)

- Jupyter Notebook
Published by csyhuang almost 6 years ago

hn2016_falwa - Use pytest instead of unittest for testing

• Replaced unittest with pytest for more flexibility in testing
• Improved the encapsulation of variables in the module oopinterface, e.g. methods like qgfield.get_lwa() are replaced by qgfield.lwa.

- Jupyter Notebook
Published by csyhuang over 6 years ago

hn2016_falwa - QGField can take in latitude grids with even number of grid points

• Enhanced functionality of the class QGField to process latitude grids with even number of grid points.
• Enhanced interface of QGField with some functions to retrieve computed quantities at intermediate steps. See documentation of QGField for details.

- Jupyter Notebook
Published by csyhuang over 7 years ago

hn2016_falwa - Issue in compute_reference_states.f90 fixed.

Note for release v0.3.4

• Fixed an issue in computereferencestates.f90 that can potentially lead to segmentation fault error in computing tbar (issue #13).
• Added unit tests for qgfield.compute_reference_states.

- Jupyter Notebook
Published by csyhuang over 7 years ago

hn2016_falwa - Added functionality to compute LWA zonal advective flux convergence

• Added a function zonal_convergence in hn2016_falwa/utilities.py that it computes the zonal component of convergence in spherical coordinates
• Added unittest for utilities.zonal_convergence in tests/test_utilities.py
• Updated the demo scripts in examples/nh2018_science/ that it now computes LWA, LWA flux and their convergence/divergence and saves them in a netCDF file for 8 days (6-hourly data) in 2005.
• Included a conda environment specification file examples/nh2018_science/environment.yml that enables one to run all the scripts with visualizations in the repository
• Included examples/README.md with brief descriptions of the sample scripts
• Updated descriptions in examples/nh2018_science/README.md

- Jupyter Notebook
Published by csyhuang over 7 years ago

hn2016_falwa - Included unit tests for all basis functions and oopinterface interpolation function

• Unit tests for all functions in basis.py and the interpolation method of QGField in oopinterface.py are included.
• Fixed a typo in hn2016_falwa/examples/nh2018_science/demo_script_for_nh2018.ipynb. Now, the timestamps in the figures are consistent with the source of data. Also, the latex symbols in the figure titles are fixed.
• Modified a procedure in eqvlat in basis.py such that division by a zero differential area is avoided.

- Jupyter Notebook
Published by csyhuang over 7 years ago

hn2016_falwa -

List of changes (Feb 26, 2018):

• hn2016falwa/betaversion.py: In solveurefboth_bc, a plotting option is added.
• hn2016falwa/wrapper.py: In all functions, when npoints are not specified, it is taken to be nlats (input). Also fixed a bug of missing argument npoints in theta_lwa.
• hn2016falwa/utilities.py: In *staticstability, make set and net an integer if they are not input. In *computeqgpvgivenvort, remove the bug that nlat_s is being hard-coded by mistake.

- Jupyter Notebook
Published by csyhuang almost 8 years ago

hn2016_falwa - v0.2.0

The package has been significantly restructured. The file api.py has been removed. Functions are classified into 4 different categories according to their structures.

For existing users: instead of using python from hn2016.api import function please switch to, for example, if you want to use the wrapper function qgpveqlatlwa python from hn2016 import wrapper qref, lwa = wrapper. qgpv_eqlat_lwa(...)

Existing functions are categorized into 4 types: basis functions (basis), wrapper functions (wrapper), utility functions (utilities) and beta-version functions (beta_version). Please refer to the documentation for the lists.

- Jupyter Notebook
Published by csyhuang over 8 years ago

hn2016_falwa - Release note of hn2016_falwa v0.1.7

This version 0.1.7 has some major updates in function names and library structure.

Major updates:

• Name of functions are all now in small letters.
• The radius of planet (planet_radius) is now an optional input for the functions (default value: Earth's radius).
• The function static_stability can now take in 2D (i.e. zonal mean) or 3D field of potential temperature.
• The syntax in the sample IPython notebooks are updated. (see example/)
• Unittest directory has been set up (tests/) and will be constantly updated.
• A new function theta_lwa has been added to compute surface wave activity (See Huang and Nakamura (2016). It is the longitudinally local version of B^* in Nakamura and Solomon (2010) / Wang and Nakamura (2015)).

Note for existing users

• Please change all characters in the names of functions into small letters.
• The directory of functions can be access via hn2016_falwa.api instead of directly from hn2016_falwa.
• The old function SolveUrefnoslip has been renamed solveurefboth_bc. The input fields are the same. The dimension-dependent parameters are functions of input instead of hard-coded in the previous version. Thanks @slubis for reminding.

- Jupyter Notebook
Published by csyhuang almost 9 years ago

hn2016_falwa - hn2016_falwa v0.1.6

Added two new functions that allows computation of LWA based on prescribed equivalent-latitudes: - barotropicinputQreftocomputeLWA - qgpvinputQreftocomputeLWA

- Jupyter Notebook
Published by csyhuang almost 9 years ago

hn2016_falwa - hn2016_falwa v0.1.5c

Updates from v0.1.4: - Included a function 'staticstability' to compute static stability from potential temperature field. - Fixed a bug in outputing equivalent latitude in the function 'qgpvEqlatLWA'. Other related subroutines are not affected. - A beta version of function 'SolveURefnosliphemisphere' is updated. It can only be used to compute eddy-free reference state in no-slip boundary conditions.

- Jupyter Notebook
Published by csyhuang almost 9 years ago