# simondelmas/hydrogr architecture

> Architecture diagram of the GitHub repository simondelmas/hydrogr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/simondelmas/hydrogr
- Repository: https://github.com/simondelmas/hydrogr

## Overview

##### Project type and purpose
- hydrogr is an open-source, multi-language hydrological modeling library.
- It combines a high-performance Rust core (implements GR1A, GR2M, GR4H, GR4J, GR5J, GR6J) with a Python wrapper to expose those models to Python users.
- It also includes example notebooks, sample datasets, automated tests, and CI pipelines to build, test, and publish Python wheels.

##### File structure
- Top-level:
- Cargo.toml / src/ → Rust library source (modules for each GR-model + library entry point)
- pyproject.toml / python/ → Python package source (hydrogr module, model_interface, input_data)
- data/ → sample CSV and pickle files for input data
- example/ → Jupyter notebooks demonstrating model usage and calibration
- python/test/ → pytest-based tests for both the Python wrapper and model outputs
- .github/ → GitHub Actions workflows for building & publishing (build_all.yml, build_and_publish_release.yml)
- Observations:
- The Rust code defines the core algorithms, compiled into a native library
- The Python layer wraps those algorithms via a FFI binding (likely via PyO3 or setuptools-rust)
- CI workflows build the Rust extension, run Python tests, and publish to PyPI
- Tests validate correctness of each model implementation and data input routines

##### README for additional insights
- Confirms it’s a Python package (PyPI), requires Python 3.7+
- Emphasizes the six GR models, inspired by the airGR R package
- Shows badges for build status, license, and downloads
- Points to example notebooks for usage and calibration

