# jayoungkim408/stasy architecture

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

- Interactive diagram: https://gitdiagram.com/jayoungkim408/stasy
- Repository: https://github.com/jayoungkim408/stasy

## Overview

##### Project Type and Purpose
- This is a research-oriented Python project that implements a score-based generative model for tabular data synthesis.
- It provides training, fine-tuning, sampling, and evaluation workflows driven by a single entry point (`main.py`) and configurable via Python config scripts in `configs/`.

##### Main Architectural Layers
A. Configuration & CLI Layer
- main.py
- `configs/` directory (e.g., `configs/shoppers.py`, `configs/iris.py`)
- CLI arguments (`--config`, `--mode`, `--workdir`)
B. Data Layer
- Raw tabular datasets under `tabular_datasets/` (JSON/NPZ)
- Dataset loader modules (`datasets.py`, `datasets_tabular.py`, `prepare_dataset.py`, `prepare_dataset_utils.py`)
- Preprocessing utilities in `utils.py`, `tabular_utils.py`
C. Model Layer
- Core score-based model implementation in `models/`:
– SDE solvers (`sde_lib.py`)
– Neural net modules (`models/layers.py`, `models/layerspp.py`)
– Model definitions (`models/ncsnpp_tabular.py`)
– EMA wrapper (`models/ema.py`)
– Misc utilities (`models/utils.py`, `models/tabular_utils.py`)
D. Training/Sampling/Evaluation Engine
- Training loop & loss computation (`losses.py`, `likelihood.py`, `run_lib.py`, `sampling.py`, `evaluation.py`)
- Checkpointing & logging (via `run_lib.py` or custom code in `main.py`)
E. External Dependencies & Environments
- Python libraries (PyTorch, NumPy, SciPy, Hydra or custom config loader)
- Conda environment (`requirements.yaml`)
- GPU/Compute cluster (optional)

##### Relationships and Data Flows
- CLI → Config Loader: Parse arguments & load Python config
- Config → Data Layer: Select dataset paths & preprocessing parameters
- Data Loader → Preprocessing → Model Input
- Model Layer ↔ SDE Module: Forward/backward passes, score estimation
- Training Engine → Loss Module → Optimizer → Model Layer (iterative)
- Model Layer → EMA Module → Checkpoint Manager
- Sampling Engine (invoked by `main.py --mode eval`) → SDE Module → Generated Samples
- Evaluation Module → Metrics & Results → Output directory under `workdir`

