codameter

An operational six-phase workflow for interpreting relative seismic velocity changes ($\delta v / v$) as stress and strain meters.

codameter implements the workflow of Denolle (in prep, JGR Solid Earth) as an executable Python pipeline. Given a $\delta v / v$ time series and the relevant environmental forcings (temperature, precipitation, earthquake catalog, etc.), the package extracts:

• depth-resolved stress estimates with propagated uncertainties,
• water-table-depth and saturation inversions (v0.2+),
• coupling-tier diagnostics that flag when linear superposition fails,
• anomaly classifications (tectonic, volcanic, hydrological, post-seismic, anthropogenic) for residual signal not explained by the physical model.

The repository is the operational counterpart to the manuscript-companion dvv-coupled repo (which generates the JGR figures); codameter is the tool that any group can apply to their own data.

Status — v0.1. Phases 0, 1, 2 (Tier 1 only), 3 (linear), 5 (anomaly), and 6 (β-bridge stress at depth) are operational. Phase 4 coupled MCMC and Tiers 2–4 are scheduled for v0.2 / v0.3.

Installation

# core install (numpy / scipy / pandas / matplotlib only)
pip install codameter

# with disba sensitivity kernels (Phase 1)
pip install "codameter[kernels]"

# everything — kernels, MCMC backend, dev tools
pip install "codameter[all]"

From source:

git clone https://github.com/Denolle-Lab/codameter.git
cd codameter
pip install -e ".[dev]"
pre-commit install
pytest

60-second quickstart

from codameter import run_workflow, load_site
from codameter.data import load_dvv, load_timeseries

site = load_site("examples/configs/parkfield.yaml")
dvv  = load_dvv("parkfield.parquet")        # DataFrame indexed by datetime
forc = {
    "temperature":   load_timeseries("T.csv"),
    "precipitation": load_timeseries("P.csv"),
}

result = run_workflow(dvv, forc, site)   # dvv, forcings, site (positional)

print(result.summary())            # text summary of all six phases
fig = result.plot_phases()         # six-panel diagnostic figure
result.export("runs/parkfield/")   # all artifacts to disk

Before fitting your own file, check what scientific interpretations your data can support:

codameter data-check --dvv parkfield.parquet \
                     --config examples/configs/parkfield.yaml \
                     --goal groundwater --goal stress --goal coupling \
                     --precip P.csv --temp T.csv

The same task from the command line:

codameter run --config examples/configs/parkfield.yaml \
                 --dvv parkfield.parquet \
                 --precip P.csv \
                 --temp T.csv \
                 --output runs/parkfield/

Validate a config before you run it (a fast pre-flight check that catches unknown forcing models, inverted date ranges, and unsupported options without executing the workflow):

codameter validate --config examples/configs/parkfield.yaml
# ✓ examples/configs/parkfield.yaml: valid. Site 'parkfield_hrsn',
#   active forcings: ['thermoelastic', 'hydrological', 'damage'].

For the phase-by-phase API and the low-level physics modules, see docs/quickstart.md and docs/workflow.md.

Apply to the Clements & Denolle (2023) California dataset

The repository ships with a config and an example notebook that run the workflow end-to-end on a station from the Clements & Denolle (2023) JGR dataset, available from Zenodo (DOI 10.5281/zenodo.6413275).

# 1. Download the C&D 2023 archive (4.4 GB) and unpack
mkdir -p data/clements_denolle_2023
cd data/clements_denolle_2023
curl -L -O https://zenodo.org/records/6413275/files/data-0.2.0.zip
unzip data-0.2.0.zip
cd ../..

# 2. Run the example (real-data mode)
python examples/02_clements_denolle_2023.py \
    --station  CI.LJR \
    --data-dir data/clements_denolle_2023 \
    --config   examples/configs/clements_denolle_2023_LJR.yaml \
    --output   runs/CI.LJR/

Without --data-dir, the same script runs in synthetic mode end-to-end in <30 s (no download required):

python examples/02_clements_denolle_2023.py --output runs/cd2023_synthetic/

The loader in codameter.data.loaders.load_clements_denolle_2023() reads the Arrow / Feather output of the upstream Julia pipeline (03-dvv-comp.jl) and converts it to the standard codameter format.

The six phases

Choosing dv/v processing parameters

Before the six-phase interpretation, you have to measure $\delta v/v$, and that measurement depends on a chain of processing choices (estimator, frequency band, coda window, reference, stacking). codameter.use_cases maps a monitoring use case (volcano, earthquake/fault, landslide, groundwater, cryosphere, geothermal) to a recommended, runnable choice set distilled from the 103-study survey in literature/best_practices.md:

