Publication-ready v2: GitHub Actions CI, Sphinx docs, PyPI publishing; drop Docker/Binder

[brmather]

Overhauls the project for the v2 release: replaces the stale Travis config with GitHub Actions, migrates the documentation from pdoc to a Sphinx site published to GitHub Pages, publishes to PyPI over OIDC trusted publishing, and removes the Docker/Binder setup.

CI — GitHub Actions (.github/workflows/)

• tests.yml — runs pytest on Python 3.9–3.13 (plus macOS on 3.13) on every push and PR. The suite imports only pytest/numpy/scipy/pycurious, so pip install -e ".[test]" && pytest runs everything.
• docs.yml — builds the Sphinx docs on every push/PR and deploys to GitHub Pages from master.
• publish.yml — builds the sdist + wheel and uploads to PyPI on a GitHub release, authenticating over OIDC trusted publishing (no stored secret).
• .travis.yml deleted.

Documentation — Sphinx + Furo (docs/)

Getting started, software dependencies, contributing (MyST-includes CONTRIBUTING.md), theory (Bouligand + Tanaka), tutorials, and an autodoc API reference. The Bouligand and Tanaka notebooks are the tutorials, executed at build time except the data-heavy Ex5 (which each pull ~600 MB); copy_notebooks.py stages them into the source tree. The method narrative and math move from the module docstrings into hand-written theory pages, and default_role = "literal" keeps the remaining pdoc-flavoured docstrings rendering cleanly.

Remove Docker & Binder

Docker/ deleted; README badges/sections stripped; logo URL fixed; new Tests + Docs badges added.

Packaging & housekeeping

Added __version__ (via importlib.metadata) and a docs extra; moved the internal bouligand-findings.md to notes/ so it stays out of the Sphinx build; refreshed README, CONTRIBUTING, CLAUDE, and .gitignore.

Verification (local)

• pytest full suite: 100 passed; -m "not slow": 97 passed.
• Clean sphinx-build: exit 0, zero warnings — notebooks executed with plots, Ex5 rendered un-executed, theory math rendered, API populated.
• python -m build + twine check: both PASSED; sdist ships exactly the 11 notebooks, no docs//notes//Docker/ leakage.

One-time settings (done by the maintainer)

• Settings → Pages → Source = GitHub Actions.
• PyPI Trusted Publisher on the pycurious project: owner brmather, repo pycurious, workflow publish.yml, environment pypi.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XS8gDB88WqK8sdQc81L28c

[brmather]

Full scope of this PR

The description above covers the packaging / CI / docs overhaul, but that's the final commit of a much larger change. This PR is really the v2 scientific rewrite of PyCurious. Here's the whole thing at a high level.

The headline: everything now carries an uncertainty

The defining change in v2 is that both methods return an estimate and an uncertainty. Anything that returned a bare number is gone. This drove a rewrite of the spectrum layer, a new covariance stack, and calibration against synthetics with a known answer.

Restructured API — two optimisers over a shared grid

CurieOptimise is split into two focused classes, both extending a shared CurieGrid (which inherits a CurieParallel mixin):

• CurieOptimiseBouligand — fits the four-parameter analytic spectrum (beta, zt, dz, C) by optimisation.
• CurieOptimiseTanaka — the centroid method: two straight lines fitted to separate wavenumber bands.

New module layout: grid.py (grid + shared spectrum & covariance machinery), optimise_bouligand.py, optimise_tanaka.py, parallel.py, and a new synthetic.py. The old optimise.py/curie.py are gone.

Uncertainty machinery (the core new science)

• window_spectrum converts the within-annulus scatter that radial_spectrum reports into the uncertainty of the annulus mean — what a fit actually needs — and is what both optimisers use.
• Two corrections, both measured by Monte Carlo rather than assumed:
  1. Within a bin — cells aren't independent (a real field is Hermitian, so ~half repeat; a taper correlates neighbours further). Encoded as a DOF factor that dominates in the sparse inner bins, which is exactly where a centroid depth is pinned down.
  2. Between bins — neighbouring residuals correlate because a taper spreads each wavenumber over several bins. Estimated from the residuals and solved with a GLS covariance (JᵀR⁻¹J)⁻¹. Ignoring it understates every reported sigma by ~30%.
• Bouligand adds profile-deviance intervals (dz/CPD are genuinely asymmetric), Metropolis–Hastings posterior sampling, and spectrum-resampling sensitivity.
• Tanaka adds a sensitivity that also jitters the band edges (band placement usually dominates the scatter) and a check_bands diagnostic reporting point counts, wavelengths, |k|d, and the bias in km. There's deliberately no profile on the Tanaka side — for a straight-line fit, profile and covariance intervals are provably identical.

Spectrum-layer correctness fixes

Several of these fixed real, depth-biasing bugs:

• Wavenumbers are rad/km everywhere (was cycles/km in places), with a guard that warns on a leftover cycles/km band.
• dk = 2π/(N·dx), the DFT fundamental — previously (N−1), which understated every depth by (N−1)/N.
• power selects the spectrum: power=2 (log power) for Bouligand, power=1 (log amplitude) for Tanaka. The pre-v2 power=0.5 was simply wrong — it halved every depth.
• radial_spectrum now uses rfft2 with Hermitian weighting instead of fft2, and bins with bincount instead of a mask per bin.
• remove_trend_linear uses a separable plane fit instead of an SVD (with a singleton-axis guard).
• Corrected wavenumber grid, exposed radial bin counts, and bounded dz below the cosh overflow.

Tanaka method, done properly

• Uses the amplitude spectrum (power=1), not the square root of it.
• Correct band weighting and real uncertainties.
• Bands have no defaults, deliberately — each straight-line limit only holds over part of the spectrum, and violating it still yields a confident-looking fit through the wrong part of the curve. check_bands is how you check.
• Removed the azimuthal spectrum.

Synthetics + recovery tests

• New fractal_anomaly(n, dx, beta, zt, dz, C, seed) filters white noise by the square root of the Bouligand model, so the expected spectrum is the model — a synthetic with a known Curie depth.
• New test_recovery.py asserts accuracy against those synthetics (accuracy claims deliberately don't rely on the narrow 305 km test_mag_data.txt fixture, which is too small to constrain long wavelengths). New test_bouligand.py and test_tanaka.py cover the two optimisers; test_grid.py was substantially expanded.

Parallelism robustness

• parallelise_routine no longer deadlocks when a worker dies — it NaN-fills and warns.
• Reserved on_error ("raise"/"ignore") and seed keywords; only @stochastic routines accept seed, so results don't depend on processor count.
• Detects spawn-unsafe closures (a taper/process_subgrid defined in a notebook or __main__) up front and falls back to serial with a warning instead of deadlocking on macOS/Windows.
• Honours max_processors.

Packaging / CI / docs (the part the description already covers)

• Dropped the Cython radon extension — v2 is pure Python, so there's no compiler/libgdal-at-build-time story; GDAL is an optional [geotiff] extra.
• GitHub Actions replaces Travis (tests.yml across Python 3.9–3.13, docs.yml → GitHub Pages, publish.yml → PyPI over OIDC trusted publishing).
• Sphinx + Furo docs, with the method narrative/math moved out of docstrings into hand-written theory pages; the notebooks are executed as tutorials at build time.
• Docker/Binder removed; the giant in-package Examples/data/test_mag_data.txt (~93k lines) and the in-package notebooks were removed from the shipped package.

Net effect on the library/tests/docs tree: ~5.4k insertions vs ~98k deletions — the large deletion is almost entirely the in-package data fixture and duplicated v1 notebooks.

_{🤖 Summary generated with Claude Code}