# azizanlab/hardnet architecture

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

- Interactive diagram: https://gitdiagram.com/azizanlab/hardnet
- Repository: https://github.com/azizanlab/hardnet

## Overview

##### Project Type and Purpose
- This is a research‐oriented machine learning framework (“HardNet”) for constructing neural networks with built-in hard constraint enforcement.
- It includes code for dataset generation, model implementations (HardNet‐Aff, HardNet‐Cvx, various baselines), experiment orchestration, evaluation, and visualization.

##### File Structure Analysis
- Top-level scripts:
- hardnet_aff.py, hardnet_cvx.py – core model training entry points
- baseline_*.py – alternative methods for comparison
- test_nets.py – evaluation harness
- run_expers.sh – batch experiment runner
- exp_*.ipynb – Jupyter notebooks for interactive experiments and visualization
- datasets/ – code to generate and load different problem datasets (cbf, opt, pwc, pwcbox, pwcfull)
- utils.py & default_args.py – shared utilities and common configuration
- requirements.txt – Python dependencies
- LICENSE, README.md, .gitignore – documentation and project metadata

##### Key Components
A. Data Generation & Loading
- Subcomponents per problem type (cbf, opt, pwc, etc.)
- Scripts: datasets/*/make_dataset.py; problem definitions (.py)
B. Model Implementations
- HardNet modules: hardnet_aff.py, hardnet_cvx.py
- Baseline modules: baseline_nn.py, baseline_dc3.py, baseline_opt.py, baseline_cbfqp.py
- Default configuration via default_args.py
C. Experiment Orchestration
- run_expers.sh: loops over seeds & problem types, invokes Python scripts
- Command-line arguments parsed in each script
D. Evaluation & Metrics
- test_nets.py: loads trained models, computes performance statistics
- Outputs saved under expDir for later analysis
E. Visualization & Reporting
- Jupyter notebooks exp_*.ipynb: read results, generate plots and tables
F. Shared Utilities & Environment
- utils.py: data loaders, logging, metric computation
- requirements.txt → external libraries (e.g., PyTorch, NumPy)

##### Relationships & Data Flow
1. Data Generation → Dataset artifacts on disk
2. Training Script (hardnet_* or baseline_*)
- Reads dataset
- Applies utils for batching, logging
- Trains model → saves checkpoints & logs
3. Evaluation (test_nets.py)
- Loads checkpoints
- Computes metrics → writes summary files
4. Visualization (notebooks)
- Reads summary files
- Renders plots, tables for the paper
5. Batch Orchestration (run_expers.sh)
- Automates step 2 and 3 across multiple seeds & problem types

##### Architectural Patterns & Design Principles
- Modular Pipeline: clear separation of data, training, evaluation, and visualization
- Configurable via command-line arguments and default_args.py
- Reusability: shared utilities (utils.py) across scripts
- Extensibility: adding a new problem type only requires a new dataset subfolder and update to script arguments

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        Datasets["datasets/"]:::dataset
        CBF["CBF Dataset\nmake_dataset.py"]:::dataset
        OPT["OPT Dataset\nmake_dataset.py"]:::dataset
        PWC["PWC Dataset\nmake_dataset.py"]:::dataset
        PWCBOX["PWCBOX Dataset\nmake_dataset.py"]:::dataset
        PWCFULL["PWCFULL Dataset\nmake_dataset.py"]:::dataset
    end

    %% Model Layer
    subgraph "Model Layer"
        Aff["HardNet-Aff Model"]:::model
        Cvx["HardNet-Cvx Model"]:::model
        BNN["Baseline NN"]:::model
        BDC3["Baseline DC3"]:::model
        BOPT["Baseline OPT"]:::model
        BQP["Baseline CBF-QP"]:::model
        Utils["Shared Utilities\nutils.py"]:::orchestration
        Args["Default Config\ndefault_args.py"]:::orchestration
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        Run["Experiment Runner\nrun_expers.sh"]:::orchestration
    end

    %% Evaluation Layer
    subgraph "Evaluation Layer"
        Test["Evaluation Harness\ntest_nets.py"]:::evaluation
    end

    %% Visualization Layer
    subgraph "Visualization Layer"
        EC["Notebook: exp_cbf.ipynb"]:::notebook
        EG["Notebook: exp_gradient.ipynb"]:::notebook
        EO["Notebook: exp_opt.ipynb"]:::notebook
        EP["Notebook: exp_pwc.ipynb"]:::notebook
        EPB["Notebook: exp_pwcbox.ipynb"]:::notebook
    end

    %% Data to Models
    Datasets -->|"raw .csv datasets"|Aff
    Datasets -->|"raw .csv datasets"|Cvx
    Datasets -->|"raw .csv datasets"|BNN
    Datasets -->|"raw .csv datasets"|BDC3
    Datasets -->|"raw .csv datasets"|BOPT
    Datasets -->|"raw .csv datasets"|BQP

    %% Utilities and Config
    Utils --> Aff
    Utils --> Cvx
    Utils --> BNN
    Utils --> BDC3
    Utils --> BOPT
    Utils --> BQP
    Args --> Aff
    Args --> Cvx
    Args --> BNN
    Args --> BDC3
    Args --> BOPT
    Args --> BQP

    %% Orchestration
    Run --> Aff
    Run --> Cvx
    Run --> BNN
    Run --> BDC3
    Run --> BOPT
    Run --> BQP
    Run --> Test

    %% Training to Evaluation
    Aff -->|".pt model checkpoints"| Test
    Cvx -->|".pt model checkpoints"| Test
    BNN -->|".pt model checkpoints"| Test
    BDC3 -->|".pt model checkpoints"| Test
    BOPT -->|".pt model checkpoints"| Test
    BQP -->|".pt model checkpoints"| Test

    %% Evaluation to Visualization
    Test -->|".json metrics"| EC
    Test -->|".json metrics"| EG
    Test -->|".json metrics"| EO
    Test -->|".json metrics"| EP
    Test -->|".json metrics"| EPB

    %% Click Events
    click Datasets "https://github.com/azizanlab/hardnet/tree/main/datasets/"
    click CBF "https://github.com/azizanlab/hardnet/blob/main/datasets/cbf/make_dataset.py"
    click OPT "https://github.com/azizanlab/hardnet/blob/main/datasets/opt/make_dataset.py"
    click PWC "https://github.com/azizanlab/hardnet/blob/main/datasets/pwc/make_dataset.py"
    click PWCBOX "https://github.com/azizanlab/hardnet/blob/main/datasets/pwcbox/make_dataset.py"
    click PWCFULL "https://github.com/azizanlab/hardnet/blob/main/datasets/pwcfull/make_dataset.py"
    click Aff "https://github.com/azizanlab/hardnet/blob/main/hardnet_aff.py"
    click Cvx "https://github.com/azizanlab/hardnet/blob/main/hardnet_cvx.py"
    click BNN "https://github.com/azizanlab/hardnet/blob/main/baseline_nn.py"
    click BDC3 "https://github.com/azizanlab/hardnet/blob/main/baseline_dc3.py"
    click BOPT "https://github.com/azizanlab/hardnet/blob/main/baseline_opt.py"
    click BQP "https://github.com/azizanlab/hardnet/blob/main/baseline_cbfqp.py"
    click Utils "https://github.com/azizanlab/hardnet/blob/main/utils.py"
    click Args "https://github.com/azizanlab/hardnet/blob/main/default_args.py"
    click Run "https://github.com/azizanlab/hardnet/blob/main/run_expers.sh"
    click Test "https://github.com/azizanlab/hardnet/blob/main/test_nets.py"
    click EC "https://github.com/azizanlab/hardnet/blob/main/exp_cbf.ipynb"
    click EG "https://github.com/azizanlab/hardnet/blob/main/exp_gradient.ipynb"
    click EO "https://github.com/azizanlab/hardnet/blob/main/exp_opt.ipynb"
    click EP "https://github.com/azizanlab/hardnet/blob/main/exp_pwc.ipynb"
    click EPB "https://github.com/azizanlab/hardnet/blob/main/exp_pwcbox.ipynb"

    %% Styles
    classDef dataset fill:#b7e4c7,stroke:#2b9348,color:#2b9348;
    classDef model fill:#89c2d9,stroke:#386fa4,color:#1b263b;
    classDef orchestration fill:#adb5bd,stroke:#495057,color:#343a40;
    classDef evaluation fill:#f08080,stroke:#c1121f,color:#6a040f;
    classDef notebook fill:#ffd166,stroke:#f4a261,color:#663f00;
```
