Merge branch 'master' of github.com-csyhuang:csyhuang/hn2016_falwa

.github/workflows/python-build-test.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11"]
+        python-version: ["3.10", "3.11", "3.12"]
 
     steps:
     - uses: actions/checkout@v3
@@ -26,15 +26,11 @@ jobs:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
-        python -m pip install flake8 pytest
+        python -m pip install --upgrade pip
+        python -m pip install flake8
         python -m pip install coverage
-        python -m pip install -U pytest
-        python -m pip install --upgrade pip setuptools wheel
         sudo apt-get install gfortran
-        python -m pip install scipy==1.11.2
-        python -m pip install xarray==2024.1.1
-        python -m pip install numpy==1.24.4
-        python setup.py develop
+        python -m pip install .[test]
     - name: Test with pytest
       run: |
         coverage run -m pytest -k "not output_results"

docs/source/conf.py

@@ -19,11 +19,8 @@
 import os
 import sys
 # Need to fix the issue below
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)) + "/../../")
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)) + "/../../falwa/")
-
-# import sphinx_rtd_theme
-
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)) + "/../../src/")
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)) + "/../../src/falwa/")
 
 autodoc_mock_imports = [
     "matplotlib",  # for plot_utils.py
@@ -79,9 +76,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'1.3.0'
+version = u'2.0.0'
 # The full version, including alpha/beta/rc tags.
-release = u'1.3.0'
+release = u'2.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/index.rst

@@ -19,25 +19,25 @@ extreme weather events. It implements the finite-amplitude local wave activity a
 Package Installation
 ------------------------------
 
-This current version works for Python 3.x. Note that since v0.3.0, some functions have backend in Fortran. To build the package from source, you need a fortran compiler (e.g. `gfortran <http://hpc.sourceforge.net/>`_) to implement the installation.
+**Attention: substantial changes took place in release v2.0.0. Installation in develop mode is no longer available.**
 
-Since the package is still being actively developed, please use the *develop* mode for installation.
+Since release v2.0.0, the F2PY modules in `falwa` is compiled with `meson` (See Issue #95 for details) to cope with the deprecation of `numpy.disutils` in python 3.12.
 
-To install the package for the first time, clone the GitHub repo and install via `develop` mode:::
+### First-time installation
 
- git clone https://github.com/csyhuang/hn2016_falwa.git
- cd falwa
- python setup.py develop
+1. To build the package from source, you need a fortran compiler (e.g., [gfortran](http://hpc.sourceforge.net/)) to implement the installation.
+2. Clone the package repo by `git clone https://github.com/csyhuang/hn2016_falwa.git` .
+3. Navigate into the repository and set up a python environment satisfying the installation requirement by `conda env create -f environment.yml`. The environment name in the file is set to be `falwa_env` (which users can change).
+4. Install the package with the command `python -m pip install .`
+5. If the installation is successful, you should be able to run through all unit tests in the folder `tests/` by executing `pytest tests/`.
 
+### Get updated code from new releases
 
-To incorporate updates, pull the new version of the code from GitHub. Remove any existing f2py modules and recompile.::
-
- # Assume you are already in the falwa/ repo
- git pull
- rm falwa/*.so
- python setup.py develop
- pytest tests/ # to check if the package can be run properly
-
+1. To incorporate updates, first, pull the new version of the code from GitHub by `git pull`.
+2. Uninstall existing version of `falwa`: `pip uninstall falwa`
+3. If there is change in `environment.yml`, remove the existing environment by `conda remove --name falwa_env --all` and create the environment again from the updated YML file: `conda env create -f environment.yml`.
+4. Reinstall the updated version by `python -m pip install .`.
+5. Run through all unit tests in the folder `tests/` by executing `pytest tests/` to make sure the package has been properly installed.
 
 Quick start
 -----------------------------------------
@@ -51,21 +51,12 @@ Depending on what you want to do, the methods to be use may be different.
 
 2. If you want to compute zonal wind reference states and wave activity fluxes in QG Formalism, look at `notebooks/nh2018_science/demo_script_for_nh2018.ipynb` for the usage of `QGField`. This notebook demonstrates how to compute wave activity and reference states presented in Nakamura and Huang (2018). To make sure the package is properly installed in your environment, run through the notebook after installation to see if there is error.
 
-THe conda environment for running the notebook can be found in `environment.yml`. To create the conda environment, execute:::
-
- conda env create -f environment.yml
-
-
-
-
 Issues Reporting
 ------------------------------
 
-- If you are interested in using the package, please leave your contact `here <https://goo.gl/forms/5L8fv0mUordugq6v2>`_ or email me([email protected]) such that I can keep you updated of any changes made.
-
+- If you are interested in getting email message related to update of this package, please leave your contact `here <https://goo.gl/forms/5L8fv0mUordugq6v2>`_ such that I can keep you updated of any changes made.
 - If you encounter *coding issues/bugs* when using the package, please create an `Issue ticket <https://github.com/csyhuang/hn2016_falwa/issues>`_.
-
-- If you have scientific questions, please contact Clare S. Y. Huang via email([email protected]).
+- If you have scientific questions, please create a thread in the `Discussion Board <https://github.com/csyhuang/hn2016_falwa/discussions>`_ with the category "General" or "Q&A" according to the circumstance.
 
 Modules
 ========

environment.yml

@@ -5,16 +5,18 @@ channels:
 - defaults
 
 dependencies:
-- python=3.10
-- numpy=1.22.3
-- scipy=1.9
+- python=3.12
+- numpy=1.26.4
+- scipy=1.14.0
+- netCDF4=1.6.5
+- cftime=1.6.2
+- xarray=2024.1.1
 - pytest=7.4.0
-- xarray=2023.2.0
-- netCDF4=1.5.8
-- gridfill
+- matplotlib=3.8.2
+- cartopy=0.22.0
 - jupyter
-- matplotlib
-- twine
-- cartopy
+- pip
+# - twine
+# - gridfill
 # Other useful packages to visualize plots in notebooks
 # - cartopy

meson.build

@@ -0,0 +1,16 @@
+project('falwa')
+
+# Based on:
+# - https://numpy.org/doc/stable/f2py/buildtools/meson.html
+# - https://meson-python.readthedocs.io/en/stable/how-to-guides/first-project.html
+# - https://github.com/jameskermode/f90wrap/blob/master/f90wrap/meson.build
+
+add_languages('c')
+add_languages('fortran')
+
+# Python configuration
+py = import('python').find_installation(pure: false)
+
+inc_root = include_directories('.')
+
+subdir('src')

notes/developer/pip_deployment.md

@@ -15,5 +15,58 @@ Deploy the package onto PyPI for real:
 ```
 python3 -m twine upload dist/*
 ```
+# Update of deployment after using pyproject.toml
 
-
+```
+pip install build
+python -m build . --sdist
+python3 -m pip install --upgrade twine
+python3 -m twine upload --repository testpypi dist/*
+```
+
+
+
+```error
+clare@otc:~/isolated_test/hn2016_falwa$ python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps falwa
+Looking in indexes: https://test.pypi.org/simple/
+Collecting falwa
+  Downloading https://test-files.pythonhosted.org/packages/b1/0c/00cd0cd844c7d5c2faed03b3a1051de15e42afabe128783c1b9eb8239651/falwa-1.4.0a0.tar.gz (46.5 MB)
+     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 46.5/46.5 MB 625.8 kB/s eta 0:00:00
+  Installing build dependencies ... error
+  error: subprocess-exited-with-error
+  
+  × pip subprocess to install build dependencies did not run successfully.
+  │ exit code: 1
+  ╰─> [13 lines of output]
+      Looking in indexes: https://test.pypi.org/simple/
+      Collecting numpy
+        Downloading https://test-files.pythonhosted.org/packages/d5/80/b947c574d9732e39db59203f9aa35cb4d9a5dd8a0ea2328acb89cf10d6e3/numpy-1.9.3.zip (4.5 MB)
+           ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.5/4.5 MB 714.2 kB/s eta 0:00:00
+        Preparing metadata (setup.py): started
+        Preparing metadata (setup.py): finished with status 'done'
+      Collecting meson-python
+        Downloading https://test-files.pythonhosted.org/packages/c9/b6/9665154ee9926317a248e2b171ea21ac2b77788adea404566eec29b84f3b/meson_python-0.13.0-py3-none-any.whl.metadata (4.1 kB)
+      Collecting meson>=0.63.3 (from meson-python)
+        Downloading https://test-files.pythonhosted.org/packages/ae/c6/e3c2fa2fc539ca99679f02b05700b56c76ffb9338c1dd62f1c64391828ba/meson-1.1.991-py3-none-any.whl.metadata (1.8 kB)
+      INFO: pip is looking at multiple versions of meson-python to determine which version is compatible with other requirements. This could take a while.
+      ERROR: Could not find a version that satisfies the requirement pyproject-metadata>=0.7.1 (from meson-python) (from versions: none)
+      ERROR: No matching distribution found for pyproject-metadata>=0.7.1
+      [end of output]
+  
+  note: This error originates from a subprocess, and is likely not a problem with pip.
+error: subprocess-exited-with-error
+
+× pip subprocess to install build dependencies did not run successfully.
+│ exit code: 1
+╰─> See above for output.
+
+note: This error originates from a subprocess, and is likely not a problem with pip.
+``` 
+
+Successfully installed from `.tar.gz`:
+
+```bash
+conda install anaconda::pip
+python3 -m pip install falwa-1.4.0a0.tar.gz 
+pytest tests/
+```

pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+build-backend = "mesonpy"
+requires = ["numpy", "meson-python"]
+
+[project]
+name = "falwa"
+authors = [
+    { name="Clare S. Y. Huang", email="[email protected]" },
+    { name="Christopher Polster", email="[email protected]" },
+]
+description = "python package to compute finite-amplitude local wave activity (Huang and Nakamura 2016, JAS)"
+readme = "readme.md"
+license = { file="LICENSE.txt" }
+version = "2.0.0"
+requires-python = ">=3.10"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Fortran",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+dependencies = [
+    "numpy>=1.22",
+    "scipy",
+    "xarray"
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "netcdf4"
+]
+
+[project.urls]
+"Documentation" = "https://hn2016-falwa.readthedocs.io/"
+"Repository" = "https://github.com/csyhuang/hn2016_falwa"
+"Bug Tracker" = "https://github.com/csyhuang/hn2016_falwa/issues"
+

readme.md

@@ -1,4 +1,4 @@
-## Python Library: falwa (v1.3.0)
+## Python Library: falwa (v2.0.0)
 
 [![Python package](https://github.com/csyhuang/hn2016_falwa/actions/workflows/python-build-test.yml/badge.svg)](https://github.com/csyhuang/hn2016_falwa/actions/workflows/python-build-test.yml)[![codecov.io](https://codecov.io/gh/csyhuang/hn2016_falwa/branch/master/graph/badge.svg)](https://codecov.io/gh/csyhuang/hn2016_falwa)[![Documentation Status](https://readthedocs.org/projects/hn2016-falwa/badge/?version=latest)](http://hn2016-falwa.readthedocs.io/en/latest/?badge=latest)[![DOI](https://zenodo.org/badge/63908662.svg)](https://zenodo.org/badge/latestdoi/63908662)
 
@@ -15,25 +15,25 @@ Compute from gridded climate data the Finite-amplitude Local Wave Activity (FALW
 
 ## Package Installation
 
-This current version works for Python 3.x. Note that since v0.3.0, some functions have backend in Fortran. To build the package from source, you need a fortran compiler (e.g. [gfortran](http://hpc.sourceforge.net/)) to implement the installation.
+**Attention: substantial changes took place in release v2.0.0. Installation in develop mode is no longer available.**
 
-Since the package is still being actively developed, please use the *develop* mode for installation.
+Since release v2.0.0, the F2PY modules in `falwa` is compiled with `meson` (See Issue #95 for details) to cope with the deprecation of `numpy.disutils` in python 3.12. 
 
-To install the package for the first time, clone the GitHub repo and install via `develop` mode:
-```
-git clone https://github.com/csyhuang/hn2016_falwa.git
-cd hn2016_falwa
-python setup.py develop
-```
+### First-time installation
 
-To incorporate updates, pull the new version of the code from GitHub. Remove any existing f2py modules and recompile.
-```
-# Assume you are already in the hn2016_falwa/ repo
-git pull
-rm falwa/*.so
-python setup.py develop
-pytest tests/ # to check if the package can be run properly
-```
+1. To build the package from source, you need a fortran compiler (e.g., [gfortran](http://hpc.sourceforge.net/)) to implement the installation.
+2. Clone the package repo by `git clone https://github.com/csyhuang/hn2016_falwa.git` .
+3. Navigate into the repository and set up a python environment satisfying the installation requirement by `conda env create -f environment.yml`. The environment name in the file is set to be `falwa_env` (which users can change).
+4. Install the package with the command `python -m pip install .` 
+5. If the installation is successful, you should be able to run through all unit tests in the folder `tests/` by executing `pytest tests/`.
+
+### Get updated code from new releases
+
+1. To incorporate updates, first, pull the new version of the code from GitHub by `git pull`.
+2. Uninstall existing version of `falwa`: `pip uninstall falwa`
+3. If there is change in `environment.yml`, remove the existing environment by `conda remove --name falwa_env --all` and create the environment again from the updated YML file: `conda env create -f environment.yml`.
+4. Reinstall the updated version by `python -m pip install .`.
+5. Run through all unit tests in the folder `tests/` by executing `pytest tests/` to make sure the package has been properly installed.
 
 ## Quick start
 
@@ -46,14 +46,8 @@ Depending on what you want to do, the methods to be use may be different.
 
 2. If you want to compute zonal wind reference states and wave activity fluxes in QG Formalism, look at `notebooks/nh2018_science/demo_script_for_nh2018.ipynb` for the usage of `QGField`. This notebook demonstrates how to compute wave activity and reference states presented in Nakamura and Huang (2018). To make sure the package is properly installed in your environment, run through the notebook after installation to see if there is error.
 
-THe conda environment for running the notebook can be found in `environment.yml`. To create the conda environment, execute:
-
-```bash
-conda env create -f environment.yml
-```
-
 ## Inquiries / Issues reporting
 
-- If you are interested in using the package, please leave your contact [here](https://goo.gl/forms/5L8fv0mUordugq6v2) or email me([email protected]) such that I can keep you updated of any changes made.
+- If you are interested in getting email message related to update of this package, please leave your contact [here](https://goo.gl/forms/5L8fv0mUordugq6v2) such that I can keep you updated of any changes made.
 - If you encounter *coding issues/bugs* when using the package, please create an [Issue ticket](https://github.com/csyhuang/hn2016_falwa/issues).
-- If you have scientific questions, please contact Clare S. Y. Huang via email([email protected]).
+- If you have scientific questions, please create a thread in the [Discussion Board](https://github.com/csyhuang/hn2016_falwa/discussions) with the category "General" or "Q&A" according to the circumstance.