# sreyas-mohan/deepfreq architecture

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

- Interactive diagram: https://gitdiagram.com/sreyas-mohan/deepfreq
- Repository: https://github.com/sreyas-mohan/deepfreq

## Overview

##### Project Type and Purpose
- This is a research‐code repository for “Data‐driven Estimation of Sinusoid Frequencies.” It provides data‐generation, model‐training (DeepFreq), baseline comparison (PSnet, CBLasso), pretrained networks, and evaluation scripts/notebooks.

##### File‐Structure Analysis
Top‐level scripts:
- generate_dataset.py – creates synthetic test data
- train.py – trains the DeepFreq networks from scratch
- test.py – runs benchmarks (DeepFreq vs. PSnet vs. CBLasso)
- example_notebook.ipynb – demo of pretrained‐model inference & visualization
- modules.py + util.py – core PyTorch model definitions and helpers
Packages:
- cblasso/ – MATLAB‐based CBLasso interface (cbl_via_matlab.py + .m files)
- data/ – dataset classes, data‐loading logic, noise/loss functions
Resources:
- test_dataset/ – .npy test signals & precomputed CBLasso results
- pretrained_models/ – DeepFreq and PSnet model checkpoints
- figures/, example_notebook.html – visualization output
Config & deps:
- requirements.txt, _config.yml, .gitignore

##### Key Components & Their Relationships
a. Data Generation
– generate_dataset.py outputs noisy sinusoids → saved in data/ or custom test_dataset/
b. Data Module
– data/dataset.py, data/data.py, data/noise.py, etc.
– Loads .npy signals, applies noise, constructs PyTorch DataLoader
c. Model Module
– modules.py defines DeepFreq frequency‐representation (FR) & frequency‐counting (FC) architectures
– util.py contains shared utilities (e.g., loss functions in data/loss.py)
d. Training Pipeline (train.py)
– Uses Data Module + Model Module
– Produces FR & FC model checkpoints → saved under output_dir
e. Pretrained Models
– pretrained_models/DeepFreq & /PSnet contain .pth files for FR, FC, PSnet baseline
f. Inference & Benchmarking (test.py + example_notebook.ipynb)
– Loads test_dataset/ + pretrained_models/
– Runs:
- DeepFreq inference: FR → FC → predicted frequencies
- PSnet inference: PSnet modules
- CBLasso baseline via cblasso/cbl_via_matlab.py + MATLAB/CVX
– Aggregates metrics (Chambers, FNR) → outputs to results/ or figures/
g. Visualization
– example_notebook shows signal plots, error curves
– generate_dataset.py + figures/ for static images

##### Architectural Patterns & Design Principles
- Modular separation:
- Data generation vs. data‐loading vs. modeling vs. evaluation
- Pluggable baselines (DeepFreq, PSnet, CBLasso) via uniform interface
- Pipeline stages:
1. Data generation → 2. Data loading → 3. Training → 4. Model artifacts → 5. Inference → 6. Benchmarking & visualization
- Language interoperability:
- Python ↔ MATLAB for CBLasso baseline

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data-related components
    DataGen["Data Generation\ngenerate_dataset.py\n(Python, NumPy)"]:::data
    Storage["Dataset Storage\ntest_dataset/"]:::data
    Loader["Data Loader Module\ndata/"]:::data

    %% Model-related components
    ModelArch["Model Architectures\nmodules.py\n(DeepFreq FR & FC)"]:::model
    Util["Utility Functions\nutil.py\n(losses, helpers)"]:::model
    Training["Training Pipeline\ntrain.py\n(PyTorch)"]:::model
    PretrainedDF["Pretrained Models\nDeepFreq/"]:::model
    PretrainedPS["Pretrained Models\nPSnet/"]:::model
    Inference["Inference & Benchmarking\ntest.py"]:::model
    Notebook["Jupyter Notebook Demo\nexample_notebook.ipynb"]:::model

    %% Baseline/Cross-lang components
    CBLasso["CBLasso Baseline Interface\ncblasso/"]:::baseline

    %% Output/Visualization components
    Visualization["Visualization Output\nfigures/"]:::output

    %% Connections
    DataGen -->|"generates"| Storage
    Storage -->|"loads data"| Loader
    Loader -->|"feeds into"| Training
    Training -->|"saves models"| PretrainedDF
    Training -->|"saves models"| PretrainedPS
    Loader -->|"passes raw data"| CBLasso
    Storage -->|"provides test data"| Inference
    PretrainedDF -->|"loads FR & FC"| Inference
    PretrainedPS -->|"loads PSnet"| Inference
    CBLasso -->|"baseline results"| Inference
    Inference -->|"outputs metrics"| Visualization
    PretrainedDF -->|"demo data"| Notebook
    PretrainedPS -->|"demo data"| Notebook
    Storage -->|"demo data"| Notebook
    Notebook -->|"visualizes"| Visualization

    %% Click Events
    click DataGen "https://github.com/sreyas-mohan/deepfreq/blob/master/generate_dataset.py"
    click Storage "https://github.com/sreyas-mohan/deepfreq/tree/master/test_dataset/"
    click Loader "https://github.com/sreyas-mohan/deepfreq/tree/master/data/"
    click ModelArch "https://github.com/sreyas-mohan/deepfreq/blob/master/modules.py"
    click Util "https://github.com/sreyas-mohan/deepfreq/blob/master/util.py"
    click Training "https://github.com/sreyas-mohan/deepfreq/blob/master/train.py"
    click PretrainedDF "https://github.com/sreyas-mohan/deepfreq/tree/master/pretrained_models/DeepFreq/"
    click PretrainedPS "https://github.com/sreyas-mohan/deepfreq/tree/master/pretrained_models/PSnet/"
    click Inference "https://github.com/sreyas-mohan/deepfreq/blob/master/test.py"
    click Notebook "https://github.com/sreyas-mohan/deepfreq/blob/master/example_notebook.ipynb"
    click CBLasso "https://github.com/sreyas-mohan/deepfreq/tree/master/cblasso/"
    click Visualization "https://github.com/sreyas-mohan/deepfreq/tree/master/figures/"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef model fill:#98FB98,stroke:#333,stroke-width:1px
    classDef baseline fill:#FFD580,stroke:#333,stroke-width:1px
    classDef output fill:#DDA0DD,stroke:#333,stroke-width:1px
```
