PyAges Documentation

PyAges is a groundwater age-dating toolkit built around environmental tracers, lumped-parameter models (LPMs), convolution, and calibration workflows.

The documentation is organized by audience: start with the user guide to run PyAges and use the scientific and architecture pages to understand its contracts. Scientific reports and archived notes remain available for traceability but are separated from task-oriented instructions because they are not user guides.

Contributors should start with the developer quickstart and then use the code tour to locate a focused implementation and test surface.

PyAges 2.0 provides a multi-chain MH qualification workflow with maintained synthetic, single-date, prior-active, and temporal profiles.

Quality and validation

• Scientific validation explains the qualification layers, executable evidence, reported results, and limits of interpretation.

• Testing maps each test family to its purpose, CI scope, evidence, and limitations.

• Generated test inventory lists every collected module with its type, short purpose, and case counts.

• Continuous integration documents workflow triggers, jobs, permissions, artifacts, schedules, and failure semantics.

For a local build:

python -m pip install --upgrade -r install/bootstrap-constraints.txt
python -m pip install -c install/constraints.txt -e ".[docs]"
python -m sphinx -b html docs docs/_build/html

Getting Started

• Overview
  • Choose a starting point
  • Project status
• User Guide
  • First inspectable run
  • Getting started
  • Running Examples
  • Configuration Reference
  • Migrating from PyAges 1.2 to 2.0
  • Concentration observations
  • Direct convolution
  • Calibrating an LPM
  • Running and qualifying multi-chain MH
  • CLI flags reference
  • Adding a New LPM
  • Adding a New Tracer

Concepts and Architecture

• Scientific overview
  • Forward model
  • Scientific inputs
  • Inference
  • Scientific assurance
  • Scientific reference
• Scientific and numerical conventions
  • Forward model and units
  • Continuous convolution
  • Inverse-Gaussian convention
  • Objective and likelihood conventions
  • Metropolis-Hastings target and sampling
  • Traceability matrix
• Figure 1 — PyAges scientific workflow (overview)
• Architecture
  • Core responsibilities
  • Execution flow
  • Package map
  • Extension points
  • Boundaries that must remain stable
  • Package dependency diagram
  • Runtime diagram
  • Workflow source layout

Examples and Reference

• Examples
  • Synthetic parameter-recovery example
  • Ploemeur F09 2010 multi-chain qualification
  • Ploemeur ig_shifted prior-active multi-chain qualification
  • Ploemeur temporal multi-chain qualification
  • Albuquerque field example
  • Holten
• Site Studies
  • Ploemeur
• Operational Reference
  • Install
  • Result files and provenance
  • Data Provenance and Redistribution
  • Workflow outputs and result manifests
  • Public API and compatibility
  • Citing PyAges
  • Release notes
  • Scripts
• Selected API reference
  • Core packages
  • I/O, CLI, and workflows
  • Administrative staged-result API

Development

• Developer Documentation