# ntuaislab/bronet architecture

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

- Interactive diagram: https://gitdiagram.com/ntuaislab/bronet
- Repository: https://github.com/ntuaislab/bronet

## Overview

##### Project type and purpose
- This is a PyTorch‐based research codebase (“BRONet”) for training and evaluating Lipschitz‐constrained neural networks using two key innovations:
- Block Reflector Orthogonal Layers (BRO)
- Logit Annealing Loss (LA)
- It actually contains two sibling implementations:
- bronet/ – the “main” BRONet experiments, configs, training & test scripts
- lipconvnet/ – a standalone LipConvNet implementation with its own model, trainer, utils

##### File structure
Top level
- requirements.txt, README.md, LICENSE, THIRD_PARTY_LICENSES.md
bronet/
- configs/benchmark_reproduce/*.yaml – dataset & hyperparameter definitions
- models/ – model definition split into backbone, layers, margin_layer, head, neck, etc.
- tools/ – data pipelines (dataloader, cifar/imagenet parsers), scheduler, env setup
- train.py, test.py, run.sh, test.sh – CLI entry points for training & evaluation
- edm2_gen_script/ – scripts to generate synthetic images for the “EDM2” setting
lipconvnet/
- main.py, run.sh – CLI entry point for training & testing LipConvNet
- models/ – layers implementations (BRO, SOC, LOT, custom linear, etc.)
- trainer/ – Trainer, Evaluator, Base classes orchestrating forward/backward loops
- utils/ – custom activations, loss functions, scheduler wrappers, data utils, misc

##### Insights from README
- The project depends on Python 3.11 and PyTorch ≥ 2.0 with CUDA
- High‐level pipeline: load a config → initialize data loaders → build model → train with LA loss and orthogonal layers → evaluate/certify → save checkpoints
- Pretrained weights live on HuggingFace; test flags and distributed launch demonstrated

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% BRONet pipeline
    subgraph "BRONet" 
        direction TB
        cfg["Configuration Manager"]:::core
        data["Data Ingestion & Preprocessing"]:::core
        subgraph "Datasets"
            direction TB
            cifar["CIFAR Loader"]:::core
            imagenet_dataset["ImageNet Loader"]:::core
            parse_tiny["Parse TinyImageNet"]:::core
            tinyimgnet["TinyImageNet Loader"]:::core
            dataloader["Generic Dataloader"]:::core
        end
        edm2["Synthetic EDM2 Generator"]:::core
        model_b["Model Definition Layer"]:::core
        train_b["Training Engine"]:::core
        eval_b["Evaluation & Testing"]:::core
    end

    %% LipConvNet pipeline
    subgraph "LipConvNet"
        direction TB
        data_l["Data Ingestion & Preprocessing"]:::core
        model_l["Model Definition Layer"]:::core
        train_l["Training Engine"]:::core
        eval_l["Evaluation & Testing"]:::core
    end

    %% Utilities & Scripts
    subgraph "Utilities & Scripts"
        direction TB
        scripts_bronet["BRONet CLI Scripts"]:::util
        scripts_lip["LipConvNet CLI & Main"]:::util
        env_sched["Env Setup & Schedulers"]:::util
        loss_util["Loss & Eval Utils"]:::util
        config_files["Requirements & Licenses"]:::util
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        gpu["GPU Cluster (CUDA)"]:::external
        hf["HuggingFace Checkpoint Store"]:::external
    end

    %% Storage
    checkpoints["Checkpoint Storage"]:::storage

    %% Connections BRONet
    cfg -->|YAML → Parser| data
    data --> cifar
    data --> imagenet_dataset
    data --> parse_tiny
    data --> tinyimgnet
    data --> dataloader
    data --> model_b
    edm2 --> data
    model_b --> train_b
    train_b --> checkpoints
    train_b --> eval_b
    checkpoints --> hf
    train_b -->|Logs & Metrics| scripts_bronet

    %% Connections LipConvNet
    data_l --> model_l
    model_l --> train_l
    train_l --> checkpoints
    train_l --> eval_l
    eval_l -->|Logs & Metrics| loss_util
    scripts_lip --> train_l

    %% Utilities connections
    scripts_bronet --> cfg
    scripts_bronet --> train_b
    scripts_bronet --> eval_b
    env_sched --> train_b
    env_sched --> train_l
    loss_util --> eval_l
    config_files --> scripts_bronet
    config_files --> scripts_lip

    %% External connections
    train_b --> gpu
    train_l --> gpu
    hf --> eval_b

    %% Click Events
    click cfg "https://github.com/ntuaislab/bronet/blob/main/bronet/configs/benchmark_reproduce/*.yaml"
    click cifar "https://github.com/ntuaislab/bronet/blob/main/bronet/tools/dataset/cifar.py"
    click imagenet_dataset "https://github.com/ntuaislab/bronet/blob/main/bronet/tools/dataset/imagenet_dataset.py"
    click parse_tiny "https://github.com/ntuaislab/bronet/blob/main/bronet/tools/dataset/parse_tinyimgnet.py"
    click tinyimgnet "https://github.com/ntuaislab/bronet/blob/main/bronet/tools/dataset/tinyimgnet.py"
    click dataloader "https://github.com/ntuaislab/bronet/blob/main/bronet/tools/dataset/dataloader.py"
    click data_l "https://github.com/ntuaislab/bronet/blob/main/lipconvnet/utils/data.py"
    click gen_sh "https://github.com/ntuaislab/bronet/blob/main/bronet/edm2_gen_script/generate.sh"
    click gen_py "https://github.com/ntuaislab/bronet/blob/main/bronet/edm2_gen_script/generate_images_subfolder_save.py"
    click backbone "https://github.com/ntuaislab/bronet/blob/main/bronet/models/backbone.py"
    click stem "https://github.com/ntuaislab/bronet/blob/main/bronet/models/stem.py"
    click ortho_v2 "https://github.com/ntuaislab/bronet/blob/main/bronet/models/orthoconv_v2.py"
    click soc_bronet "https://github.com/ntuaislab/bronet/blob/main/bronet/models/soc.py"
    click bro_lip "https://github.com/ntuaislab/bronet/blob/main/lipconvnet/models/layers/bro.py"
    click soc_lip "https://github.com/ntuaislab/bronet/blob/main/lipconvnet/models/layers/soc.py"
    click lot_lip "https://github.com/ntuaislab/bronet/blob/main/lipconvnet/models/layers/lot.py"
    click margin_b "https://github.com/ntuaislab/bronet/blob/main/bronet/models/margin_layer.py"
    click custom_loss "https://github.com/ntuaislab/bronet/blob/main/lipconvnet/utils/custom_loss.py"
    click head "https://github.com/ntuaislab/bronet/blob/main/bronet/models/head.py"
    click neck "https://github.com/ntuaislab/bronet/blob/main/bronet/models/neck.py"
    click model_b "https://github.com/ntuaislab/bronet/blob/main/bronet/models/model.py"
    click lip_convnets "https://github.com/ntuaislab/bronet/blob/main/lipconvnet/models/lip_convnets.py"
    click lip_block "https://github.com/ntuaislab/bronet/blob/main/lipconvnet/models/lip_block.py"
    click train_py "https://github.com/ntuaislab/bronet/blob/main/bronet/train.py"
    click scheduler "https://github.com/ntuaislab/bronet/blob/main/bronet/tools/scheduler.py"
    click env_set "https://github.com/ntuaislab/bronet/blob/main/bronet/tools/set_env.py"
    click trainer_py "https://github.com/ntuaislab/bronet/blob/main/lipconvnet/trainer/trainer.py"
    click base_py "https://github.com/ntuaislab/bronet/blob/main/lipconvnet/trainer/base.py"
    click custom_sched "https://github.com/ntuaislab/bronet/blob/main/lipconvnet/utils/custom_scheduler.py"
    click test_py "https://github.com/ntuaislab/bronet/blob/main/bronet/test.py"
    click evaluator "https://github.com/ntuaislab/bronet/blob/main/lipconvnet/trainer/evaluator.py"
    click eval_util "https://github.com/ntuaislab/bronet/blob/main/lipconvnet/utils/eval.py"
    click run_bronet "https://github.com/ntuaislab/bronet/blob/main/bronet/run.sh"
    click test_bronet "https://github.com/ntuaislab/bronet/blob/main/bronet/test.sh"
    click run_lip "https://github.com/ntuaislab/bronet/blob/main/lipconvnet/run.sh"
    click main_lip "https://github.com/ntuaislab/bronet/blob/main/lipconvnet/main.py"
    click req "https://github.com/ntuaislab/bronet/blob/main/requirements.txt"
    click lic "https://github.com/ntuaislab/bronet/tree/main/LICENSE"
    click third_party "https://github.com/ntuaislab/bronet/blob/main/THIRD_PARTY_LICENSES.md"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#1F618D,color:#1F618D
    classDef util fill:#D5F5E3,stroke:#239B56,color:#239B56
    classDef external fill:#FAD7A0,stroke:#B9770E,color:#B9770E
    classDef storage fill:#F5CBA7,stroke:#9A7D0A,color:#9A7D0A
```
