diff --git a/README.md b/README.md index 2297dd8..dd5fee4 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,52 @@ -[![Tests](https://github.com/pyCOARE/coare/actions/workflows/tests.yml/badge.svg)](https://github.com/pyCOARE/coare/actions/workflows/tests.yml) -[![License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](ttps://github.com/pyCOARE/coare/blob/master/LICENSE.txt) -[![Code coverage](https://codecov.io/gh/pyCOARE/coare/branch/main/graph/badge.svg)](https://app.codecov.io/gh/pyCOARE/coare) +[![Tests](https://github.com/pycoare/coare/actions/workflows/tests.yml/badge.svg)](https://github.com/pycoare/coare/actions/workflows/tests.yml) +[![License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](ttps://github.com/pycoare/coare/blob/master/LICENSE.txt) +[![Code coverage](https://codecov.io/gh/pycoare/coare/branch/main/graph/badge.svg)](https://app.codecov.io/gh/pycoare/coare) [![Docs](https://readthedocs.org/projects/pycoare/badge/?version=latest)](https://pycoare.readthedocs.io/en/latest/?badge=latest) [![PyPI version](https://img.shields.io/pypi/v/pycoare?style=plastic)](https://pypi.org/project/pycoare/) # pycoare -This is a beta version of an implementation of the [COARE algorithm](https://doi.org/10.1175/1520-0442(2003)016%3C0571:BPOASF%3E2.0.CO;2) that builds on the [original NOAA-PSL pycoare code](https://github.com/NOAA-PSL/COARE-algorithm). Currently only COARE v3.5 is implemented - hopefully v3.6 will come soon! +**pycoare** is a Python package for calculating various **air-sea fluxes** from **bulk variables** (e.g., wind speed, temperature, humidity), +using the COARE algorithms developed through the TOGA-COARE project ([Fairall et al., 1996a](https://agupubs.onlinelibrary.wiley.com/doi/10.1029/95JC03190), [Fairall et al., 1996b](https://agupubs.onlinelibrary.wiley.com/doi/10.1029/95JC03205), [Fairall et al., 1997](http://journals.ametsoc.org/doi/10.1175/1520-0426(1997)014%3C0338:ISMOTM%3E2.0.CO;2)). -This version makes minor updates to the code itself, refactors code to improve readability, maintability, and distribution, and creates a standardized API for calling functions. [See the changelog](https://github.com/pyCOARE/coare/blob/main/docs/changelog.md) for all mathematically relevant changes made to the original code. +Included in this package are implementations of the **COARE v3.5 and v3.6 algorithms** that builds on the [original NOAA-PSL pycoare code](https://github.com/NOAA-PSL/COARE-algorithm). This package makes very minor updates to the algorithm itself, instead focusing on improved code structure, packaging, documentation, and distribution by implementing an object oriented approach and utilizing modern Python tooling. The goal of this new version is to improve usability and reproducibility, encourage collaboration, and ease maintenance. + +[See the changelog](https://github.com/pycoare/coare/blob/main/docs/changelog.md) for all mathematically relevant changes made to the algorithm itself. + +**Find more details on the usage and api [in the documentation](https://pycoare.readthedocs.io).** ## Installation -The latest stable version (currently a beta) can be downloaded using Pip +The latest stable version (currently a beta) can be downloaded using pip: ``` pip install pycoare ``` - -You can install the most up-to-date version using +The package can also be added to projects via [uv](https://docs.astral.sh/uv/): ``` -pip install git+https://github.com/pyCOARE/coare +uv add pycoare +``` +You can install the most up-to-date version using: +``` +pip install git+https://github.com/pycoare/coare ``` - -## Contribution - -I welcome any contributions. Please feel free to [raise an issue](https://github.com/pyCOARE/coare/issues) or submit a [pull request](https://github.com/pyCOARE/coare/pulls). - -## Origins and Credits -The international TOGA-COARE field program which took place in the western Pacific warm pool over 4 months from November 1992 to February 1993 ([Fairall et al. 1996a](https://github.com/noaa-psd/COARE-algorithm/blob/master/References/Fairall%20et%20al.%201996a%20-%20cool%20skin%20warm%20layer.pdf), [1996b](https://github.com/noaa-psd/COARE-algorithm/blob/master/References/Fairall%20et%20al.%201996b%20-%20bulk%20fluxes%20of%20variables.pdf) and [1997](https://github.com/noaa-psd/COARE-algorithm/blob/master/References/Fairall%20et%20al.%201997%20-%20ship%20measurements%20MABL.pdf)) spurred the development of the COARE model. The algorithm is intended to provide estimates of `momentum, sensible heat`, and `latent heat fluxes` using inputs of bulk atmospheric variables (`wind speed, SST, air temperature, air humidity`). The algorithm contains subroutines/functions to handle near-surface gradients of temperature in the ocean. - -This Python implementation of the COARE algorithm was initially translated from MATLAB by Byron Blomquist and Ludovic Bariteau. For more information on the people and publications that developed the COARE algorithm, see the references below. ## Versions -- **Version 2.5** was published in 1996. -- **Version 3.0** was published in 2003; it was a major update from Version 2.5. This update was based on new observations at higher wind speeds (10 to 20 m/s). Available in MATLAB and FORTRAN only. -- **Version 3.5** was released in 2013 following the publication of [Edson et al. 2013](https://github.com/noaa-psd/COARE-algorithm/blob/master/References/Edson%20et%20al.%202013%20-%20momentum%20flux.pdf), which made adjustments to the wind speed dependence of the Charnock parameter based on a large database of direct covariance stress observations (principally from a buoy). This led to an increase in stress for wind speeds greater than about 18 m/s. The roughness Reynolds number formulation of the scalar roughness length was tuned slightly to give the same values of `Ch` and `Ce` as Version 3.0. The diurnal warm layer model was structured as a separate routine instead of embedded in a driver program. COARE 3.5 was based on Edson’s buoy data ([Edson et al. 2013](https://github.com/noaa-psd/COARE-algorithm/blob/master/References/Edson%20et%20al.%202013%20-%20momentum%20flux.pdf)) and was compared to a large database (a total of 16,000 hours of observations) combining observations from NOAA, WHOI, and U. Miami ([Fairall et al. 2011](https://github.com/noaa-psd/COARE-algorithm/blob/master/References/Fairall%20et%20al.%202011%20-%20COAREG.pdf)). It is available in Python and MATLAB. -- **Version 3.6** is slightly restructured and built around improvements in the representation of the effects of waves on fluxes. This includes improved relationships of `surface roughness`, $z_o$, and `whitecap fraction`, $W_f$, on wave parameters. More details can be found in [coare3.6\_readme\_1.pdf](https://github.com/noaa-psd/COARE-algorithm/blob/master/References/coare36_readme_1.pdf). This version is available in Python, MATLAB and FORTRAN. +pycoare contains two versions of the COARE algorithm: **COARE v3.5** and **COARE v3.6**. -## References: +Version 3.5 was released in 2013, which made adjustments to the wind speed dependence of the Charnock parameter based on a large database of direct covariance stress observations (principally from a buoy) ([Edson et al., 2013](https://doi.org/10.1175/JPO-D-12-0173.1)). +This led to an increase in stress for wind speeds greater than about 18 m/s. The roughness Reynolds number formulation of the scalar roughness length was tuned slightly to give the same values of `Ch` and `Ce` as Version 3.0. The diurnal warm layer model was structured as a separate routine instead of embedded in a driver program. COARE v3.5 was based on buoy data ([Edson et al., 2013](https://doi.org/10.1175/JPO-D-12-0173.1)) and was compared to a large database (a total of 16,000 hours of observations) combining observations from NOAA, WHOI, and U. Miami ([Fairall et al., 2011](http://doi.wiley.com/10.1029/2010JC006884)). -* Edson, J.B., J. V. S. Raju, R.A. Weller, S. Bigorre, A. Plueddemann, C.W. Fairall, S. Miller, L. Mahrt, Dean Vickers, and Hans Hersbach, 2013: On the Exchange of momentum over the open ocean. J. Phys. Oceanogr., 43, 1589–1610. doi: http://dx.doi.org/10.1175/JPO-D-12-0173.1 +Version 3.6 is slightly restructured and built around improvements in the representation of the effects of waves on fluxes. This includes improved relationships of surface roughness and whitecap fraction on wave parameters ([Fairall et al., 2022](https://doi.org/10.3389/fmars.2022.826606)). -* Fairall, C.W., E.F. Bradley, J.S. Godfrey, G.A. Wick, J.B. Edson, and G.S. Young, 1996a: The cool skin and the warm layer in bulk flux calculations. J. Geophys. Res. 101, 1295-1308. https://doi.org/10.1029/95JC03190 +## Contribution -* Fairall, C.W., E.F. Bradley, D.P. Rogers, J.B. Edson, G.S. Young, 1996b: Bulk parameterization of air-sea fluxes for TOGA COARE. J. Geophys. Res. 101, 3747-3764. https://doi.org/10.1029/95JC03205 +I welcome any contributions - feel free to [raise an issue](https://github.com/pycoare/coare/issues) or submit a [pull request](https://github.com/pycoare/coare/pulls). Take a look at the [contribution guide](https://pycoare.readthedocs.io/en/latest/contributing.html) to get started! -* Fairall, C. W., White, A. B., Edson, J. B., and Hare, J. E.: Integrated Shipboard Measurements of the Marine Boundary Layer, J. Atmos. Ocean. Tech., 14, 338–359, 1997. https://doi.org/10.1175/1520-0426(1997)014<0338:ISMOTM>2.0.CO;2 +## Credits -* Fairall, C.W., E.F. Bradley, J.E. Hare, A.A. Grachev, and J.B. Edson, 2003: Bulk parameterization of air-sea fluxes: Updates and verification for the COARE algorithm. J. Climate 16, 571-591. https://doi.org/10.1175/1520-0442(2003)016<0571:BPOASF>2.0.CO;2 +This Python implementation of the COARE algorithm was initially translated from MATLAB by +Byron Blomquist, Ludovic Bariteau, with support from the NOAA Physical Sciences Laboratory ([Ludovic et al., 2021](https://zenodo.org/records/5110991)). -* Fairall, C.W., Mingxi Yang, Ludovic Bariteau, J.B. Edson, D. Helmig, W. McGillis, S. Pezoa, J.E. Hare, B. Huebert, and B. Blomquist, 2011: Implementation of the COARE flux algorithm with CO2, DMS, and O3. J. Geophys. Res., 116, C00F09, https://doi.org/10.1029/2010JC006884 +The development of the COARE algorithm builds upon decades of research, for which I am extremely appreciative. +The history of the COARE algorithm and its development [can be found here](https://github.com/pyCOARE/coare/tree/main/docs/References) ([Fairall et al., 2022](https://doi.org/10.3389/fmars.2022.826606)). diff --git a/docs/References/Edson et al. 2013 - momentum flux correction.pdf b/docs/References/Edson et al. 2013 - momentum flux correction.pdf deleted file mode 100644 index b083aff..0000000 Binary files a/docs/References/Edson et al. 2013 - momentum flux correction.pdf and /dev/null differ diff --git a/docs/References/Edson et al. 2013 - momentum flux.pdf b/docs/References/Edson et al. 2013 - momentum flux.pdf deleted file mode 100644 index eeddc19..0000000 Binary files a/docs/References/Edson et al. 2013 - momentum flux.pdf and /dev/null differ diff --git a/docs/References/Fairall et al. 1996a - cool skin warm layer.pdf b/docs/References/Fairall et al. 1996a - cool skin warm layer.pdf deleted file mode 100644 index 0f2bb06..0000000 Binary files a/docs/References/Fairall et al. 1996a - cool skin warm layer.pdf and /dev/null differ diff --git a/docs/References/Fairall et al. 1996b - bulk fluxes of variables.pdf b/docs/References/Fairall et al. 1996b - bulk fluxes of variables.pdf deleted file mode 100644 index 417295c..0000000 Binary files a/docs/References/Fairall et al. 1996b - bulk fluxes of variables.pdf and /dev/null differ diff --git a/docs/References/Fairall et al. 1997 - ship measurements MABL.pdf b/docs/References/Fairall et al. 1997 - ship measurements MABL.pdf deleted file mode 100644 index c284645..0000000 Binary files a/docs/References/Fairall et al. 1997 - ship measurements MABL.pdf and /dev/null differ diff --git a/docs/References/Fairall et al. 2003 - bulk fluxes.pdf b/docs/References/Fairall et al. 2003 - bulk fluxes.pdf deleted file mode 100644 index 7e71e86..0000000 Binary files a/docs/References/Fairall et al. 2003 - bulk fluxes.pdf and /dev/null differ diff --git a/docs/References/Fairall et al. 2011 - COAREG.pdf b/docs/References/Fairall et al. 2011 - COAREG.pdf deleted file mode 100644 index e2a82e3..0000000 Binary files a/docs/References/Fairall et al. 2011 - COAREG.pdf and /dev/null differ diff --git a/docs/References/Fairall-2022-COARE-development.pdf b/docs/References/Fairall-2022-COARE-development.pdf new file mode 100644 index 0000000..3fb74fd Binary files /dev/null and b/docs/References/Fairall-2022-COARE-development.pdf differ diff --git a/docs/References/coare36_readme_1.pdf b/docs/References/coare36_readme_1.pdf deleted file mode 100644 index d6a7f4e..0000000 Binary files a/docs/References/coare36_readme_1.pdf and /dev/null differ diff --git a/docs/c36_api.rst b/docs/c36_api.rst new file mode 100644 index 0000000..985955e --- /dev/null +++ b/docs/c36_api.rst @@ -0,0 +1,28 @@ +COARE v3.6 +========== + +.. caution:: + + The COARE algorithm is designed to work best when the user has time series of as many input variables as possible. + This implementation only specifically requires that the ocean surface wind speed ``u`` be provide, but it is highly recommended to use additional variables. + If any of variables are not available for the full ``u`` time series, a single, representative (e.g., mean) value can be input that will be used in place of the entire time series. + Please read the documentation carefully to understand each of the input variables to :class:`coare_36`. + +.. currentmodule:: pycoare + +.. autoclass:: coare_36 + :members: + +.. autoclass:: pycoare.coare_36.fluxes + +.. autoclass:: pycoare.coare_36.transfer_coefficients + +.. autoclass:: pycoare.coare_36.stability_functions + +.. autoclass:: pycoare.coare_36.stability_parameters + +.. autoclass:: pycoare.coare_36.velocities + +.. autoclass:: pycoare.coare_36.temperatures + +.. autoclass:: pycoare.coare_36.humidities diff --git a/docs/conf.py b/docs/conf.py index 41cf89a..c406fa5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,17 +1,17 @@ # Configuration file for the Sphinx documentation builder. -import sys import os +import sys sys.path.insert(0, os.path.abspath("..")) # -- Project information -project = "pyCOARE" +project = "pycoare" author = "Andrew Scherer" release = "1" -version = "0.2.0" +version = "0.3.0" # -- General configuration @@ -22,8 +22,11 @@ "sphinx.ext.autosummary", "sphinx.ext.intersphinx", "sphinx_search.extension", + "sphinxcontrib.bibtex", ] +bibtex_bibfiles = ["references.bib"] + autodoc_typehints = "none" autodoc_member_order = "alphabetical" diff --git a/docs/contributing.rst b/docs/contributing.rst index 501e5de..2130a8e 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -13,13 +13,12 @@ Please follow these guidelines for contributing to this project: $ git clone $ cd coare -* Install the development requirements in a new environment +* Install the development requirements using `uv `_ and activate the virtual environment .. code-block:: bash - $ conda create -n pycoare - $ conda activate pycoare - $ pip install -r requirements-dev.txt + $ uv sync --dev + $ .venv/bin/activate * Create a new branch for your feature diff --git a/docs/index.rst b/docs/index.rst index 3813029..df808e7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,40 +1,75 @@ pycoare ======= -**pycoare** is a Python package for calculating various air-sea fluxes from bulk variables, -using code developed through the TOGA-COARE project. +**pycoare** is a Python package for calculating various **air-sea fluxes** from **bulk variables** (e.g., wind speed, temperature, humidity), +using code developed through the TOGA-COARE project :cite:`fairall_bulk_1996,fairall_coolskin_1996,fairall_integrated_1997`. + +Included in this package are implementations of the **COARE v3.5 and v3.6 algorithms** that builds on the `original NOAA-PSL pycoare code `_. +This package makes very minor updates to the algorithm itself, instead focusing on improved code structure, packaging, documentation, and distribution by implementing an object oriented approach and utilizing modern Python tooling. +The goal of this new version is to improve usability and reproducibility, encourage collaboration, and ease maintenance. Installation ------------ -The latest stable version (currently a beta) can be downloaded using Pip:: +The latest stable version (currently a beta) can be downloaded using pip:: >>> pip install pycoare +The package can also be added to projects via `uv `_:: + + >>> uv add pycoare + You can install the most up-to-date version using:: - >>> pip install git+https://github.com/pyCOARE/coare + >>> pip install git+https://github.com/pycoare/coare + +Versions +-------- + +pycoare contains two versions of the COARE algorithm: COARE v3.5 and COARE v3.6. + +Version 3.5 was released in 2013, which made adjustments to the wind speed dependence of the Charnock parameter based on a large database of direct covariance stress observations (principally from a buoy) :cite:`edson_exchange_2013`. +This led to an increase in stress for wind speeds greater than about 18 m/s. +The roughness Reynolds number formulation of the scalar roughness length was tuned slightly to give the same values of `Ch` and `Ce` as Version 3.0. +The diurnal warm layer model was structured as a separate routine instead of embedded in a driver program. +COARE 3.5 was based on buoy data :cite:`edson_exchange_2013` and was compared to a large database (a total of 16,000 hours of observations) combining observations from NOAA, WHOI, and U. Miami :cite:`fairall_implementation_2011`. + +Version 3.6 is slightly restructured and built around improvements in the representation of the effects of waves on fluxes. This includes improved relationships of surface roughness and whitecap fraction on wave parameters :cite:`fairall_air-sea_2022`. + +Contribution +------------ + +I welcome any contributions - feel free to `raise an issue `_ or submit a `pull request `_. +Take a look at the `contribution guide `_ to get started! Credits ------- -This version of the Python implementation of the COARE algorithm was `initially translated from MATLAB by Byron Blomquist and Ludovic Bariteau `_. -For more information on the people and publications that developed the COARE algorithm, see the references at the link below. +This Python implementation of the COARE algorithm was initially translated from MATLAB by +Byron Blomquist, Ludovic Bariteau, with support from the NOAA Physical Sciences Laboratory :cite:`ludovic_python_2021`. + +The development of the COARE algorithm builds upon decades of research, for which I am extremely appreciative. +The history of the COARE algorithm and its development can be found by downloading :download:`this supplementary material ` :cite:`fairall_air-sea_2022`. +See the `references `_ for more information. .. toctree:: :maxdepth: 2 :caption: Getting Started + installation usage - References .. toctree:: :maxdepth: 2 :caption: API Reference c35_api + c36_api util_api .. toctree:: + :maxdepth: 2 + :caption: Resources contributing + references diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..3b6c342 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,33 @@ +Installation +============ + +The latest stable version (currently a beta) can be downloaded using pip:: + + >>> pip install pycoare + +The package can also be added to projects via `uv `_:: + + >>> uv add pycoare + +Dependencies +------------ + +pycoare requires Python 3.9 or later. + +Currently, the only dependency is `numpy `_ (v2.0 or later). + +Future versions may implement support for and require `xarray `_. + +Development Installation +------------------------ + +Installing the development dependencies is simple using uv:: + + >>> uv sync --dev + >>> .venv/bin/activate + +If you are not using uv, you can install the development dependencies using pip:: + + >>> pip install -r requirements.txt + +See more in the `contribution guide `_. diff --git a/docs/references.bib b/docs/references.bib new file mode 100644 index 0000000..3ae90f8 --- /dev/null +++ b/docs/references.bib @@ -0,0 +1,240 @@ +@article{fairall_implementation_2011, + title = {Implementation of the {Coupled} {Ocean}-{Atmosphere} {Response} {Experiment} flux algorithm with {CO2} , dimethyl sulfide, and O3}, + volume = {116}, + issn = {0148-0227}, + url = {http://doi.wiley.com/10.1029/2010JC006884}, + doi = {10.1029/2010JC006884}, + language = {en}, + journal = {Journal of Geophysical Research}, + author = {Fairall, C. W. and Yang, Mingxi and Bariteau, Ludovic and Edson, J. B. and Helmig, D. and McGillis, W. and Pezoa, S. and Hare, J. E. and Huebert, B. and Blomquist, B.}, + month = oct, + year = {2011}, + pages = {C00F09}, +} + +@article{beljaars_flux_1991, + title = {Flux {Parameterization} over {Land} {Surfaces} for {Atmospheric} {Models}}, + volume = {30}, + issn = {1520-0450, 0894-8763}, + url = {https://journals.ametsoc.org/view/journals/apme/30/3/1520-0450_1991_030_0327_fpolsf_2_0_co_2.xml}, + doi = {10.1175/1520-0450(1991)030<0327:FPOLSF>2.0.CO;2}, + language = {EN}, + number = {3}, + journal = {Journal of Applied Meteorology and Climatology}, + author = {Beljaars, A. C. M. and Holtslag, A. a. M.}, + month = mar, + year = {1991}, + note = {Publisher: American Meteorological Society +Section: Journal of Applied Meteorology and Climatology}, + pages = {327--341}, +} + +@article{grachev_convective_2000, + title = {Convective {Profile} {Constants} {Revisited}}, + volume = {94}, + doi = {10.1023/A:1002452529672}, + journal = {Boundary-Layer Meteorology}, + author = {Grachev, Andrey and Fairall, Chris and Bradley, E.}, + month = mar, + year = {2000}, + pages = {495--515}, +} + +@article{grachev_dependence_1997, + title = {Dependence of the {Monin}–{Obukhov} {Stability} {Parameter} on the {Bulk} {Richardson} {Number} over the {Ocean}}, + volume = {36}, + issn = {1520-0450, 0894-8763}, + url = {https://journals.ametsoc.org/view/journals/apme/36/4/1520-0450_1997_036_0406_dotmos_2.0.co_2.xml}, + doi = {10.1175/1520-0450(1997)036<0406:DOTMOS>2.0.CO;2}, + language = {EN}, + number = {4}, + journal = {Journal of Applied Meteorology and Climatology}, + author = {Grachev, A. A. and Fairall, C. W.}, + month = apr, + year = {1997}, + note = {Publisher: American Meteorological Society +Section: Journal of Applied Meteorology and Climatology}, + pages = {406--414}, +} + +@misc{ludovic_python_2021, + title = {Python implementation of the {COARE} 3.5 {Bulk} {Air}-{Sea} {Flux} algorithm}, + url = {https://zenodo.org/records/5110991}, + publisher = {Zenodo}, + author = {Ludovic, Bariteau and Byron, Blomquist and Christopher, Fairall and Elizabeth, Thompson and Jim, Edson and Robert, Pincus}, + month = jul, + year = {2021}, + doi = {10.5281/zenodo.5110991}, + keywords = {air humidity, air temperature, air-sea flux, COARE, cool skin, drag coefficient, SST, tangential stress, warm layer, wind speed}, +} + +@article{fairall_bulk_1996, + title = {Bulk parameterization of air‐sea fluxes for {Tropical} {Ocean}‐{Global} {Atmosphere} {Coupled}‐{Ocean} {Atmosphere} {Response} {Experiment}}, + volume = {101}, + copyright = {http://onlinelibrary.wiley.com/termsAndConditions\#vor}, + issn = {0148-0227}, + url = {https://agupubs.onlinelibrary.wiley.com/doi/10.1029/95JC03205}, + doi = {10.1029/95JC03205}, + language = {en}, + number = {C2}, + journal = {Journal of Geophysical Research: Oceans}, + author = {Fairall, C. W. and Bradley, E. F. and Rogers, D. P. and Edson, J. B. and Young, G. S.}, + month = feb, + year = {1996}, + pages = {3747--3764}, +} + +@article{fairall_integrated_1997, + title = {Integrated {Shipboard} {Measurements} of the {Marine} {Boundary} {Layer}}, + volume = {14}, + issn = {0739-0572, 1520-0426}, + url = {http://journals.ametsoc.org/doi/10.1175/1520-0426(1997)014<0338:ISMOTM>2.0.CO;2}, + doi = {10.1175/1520-0426(1997)014<0338:ISMOTM>2.0.CO;2}, + language = {en}, + number = {3}, + journal = {Journal of Atmospheric and Oceanic Technology}, + author = {Fairall, C. W. and White, A. B. and Edson, J. B. and Hare, J. E.}, + month = jun, + year = {1997}, + pages = {338--359}, +} + +@article{fairall_coolskin_1996, + title = {Cool‐skin and warm‐layer effects on sea surface temperature}, + volume = {101}, + copyright = {http://onlinelibrary.wiley.com/termsAndConditions\#vor}, + issn = {0148-0227}, + url = {https://agupubs.onlinelibrary.wiley.com/doi/10.1029/95JC03190}, + doi = {10.1029/95JC03190}, + language = {en}, + number = {C1}, + journal = {Journal of Geophysical Research: Oceans}, + author = {Fairall, C. W. and Bradley, E. F. and Godfrey, J. S. and Wick, G. A. and Edson, J. B. and Young, G. S.}, + month = jan, + year = {1996}, + pages = {1295--1308}, +} + +@article{edson_exchange_2013, + title = {On the {Exchange} of {Momentum} over the {Open} {Ocean}}, + volume = {43}, + issn = {0022-3670, 1520-0485}, + url = {https://journals.ametsoc.org/view/journals/phoc/43/8/jpo-d-12-0173.1.xml}, + doi = {10.1175/JPO-D-12-0173.1}, + language = {en}, + number = {8}, + journal = {Journal of Physical Oceanography}, + author = {Edson, James B. and Jampana, Venkata and Weller, Robert A. and Bigorre, Sebastien P. and Plueddemann, Albert J. and Fairall, Christopher W. and Miller, Scott D. and Mahrt, Larry and Vickers, Dean and Hersbach, Hans}, + month = aug, + year = {2013}, + pages = {1589--1610}, +} + +@article{liu_bulk_1979, + title = {Bulk {Parameterization} of {Air}-{Sea} {Exchanges} of {Heat} and {Water} {Vapor} {Including} the {Molecular} {Constraints} at the {Interface}}, + volume = {36}, + issn = {0022-4928, 1520-0469}, + url = {https://journals.ametsoc.org/view/journals/atsc/36/9/1520-0469_1979_036_1722_bpoase_2_0_co_2.xml}, + doi = {10.1175/1520-0469(1979)036<1722:BPOASE>2.0.CO;2}, + language = {EN}, + number = {9}, + journal = {Journal of the Atmospheric Sciences}, + author = {Liu, W. Timothy and Katsaros, Kristina B. and Businger, Joost A.}, + month = sep, + year = {1979}, + note = {Publisher: American Meteorological Society +Section: Journal of the Atmospheric Sciences}, + pages = {1722--1735}, +} + +@article{smith_coefficients_1988, + title = {Coefficients for sea surface wind stress, heat flux, and wind profiles as a function of wind speed and temperature}, + volume = {93}, + copyright = {Copyright 1988 by the American Geophysical Union.}, + issn = {2156-2202}, + url = {https://onlinelibrary.wiley.com/doi/abs/10.1029/JC093iC12p15467}, + doi = {10.1029/JC093iC12p15467}, + language = {en}, + number = {C12}, + journal = {Journal of Geophysical Research: Oceans}, + author = {Smith, Stuart D.}, + year = {1988}, + note = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1029/JC093iC12p15467}, + pages = {15467--15472}, +} + +@article{godfrey_turbulent_1991, + title = {On the turbulent fluxes of buoyancy, heat and moisture at the air-sea interface at low wind speeds}, + volume = {96}, + copyright = {Copyright 1991 by the American Geophysical Union.}, + issn = {2156-2202}, + url = {https://onlinelibrary.wiley.com/doi/abs/10.1029/91JC02015}, + doi = {10.1029/91JC02015}, + language = {en}, + number = {C12}, + journal = {Journal of Geophysical Research: Oceans}, + author = {Godfrey, J. S. and Beljaars, A. C. M.}, + year = {1991}, + note = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1029/91JC02015}, + pages = {22043--22048}, +} + +@techreport{bradley_joint_1997, + address = {Boulder, Colorado, USA}, + title = {Joint workshop of the toga coare flux and oceans working groups, and the gewex gcss working group 4.}, + author = {Bradley, E and Moncrieff, M and Weller, R}, + year = {1997}, + pages = {14--16}, + institution = {National Center for Atmospheric Research (NCAR)}, +} + +@techreport{bradley_third_1995, + address = {Honolulu, Hawaii, USA}, + title = {Third workshop of the toga coare air-sea interaction (flux) working group.}, + author = {Bradley, E and Weller, R}, + year = {1995}, + pages = {2--4}, + institution = {East-West Center, University of Hawaii} +} + +@techreport{bradley_fourth_1997, + address = {Boulder, Colorado, USA}, + title = {Fourth workshop of the togacoare air–sea interaction (flux) working group.}, + author = {Bradley, E and Weller, R}, + year = {1997}, + pages = {61}, + institution = {University Corporation for Atmospheric Research (UCAR)} +} + +@article{fairall_air-sea_2022, + title = {Air-{Sea} {Trace} {Gas} {Fluxes}: {Direct} and {Indirect} {Measurements}}, + volume = {9}, + issn = {2296-7745}, + shorttitle = {Air-{Sea} {Trace} {Gas} {Fluxes}}, + url = {https://www.frontiersin.org/journals/marine-science/articles/10.3389/fmars.2022.826606/full}, + doi = {10.3389/fmars.2022.826606}, + language = {English}, + journal = {Frontiers in Marine Science}, + author = {Fairall, Christopher W. and Yang, Mingxi and Brumer, Sophia E. and Blomquist, Byron W. and Edson, James B. and Zappa, Christopher J. and Bariteau, Ludovic and Pezoa, Sergio and Bell, Thomas G. and Saltzman, Eric S.}, + month = jul, + year = {2022}, + note = {Publisher: Frontiers}, + keywords = {Bubble mediated transfer, Bulk Algorithm, cardon dioxide (CO2), chemical enhancement, COARE gas flux parameterization, Dimethylsufide (DMS), direct observation, Gas transfer velocity}, +} + +@article{fairall_bulk_2003, + title = {Bulk {Parameterization} of {Air}–{Sea} {Fluxes}: {Updates} and {Verification} for the {COARE} {Algorithm}}, + volume = {16}, + issn = {0894-8755, 1520-0442}, + shorttitle = {Bulk {Parameterization} of {Air}–{Sea} {Fluxes}}, + url = {https://journals.ametsoc.org/view/journals/clim/16/4/1520-0442_2003_016_0571_bpoasf_2.0.co_2.xml}, + doi = {10.1175/1520-0442(2003)016<0571:BPOASF>2.0.CO;2}, + language = {EN}, + number = {4}, + journal = {Journal of Climate}, + author = {Fairall, C. W. and Bradley, E. F. and Hare, J. E. and Grachev, A. A. and Edson, J. B.}, + month = feb, + year = {2003}, + note = {Publisher: American Meteorological Society Section: Journal of Climate}, + pages = {571--591}, +} diff --git a/docs/references.rst b/docs/references.rst new file mode 100644 index 0000000..83fc5d3 --- /dev/null +++ b/docs/references.rst @@ -0,0 +1,8 @@ +References +========== + +Not all of the references here are cited in the documentation, but they all contain contributions to the COARE algorithms. + +.. bibliography:: references.bib + :style: plain + :all: diff --git a/docs/requirements.txt b/docs/requirements.txt index 96ea3b9..426529f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,4 +2,5 @@ numpy pytest sphinx sphinx-book-theme +sphinxcontrib-bibtex readthedocs-sphinx-search diff --git a/docs/usage.rst b/docs/usage.rst index 8998095..e88745d 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,6 +1,11 @@ Usage ===== +.. tip:: + Both the COARE v3.5 and COARE v3.6 algorithms use the same input variables and provide the same output variables. + This example shows how to use the COARE v3.5 algorithm, but the same steps can be used for the COARE v3.6 algorithm - + simply replace ``coare_35`` with ``coare_36`` in any code! + This package is designed around an object oriented approach, since the number of parameters that the COARE algorithm outputs can be quite unwieldy otherwise. Therefore, the first step in using the COARE algorithm is to create an instance of the ``coare_35`` class: @@ -9,13 +14,13 @@ Therefore, the first step in using the COARE algorithm is to create an instance Note that this (and other examples in this documentation) uses *only* wind speed as input. This is bad practice, and ideally you should use as many input variables as possible. -See :class:`~pycoare.coare_35` for a complete list of input variables. +See :class:`~pycoare.coare_35` or :class:`~pycoare.coare_36` for a complete list of input variables. .. note:: - The COARE v3.5 algorithm can accept NumPy ``ArrayLike`` objects (e.g., ``float``, ``list``, ``numpy.ndarray``, etc.) as input. + ``coare_35`` and ``coare_36`` can accept NumPy ``ArrayLike`` objects (e.g., ``float``, ``list``, ``numpy.ndarray``, etc.) as input. It is not yet designed to work with ``xarray`` objects (support coming soon). - Please convert any ``xarray.DataArray`` to ``numpy.ndarray`` using the ``.values`` attribute before passing them to the COARE algorithm. + Please convert any ``xarray.DataArray`` to ``numpy.ndarray`` before passing them to the COARE algorithm. Once the ``coare_35`` object is created, the algorithm will automatically be ran. The output of the algorithm is stored in several "output classes", which can be accessed as attributes from the ``coare_35`` class. @@ -31,7 +36,7 @@ To access the wind stress (i.e. the air-sea momentum flux), you can use the ``ta .. important:: - These "output classes" should only ever be accessed from within a ``coare_35`` instance (as shown in the examples). + These "output classes" should only ever be accessed from within a ``coare_35`` or ``coare_36`` instance (as shown in the examples). As another example, the ``transfer_coefficients`` output class contains the output of the algorithm related, unsurprisingly, to transfer coefficients. To access the neutral wind stress transfer coefficient (i.e., neutral drag coefficient), you can use the ``cdn_rf`` subattribute of the ``transfer_coffiencient`` attribute of the ``coare_35`` object: @@ -50,5 +55,14 @@ The available output classes accessible from a :class:`~pycoare.coare_35` instan * :class:`~pycoare.coare_35.temperatures` * :class:`~pycoare.coare_35.humidities` +The same output classes are available from a :class:`~pycoare.coare_36` instance: + +* :class:`~pycoare.coare_36.fluxes` +* :class:`~pycoare.coare_36.transfer_coefficients` +* :class:`~pycoare.coare_36.stability_functions` +* :class:`~pycoare.coare_36.velocities` +* :class:`~pycoare.coare_36.temperatures` +* :class:`~pycoare.coare_36.humidities` + The links above will take you to the documentation for each of these output classes. This contains information on the subattributes that are available in each output class. diff --git a/pycoare/coare_35.py b/pycoare/coare_35.py index 01b5c18..82dd945 100644 --- a/pycoare/coare_35.py +++ b/pycoare/coare_35.py @@ -21,12 +21,7 @@ class coare_35: """ - .. |fairall2003| replace:: COARE 3.0 code - .. _fairall2003: https://doi.org/10.1175/1520-0442(2003)016<0571:BPOASF>2.0.CO;2 - .. |edson2013| replace:: CLIMODE, MBL and CBLAST experiments - .. _edson2013: https://doi.org/10.1175/JPO-D-12-0173.1 - - The COARE v3.5 algorithm is based on the |fairall2003|_ with modifications from the results of the |edson2013|_. + Primary class used for running the COARE v3.5 bulk flux algorithm. Usage example using only wind speed as an input (see note above):: @@ -1121,7 +1116,8 @@ def _return_vars(self, out): class fluxes: - """Fluxes computed from COARE. + """ + Class containing the flux outputs computed from the COARE v3.5 algorithm. An instance of this class is created whenever a :class:`coare_35` class is created. Variables in this class should only be accessed through this instance of the :class:`coare_35` class:: @@ -1247,7 +1243,8 @@ def __init__(self, _bulk_loop_inputs, _bulk_loop_outputs): class velocities: - """Velocities computed from COARE. + """ + Class containing the velocity outputs computed from the COARE v3.5 algorithm. An instance of this class is created whenever a :class:`coare_35` class is created. Variables in this class should only be accessed through this instance of the :class:`coare_35` class:: @@ -1309,7 +1306,8 @@ def __init__(self, _bulk_loop_inputs, _bulk_loop_outputs, stability_functions): class temperatures: - """Temperatures computed from COARE. + """ + Class containing temperature outputs computed from the COARE v3.5 algorithm. An instance of this class is created whenever a :class:`coare_35` class is created. Variables in this class should only be accessed through this instance of the :class:`coare_35` class:: @@ -1360,7 +1358,8 @@ def __init__(self, _bulk_loop_inputs, _bulk_loop_outputs, stability_functions): class humidities: - """Stability parameters computed from COARE. + """ + Class containing the humidity outputs computed from the COARE v3.5 algorithm. An instance of this class is created whenever a :class:`coare_35` class is created. Variables in this class should only be accessed through this instance of the :class:`coare_35` class:: @@ -1413,7 +1412,8 @@ def __init__( class stability_parameters: - """Stability parameters computed from COARE. + """ + Class containing the stability parameters computed from the COARE v3.5 algorithm. An instance of this class is created whenever a :class:`coare_35` class is created. Variables in this class should only be accessed through this instance of the :class:`coare_35` class:: @@ -1460,7 +1460,8 @@ def __init__(self, _bulk_loop_outputs): class transfer_coefficients: - """Transfer coefficients computed from COARE. + """ + Class containing the transfer coefficients computed from the COARE v3.5 algorithm. An instance of this class is created whenever a :class:`coare_35` class is created. Variables in this class should only be accessed through this instance of the :class:`coare_35` class:: @@ -1534,7 +1535,8 @@ def __init__(self, _bulk_loop_inputs, _bulk_loop_outputs, fluxes): class stability_functions: - """Stability functions computed from COARE. + """ + Class containing stability functions calculated from the COARE v3.5 algorithm. An instance of this class is created whenever a :class:`coare_35` class is created. Variables in this class should only be accessed through this instance of the :class:`coare_35` class:: diff --git a/pycoare/coare_36.py b/pycoare/coare_36.py index 8a393a6..c6904e4 100644 --- a/pycoare/coare_36.py +++ b/pycoare/coare_36.py @@ -23,14 +23,9 @@ class coare_36: """ - .. |fairall2003| replace:: COARE 3.0 code - .. _fairall2003: https://doi.org/10.1175/1520-0442(2003)016<0571:BPOASF>2.0.CO;2 - .. |edson2013| replace:: CLIMODE, MBL and CBLAST experiments - .. _edson2013: https://doi.org/10.1175/JPO-D-12-0173.1 + Primary class used for running the COARE v3.6 bulk flux algorithm. - The COARE v3.5 algorithm is based on the |fairall2003|_ with modifications from the results of the |edson2013|_. - - Usage example using only wind speed as an input (see note above):: + Usage example using only wind speed as an input (see note):: from pycoare import coare_36 # creating a coare_36 instance @@ -657,7 +652,8 @@ def _return_vars(self, out): class fluxes: - """Fluxes computed from COARE. + """ + Class containing the flux outputs computed from the COARE v3.6 algorithm. An instance of this class is created whenever a :class:`coare_36` class is created. Variables in this class should only be accessed through this instance of the :class:`coare_36` class:: @@ -786,7 +782,8 @@ def __init__(self, _bulk_loop_inputs, _bulk_loop_outputs): class velocities: - """Velocities computed from COARE. + """ + Class containing the velocity outputs computed from the COARE v3.6 algorithm. An instance of this class is created whenever a :class:`coare_36` class is created. Variables in this class should only be accessed through this instance of the :class:`coare_36` class:: @@ -848,7 +845,8 @@ def __init__(self, _bulk_loop_inputs, _bulk_loop_outputs, stability_functions): class temperatures: - """Temperatures computed from COARE. + """ + Class containing temperature outputs computed from the COARE v3.6 algorithm. An instance of this class is created whenever a :class:`coare_36` class is created. Variables in this class should only be accessed through this instance of the :class:`coare_36` class:: @@ -899,7 +897,8 @@ def __init__(self, _bulk_loop_inputs, _bulk_loop_outputs, stability_functions): class humidities: - """Stability parameters computed from COARE. + """ + Class containing the humidity outputs computed from the COARE v3.6 algorithm. An instance of this class is created whenever a :class:`coare_36` class is created. Variables in this class should only be accessed through this instance of the :class:`coare_36` class:: @@ -952,7 +951,8 @@ def __init__( class stability_parameters: - """Stability parameters computed from COARE. + """ + Class containing the stability parameters computed from the COARE v3.6 algorithm. An instance of this class is created whenever a :class:`coare_36` class is created. Variables in this class should only be accessed through this instance of the :class:`coare_36` class:: @@ -999,7 +999,8 @@ def __init__(self, _bulk_loop_outputs): class transfer_coefficients: - """Transfer coefficients computed from COARE. + """ + Class containing the transfer coefficients computed from the COARE v3.6 algorithm. An instance of this class is created whenever a :class:`coare_36` class is created. Variables in this class should only be accessed through this instance of the :class:`coare_36` class:: @@ -1073,7 +1074,8 @@ def __init__(self, _bulk_loop_inputs, _bulk_loop_outputs, fluxes): class stability_functions: - """Stability functions computed from COARE. + """ + Class containing stability functions calculated from the COARE v3.6 algorithm. An instance of this class is created whenever a :class:`coare_36` class is created. Variables in this class should only be accessed through this instance of the :class:`coare_36` class::