# dabdul-wahab1988/hydrosheaf architecture

> Architecture diagram of the GitHub repository dabdul-wahab1988/hydrosheaf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dabdul-wahab1988/hydrosheaf
- Repository: https://github.com/dabdul-wahab1988/hydrosheaf

## Overview

Hydrosheaf is a groundwater-inference framework: users provide hydrochemical, isotope/tracer, and site/network data, then obtain fitted edge-level transport and reaction results plus diagnostics. Its documented workflow combines data handling, graph construction, chemical inference, topology and assumption auditing, and result export. The README also describes age, temporal, 3D, calibration, and measurement-planning capabilities, shown as distinct branches. Sampled source excerpts do not include the API implementation, so detailed internal call ownership is uncertain; the connections below reflect documented workflow roles rather than verified calls.

Main entry points: [`hydrosheaf/inference/network_fit.py`](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/inference/network_fit.py) (Network fitting), [`hydrosheaf/api.py`](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/api.py) (Network pipeline), [`hydrosheaf/graph/build.py`](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/graph/build.py) (Candidate graph), [`hydrosheaf/calibration/active_learning.py`](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/calibration/active_learning.py) (Active learning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Inference workflow"]
  node_api["Network pipeline<br/>[api.py]"]
  node_config["Inference config<br/>[config.py]"]
  node_data["Data parsing and QC<br/>[parsing.py]"]
  node_graphbuild["Candidate graph<br/>[build.py]"]
  node_networkfit["Network fitting<br/>[network_fit.py]"]
  node_results["Result export<br/>[export.py]"]
end

subgraph group_chemistry["Chemistry and reactions"]
  node_transport["Transport models<br/>[mixing.py]"]
  node_reactions["Reaction inference<br/>[reactions.py]"]
  node_thermo["PHREEQC constraints<br/>[constraints.py]"]
  node_isotopes["Isotope analysis<br/>[isotopes.py]"]
end

subgraph group_network["Network evidence"]
  node_nulls["Null-model screening<br/>[chemistry.py]"]
  node_head["Head inference<br/>[head_inference.py]"]
  node_sheaf["Sheaf refinement<br/>[topology_refine.py]"]
  node_posterior["Topology posterior"]
end

subgraph group_ages["Tracer and time"]
  node_nuclear["Nuclear tracer ages<br/>[joint_lpm.py]"]
  node_temporal["Residence-time analysis<br/>[residence_time.py]"]
  node_three_d["3D flow networks<br/>[build_3d.py]"]
end

subgraph group_extensions["Analysis extensions"]
  node_active["Active learning<br/>[active_learning.py]"]
  node_calibration["Model calibration"]
  node_uncertainty["Uncertainty analysis<br/>[bayesian.py]"]
  node_validation["Benchmark validation"]
end

node_user(("Groundwater analyst"))

node_user -->|"submits inputs"| node_api
node_user -->|"sets options"| node_config
node_api -->|"accepts samples"| node_data
node_api -->|"runs pipeline"| node_graphbuild
node_api -->|"fits network"| node_networkfit
node_networkfit -->|"produces results"| node_results
node_graphbuild -->|"supplies candidates"| node_networkfit
node_networkfit -->|"fits transport"| node_transport
node_networkfit -->|"fits reactions"| node_reactions
node_networkfit -.->|"applies constraints"| node_thermo
node_networkfit -.->|"uses isotope evidence"| node_isotopes
node_networkfit -.->|"uses head evidence"| node_head
node_networkfit -.->|"screens alternatives"| node_nulls
node_networkfit -.->|"refines topology"| node_sheaf
node_networkfit -.->|"estimates topology"| node_posterior
node_networkfit -.->|"uses tracer ages"| node_nuclear
node_networkfit -.->|"estimates residence time"| node_temporal
node_networkfit -.->|"supports 3D analysis"| node_three_d
node_networkfit -.->|"quantifies uncertainty"| node_uncertainty
node_active -.->|"guides measurements"| node_networkfit
node_calibration -.->|"calibrates models"| node_networkfit
node_validation -.->|"benchmarks inference"| node_networkfit

click node_api "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/api.py"
click node_config "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/config.py"
click node_data "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/data/parsing.py"
click node_graphbuild "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/graph/build.py"
click node_networkfit "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/inference/network_fit.py"
click node_results "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/outputs/export.py"
click node_transport "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/models/mixing.py"
click node_reactions "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/models/reactions.py"
click node_thermo "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/phreeqc/constraints.py"
click node_isotopes "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/isotopes.py"
click node_nulls "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/null_models/chemistry.py"
click node_head "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/graph/head_inference.py"
click node_sheaf "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/sheaf/topology_refine.py"
click node_posterior "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/inference/topology_posterior.py"
click node_nuclear "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/nuclear/joint_lpm.py"
click node_temporal "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/temporal/residence_time.py"
click node_three_d "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/graph3d/build_3d.py"
click node_active "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/calibration/active_learning.py"
click node_calibration "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/calibration/validation_workflow.py"
click node_uncertainty "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/uncertainty/bayesian.py"
click node_validation "https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/validation/integrated_benchmark.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_config,node_data,node_graphbuild,node_networkfit,node_results toneBlue
class node_transport,node_reactions,node_thermo,node_isotopes toneAmber
class node_nulls,node_head,node_sheaf,node_posterior toneMint
class node_nuclear,node_temporal,node_three_d toneRose
class node_active,node_calibration,node_uncertainty,node_validation,node_user toneIndigo
```

## Components

### Inference workflow

- [Network pipeline](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/api.py): `hydrosheaf/api.py`
- [Inference config](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/config.py): `hydrosheaf/config.py`
- [Data parsing and QC](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/data/parsing.py): `hydrosheaf/data/parsing.py`
- [Candidate graph](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/graph/build.py): `hydrosheaf/graph/build.py`
- [Network fitting](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/inference/network_fit.py): `hydrosheaf/inference/network_fit.py`
- [Result export](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/outputs/export.py): `hydrosheaf/outputs/export.py`

### Chemistry and reactions

- [Transport models](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/models/mixing.py): `hydrosheaf/models/mixing.py`
- [Reaction inference](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/models/reactions.py): `hydrosheaf/models/reactions.py`
- [PHREEQC constraints](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/phreeqc/constraints.py): `hydrosheaf/phreeqc/constraints.py`
- [Isotope analysis](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/isotopes.py): `hydrosheaf/isotopes.py`

### Network evidence

- [Null-model screening](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/null_models/chemistry.py): `hydrosheaf/null_models/chemistry.py`
- [Head inference](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/graph/head_inference.py): `hydrosheaf/graph/head_inference.py`
- [Sheaf refinement](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/sheaf/topology_refine.py): `hydrosheaf/sheaf/topology_refine.py`
- [Topology posterior](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/inference/topology_posterior.py): `hydrosheaf/inference/topology_posterior.py`

### Tracer and time

- [Nuclear tracer ages](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/nuclear/joint_lpm.py): `hydrosheaf/nuclear/joint_lpm.py`
- [Residence-time analysis](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/temporal/residence_time.py): `hydrosheaf/temporal/residence_time.py`
- [3D flow networks](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/graph3d/build_3d.py): `hydrosheaf/graph3d/build_3d.py`

### Analysis extensions

- [Active learning](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/calibration/active_learning.py): `hydrosheaf/calibration/active_learning.py`
- [Model calibration](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/calibration/validation_workflow.py): `hydrosheaf/calibration/validation_workflow.py`
- [Uncertainty analysis](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/uncertainty/bayesian.py): `hydrosheaf/uncertainty/bayesian.py`
- [Benchmark validation](https://github.com/dabdul-wahab1988/hydrosheaf/blob/main/hydrosheaf/validation/integrated_benchmark.py): `hydrosheaf/validation/integrated_benchmark.py`

### Other components

- **Groundwater analyst**

## Connections

- Groundwater analyst → Network pipeline: submits inputs
- Groundwater analyst → Inference config: sets options
- Network pipeline → Data parsing and QC: accepts samples
- Network pipeline → Candidate graph: runs pipeline
- Network pipeline → Network fitting: fits network
- Network fitting → Result export: produces results
- Candidate graph → Network fitting: supplies candidates
- Network fitting → Transport models: fits transport
- Network fitting → Reaction inference: fits reactions
- Network fitting → PHREEQC constraints: applies constraints
- Network fitting → Isotope analysis: uses isotope evidence
- Network fitting → Head inference: uses head evidence
- Network fitting → Null-model screening: screens alternatives
- Network fitting → Sheaf refinement: refines topology
- Network fitting → Topology posterior: estimates topology
- Network fitting → Nuclear tracer ages: uses tracer ages
- Network fitting → Residence-time analysis: estimates residence time
- Network fitting → 3D flow networks: supports 3D analysis
- Network fitting → Uncertainty analysis: quantifies uncertainty
- Active learning → Network fitting: guides measurements
- Model calibration → Network fitting: calibrates models
- Benchmark validation → Network fitting: benchmarks inference