shallowwater 0.1.3

Shallow-water model on a C-grid over a beta-plane (educational)

Shallow Water Model

A small single-layer shallow-water model for teaching, experimentation, and simple geophysical-fluid-dynamics demonstrations.

The model is intentionally lightweight. It includes tutorial-style Python scripts, guided lab notebooks, and examples covering gravity waves, tsunamis, wind-driven circulation, storm surge, rotation, Rossby waves, tides, and simple abyssal/source-sink flows.

Repository layout

src/shallowwater/        Core model package
notebooks/              Guided lab notebooks
labs/                   Lab handouts and instructions
scripts/                Runnable example scripts and helper tools
animations/             Generated animations; not tracked by git
.github/                GitHub metadata/workflows; keep tracked

The animations/ directory is for generated output and should be ignored by git.

Installation with uv

This project can be run with uv, which manages the Python environment and dependencies.

From the repository root:

uv sync

Then test that the package imports:

uv run python -c "import shallowwater; print('shallowwater import OK')"

If you prefer not to use uv, create your own Python environment and install the package in editable mode:

python -m pip install -e .

Guided labs

The guided lab material is in labs/ and notebooks/.

Recommended lab sequence:

1. labs/01_waves_in_a_box.md
   Gravity waves, reflections, and seiches.

2. labs/02_tsunami_shoaling.md
   Tsunami propagation, variable bathymetry, shoaling, and sponge layers.

3. labs/02_tsunami_shoaling_sv.md
   Swedish version of the tsunami-shoaling lab.

4. labs/03_wind_storms_and_coasts.md
   Wind forcing, coastal setup, storm surge, and coastal waves.

5. labs/04_rotation_geostrophy_rossby.md
   Rotation, geostrophic adjustment, deformation radius, and Rossby waves.

6. labs/05_ocean_pathways.md
   Gyres, tides, source-sink flows, and reduced-gravity behaviour.

The corresponding notebooks are kept directly in notebooks/:

notebooks/01_waves_in_a_box.ipynb
notebooks/02_tsunami_shoaling.ipynb
notebooks/03_wind_storms_and_coasts.ipynb
notebooks/04_rotation_geostrophy_rossby.ipynb
notebooks/05_ocean_pathways.ipynb

Notebook outputs should not be committed. See Keeping notebooks clean.

Running example scripts

The older tutorial notebooks have been converted to Python scripts under scripts/. These scripts can be used to regenerate examples and animations.

Generated animations are written to:

animations/

This folder should not be tracked by git.

Linux

List available scripts:

uv run ./scripts/run_scripts_linux.sh -l

Run one script:

uv run ./scripts/run_scripts_linux.sh scripts/01_wind_gyre.py

Run all scripts:

uv run ./scripts/run_scripts_linux.sh -a

macOS

List available scripts:

uv run ./scripts/run_scripts_mac.sh -l

Run one script:

uv run ./scripts/run_scripts_mac.sh scripts/01_wind_gyre.py

Run all scripts:

uv run ./scripts/run_scripts_mac.sh -a

The macOS runner avoids Bash features such as mapfile, which are not available in the older Bash version shipped with macOS.

Windows PowerShell

List available scripts:

uv run powershell -ExecutionPolicy Bypass -File .\scripts\run_scripts_windows.ps1 -List

Run one script:

uv run powershell -ExecutionPolicy Bypass -File .\scripts\run_scripts_windows.ps1 -Script scripts\01_wind_gyre.py

Run all scripts:

uv run powershell -ExecutionPolicy Bypass -File .\scripts\run_scripts_windows.ps1 -All

Optional numba acceleration

The model can optionally use numba-accelerated operators. By default, the example scripts run without numba so that the code works in the simplest possible environment.

If numba is disabled, scripts may print:

not using numba

To enable numba on Linux or macOS, set:

export SHALLOWWATER_USE_NUMBA=1

Then run a script, for example:

uv run ./scripts/run_scripts_mac.sh scripts/01_wind_gyre.py

You can also enable numba for a single command:

SHALLOWWATER_USE_NUMBA=1 uv run ./scripts/run_scripts_mac.sh scripts/01_wind_gyre.py

Run all scripts with numba:

SHALLOWWATER_USE_NUMBA=1 uv run ./scripts/run_scripts_mac.sh -a

On Windows PowerShell:

$env:SHALLOWWATER_USE_NUMBA = "1"
uv run powershell -ExecutionPolicy Bypass -File .\scripts\run_scripts_windows.ps1 -All

Check whether numba is installed:

uv run python -c "import numba; print(numba.__version__)"

Check whether the numba operators import correctly:

uv run python -c "from shallowwater import operators_numba; print('numba operators import OK')"

Numba acceleration is used only when all of the following are true:

1. numba is installed.
2. src/shallowwater/operators_numba.py imports successfully.
3. SHALLOWWATER_USE_NUMBA=1 is set.

If any of these are false, the scripts should fall back to the pure NumPy implementation.

Tsunami shoaling example

The tsunami-shoaling material demonstrates a long wave crossing from deep water toward a shallow coast.

Key ingredients:

• variable bathymetry
• shallow-water wave speed, c = sqrt(g H)
• shoaling as the wave enters shallower water
• a sponge layer that damps outgoing waves and reduces reflections

Relevant files:

labs/02_tsunami_shoaling.md
labs/02_tsunami_shoaling_sv.md
notebooks/02_tsunami_shoaling.ipynb
src/shallowwater/bathymetry.py
src/shallowwater/sponge.py

This is a teaching example for wave propagation and shoaling. It is not a full coastal inundation or wetting-and-drying model.

Keeping notebooks clean

Notebook outputs should not be committed to git.

To strip outputs manually:

uv run python scripts/strip_notebooks.py notebooks/*.ipynb

Then commit the cleaned notebooks:

git add notebooks/*.ipynb
git commit -m "Clean notebook outputs"

A git pre-commit hook may also be used, but it is optional. If a custom hook causes problems, disable it with:

git config --unset core.hooksPath

Git ignore recommendations

The repository should keep .github/ tracked, but ignore local environments, generated outputs, and Jupyter helper files.

Recommended .gitignore entries include:

# Python cache
__pycache__/
*.py[cod]
*$py.class

# uv / virtual environments
.venv/
.uv-cache/
uv-cache/

# Python build / packaging
build/
dist/
*.egg-info/
.eggs/

# Test / coverage output
.pytest_cache/
.coverage
htmlcov/
.tox/
.nox/

# Jupyter
.ipynb_checkpoints/
.virtual_documents/

# Generated model outputs
animations/
outputs/
figures/
movies/
*.mp4
*.mov
*.avi
*.gif
*.webm

# Generated data / diagnostics
*.nc
*.h5
*.hdf5
*.zarr/
*.npz

# Logs
*.log

# OS/editor files
.DS_Store
Thumbs.db
.vscode/
.idea/
*.swp
*.swo

# Local environment config
.env
.env.*

Do not ignore .github/; it is normally used for GitHub Actions, issue templates, pull-request templates, and other repository metadata.

Development notes

Run a quick import check:

uv run python -c "import shallowwater; print('OK')"

Compile the scripts to catch syntax errors:

uv run python -m py_compile scripts/*.py

Run a single example before running all scripts:

uv run ./scripts/run_scripts_mac.sh scripts/01_wind_gyre.py

Replace run_scripts_mac.sh with the Linux or Windows runner as appropriate.