This document provides a high-level introduction to the wavespectra library, explaining its architecture, core components, and capabilities. It covers the foundational design patterns, data model, and how the system processes ocean wave spectral data.
For detailed information on specific subsystems:
Wavespectra is a Python library for processing and analyzing ocean wave spectral data. It is built on top of xarray, extending xarray.DataArray and xarray.Dataset with domain-specific functionality for wave spectra through the .spec accessor namespace. The library provides:
freq, dir, time) and variables (efth, wspd, wdir, dpt)Sources: README.rst1-321 docs/quickstart.rst1-369
Wavespectra uses xarray's accessor registration pattern to extend core xarray objects without modifying them. Two primary accessor classes are registered under the .spec namespace:
Accessor Pattern Implementation
The SpecArray class extends xarray.DataArray and provides spectral analysis methods. The SpecDataset class extends xarray.Dataset and wraps SpecArray methods while adding dataset-level operations like I/O and spatial selection. Once wavespectra is imported, any xarray object following the required conventions automatically gains the .spec accessor.
Sources: docs/quickstart.rst47-76 docs/library.rst1-134 docs/conventions.rst1-72
Wavespectra requires specific coordinate and variable naming conventions:
| Type | Name | Units | Description | Required |
|---|---|---|---|---|
| Coordinate | freq | Hz | Wave frequency | Yes |
| Coordinate | dir | degrees | Wave direction (coming-from) | Yes (2D spectra) |
| Coordinate | time | datetime | Time coordinate | Optional |
| Variable | efth | m²/Hz/degree or m²/Hz | Wave energy density | Yes |
| Variable | wspd | m/s | Wind speed | Optional (partitioning) |
| Variable | wdir | degrees | Wind direction | Optional (partitioning) |
| Variable | dpt | m | Water depth | Optional (partitioning, physics) |
These conventions are defined in wavespectra/core/attributes.py and enforced through the attrs module, which provides CF-compliant metadata from wavespectra/core/attributes.yml
Sources: docs/conventions.rst1-72 README.rst210-228
Architecture Overview
The system follows a layered architecture:
Input Layer: Dynamically loaded format-specific readers normalize diverse data sources into the unified data model. Backend entrypoints enable xr.open_dataset(file, engine='format') integration.
Core Data Model: xarray objects extended via SpecArray and SpecDataset accessors, providing the .spec namespace for all operations.
Analysis Engines: Modular computation engines for statistics, transformations, partitioning, construction, and physics calculations.
Output Layer: Format-specific writers that transform the unified data model back to external formats.
Utilities: Cross-cutting functionality including C-compiled watershed algorithm for performance-critical operations.
Sources: README.rst1-321 docs/api.rst1-309
Data Flow Steps
read_swan(), read_ww3()) parses external formatfreq, dir, time) and variables (efth).spec namespace for analysis methodsSources: README.rst84-130 docs/quickstart.rst77-102
The I/O system supports 15+ input formats and 7+ output formats through a plugin architecture:
Input Formats:
Output Formats:
Readers are dynamically loaded by wavespectra/input/__init__.py and exposed at module level. xarray backend entrypoints are defined in pyproject.toml for seamless xr.open_dataset() integration.
Sources: README.rst229-238 docs/api.rst113-178
The SpecArray accessor provides 60+ methods organized into categories:
| Category | Methods | Examples |
|---|---|---|
| Wave Parameters | Integrated statistics | hs(), tp(), fp(), tm01(), tm02(), dp(), dpm(), dm(), dspr() |
| Transformations | Spectral manipulation | oned(), split(), rotate(), interp(), smooth(), scale_by_hs() |
| Moments | Spectral moments | momf(), momd() |
| Wave Physics | Physical properties | celerity(), wavelen(), uss() (Stokes drift) |
| Fitting | Parametric fitting | fit_jonswap(), fit_gaussian() |
All methods leverage xarray's lazy evaluation and dask integration for efficient processing of large datasets.
Sources: docs/api.rst23-92 README.rst94-102
The partitioning subsystem separates complex wave spectra into physically meaningful components (wind sea + swells). Accessed via .spec.partition, it provides 7 algorithms:
The watershed algorithm in wavespectra/partition/specpart.c provides 10-100x speedup for critical partitioning operations. Algorithms requiring meteorological data use the wave age criterion from wavespectra/core/utils.py to classify partitions as wind sea vs swell.
Sources: README.rst134-158 docs/api.rst56-72 docs/quickstart.rst258-297
The construction subsystem creates synthetic spectra from parametric forms:
Frequency Shapes (wavespectra/construct/frequency.py):
jonswap(): JONSWAP spectrum for developing seastma(): TMA spectrum for finite depthgaussian(): Gaussian spectrumpierson_moskowitz(): Pierson-Moskowitz spectrumDirectional Shapes (wavespectra/construct/direction.py):
cartwright(): Cartwright directional distributionasymmetric(): Asymmetric directional distributionCombined Construction:
construct_partition(): Combines frequency and directional shapes into 2D spectrapartition_and_reconstruct(): Partition existing spectra, fit parametric forms, and reconstructSources: README.rst160-189 docs/api.rst180-194 docs/quickstart.rst299-325
The package uses setuptools with a C extension for the watershed algorithm. Key build components:
The build system compiles the C extension during installation, requiring a C compiler and NumPy headers.
Sources: docs/install.rst1-139
Testing infrastructure includes:
Sources: README.rst277-283
The system uses three plugin mechanisms:
input/*.py files and exposes read_* functions at module levelxr.open_dataset(engine='format') integrationSpecDatasetThis architecture allows users to extend the system with custom readers and writers without modifying core code.
Sources: docs/api.rst1-309
Sources: README.rst84-130 docs/quickstart.rst1-369
Refresh this wiki