# hrithik-v/phyre-mamba architecture

> Architecture diagram of the GitHub repository hrithik-v/phyre-mamba, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hrithik-v/phyre-mamba
- Repository: https://github.com/hrithik-v/phyre-mamba

## Overview

1. **What this repo is**
   - PhyRe-Mamba is a training/inference codebase for **underwater image restoration**.
   - The core pipeline is: **UIEB-style dataset → physics feature augmentation → PhyRe-Mamba model → flow-matching training → checkpointed evaluation**.

2. **Main entry points**
   - `train.py` is the primary orchestration script for full training.
   - `overfit_test.py` is a small-sample sanity check to verify the pipeline can learn.
   - `verify_arch.py` checks that the model can be instantiated and run a forward pass.
   - `test.py` is the separate testing/inference entry point.

3. **Configuration boundary**
   - `config.yaml` is the central control plane for dataset paths, image size, batch size, learning rate, epochs, validation frequency, and checkpoint location.
   - `src/utils/config.py` loads that YAML into the runtime scripts, so the architecture is largely **config-driven** rather than hardcoded.

4. **Data subsystem**
   - `src/data/dataset.py` defines the UIEB dataset handling and train/validation split.
   - The dataset expects paired **input/target** underwater images laid out under the configured dataset root.
   - This layer is the boundary between raw filesystem data and model-ready tensors.

5. **Physics-guided feature generation**
   - `src/data/physics.py` adds domain features such as **dark channel prior, transmission, and depth**.
   - These are important because the model is not purely image-to-image; it injects physical underwater priors as additional guidance channels/features.

6. **Model architecture**
   - `src/model/phyre_mamba.py` is the top-level PhyRe-Mamba network definition.
   - `src/model/encoder.py` provides the CNN encoder.
   - `src/model/blocks.py` contains the Mamba-based state-space block wrapper (`VSSBlock`).
   - `src/model/decoder.py` implements the decoder, described in the README as a **cross-latent decoder**.
   - Overall, the model combines **local convolutional encoding** with **global sequence/state-space modeling** and a reconstruction decoder.

7. **Training objective**
   - `src/train/loss.py` defines the losses used for learning.
   - The README indicates a combination of **Flow Matching / rectified flow** and **perceptual loss**.
   - This means the training signal is not just pixel regression; it is shaped to support smooth restoration dynamics and perceptual fidelity.

8. **Training loop responsibilities**
   - `src/train/trainer.py` is the central runtime controller for epoch/batch iteration.
   - It handles logging of **loss, PSNR, and validation MSE/PSNR**, performs validation at `val_freq`, and manages checkpointing.
   - It also saves the best model and periodic checkpoints, so the trainer is both the optimization engine and the experiment manager.

9. **Metrics and artifacts**
   - The repo treats **PSNR** as the main quality metric during training and validation, with **MSE** used for validation selection.
   - Checkpoints are written to the configured `save_dir` (default `./checkpoints`), with a best-model file and periodic snapshots.
   - This creates a clear artifact boundary between ephemeral training state and persisted models.

10. **Runtime and infrastructure assumptions**
   - The project depends on CUDA-capable builds of **`mamba-ssm`** and **`causal-conv1d`**, so GPU support is material to the architecture.
   - Training can use multiple GPUs through **PyTorch `DataParallel`** when available.
   - The repo is therefore organized around a **GPU-backed research training workflow**, not a deployment service.

11. **How the pieces connect**
   - In a typical run, a script reads `config.yaml`, constructs the dataset, augments inputs with physics features, builds the PhyRe-Mamba model, and hands everything to the trainer.
   - The trainer computes the flow-based loss, logs metrics, validates periodically, and writes checkpoints.
   - The overfit and verify scripts provide lightweight preflight checks before full-scale training.

12. **Useful architecture diagram boundaries**
   - Draw four major boxes: **Configuration**, **Data/Physics preprocessing**, **Model**, and **Training/Evaluation**.
   - Show the data flow from dataset files into physics-guided tensors, then into the encoder/Mamba/decoder stack, then into loss/metrics/checkpoints.
   - Treat `train.py`, `overfit_test.py`, `verify_arch.py`, and `test.py` as orchestration entry points around the same core components.