- Under Rust, list each src/*.rs module and show how lib.rs aggregates them
- Data input module reading files from data/ → feeding model inputs
- At the top or bottom, sketch the CI workflow steps in sequence, linking to GitHub and PyPI
- Every module and external dependency is represented and clearly labeled

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% External Services
  GH[("GitHub")]:::external
  PyPI[("PyPI")]:::external

  %% CI/CD Workflows
  subgraph "CI/CD Pipeline"
    direction TB
    WF1["build_all.yml"]:::ci
    WF2["build_and_publish_release.yml"]:::ci
    subgraph "Custom Actions"
      direction TB
      WFA["build_and_test/action.yml"]:::ci
      WFDir["build_and_test/"]:::ci
    end
  end

  GH --> WF1
  GH --> WF2
  WF1 --> WFA
  WFA -->|"runs tests"| WF2
  WF2 -->|"publish"| PyPI

  %% Rust Core Library
  subgraph "Rust Core Library"
    direction TB
    RC_Lib["lib.rs"]:::rust
    RC_GR1A["gr1a.rs"]:::rust
    RC_GR2M["gr2m.rs"]:::rust
    RC_GR4H["gr4h.rs"]:::rust
    RC_GR4J["gr4j.rs"]:::rust
    RC_GR5J["gr5j.rs"]:::rust
    RC_GR6J["gr6j.rs"]:::rust
    RC_Scurves["s_curves.rs"]:::rust
  end

  RC_Lib --> RC_GR1A
  RC_Lib --> RC_GR2M
  RC_Lib --> RC_GR4H
  RC_Lib --> RC_GR4J
  RC_Lib --> RC_GR5J
  RC_Lib --> RC_GR6J
  RC_Lib --> RC_Scurves

  %% Python Wrapper Package
  subgraph "Python Wrapper Package"
    direction TB
    PYProj["pyproject.toml"]:::python
    MI["model_interface.py"]:::python
    PY_GR1A["gr1a.py"]:::python
    PY_GR2M["gr2m.py"]:::python
    PY_GR4H["gr4h.py"]:::python
    PY_GR4J["gr4j.py"]:::python
    PY_GR5J["gr5j.py"]:::python
    PY_GR6J["gr6j.py"]:::python
  end

  PYProj --> MI
  MI --> PY_GR1A
  MI --> PY_GR2M
  MI --> PY_GR4H
  MI --> PY_GR4J
  MI --> PY_GR5J
  MI --> PY_GR6J

  %% Data Input Module
  subgraph "Data Input Module"
    direction TB
    InputMod["input_data.py"]:::python
    CSV1[(L0123001.csv)]:::data
    PCL1[(L0123001.pkl)]:::data
    CSV2[(L0123002.csv)]:::data
    CSV3[(L0123003.csv)]:::data
    PCL3[(L0123003.pkl)]:::data
  end

  InputMod --> CSV1
  InputMod --> PCL1
  InputMod --> CSV2
  InputMod --> CSV3
  InputMod --> PCL3

  %% Example Notebooks
  subgraph "Example Notebooks"
    direction TB
    NB1["gr1a.ipynb"]:::external
    NB2["gr4h.ipynb"]:::external
    NB3["gr4j.ipynb"]:::external
    NB4["gr6j.ipynb"]:::external
    NB5["calibrating_gr4j.ipynb"]:::external
  end

  NB1 --> MI
  NB2 --> MI
  NB3 --> MI
  NB4 --> MI
  NB5 --> MI

  %% Test Suite
  subgraph "Test Suite"
    direction TB
    TCft["conftest.py"]:::python
    T1["test_model_gr1a.py"]:::python
    T2["test_model_gr2m.py"]:::python
    T3["test_model_gr4h.py"]:::python
    T4["test_model_gr4j.py"]:::python
    T5["test_model_gr5j.py"]:::python
    T6["test_model_gr6j.py"]:::python
    TI["test_model_inputs.py"]:::python
  end

  TCft --> T1
  TCft --> T2
  TCft --> T3
  TCft --> T4
  TCft --> T5
  TCft --> T6
  TCft --> TI
  TCft --> MI

  %% FFI Boundary
  MI <-->|"calls via FFI"| RC_Lib

  InputMod -->|feeds| MI
  MI -->|returns results| InputMod

  %% Styles
  classDef rust fill:#f4a261,stroke:#000,stroke-width:1px;
  classDef python fill:#2a9d8f,stroke:#000,stroke-width:1px;
  classDef ci fill:#e9c46a,stroke:#000,stroke-width:1px;
  classDef data fill:#264653,stroke:#000,stroke-width:1px;
  classDef external fill:#8d99ae,stroke:#000,stroke-width:1px;

  %% Click Events
  click RC_Lib "https://github.com/simondelmas/hydrogr/blob/master/src/lib.rs"
  click RC_GR1A "https://github.com/simondelmas/hydrogr/blob/master/src/gr1a.rs"
  click RC_GR2M "https://github.com/simondelmas/hydrogr/blob/master/src/gr2m.rs"
  click RC_GR4H "https://github.com/simondelmas/hydrogr/blob/master/src/gr4h.rs"
  click RC_GR4J "https://github.com/simondelmas/hydrogr/blob/master/src/gr4j.rs"
  click RC_GR5J "https://github.com/simondelmas/hydrogr/blob/master/src/gr5j.rs"
  click RC_GR6J "https://github.com/simondelmas/hydrogr/blob/master/src/gr6j.rs"
  click RC_Scurves "https://github.com/simondelmas/hydrogr/blob/master/src/s_curves.rs"
  click PYProj "https://github.com/simondelmas/hydrogr/blob/master/pyproject.toml"
  click MI "https://github.com/simondelmas/hydrogr/blob/master/python/hydrogr/model_interface.py"
  click PY_GR1A "https://github.com/simondelmas/hydrogr/blob/master/python/hydrogr/gr1a.py"
  click PY_GR2M "https://github.com/simondelmas/hydrogr/blob/master/python/hydrogr/gr2m.py"
  click PY_GR4H "https://github.com/simondelmas/hydrogr/blob/master/python/hydrogr/gr4h.py"
  click PY_GR4J "https://github.com/simondelmas/hydrogr/blob/master/python/hydrogr/gr4j.py"
  click PY_GR5J "https://github.com/simondelmas/hydrogr/blob/master/python/hydrogr/gr5j.py"
  click PY_GR6J "https://github.com/simondelmas/hydrogr/blob/master/python/hydrogr/gr6j.py"
  click InputMod "https://github.com/simondelmas/hydrogr/blob/master/python/hydrogr/input_data.py"
  click CSV1 "https://github.com/simondelmas/hydrogr/blob/master/data/L0123001.csv"
  click PCL1 "https://github.com/simondelmas/hydrogr/blob/master/data/L0123001.pkl"
  click CSV2 "https://github.com/simondelmas/hydrogr/blob/master/data/L0123002.csv"
  click CSV3 "https://github.com/simondelmas/hydrogr/blob/master/data/L0123003.csv"
  click PCL3 "https://github.com/simondelmas/hydrogr/blob/master/data/L0123003.pkl"
  click NB1 "https://github.com/simondelmas/hydrogr/blob/master/example/gr1a.ipynb"
  click NB2 "https://github.com/simondelmas/hydrogr/blob/master/example/gr4h.ipynb"
  click NB3 "https://github.com/simondelmas/hydrogr/blob/master/example/gr4j.ipynb"
  click NB4 "https://github.com/simondelmas/hydrogr/blob/master/example/gr6j.ipynb"
  click NB5 "https://github.com/simondelmas/hydrogr/blob/master/example/calibrating_gr4j.ipynb"
  click TCft "https://github.com/simondelmas/hydrogr/blob/master/python/test/conftest.py"
  click T1 "https://github.com/simondelmas/hydrogr/blob/master/python/test/test_model_gr1a.py"
  click T2 "https://github.com/simondelmas/hydrogr/blob/master/python/test/test_model_gr2m.py"
  click T3 "https://github.com/simondelmas/hydrogr/blob/master/python/test/test_model_gr4h.py"
  click T4 "https://github.com/simondelmas/hydrogr/blob/master/python/test/test_model_gr4j.py"
  click T5 "https://github.com/simondelmas/hydrogr/blob/master/python/test/test_model_gr5j.py"
  click T6 "https://github.com/simondelmas/hydrogr/blob/master/python/test/test_model_gr6j.py"
  click TI "https://github.com/simondelmas/hydrogr/blob/master/python/test/test_model_inputs.py"
  click WF1 "https://github.com/simondelmas/hydrogr/blob/master/.github/workflows/build_all.yml"
  click WF2 "https://github.com/simondelmas/hydrogr/blob/master/.github/workflows/build_and_publish_release.yml"
  click WFA "https://github.com/simondelmas/hydrogr/blob/master/.github/actions/build_and_test/action.yml"
  click WFDir "https://github.com/simondelmas/hydrogr/tree/master/.github/actions/build_and_test/"
```