##### Architectural Patterns & Principles
- Layered separation: Config/CLI, Data, Model, Training/Evaluation
- Modular design: Each concern (data prep, model, sampling, evaluation) lives in its own module
- Reusable utilities: Shared functions in `utils.py`, `tabular_utils.py`
- Experiment reproducibility: Checkpoints and logging in a per-`workdir` folder

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration & CLI Layer
    subgraph "Configuration & CLI"
        direction TB
        CLI["main.py"]:::config
        CFG_DEFAULT["default_tabular_configs.py"]:::config
        CFG_IRIS["iris.py"]:::config
        CFG_SHOPPERS["shoppers.py"]:::config
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DATASETS_DIR["tabular_datasets/"]:::data
        DATASETS_JSON["iris.json / shoppers.json"]:::data
        DATASETS_NPZ["iris.npz / shoppers.npz"]:::data
        DS_BASE["datasets.py"]:::data
        DS_TAB["datasets_tabular.py"]:::data
        PREP["prepare_dataset.py"]:::util
        PREP_UTIL["prepare_dataset_utils.py"]:::util
        UTIL_DATA["utils.py"]:::util
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        SDE["sde_lib.py"]:::model
        EMA["models/ema.py"]:::model
        LAYERS["models/layers.py"]:::model
        LAYERSPP["models/layerspp.py"]:::model
        NCSNPP["models/ncsnpp_tabular.py"]:::model
        MODEL_UTIL["models/utils.py"]:::model
        TAB_UTIL["models/tabular_utils.py"]:::model
    end

    %% Orchestration & Engines
    subgraph "Orchestration & Engines"
        direction TB
        TRAIN_LOOP["run_lib.py"]:::core
        LOSSES["losses.py"]:::core
        LIKELI["likelihood.py"]:::core
        SAMPLING["sampling.py"]:::core
        EVAL["evaluation.py"]:::core
        CHECKPOINT["Checkpoint & Logging"]:::external
    end

    %% External Dependencies
    subgraph "External & Environment"
        direction TB
        REQ["requirements.yaml"]:::external
        README["README.md"]:::external
        GPU["GPU Cluster"]:::external
    end

    %% Connections
    CLI -->|"--config, --mode, --workdir"| CFG_DEFAULT
    CLI --> CFG_IRIS
    CLI --> CFG_SHOPPERS
    CFG_DEFAULT -->|"loads hyperparams"| TRAIN_LOOP
    CFG_IRIS --> TRAIN_LOOP
    CFG_SHOPPERS --> TRAIN_LOOP

    TRAIN_LOOP -->|"select dataset"| DATASETS_DIR
    DATASETS_DIR --> DATASETS_JSON
    DATASETS_DIR --> DATASETS_NPZ
    DATASETS_JSON --> DS_BASE
    DATASETS_NPZ --> DS_TAB
    DS_BASE --> PREP
    DS_TAB --> PREP
    PREP --> PREP_UTIL
    PREP_UTIL --> UTIL_DATA
    UTIL_DATA -->|"batch of preprocessed tensors"| SDE

    SDE -->|"score estimates"| NCSNPP
    LAYERS --> NCSNPP
    LAYERSPP --> NCSNPP
    MODEL_UTIL --> NCSNPP
    TAB_UTIL --> NCSNPP
    NCSNPP --> EMA
    EMA --> CHECKPOINT

    TRAIN_LOOP -->|"parameters & gradients"| LOSSES
    LOSSES --> LIKELI
    LIKELI --> TRAIN_LOOP
    TRAIN_LOOP --> CHECKPOINT

    CHECKPOINT --> SAMPLING
    SAMPLING -->|"invoke SDE sampling"| SDE
    SDE -->|"generated samples"| SAMPLING
    SAMPLING -->|"synthetic data"| EVAL
    EVAL -->|"metrics & results"| CHECKPOINT

    %% External Dependencies usage
    TRAIN_LOOP --> REQ
    CLI --> REQ
    SDE --> REQ
    TRAIN_LOOP --> GPU

    %% Click Events
    click CLI "https://github.com/jayoungkim408/stasy/blob/main/main.py"
    click CFG_DEFAULT "https://github.com/jayoungkim408/stasy/blob/main/configs/default_tabular_configs.py"
    click CFG_IRIS "https://github.com/jayoungkim408/stasy/blob/main/configs/iris.py"
    click CFG_SHOPPERS "https://github.com/jayoungkim408/stasy/blob/main/configs/shoppers.py"
    click DATASETS_DIR "https://github.com/jayoungkim408/stasy/tree/main/tabular_datasets/"
    click DS_BASE "https://github.com/jayoungkim408/stasy/blob/main/datasets.py"
    click DS_TAB "https://github.com/jayoungkim408/stasy/blob/main/datasets_tabular.py"
    click PREP "https://github.com/jayoungkim408/stasy/blob/main/prepare_dataset.py"
    click PREP_UTIL "https://github.com/jayoungkim408/stasy/blob/main/prepare_dataset_utils.py"
    click UTIL_DATA "https://github.com/jayoungkim408/stasy/blob/main/utils.py"
    click SDE "https://github.com/jayoungkim408/stasy/blob/main/sde_lib.py"
    click EMA "https://github.com/jayoungkim408/stasy/blob/main/models/ema.py"
    click LAYERS "https://github.com/jayoungkim408/stasy/blob/main/models/layers.py"
    click LAYERSPP "https://github.com/jayoungkim408/stasy/blob/main/models/layerspp.py"
    click NCSNPP "https://github.com/jayoungkim408/stasy/blob/main/models/ncsnpp_tabular.py"
    click MODEL_UTIL "https://github.com/jayoungkim408/stasy/blob/main/models/utils.py"
    click TAB_UTIL "https://github.com/jayoungkim408/stasy/blob/main/models/tabular_utils.py"
    click TRAIN_LOOP "https://github.com/jayoungkim408/stasy/blob/main/run_lib.py"
    click LOSSES "https://github.com/jayoungkim408/stasy/blob/main/losses.py"
    click LIKELI "https://github.com/jayoungkim408/stasy/blob/main/likelihood.py"
    click SAMPLING "https://github.com/jayoungkim408/stasy/blob/main/sampling.py"
    click EVAL "https://github.com/jayoungkim408/stasy/blob/main/evaluation.py"
    click REQ "https://github.com/jayoungkim408/stasy/blob/main/requirement.yaml"
    click README "https://github.com/jayoungkim408/stasy/blob/main/README.md"

    %% Styles
    classDef config fill:#9ae6b4,stroke:#2f855a,color:#1a202c;
    classDef data fill:#bee3f8,stroke:#2b6cb0,color:#1a202c;
    classDef util fill:#fbd38d,stroke:#dd6b20,color:#1a202c;
    classDef model fill:#c6f6d5,stroke:#38a169,color:#1a202c;
    classDef core fill:#bee3f8,stroke:#2b6cb0,color:#1a202c;
    classDef external fill:#edf2f7,stroke-dasharray: 5 5,stroke:#4a5568,color:#1a202c;
```
