Metadata-Version: 2.4
Name: sverdrup
Version: 0.1.0
Summary: Regional sea-surface-height-anomaly reconstruction with first-class predictive uncertainty
Project-URL: Homepage, https://github.com/killett/sverdrup
Project-URL: Repository, https://github.com/killett/sverdrup
Project-URL: Issues, https://github.com/killett/sverdrup/issues
Author-email: Emmy Killett <emmykillett@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: gaussian process,oceanography,optimal interpolation,sea surface height,uncertainty quantification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.12
Requires-Dist: numpy>=1.26
Requires-Dist: pyproj>=3.6
Requires-Dist: scipy>=1.11
Provides-Extra: all
Requires-Dist: dask[distributed]>=2024.1; extra == 'all'
Requires-Dist: fsspec>=2024.1; extra == 'all'
Requires-Dist: netcdf4>=1.6; extra == 'all'
Requires-Dist: requests>=2.31; extra == 'all'
Requires-Dist: tenacity>=8.2; extra == 'all'
Requires-Dist: xarray>=2024.1; extra == 'all'
Provides-Extra: dask
Requires-Dist: dask[distributed]>=2024.1; extra == 'dask'
Provides-Extra: io
Requires-Dist: fsspec>=2024.1; extra == 'io'
Requires-Dist: netcdf4>=1.6; extra == 'io'
Requires-Dist: requests>=2.31; extra == 'io'
Requires-Dist: tenacity>=8.2; extra == 'io'
Requires-Dist: xarray>=2024.1; extra == 'io'
Description-Content-Type: text/markdown

# sverdrup

A regional SSHA (sea-surface-height anomaly) reconstruction framework with first-class,
rigorous predictive-distribution uncertainty. Phase 1 wires a single space-time tile
end-to-end (OSSE + OSE) through a hexagonal stack: a hand-rolled dense space-time GP / optimal
interpolation exposes native covariance and whole-field samples behind a `CovarianceOperator`
seam, and each unit of work returns a *Persisted* `Product` bundle (mean + exact marginal
variance + low-rank factor + clipped diagonal residual + eval-point predictions) reduced
on-worker while the exact operator is still live.

## Installation

Dependencies are managed with [pixi](https://pixi.sh):

```
pixi install
```

## Quick usage

Run a config-driven pipeline over a regional tile (OSSE on the committed fixtures):

```
pixi run python -m sverdrup tests/integration/config_osse.json
```

This windows the observations, dispatches the solve through a `dask.distributed` LocalCluster,
writes the persisted `Product` to an fsspec URL, and prints evaluator scores (RMSE vs truth,
calibration, ground-track power).

Programmatically:

```python
from sverdrup.adapters.odc.fixtures import FixtureSource
from sverdrup.application.pipeline import PipelineInputs, run_pipeline

src = FixtureSource("tests/fixtures/natl60_tiny.nc", ref_path="tests/fixtures/natl60_ref_tiny.nc")
product, scores = run_pipeline(PipelineInputs(
    mode="OSSE", method_name="oi", source=src, out_url="file:///tmp/osse.zarr",
    lon_range=(-64, -56), lat_range=(34, 42), time_range=(0, 5), output_times=[2.0],
    params={"length_scale": 300.0, "time_scale": 10.0, "variance": 0.05},
))
```

## Common tasks

```
pixi run test        # pytest (the opt-in oracle is skipped without SVERDRUP_ODC_DATA)
pixi run lint        # ruff check
pixi run format      # ruff format
pixi run typecheck   # mypy
```

The correctness oracle (reproducing the ODC OI leaderboard number) is opt-in — see
[`docs/oracle-runbook.md`](docs/oracle-runbook.md).

## Releasing

Publishing to PyPI is automated via GitHub Actions Trusted Publishing on tag push. The
workflow lives at `docs/superpowers/ci/release.yml`; copy it to `.github/workflows/release.yml`
in the GitHub repo (a one-time step — the local tooling token cannot push workflow files).
Configure the PyPI trusted publisher (project `sverdrup`, owner `killett`, repo `sverdrup`,
workflow `release.yml`, environment `pypi`), then `git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z`.

## Project structure

```
src/sverdrup/
  core/          # pure protocols + value objects (grid, types, distribution, product, ports, ...)
  distributions/ # Gaussian / Ensemble / Persisted distributions + lifting adapters
  methods/       # space-time Matern-3/2 kernel, Cholesky solver, GP/OI (Method 1), trivial (Method 0)
  derived/       # CRS-aware first-difference (real) + committed stubs
  eval/          # accuracy, calibration (+ polar-void), ground-track evaluators
  adapters/      # dask executor, fsspec result sink, ODC data sources + fixtures
  application/   # unit of work, solve_unit, splits, run config, end-to-end pipeline
tests/           # unit, integration, oracle; tiny committed NetCDF fixtures
docs/            # architecture design, implementation plan, oracle runbook
```

See `PROGRESS.md` for the running project notebook (decisions, gotchas, deviations).
