py-wave-runup

A Python module which makes it easy for coastal engineers and scientists to test and use various empirical wave runup models which have been published in literature.
https://github.com/chrisleaman/py-wave-runup

Category: Hydrosphere
Sub Category: Coastal and Reefs

Keywords

beach beaches coastal coastal-engineering coastal-modelling

Keywords from Contributors

hurricane imagery noaa storms

Last synced: about 15 hours ago
JSON representation

Repository metadata

Empirical wave runup models implemented in Python

• Host: GitHub
• URL: https://github.com/chrisleaman/py-wave-runup
• Owner: chrisleaman
• Created: 2019-04-09T03:07:38.000Z (over 6 years ago)
• Default Branch: master
• Last Pushed: 2025-10-01T06:02:21.000Z (3 months ago)
• Last Synced: 2025-11-13T13:51:43.884Z (about 1 month ago)
• Topics: beach, beaches, coastal, coastal-engineering, coastal-modelling
• Language: Python
• Size: 2.88 MB
• Stars: 41
• Watchers: 2
• Forks: 17
• Open Issues: 21
• Releases: 12
• Metadata Files:
  • Readme: README.rst

README.rst

          =================
Python Wave Runup
=================
::

    Empirical wave runup models implemented in Python for coastal engineers and scientists.

.. image:: https://zenodo.org/badge/180274721.svg
   :target: https://zenodo.org/badge/latestdoi/180274721

.. image:: https://img.shields.io/pypi/v/py-wave-runup.svg
        :target: https://pypi.python.org/pypi/py-wave-runup

.. image:: https://readthedocs.org/projects/py-wave-runup/badge/?version=latest
    :target: https://py-wave-runup.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. image:: https://codecov.io/gh/chrisleaman/py-wave-runup/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/chrisleaman/py-wave-runup

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/ambv/black


Contents
----------
- `Installation`_
- `Usage`_
- `Documentation`_
- `Background`_
- `Contributing`_
- `Citation`_
- `License`_
- `References`_



Installation
------------

Installation of ``py-wave-runup`` can be done with uv or pip:

.. code:: bash

    # Using uv (recommended)
    uv add py-wave-runup

    # Using pip
    pip install py-wave-runup


Usage
-----

The following `wave runup models`_ are available for use:

- ``models.Stockdon2006``: The most commonly cited and widely used runup model.
- ``models.Power2018``: Based on the Gene-Expression Programming technique.
- ``models.Holman1986``: Incorporated wave setup using Duck, NC measurements.
- ``models.Nielsen2009``: Based on runup measurements from NSW, Australia.
- ``models.Ruggiero2001``: Based on runup measurements from dissipative Orgeon beaches.
- ``models.Vousdoukas2012``: Based on runup from European Atlantic coast
- ``models.Senechal2011``: Based on extreme storm condition at Truc Vert, France
- ``models.Beuzen2019``: Gaussian Process (GP) runup model
- ``models.Passarella2018``: Genetic Programming (infragravity and total) swash model 

To get calculate runup, setup and swash, define your offshore conditions in your
selected runup model then you can access each parameter:

.. code:: python

    from py_wave_runup import models

    model_sto06 = models.Stockdon2006(Hs=4, Tp=12, beta=0.1)

    model_sto06.R2     # 2.54
    model_sto06.setup  # 0.96
    model_sto06.sinc   # 2.06
    model_sto06.sig    # 1.65

.. _wave runup models: https://py-wave-runup.readthedocs.io/en/develop/models.html

Documentation
-------------
Documentation is located at https://py-wave-runup.readthedocs.io.


Background
----------

Wave runup refers to the final part of a wave's journey as it travels from offshore
onto the beach. It is observable by anyone who goes to the beach and watches the edge
of the water "runup" and rundown the beach. It is comprised of two components:

    - **setup**: the height of the time averaged superelevation of the mean water level
      above the Still Water Level (SWL)
    - **swash**: the height of the time varying fluctuation of the instantaneous water
      level about the setup elevation

Setup, swash and other components of Total Water Level (TWL) rise are shown in this
handy figure below.

.. image:: https://raw.githubusercontent.com/chrisleaman/py-wave-runup/master/docs/_static/VitousekDoubling2017Fig1.jpg
   :width: 500 px
   :align: center
