# rohanasthana/dinas architecture

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

- Interactive diagram: https://gitdiagram.com/rohanasthana/dinas
- Repository: https://github.com/rohanasthana/dinas

## Overview

##### Project Type & Purpose
- This is a research-oriented machine-learning framework (not a web app), focusing on neural architecture search (NAS) via graph diffusion.
- It orchestrates dataset loading, conditional diffusion-based generator models, training loops, metrics computation, and analysis/visualization.
- It also bundles several NAS benchmarks (NASBench101/201/301/NLP/HW), each accessed through dedicated APIs.

##### Core Components

A. Configuration Manager
– Location: configs/ + src/Settings.py
– Role: Load YAML config files (dataset settings, experiment settings, model/training hyperparameters) and expose them to the rest of the system.

B. Dataset Module
– Location: src/datasets/ + subfolders for each benchmark
– Role: AbstractDataset → specific dataset classes (nasbench101_dataset, guacamol_dataset, qm9_dataset, etc.)
– Interactions: Fetch raw data via API wrappers (e.g., src/datasets/nasbench/api.py) or external libraries.

C. Graph Diffusion Generator
– Location: src/diffusion_model.py, src/diffusion_model_discrete*.py, src/Generator.py
– Role: Implement the core diffusion process—discrete or continuous—conditioned on accuracy/latency.
– Dependencies: src/diffusion/layers.py, noise_schedule.py, distributions.py, extra_features.py, etc.

D. Model Definitions
– Location: src/models/transformer_*.py, src/models/layers.py
– Role: Define architecture of the transformer-based denoiser or regressor used during diffusion.

E. Training Orchestrator (CLI)
– Location: main_reg_free.py and src/main.py
– Role: Parse CLI arguments, invoke Settings, instantiate dataset + model + training loop, checkpoint saving.

F. Metrics & Evaluation
– Location: src/metrics/ + train_metrics.py
– Role: AbstractMetrics → specific metrics (molecular_metrics, nasbench201metrics, etc.). Computes quality of generated architectures.

G. Analysis & Visualization
– Location: src/analysis/ + visualization.py, spectre_utils.py, rdkit_functions*.py
– Role: Post-hoc analysis of generated samples, plotting, chemical graph operations (via RDKit), ORCA binding for quantum metrics.

H. External NASBenchX11 Submodule
– Location: src/nasbenchx11/… (a full subproject)
– Role: Alternate NAS API with ensemble surrogate models, own dataset loaders, encodings, predictors, and optimizers.

I. Utilities & Scripts
– Location: src/utils.py, src/job_script.sh, generate_samples.py
– Role: Helper functions, sample generation script, HPC job wrappers.

##### Component Interactions & Data Flow
– The user invokes the CLI (main_reg_free.py or main.py) with flags (e.g., `--dataset nasbench101`).
→ CLI loads config via Settings.
→ Settings selects a Dataset class and constructs it.
→ Dataset module either loads from local cache or queries the NASBench API subpackages.
→ CLI then constructs the Graph Diffusion Generator, injecting model hyperparameters from config.
→ The Training Loop kicks off:
- For each epoch/step: apply forward/backward passes through diffusion_model → compute loss → update weights.
- Periodically save checkpoints to disk.
- After training, or concurrently, generate new architectures via Generator.sample().
→ Generated architectures flow into Metrics module for evaluation (accuracy, latency, chemical properties, etc.).
→ Analysis module ingests metrics + samples to produce visualizations, graphs, or quantum-level metrics (via ORCA).
→ Final trained models and metrics are stored locally or uploaded to Google Drive (pre-trained models).

##### Architectural Patterns & Principles
– Modular separation by concern (Configs, Datasets, Models, Training, Metrics, Analysis).
– Factory pattern in Dataset selection (abstract base → concrete classes).
– Plug-in style for diffusion variants (continuous vs. discrete vs. reg-free).
– Clear layering:
- Top layer: CLI & Experiment scripts
- Middle layer: Orchestrator & Models
- Bottom layer: Data access & Utilities