from codameter import use_cases as uc, golden
from codameter.deviations import run_pipeline

cfg = uc.recommend("landslide")        # {'estimator': 'stretching (TS)', 'band': (4.0, 12.0), ...}
d = golden.generate(golden.MAINSTREAM_BY_USE_CASE["landslide"])
dvv, valid = run_pipeline(d["ccfs"], d["t"], d["fs"], cfg, eps_max=uc.eps_max("landslide"))

The codameter-advisor skill (.claude/skills/codameter-advisor/) wraps this in a conversation: it elicits your use case, recommends a config, then proves the recommendation by running the synthetic engine live and quantifying the bias and error-bar cost of your choices against a known ground truth.

The golden datasets (tests/data/golden/, generated by codameter.golden) are seeded synthetic CCF suites covering the mainstream per-application cases and four edge regimes (low SNR + large dv/v, clock drift + seasonal coda noise, frequency-dependent shallow+deep media, sparse cadence + decorrelation). They are both a pytest regression oracle and the advisor's validation corpus. Regenerate with pixi run golden.

The same golden cases are exposed as a FrugalMind benchmark via codameter.frugalmind, with two suites: param_recommendation (the agent returns a processing config; scored by running it and grading dv/v recovery) and dvv_series (the agent returns the recovered dv/v(t); scored by regression against the known truth). Export the JSONL with pixi run frugalmind-export; the drop-in FrugalMind suite lives in integrations/frugalmind/.

Scaling the sweep (Fargate / AWS Batch)

codameter-bench scores a grid of processing configs against every golden case and records recovery RMS. The work is deterministic and embarrassingly parallel, so it shards cleanly across an array of tasks:

codameter-bench plan  --grid multiverse --shard 0/64      # size the job (no compute)
codameter-bench sweep --grid multiverse --shard 0/64 --jobs 4 --out s3://bucket/run/
codameter-bench aggregate --src s3://bucket/run/ --out s3://bucket/run/agg/

Each task writes one shard-<k>-of-<N>.jsonl, so retries are idempotent and no coordination is needed. On AWS Batch the shard is read from AWS_BATCH_JOB_ARRAY_INDEX + CODAMETER_SHARDS, so one image runs every array task. Container image and a Batch job definition are in docker/; s3:// output needs the aws extra (pip install "codameter[aws]").

Models, hyperparameters, and physical bounds

Where to find them in the code

Hydrological forward models

Thermoelastic forward model

Surface-loading forward models

Material-property priors (MaterialProperties)

All priors are Gaussian N(mean, std) and are defined in src/codameter/config.py. In v0.1 (WLS) they are not used in the inversion — they feed the Phase 6 uncertainty-propagation step. In v0.2+ (MCMC) they act as proper prior distributions.

Physical bound validation is implemented in src/codameter/inverse/priors.py::validate_priors.

Hard physical sign-constraints on regression coefficients

Defined as _PHYSICAL_PARAM_BOUNDS in src/codameter/workflow.py and enforced via bounded-variable least squares (scipy.optimize.lsq_linear, method "bvls") in Phase 4.

When a parameter is clamped at its bound, its posterior standard deviation is reported as 0.0 (parameter is not free). To add or modify bounds, edit the _PHYSICAL_PARAM_BOUNDS dict in src/codameter/workflow.py.

Citing

If you use codameter in published work, please cite both the framework paper and the software:

@article{Denolle2026,
  author = {Denolle, M. A.},
  title  = {{Relative seismic velocity changes as coupled stress and strain meters: a unified framework}},
  journal = {Journal of Geophysical Research: Solid Earth},
  year   = {2026},
  note   = {in prep}
}

@software{codameter,
  author = {Denolle, M. A. and the GAIA HazLab},
  title  = {codameter: An operational pipeline for interpreting seismic velocity changes},
  year   = {2026},
  doi    = {10.5281/zenodo.XXXXXXX},
  url    = {https://github.com/Denolle-Lab/codameter}
}

A CITATION.cff is provided in the repo root.

License

MIT — see LICENSE.

Acknowledgements

This package builds directly on the open-source ecosystem of the seismology community: disba (Luu, 2021) for surface-wave eigenmodes, emcee (Foreman-Mackey et al., 2013) for MCMC, xarray, pandas, pyarrow, numpy, and scipy. The empirical models implemented here are due to Berger (1975), Roeloffs (1988), Talwani et al. (2007), Snieder et al. (2017), Fokker et al. (2021), Okubo et al. (2024), Clements & Denolle (2023), Ermert et al. (2023), Tromp & Trampert (2018), and Shi et al. (2026), among others.