..

    | Figure from Vitousek et al. (2017) [#vit17]_

Wave runup can contribute a significant portion of the increase in TWL in coastal
storms causing erosion and inundation. For example, Stockdon et al. (2006) [#sto06]_
collated data from numerous experiments, some of which showed wave runup 2% excedence
heights in excess of 3 m during some storms.

Given the impact such a large increase in TWL can have on coastlines, there has been
much research conducted to try improve our understanding of wave runup processes.
Although there are many processes which can influence wave runup (such as nonlinear
wave transformation, wave reflection, three-dimensional effects, porosity, roughness,
permeability and groundwater) [#cem06]_, many attempts have been made to derive
empirical relatinoships based on easily measurable parameters. Typically, empirical
wave runup models include:

    - **Hs**: significant wave height
    - **Tp**: peak wave length
    - **beta**: beach slope

This python package attempts to consolidate the work done by others in this field and
collate the numerous empirical relationships for wave runup which have been published.

Contributing
------------

As there are many different empirical wave models out there, contributions are most
welcome. If you don't feel confident about changing the code yourself, feel free to open
a `Github issue`_ and let us know what could be added. Otherwise, follow the steps below
to create a Pull Request:

.. _Github issue: https://github.com/chrisleaman/py-wave-runup/issues

1. Fork it (https://github.com/chrisleaman/py-wave-runup/fork)
2. Create the development environment:

    - Using `uv`_ (recommended): ``uv sync --dev``
    - For pip: ``pip install -e ".[dev]"``

3. Create your feature branch (``git checkout -b feature/fooBar``)
4. Install pre-commit hooks for automatic formatting (``uv run pre-commit install``)
5. Add your code!
6. Add and run tests (``uv run pytest``)
7. Update and check documentation compiles (``uv run sphinx-build -M html ".\docs" ".\docs\_build"``)
8. Commit your changes (``git commit -am 'Add some fooBar'``)
9. Push to the branch (``git push origin feature/fooBar``)
10. Create a new Pull Request

.. _uv: https://docs.astral.sh/uv/


Publishing
----------

To build and publish the package to PyPI:

.. code:: bash

    # Build the package
    uv build

    # Check the package (optional)
    uv run --active twine check dist/*

    # Publish to Test PyPI first (recommended)
    uv publish --publish-url https://test.pypi.org/legacy/

    # Publish to PyPI
    uv publish


Citation
--------

If this package has been useful to you, please cite the following DOI: https://doi.org/10.5281/zenodo.2667464


License
--------

Distributed under the GNU General Public License v3.


References
----------

.. [#vit17] Vitousek, Sean, Patrick L. Barnard, Charles H. Fletcher, Neil Frazer,
       Li Erikson, and Curt D. Storlazzi. "Doubling of Coastal Flooding Frequency
       within Decades Due to Sea-Level Rise." Scientific Reports 7, no. 1 (May 18,
       2017): 1399. https://doi.org/10.1038/s41598-017-01362-7.
.. [#sto06] Stockdon, Hilary F., Robert A. Holman, Peter A. Howd, and Asbury H. Sallenger.
       "Empirical Parameterization of Setup, Swash, and Runup." Coastal Engineering 53,
       no. 7 (May 1, 2006): 573-88. https://doi.org/10.1016/j.coastaleng.2005.12.005
.. [#cem06] United States, Army, and Corps of Engineers. Coastal Engineering Manual.
       Washington, D.C.: U.S. Army Corps of Engineers, 2006.

        

---

Owner metadata

• Name: Chris Leaman
• Login: chrisleaman
• Email:
• Kind: user
• Description: Postdoctoral researcher at UNSW Sydney. Researching coastal erosion, remote sensing and early warning systems.
• Website: https://www.leaman.io
• Location: Brisbane, Australia
• Twitter:
• Company: Water Research Laboratory (UNSW)
• Icon url: https://avatars.githubusercontent.com/u/7591552?u=d2a80d61d1a53bb6b6a50012efe7357c985fa104&v=4
• Repositories: 11
• Last ynced at: 2024-06-11T15:36:43.012Z
• Profile URL: https://github.com/chrisleaman

---

GitHub Events

Total

• Issues event: 3
• Watch event: 4
• Delete event: 5
• Issue comment event: 8
• Push event: 2
• Pull request event: 7
• Fork event: 1
• Create event: 5

Last Year

• Issues event: 3
• Watch event: 3
• Delete event: 5
• Issue comment event: 8
• Push event: 2
• Pull request event: 7
• Fork event: 1
• Create event: 5

---

Committers metadata

Last synced: 11 days ago

Name	Email	Commits
Chris Leaman	c****n@g****m	160
dependabot-preview[bot]	2****]	41
Evan B. Goldstein	e****n	7
Tomas Beuzen	t****n@g****m	7
dependabot[bot]	4****]	5
Christopher Leaman	z****9@a****u	5
dependabot[bot]	s****t@d****m	4
mandi thran	m****n@u****u	2
Matthew Conlin	3****t	1

Committer domains:

• unsw.edu.au: 1
• dependabot.com: 1
• ad.unsw.edu.au: 1

---

Issue and Pull Request metadata

Last synced: about 2 months ago

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/chrisleaman/py-wave-runup

---

---

---

Package metadata

• Total packages: 2
• Total downloads:
  • pypi: 74 last-month
• Total docker downloads: 122
• Total dependent packages: 0 (may contain duplicates)
• Total dependent repositories: 1 (may contain duplicates)
• Total versions: 23
• Total maintainers: 1

---

Dependencies

Score: 11.617663787105803