##### Technologies & Frameworks
– Language: Python 3.x
– Config management: YAML + custom Settings loader
– ML libraries: PyTorch (implied by model code), RDKit for molecular graphs, ORCA for quantum metrics
– Environments: Conda (environment.yml)
– External APIs: NASBench101/201/301 libraries, GuacaMol benchmark, QM9 dataset, etc.

##### Final Checklist
– Have you named each component clearly?
– Are any key interactions (e.g., model → metrics → analysis) missing?

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration Layer
    CLI["CLI<br/>(main_reg_free.py, src/main.py)"]:::orchestration
    Configs["Configuration Manager<br/>(configs/, src/Settings.py)"]:::orchestration

    %% Data Layer
    subgraph "Dataset Module" 
        direction TB
        Datasets["Dataset Module<br/>(src/datasets/)"]:::data
        Abstract["abstract_dataset.py"]:::data
        Guaca["guacamol_dataset.py"]:::data
        NB101API["nasbench/api.py"]:::data
        NB101DS["nasbench101_dataset.py"]:::data
        NB201API["nasbench201/api.py"]:::data
        QM9["qm9_dataset.py"]:::data
    end

    %% External APIs
    subgraph "External NASBenchX11 Submodule"
        direction TB
        X11["src/nasbenchx11/"]:::external
    end

    %% Compute/Model Layer
    subgraph "Graph Diffusion Generator"
        direction TB
        DiffusionCore["diffusion_model.py"]:::compute
        DiffusionDisc["diffusion_model_discrete.py"]:::compute
        DiffusionRegFree["diffusion_model_discrete_reg_free.py"]:::compute
        Generator["Generator.py"]:::compute
        subgraph "Diffusion Dependencies"
            direction TB
            Layers["layers.py"]:::compute
            Noise["noise_schedule.py"]:::compute
            Dist["distributions.py"]:::compute
            ExtraFeat["extra_features.py"]:::compute
            ExtraMol["extra_features_molecular.py"]:::compute
            UtilsDiff["diffusion_utils.py"]:::compute
        end
    end

    subgraph "Model Definitions"
        direction TB
        M_Layers["layers.py"]:::compute
        T_Clean["transformer_clean.py"]:::compute
        T_Model["transformer_model.py"]:::compute
        T_RegFree["transformer_reg_free.py"]:::compute
        T_HW["transformer_reg_free_HW.py"]:::compute
        T_ImageNet["transformer_reg_free_ImageNet.py"]:::compute
    end

    %% Training Loop
    Training["Training Orchestrator & Loop"]:::compute

    %% Evaluation Layer
    subgraph "Metrics & Evaluation"
        direction TB
        MetricsCore["abstract_metrics.py"]:::evaluation
        TrainMet["train_metrics.py"]:::evaluation
        MolMet["molecular_metrics.py"]:::evaluation
        NB201Met["nasbench201metrics.py"]:::evaluation
        NB301Met["nasbench301metrics.py"]:::evaluation
        HWMet["nasbenchHWmetrics.py"]:::evaluation
        IMGMet["nasbenchImageNetmetrics.py"]:::evaluation
        NLPMet["nasbenchNLPmetrics.py"]:::evaluation
    end

    subgraph "Analysis & Visualization"
        direction TB
        Viz["visualization.py"]:::evaluation
        Spectre["spectre_utils.py"]:::evaluation
        RDKit["rdkit_functions.py"]:::evaluation
        RDKit201["rdkit_functions201.py"]:::evaluation
        RDKit301["rdkit_functions301.py"]:::evaluation
        RDKitHW["rdkit_functionsHW.py"]:::evaluation
        RDKitIMG["rdkit_functionsImageNet.py"]:::evaluation
        RDKitNLP["rdkit_functionsNLP.py"]:::evaluation
        ORCA["orca/"]:::evaluation
        DistHelper["dist_helper.py"]:::evaluation
    end

    %% Utilities
    subgraph "Utilities & Scripts"
        direction TB
        Utils["utils.py"]:::external
        GenSamples["generate_samples.py"]:::external
        JobScript["job_script.sh"]:::external
        Predinas["predinas.sh"]:::external
    end

    %% Flow
    CLI -->|"loads config"| Configs
    Configs -->|"config dict"| Datasets
    Datasets -->|"batch of graphs"| DiffusionCore
    DiffusionCore -->|"conditioned model"| Training
    DiffusionDisc --> Training
    DiffusionRegFree --> Training
    Generator -->|"sample()"| Training
    Training -->|"checkpoints"| Utils
    Training -->|"generated samples"| MolMet
    Training -->|"generated samples"| NB201Met
    Training -->|"generated samples"| NB301Met
    Training -->|"generated samples"| HWMet
    Training -->|"generated samples"| IMGMet
    Training -->|"generated samples"| NLPMet
    MetricsCore -->|"metrics dict"| DistHelper
    MolMet --> DistHelper
    NB201Met --> DistHelper
    NB301Met --> DistHelper
    HWMet --> DistHelper
    IMGMet --> DistHelper
    NLPMet --> DistHelper
    DistHelper --> Viz
    Spectre --> Viz
    RDKit --> Viz
    ORCA --> Viz
    X11 --> Datasets
    Utils --> Training
    GenSamples --> Training
    Predinas --> Training
    JobScript --> Training

    %% Click Events
    click Configs "https://github.com/rohanasthana/dinas/tree/master/configs/"
    click Configs "https://github.com/rohanasthana/dinas/blob/master/src/Settings.py"
    click CLI "https://github.com/rohanasthana/dinas/blob/master/main_reg_free.py"
    click CLI "https://github.com/rohanasthana/dinas/blob/master/src/main.py"
    click Datasets "https://github.com/rohanasthana/dinas/tree/master/src/datasets/"
    click Abstract "https://github.com/rohanasthana/dinas/blob/master/src/datasets/abstract_dataset.py"
    click Guaca "https://github.com/rohanasthana/dinas/blob/master/src/datasets/guacamol_dataset.py"
    click NB101API "https://github.com/rohanasthana/dinas/blob/master/src/datasets/nasbench/api.py"
    click NB101DS "https://github.com/rohanasthana/dinas/blob/master/src/datasets/nasbench101_dataset.py"
    click NB201API "https://github.com/rohanasthana/dinas/blob/master/src/datasets/nasbench201/api.py"
    click QM9 "https://github.com/rohanasthana/dinas/blob/master/src/datasets/qm9_dataset.py"
    click DiffusionCore "https://github.com/rohanasthana/dinas/blob/master/src/diffusion_model.py"
    click DiffusionDisc "https://github.com/rohanasthana/dinas/blob/master/src/diffusion_model_discrete.py"
    click DiffusionRegFree "https://github.com/rohanasthana/dinas/blob/master/src/diffusion_model_discrete_reg_free.py"
    click Generator "https://github.com/rohanasthana/dinas/blob/master/src/Generator.py"
    click Layers "https://github.com/rohanasthana/dinas/blob/master/src/diffusion/layers.py"
    click Noise "https://github.com/rohanasthana/dinas/blob/master/src/diffusion/noise_schedule.py"
    click Dist "https://github.com/rohanasthana/dinas/blob/master/src/diffusion/distributions.py"
    click ExtraFeat "https://github.com/rohanasthana/dinas/blob/master/src/diffusion/extra_features.py"
    click ExtraMol "https://github.com/rohanasthana/dinas/blob/master/src/diffusion/extra_features_molecular.py"
    click UtilsDiff "https://github.com/rohanasthana/dinas/blob/master/src/diffusion/diffusion_utils.py"
    click M_Layers "https://github.com/rohanasthana/dinas/blob/master/src/models/layers.py"
    click T_Clean "https://github.com/rohanasthana/dinas/blob/master/src/models/transformer_clean.py"
    click T_Model "https://github.com/rohanasthana/dinas/blob/master/src/models/transformer_model.py"
    click T_RegFree "https://github.com/rohanasthana/dinas/blob/master/src/models/transformer_reg_free.py"
    click T_HW "https://github.com/rohanasthana/dinas/blob/master/src/models/transformer_reg_free_HW.py"
    click T_ImageNet "https://github.com/rohanasthana/dinas/blob/master/src/models/transformer_reg_free_ImageNet.py"
    click MetricsCore "https://github.com/rohanasthana/dinas/blob/master/src/metrics/abstract_metrics.py"
    click TrainMet "https://github.com/rohanasthana/dinas/blob/master/src/metrics/train_metrics.py"
    click MolMet "https://github.com/rohanasthana/dinas/blob/master/src/metrics/molecular_metrics.py"
    click NB201Met "https://github.com/rohanasthana/dinas/blob/master/src/metrics/nasbench201metrics.py"
    click NB301Met "https://github.com/rohanasthana/dinas/blob/master/src/metrics/nasbench301metrics.py"
    click HWMet "https://github.com/rohanasthana/dinas/blob/master/src/metrics/nasbenchHWmetrics.py"
    click IMGMet "https://github.com/rohanasthana/dinas/blob/master/src/metrics/nasbenchImageNetmetrics.py"
    click NLPMet "https://github.com/rohanasthana/dinas/blob/master/src/metrics/nasbenchNLPmetrics.py"
    click Viz "https://github.com/rohanasthana/dinas/blob/master/src/analysis/visualization.py"
    click Spectre "https://github.com/rohanasthana/dinas/blob/master/src/analysis/spectre_utils.py"
    click RDKit "https://github.com/rohanasthana/dinas/blob/master/src/analysis/rdkit_functions.py"
    click RDKit201 "https://github.com/rohanasthana/dinas/blob/master/src/analysis/rdkit_functions201.py"
    click RDKit301 "https://github.com/rohanasthana/dinas/blob/master/src/analysis/rdkit_functions301.py"
    click RDKitHW "https://github.com/rohanasthana/dinas/blob/master/src/analysis/rdkit_functionsHW.py"
    click RDKitIMG "https://github.com/rohanasthana/dinas/blob/master/src/analysis/rdkit_functionsImageNet.py"
    click RDKitNLP "https://github.com/rohanasthana/dinas/blob/master/src/analysis/rdkit_functionsNLP.py"
    click ORCA "https://github.com/rohanasthana/dinas/tree/master/src/analysis/orca/"
    click DistHelper "https://github.com/rohanasthana/dinas/blob/master/src/analysis/dist_helper.py"
    click X11 "https://github.com/rohanasthana/dinas/tree/master/src/nasbenchx11/"
    click Utils "https://github.com/rohanasthana/dinas/blob/master/src/utils.py"
    click GenSamples "https://github.com/rohanasthana/dinas/blob/master/src/generate_samples.py"
    click JobScript "https://github.com/rohanasthana/dinas/blob/master/src/job_script.sh"
    click Predinas "https://github.com/rohanasthana/dinas/blob/master/src/predinas.sh"

    %% Styles
    classDef data fill:#D0E8FF,stroke:#005B96,stroke-width:2px
    classDef compute fill:#D5FFD0,stroke:#2E8B57,stroke-width:2px
    classDef orchestration fill:#FFE8B0,stroke:#D2691E,stroke-width:2px
    classDef evaluation fill:#E8D0FF,stroke:#800080,stroke-width:2px
    classDef external fill:#F0F0F0,stroke:#999999,stroke-width:2px
```