Main entry points: [`src/train/trainer.py`](https://github.com/hrithik-v/phyre-mamba/blob/main/src/train/trainer.py) (Trainer), [`src/model/phyre_mamba.py`](https://github.com/hrithik-v/phyre-mamba/blob/main/src/model/phyre_mamba.py) (PhyRe-Mamba), [`src/utils/config.py`](https://github.com/hrithik-v/phyre-mamba/blob/main/src/utils/config.py) (Config load), [`src/model/blocks.py`](https://github.com/hrithik-v/phyre-mamba/blob/main/src/model/blocks.py) (VSS block)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cfg["Configuration"]
  node_config_yaml["config.yaml<br/>yaml config<br/>[config.yaml]"]
  node_config_loader["Config load<br/>runtime config<br/>[config.py]"]
end

subgraph group_data["Data and Physics"]
  node_dataset[("UIEB dataset<br/>paired dataset<br/>[dataset.py]")]
  node_physics["Physics feats<br/>feature aug<br/>[physics.py]"]
end

subgraph group_model["Model"]
  node_phyre_mamba["PhyRe-Mamba<br/>restoration model<br/>[phyre_mamba.py]"]
  node_encoder["Encoder<br/>[encoder.py]"]
  node_blocks{{"VSS block<br/>mamba block<br/>[blocks.py]"}}
  node_decoder["Cross-latent decoder<br/>reconstruction decoder<br/>[decoder.py]"]
end

subgraph group_train["Training and Evaluation"]
  node_entry_train["train.py<br/>training entry<br/>[train.py]"]
  node_entry_overfit["overfit_test.py<br/>sanity entry<br/>[overfit_test.py]"]
  node_entry_verify["verify_arch.py<br/>verify entry<br/>[verify_arch.py]"]
  node_entry_test["test.py<br/>inference entry<br/>[test.py]"]
  node_trainer["Trainer<br/>runtime controller<br/>[trainer.py]"]
  node_loss["Flow loss<br/>training loss<br/>[loss.py]"]
  node_metrics(("PSNR / MSE<br/>metrics"))
  node_checkpoints[("Checkpoints<br/>artifacts")]
  node_gpu_stack{{"CUDA Mamba<br/>runtime deps"}}
end

node_config_yaml -->|"loaded by"| node_config_loader
node_config_loader -->|"dataset paths"| node_dataset
node_config_loader -->|"train params"| node_trainer
node_config_loader -->|"model params"| node_phyre_mamba
node_dataset -->|"augmented by"| node_physics
node_physics -->|"feature input"| node_phyre_mamba
node_phyre_mamba -->|"encode"| node_encoder
node_encoder -->|"mix"| node_blocks
node_blocks -->|"decode"| node_decoder
node_trainer -->|"optimizes"| node_loss
node_trainer -->|"logs"| node_metrics
node_trainer -->|"writes"| node_checkpoints
node_entry_train -->|"runs"| node_trainer
node_entry_overfit -->|"sanity run"| node_trainer
node_entry_test -->|"inference"| node_phyre_mamba
node_entry_verify -->|"forward pass"| node_phyre_mamba
node_gpu_stack -.->|"accelerates"| node_blocks
node_gpu_stack -.->|"parallelism"| node_trainer

click node_config_yaml "https://github.com/hrithik-v/phyre-mamba/blob/main/config.yaml"
click node_config_loader "https://github.com/hrithik-v/phyre-mamba/blob/main/src/utils/config.py"
click node_dataset "https://github.com/hrithik-v/phyre-mamba/blob/main/src/data/dataset.py"
click node_physics "https://github.com/hrithik-v/phyre-mamba/blob/main/src/data/physics.py"
click node_entry_train "https://github.com/hrithik-v/phyre-mamba/blob/main/train.py"
click node_entry_overfit "https://github.com/hrithik-v/phyre-mamba/blob/main/overfit_test.py"
click node_entry_verify "https://github.com/hrithik-v/phyre-mamba/blob/main/verify_arch.py"
click node_entry_test "https://github.com/hrithik-v/phyre-mamba/blob/main/test.py"
click node_phyre_mamba "https://github.com/hrithik-v/phyre-mamba/blob/main/src/model/phyre_mamba.py"
click node_encoder "https://github.com/hrithik-v/phyre-mamba/blob/main/src/model/encoder.py"
click node_blocks "https://github.com/hrithik-v/phyre-mamba/blob/main/src/model/blocks.py"
click node_decoder "https://github.com/hrithik-v/phyre-mamba/blob/main/src/model/decoder.py"
click node_trainer "https://github.com/hrithik-v/phyre-mamba/blob/main/src/train/trainer.py"
click node_loss "https://github.com/hrithik-v/phyre-mamba/blob/main/src/train/loss.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_config_yaml,node_config_loader toneBlue
class node_dataset,node_physics toneAmber
class node_phyre_mamba,node_encoder,node_blocks,node_decoder toneMint
class node_entry_train,node_entry_overfit,node_entry_verify,node_entry_test,node_trainer,node_loss,node_metrics,node_checkpoints,node_gpu_stack toneRose
```

## Components

### Configuration

Central runtime settings and config loading.

- [config.yaml](https://github.com/hrithik-v/phyre-mamba/blob/main/config.yaml): yaml config · Central control plane for dataset, training, and checkpoint settings. · `config.yaml`
- [Config load](https://github.com/hrithik-v/phyre-mamba/blob/main/src/utils/config.py): runtime config · Loads YAML settings into the training and inference scripts. · `src/utils/config.py`

### Data and Physics

Dataset loading plus physics-guided feature augmentation.

- [UIEB dataset](https://github.com/hrithik-v/phyre-mamba/blob/main/src/data/dataset.py): paired dataset · Reads paired underwater input/target images and handles train/validation split. · `src/data/dataset.py`
- [Physics feats](https://github.com/hrithik-v/phyre-mamba/blob/main/src/data/physics.py): feature aug · Adds domain priors such as dark channel prior, transmission, and depth. · `src/data/physics.py`

### Model

PhyRe-Mamba network stack.

- [PhyRe-Mamba](https://github.com/hrithik-v/phyre-mamba/blob/main/src/model/phyre_mamba.py): restoration model · Top-level underwater image restoration network. · `src/model/phyre_mamba.py`
- [Encoder](https://github.com/hrithik-v/phyre-mamba/blob/main/src/model/encoder.py): cnn encoder · Convolutional feature extractor for local image structure. · `src/model/encoder.py`
- [VSS block](https://github.com/hrithik-v/phyre-mamba/blob/main/src/model/blocks.py): mamba block · Mamba-based state-space block wrapper for sequence modeling. · `src/model/blocks.py`
- [Cross-latent decoder](https://github.com/hrithik-v/phyre-mamba/blob/main/src/model/decoder.py): reconstruction decoder · Decodes latent features back into restored imagery. · `src/model/decoder.py`

### Training and Evaluation

Optimization, metrics, checkpointing, and entry points.

- [train.py](https://github.com/hrithik-v/phyre-mamba/blob/main/train.py): training entry · Primary orchestration script for full training runs. · `train.py`
- [overfit_test.py](https://github.com/hrithik-v/phyre-mamba/blob/main/overfit_test.py): sanity entry · Small-sample overfit check for pipeline and learning sanity. · `overfit_test.py`
- [verify_arch.py](https://github.com/hrithik-v/phyre-mamba/blob/main/verify_arch.py): verify entry · Instantiates the model and runs a forward-pass check. · `verify_arch.py`
- [test.py](https://github.com/hrithik-v/phyre-mamba/blob/main/test.py): inference entry · Separate testing and inference entry point. · `test.py`
- [Trainer](https://github.com/hrithik-v/phyre-mamba/blob/main/src/train/trainer.py): runtime controller · Coordinates epochs, validation, logging, and checkpointing. · `src/train/trainer.py`
- [Flow loss](https://github.com/hrithik-v/phyre-mamba/blob/main/src/train/loss.py): training loss · Combines flow-matching / rectified-flow objective with perceptual loss. · `src/train/loss.py`
- **PSNR / MSE**: metrics · Tracks training quality and validation selection signals.
- **Checkpoints**: artifacts · Best model and periodic snapshots saved under the configured directory.
- **CUDA Mamba**: runtime deps · GPU-backed dependencies for mamba-ssm and causal-conv1d, with optional multi-GPU DataParallel.

## Connections

- config.yaml → Config load: loaded by · YAML settings are parsed into runtime configuration objects.
- Config load → UIEB dataset: dataset paths · Configuration supplies dataset root, split, and image sizing.
- Config load → Trainer: train params · Configuration drives batch size, learning rate, epochs, validation frequency, and save directory.
- Config load → PhyRe-Mamba: model params · Configuration influences model construction and runtime choices.
- UIEB dataset → Physics feats: augmented by · Loaded paired images are enriched with underwater physics features.
- Physics feats → PhyRe-Mamba: feature input · Physics-guided channels are fed into the restoration model.
- PhyRe-Mamba → Encoder: encode · The model begins with convolutional feature extraction.
- Encoder → VSS block: mix · Encoded features are processed by Mamba-based state-space blocks.
- VSS block → Cross-latent decoder: decode · Latent features are reconstructed through the decoder stack.
- Trainer → Flow loss: optimizes · Trainer computes the flow-based training objective.
- Trainer → PSNR / MSE: logs · Trainer tracks PSNR and validation MSE/PSNR.
- Trainer → Checkpoints: writes · Trainer persists best and periodic checkpoints.
- train.py → Trainer: runs · Main training script launches the full training controller.
- overfit_test.py → Trainer: sanity run · Overfit test uses the same core training path on a small sample.
- test.py → PhyRe-Mamba: inference · Testing uses the trained model for restoration inference.
- verify_arch.py → PhyRe-Mamba: forward pass · Architecture verification instantiates and exercises the model.
- CUDA Mamba → VSS block: accelerates · The Mamba blocks rely on CUDA-capable dependencies.
- CUDA Mamba → Trainer: parallelism · Training can use multi-GPU DataParallel when available.
