# syeddaniyalg/blissnet-era5-inference architecture

> Architecture diagram of the GitHub repository syeddaniyalg/blissnet-era5-inference, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/syeddaniyalg/blissnet-era5-inference
- Repository: https://github.com/syeddaniyalg/blissnet-era5-inference

## Overview

This repository implements BLISSNet to reconstruct ERA5 temperature fields, progressing from data preparation through two-stage training to cross-region inference. The model’s internal stages include a coordinate-based SIREN trunk, a full-grid coefficient branch, and a sparse-sensor branch. The README documents the notebook workflows and evaluation; notebook source was not sampled, so those connections are based on its explicit descriptions rather than inspected calls.

Main entry points: [`blissnet/blissnet.py`](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py) (BLISSNet orchestration), [`training.ipynb`](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/training.ipynb) (Stage 1 training), [`inference.ipynb`](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/inference.ipynb) (Cross-region evaluation), [`datasets`](https://github.com/syeddaniyalg/blissnet-era5-inference/tree/main/datasets) (Regional NetCDF)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_prep["Prepare data"]
  node_prepared[("Regional NetCDF")]
end

subgraph group_architecture["BLISSNet model"]
  node_blissnet["BLISSNet orchestration<br/>[blissnet.py]"]
  node_trunk["SIREN trunk<br/>[blissnet.py]"]
  node_branch1["Full-grid branch<br/>[blissnet.py]"]
  node_unet["Attention U-Net<br/>[blissnet.py]"]
  node_branch2["Sparse-sensor branch<br/>[blissnet.py]"]
  node_sensor_encoder["Sensor transformer<br/>[blissnet.py]"]
  node_cross_attention["Cross-attention<br/>[blissnet.py]"]
  node_pool["Attention pool<br/>[blissnet.py]"]
  node_decoder["Coefficient decoder<br/>[blissnet.py]"]
end

subgraph group_training["Model training"]
  node_stage1["Stage 1 training<br/>[training.ipynb]"]
  node_stage2["Stage 2 training<br/>[training.ipynb]"]
  node_weights[("Model checkpoints")]
end

subgraph group_evaluation["Inference evaluation"]
  node_inference["Cross-region evaluation<br/>[inference.ipynb]"]
  node_outputs[("Evaluation outputs")]
end

node_operator(("Researcher"))
node_era5[("Raw ERA5 data")]

node_operator -->|"prepares data"| node_prep
node_era5 -->|"provides GRIB"| node_prep
node_prep -->|"exports NetCDF"| node_prepared
node_operator -->|"starts training"| node_stage1
node_prepared -->|"trains on grids"| node_stage1
node_stage1 -->|"trains model"| node_blissnet
node_blissnet -->|"evaluates basis"| node_trunk
node_blissnet -->|"routes full grids"| node_branch1
node_branch1 -->|"extracts features"| node_unet
node_operator -->|"starts training"| node_stage2
node_stage1 -->|"freezes components"| node_stage2
node_stage2 -->|"trains sparse path"| node_blissnet
node_blissnet -->|"routes sensors"| node_branch2
node_branch2 -->|"encodes sensors"| node_sensor_encoder
node_branch2 -->|"attends to latents"| node_cross_attention
node_branch2 -->|"pools features"| node_pool
node_branch2 -->|"decodes coefficients"| node_decoder
node_stage1 -->|"saves checkpoints"| node_weights
node_stage2 -->|"saves checkpoints"| node_weights
node_operator -->|"runs evaluation"| node_inference
node_weights -->|"loads checkpoints"| node_inference
node_prepared -->|"supplies test data"| node_inference
node_inference -->|"evaluates model"| node_blissnet
node_inference -->|"records metrics"| node_outputs

click node_prep "https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/dataset_and_visualization.ipynb"
click node_prepared "https://github.com/syeddaniyalg/blissnet-era5-inference/tree/main/datasets"
click node_blissnet "https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py"
click node_trunk "https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py"
click node_branch1 "https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py"
click node_unet "https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py"
click node_branch2 "https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py"
click node_sensor_encoder "https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py"
click node_cross_attention "https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py"
click node_pool "https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py"
click node_decoder "https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py"
click node_stage1 "https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/training.ipynb"
click node_stage2 "https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/training.ipynb"
click node_inference "https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/inference.ipynb"

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_prep,node_prepared toneBlue
class node_blissnet,node_trunk,node_branch1,node_unet,node_branch2,node_sensor_encoder,node_cross_attention,node_pool,node_decoder,node_era5 toneAmber
class node_stage1,node_stage2,node_weights toneMint
class node_inference,node_outputs toneRose
class node_operator toneIndigo
```

## Components

### Data preparation

- [Prepare data](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/dataset_and_visualization.ipynb): `dataset_and_visualization.ipynb`
- [Regional NetCDF](https://github.com/syeddaniyalg/blissnet-era5-inference/tree/main/datasets): `datasets`

### BLISSNet model

- [BLISSNet orchestration](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py): `blissnet/blissnet.py`
- [SIREN trunk](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py): `blissnet/blissnet.py`
- [Full-grid branch](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py): `blissnet/blissnet.py`
- [Attention U-Net](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py): `blissnet/blissnet.py`
- [Sparse-sensor branch](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py): `blissnet/blissnet.py`
- [Sensor transformer](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py): `blissnet/blissnet.py`
- [Cross-attention](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py): `blissnet/blissnet.py`
- [Attention pool](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py): `blissnet/blissnet.py`
- [Coefficient decoder](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/blissnet/blissnet.py): `blissnet/blissnet.py`

### Model training

- [Stage 1 training](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/training.ipynb): `training.ipynb`
- [Stage 2 training](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/training.ipynb): `training.ipynb`
- **Model checkpoints**

### Inference evaluation

- [Cross-region evaluation](https://github.com/syeddaniyalg/blissnet-era5-inference/blob/main/inference.ipynb): `inference.ipynb`
- **Evaluation outputs**

### Other components

- **Researcher**
- **Raw ERA5 data**

## Connections

- Researcher → Prepare data: prepares data (evidence: `README.md`)
- Raw ERA5 data → Prepare data: provides GRIB (evidence: `README.md`)
- Prepare data → Regional NetCDF: exports NetCDF (evidence: `README.md`)
- Researcher → Stage 1 training: starts training (evidence: `README.md`)
- Regional NetCDF → Stage 1 training: trains on grids (evidence: `README.md`)
- Stage 1 training → BLISSNet orchestration: trains model (evidence: `README.md`)
- BLISSNet orchestration → SIREN trunk: evaluates basis (evidence: `blissnet/blissnet.py`)
- BLISSNet orchestration → Full-grid branch: routes full grids (evidence: `blissnet/blissnet.py`)
- Full-grid branch → Attention U-Net: extracts features (evidence: `blissnet/blissnet.py`)
- Researcher → Stage 2 training: starts training (evidence: `README.md`)
- Stage 1 training → Stage 2 training: freezes components (evidence: `README.md`)
- Stage 2 training → BLISSNet orchestration: trains sparse path (evidence: `README.md`)
- BLISSNet orchestration → Sparse-sensor branch: routes sensors (evidence: `blissnet/blissnet.py`)
- Sparse-sensor branch → Sensor transformer: encodes sensors (evidence: `blissnet/blissnet.py`)
- Sparse-sensor branch → Cross-attention: attends to latents (evidence: `blissnet/blissnet.py`)
- Sparse-sensor branch → Attention pool: pools features (evidence: `blissnet/blissnet.py`)
- Sparse-sensor branch → Coefficient decoder: decodes coefficients (evidence: `blissnet/blissnet.py`)
- Stage 1 training → Model checkpoints: saves checkpoints (evidence: `README.md`)
- Stage 2 training → Model checkpoints: saves checkpoints (evidence: `README.md`)
- Researcher → Cross-region evaluation: runs evaluation (evidence: `README.md`)
- Model checkpoints → Cross-region evaluation: loads checkpoints (evidence: `README.md`)
- Regional NetCDF → Cross-region evaluation: supplies test data (evidence: `README.md`)
- Cross-region evaluation → BLISSNet orchestration: evaluates model (evidence: `README.md`)
- Cross-region evaluation → Evaluation outputs: records metrics (evidence: `README.md`)
