# sigcgans/conditional-sig-wasserstein-gans architecture

> Architecture diagram of the GitHub repository sigcgans/conditional-sig-wasserstein-gans, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sigcgans/conditional-sig-wasserstein-gans
- Repository: https://github.com/sigcgans/conditional-sig-wasserstein-gans

## Overview

##### Project Type and Purpose
- This is a research‐oriented PyTorch codebase implementing Conditional Sig-Wasserstein GANs (SigCWGAN) for time-series data generation, with scripts for training, evaluation, and baseline comparisons.

##### File Structure Analysis
- Top-Level Scripts
- train.py – orchestrates model training (loads data, configures hyperparameters, instantiates models, logs results)
- evaluate.py – runs evaluation metrics on saved checkpoints
- hyperparameters.py – central location for default training/evaluation settings
- Library Code (lib/)
- lib/data.py – data loading, dataset wrappers (synthetic VAR/ARCH and real stock data)
- lib/augmentations.py – time-series augmentation utilities
- lib/algos/ – GAN implementations
– base.py (abstract GAN interface)
– gans.py (standard GAN)
– gmmn.py (GAN with MMD)
– sigcwgan.py (the Sig-Wasserstein variant)
- lib/arfnn.py – autoregressive feedforward neural network baseline
- lib/test_metrics.py – evaluation metrics module
- lib/plot.py – visualization helpers
- lib/utils.py – shared utility functions (logging, checkpointing)
- Config & Environment
- requirements.yml – conda environment spec
- .gitignore

##### Key Architectural Patterns
- Modular, plug-and-play algorithm implementations via a common base class (lib/algos/base.py)
- Separation of concerns: data ingestion → model definitions → training loop → evaluation → plotting/storage
- Script-driven orchestration (train.py and evaluate.py) rather than a web API

a. Data Layer
- Synthetic Data Generator (VAR, ARCH)
- Real-world Data Loader (stock data)
- Augmentation Pipeline
b. Model Layer (lib/algos)
- SigCWGAN core (generator, discriminator, scoring)
- Baseline GANs (RCGAN, TimeGAN, GMMN)
- ARFNN baseline
c. Orchestration Layer
- Training Script (train.py)
- Evaluation Script (evaluate.py)
- Hyperparameter Manager (hyperparameters.py)
d. Utility Layer
- Logging & Checkpointing (utils.py)
- Plotting & Metrics (plot.py, test_metrics.py)
e. Results Storage
- numerical_results/ (training logs, CSV summaries, model checkpoints)

##### Component Interactions & Data Flow
1. train.py reads hyperparameters → calls data.py → obtains data batches
2. Data batches pass through augmentations.py → fed into selected lib/algos model
3. Model’s forward/backward loops handled by train.py → util.py manages checkpoints & logging
4. At intervals, train.py invokes plot.py to generate figures → stored under numerical_results
5. evaluate.py loads saved checkpoints → uses test_metrics.py to compute metrics → writes summary.csv

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    PT["PyTorch"]:::external
    CONDA["Conda Environment"]:::external

    %% Data Layer
    subgraph "Data Layer"
        SDG["Synthetic Data Generator"]:::data
        RLD["Real-world Data Loader"]:::data
        AUG["Augmentation Pipeline"]:::data
    end

    %% Model Layer
    subgraph "Model Layer"
        BASE["GAN Interface Base Class"]:::model
        GANS["Standard & Conditional GANs"]:::model
        GMMN["MMD GAN (GMMN)"]:::model
        SIG["Sig-Wasserstein GAN"]:::model
        ARFNN["ARFNN Baseline"]:::model
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        TRAIN["Training Script"]:::orch
        EVAL["Evaluation Script"]:::orch
        HP["Hyperparameter Manager"]:::orch
    end

    %% Utility Layer
    subgraph "Utility Layer"
        UTIL["Logging & Checkpointing"]:::util
        PLOT["Plotting Helpers"]:::util
        MET["Evaluation Metrics Module"]:::util
    end

    %% Results Storage
    subgraph "Results Storage"
        RES["numerical_results/"]:::storage
    end

    %% Data Flow
    HP -->|"configs"| TRAIN
    TRAIN -->|"requests data"| SDG
    TRAIN -->|"requests data"| RLD
    SDG -->|"raw batch"| AUG
    RLD -->|"raw batch"| AUG
    AUG -->|"augmented batch"| BASE
    BASE -->|"interface"| GANS
    BASE -->|"interface"| GMMN
    BASE -->|"interface"| SIG
    BASE -->|"interface"| ARFNN
    TRAIN -->|"model training"| UTIL
    UTIL -->|"checkpoint .pt"| RES
    TRAIN -->|"invoke plotting"| PLOT
    PLOT -->|"figures"| RES
    RES -->|"load checkpoint"| EVAL
    EVAL -->|"metrics dict"| MET
    MET -->|"summary.csv"| RES

    %% External Dependencies Links
    PT -.-> BASE
    PT -.-> GANS
    PT -.-> GMMN
    PT -.-> SIG
    PT -.-> ARFNN
    CONDA -.-> TRAIN
    CONDA -.-> EVAL
    CONDA -.-> HP

    %% Click Events
    click SDG "https://github.com/sigcgans/conditional-sig-wasserstein-gans/blob/master/lib/data.py"
    click RLD "https://github.com/sigcgans/conditional-sig-wasserstein-gans/blob/master/lib/data.py"
    click AUG "https://github.com/sigcgans/conditional-sig-wasserstein-gans/blob/master/lib/augmentations.py"
    click BASE "https://github.com/sigcgans/conditional-sig-wasserstein-gans/blob/master/lib/algos/base.py"
    click GANS "https://github.com/sigcgans/conditional-sig-wasserstein-gans/blob/master/lib/algos/gans.py"
    click GMMN "https://github.com/sigcgans/conditional-sig-wasserstein-gans/blob/master/lib/algos/gmmn.py"
    click SIG "https://github.com/sigcgans/conditional-sig-wasserstein-gans/blob/master/lib/algos/sigcwgan.py"
    click ARFNN "https://github.com/sigcgans/conditional-sig-wasserstein-gans/blob/master/lib/arfnn.py"
    click TRAIN "https://github.com/sigcgans/conditional-sig-wasserstein-gans/blob/master/train.py"
    click EVAL "https://github.com/sigcgans/conditional-sig-wasserstein-gans/blob/master/evaluate.py"
    click HP "https://github.com/sigcgans/conditional-sig-wasserstein-gans/blob/master/hyperparameters.py"
    click UTIL "https://github.com/sigcgans/conditional-sig-wasserstein-gans/blob/master/lib/utils.py"
    click PLOT "https://github.com/sigcgans/conditional-sig-wasserstein-gans/blob/master/lib/plot.py"
    click MET "https://github.com/sigcgans/conditional-sig-wasserstein-gans/blob/master/lib/test_metrics.py"

    %% Styles
    classDef data fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef model fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef orch fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef util fill:#EEEEEE,stroke:#424242,color:#424242
    classDef storage fill:#F5F5F5,stroke:#9E9E9E,color:#424242
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
```
