# b-cos/b-cos-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/b-cos/b-cos-v2
- Repository: https://github.com/b-cos/b-cos-v2

## Overview

##### Main Components

a) Core Architecture Components:
- Model Architecture Layer
- Base Models (ResNet, DenseNet, VGG, ConvNext, ViT variants)
- B-cos Specific Modules (BCOSConv2d, BCOSLinear)
- Normalization Modules (Centered and Uncentered)

- Data Processing Layer
- Data Loading & Caching System
- Transforms Pipeline
- Sampling Mechanisms

- Training Infrastructure
- Training Loop Management
- Optimization Components
- Callbacks System

- Interpretability Framework
- Explanation Methods
- Analysis Tools
- Visualization Components

b) Supporting Components:
- Configuration Management
- Experiment Management
- Model Zoo Interface
- Evaluation Pipeline

##### Component Relationships and Data Flow

**[Input Data] → [Data Processing Layer]**
- ↓
**[Model Architecture Layer] ← [B-cos Specific Modules]**
- ↓
**[Training Infrastructure] ← [Optimization Components]**
- ↓
**[Interpretability Framework]**
- ↓
**[Evaluation & Analysis]**

##### Specific Implementation Details

- Rectangles: Core processing modules
- Hexagons: Data storage/caching components
- Diamonds: Decision points/configuration
- Rounded rectangles: External interfaces

- Blue: Core model components
- Green: Data processing
- Orange: Training infrastructure
- Purple: Interpretability components
- Gray: Utility/support components

##### Key Architectural Patterns to Highlight

a) Modular Design:
- Clear separation between model definitions, training infrastructure, and interpretability components
- Plugin architecture for different model types

b) Data Flow:
- Caching mechanism with Redis/SHM
- Transform pipeline flow

c) Training Pipeline:
- Demonstrate the interaction between trainer, callbacks, and metrics tracking
- Optimization loop with learning rate scheduling

- Data Pipeline     |

- CachedImageFolder   |
- Data Transforms     |
- Sampling Logic      |

- Model Components   |

- Base Networks       |
- B-cos Modules       |
- Normalization       |

- Training Pipeline    |

- Trainer             |
- Callbacks           |
- Optimization        |

- Interpretability      |

- Explainers          |
- Analysis Tools      |
- Visualization       |

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Data["Data Processing Layer"]
        DL[Data Loading]
        DP["Data Processing"]:::data
        Cache["Caching System"]:::data
        Trans["Transforms Pipeline"]:::data
        Samp["Sampling Mechanisms"]:::data
        
        DL --> Cache
        Cache --> DP
        DP --> Trans
        Trans --> Samp
    end

    subgraph Models["Model Architecture Layer"]
        direction TB
        BaseM["Base Models"]:::model
        BCOS["B-cos Modules"]:::bcos
        Norm["Normalization"]:::model
        
        subgraph BaseModels["Base Model Types"]
            ResNet["ResNet"]:::model
            DenseNet["DenseNet"]:::model
            VGG["VGG"]:::model
            ConvNext["ConvNext"]:::model
            ViT["ViT"]:::model
        end
        
        subgraph BCOSModules["B-cos Components"]
            Conv["BCOSConv2d"]:::bcos
            Linear["BCOSLinear"]:::bcos
        end
        
        subgraph NormModules["Normalization Types"]
            Centered["Centered Norms"]:::model
            Uncentered["Uncentered Norms"]:::model
        end
        
        BaseModels --> BaseM
        BCOSModules --> BCOS
        NormModules --> Norm
    end

    subgraph Training["Training Infrastructure"]
        Train["Trainer"]:::training
        Opt["Optimization"]:::training
        Call["Callbacks"]:::training
        
        subgraph OptComp["Optimization Components"]
            OptF["Optimizer Factory"]:::training
            LRF["LR Scheduler Factory"]:::training
        end
        
        subgraph CallbackSystem["Callback Components"]
            ExpLog["Explanation Logger"]:::training
            MetTrack["Metrics Tracker"]:::training
        end
        
        OptComp --> Opt
        CallbackSystem --> Call
    end

    subgraph Interpret["Interpretability Framework"]
        Explain["Explanation Methods"]:::interp
        Analysis["Analysis Tools"]:::interp
        Vis["Visualization"]:::interp
        
        Explain --> Analysis
        Analysis --> Vis
    end

    subgraph Support["Supporting Systems"]
        Config["Configuration Management"]:::support
        ExpMgmt["Experiment Management"]:::support
        ModelZoo["Model Zoo Interface"]:::support
        Eval["Evaluation Pipeline"]:::support
    end

    Data --> Models
    Models --> Training
    Training --> Interpret
    Support --> Models
    Support --> Training

    classDef model fill:#3498db,stroke:#2980b9,color:white
    classDef bcos fill:#e74c3c,stroke:#c0392b,color:white
    classDef data fill:#2ecc71,stroke:#27ae60,color:white
    classDef training fill:#f1c40f,stroke:#f39c12,color:black
    classDef interp fill:#9b59b6,stroke:#8e44ad,color:white
    classDef support fill:#95a5a6,stroke:#7f8c8d,color:white

    click ResNet "https://github.com/B-cos/B-cos-v2/blob/main/bcos/models/resnet.py"
    click DenseNet "https://github.com/B-cos/B-cos-v2/blob/main/bcos/models/densenet.py"
    click VGG "https://github.com/B-cos/B-cos-v2/blob/main/bcos/models/vgg.py"
    click ConvNext "https://github.com/B-cos/B-cos-v2/blob/main/bcos/models/convnext.py"
    click ViT "https://github.com/B-cos/B-cos-v2/blob/main/bcos/models/vit.py"
    click Conv "https://github.com/B-cos/B-cos-v2/blob/main/bcos/modules/bcosconv2d.py"
    click Linear "https://github.com/B-cos/B-cos-v2/blob/main/bcos/modules/bcoslinear.py"
    click Centered "https://github.com/B-cos/B-cos-v2/blob/main/bcos/modules/norms/centered_norms.py"
    click Uncentered "https://github.com/B-cos/B-cos-v2/tree/main/bcos/modules/norms/uncentered_norms/"
    click Trans "https://github.com/B-cos/B-cos-v2/blob/main/bcos/data/transforms.py"
    click Cache "https://github.com/B-cos/B-cos-v2/tree/main/bcos/data/caching/cached_imagefolder/"
    click Samp "https://github.com/B-cos/B-cos-v2/blob/main/bcos/data/sampler.py"
    click Train "https://github.com/B-cos/B-cos-v2/blob/main/bcos/training/trainer.py"
    click Call "https://github.com/B-cos/B-cos-v2/tree/main/bcos/training/callbacks/"
    click OptF "https://github.com/B-cos/B-cos-v2/blob/main/bcos/optim/optimizer_factory.py"
    click LRF "https://github.com/B-cos/B-cos-v2/blob/main/bcos/optim/lr_scheduler_factory.py"
    click Explain "https://github.com/B-cos/B-cos-v2/tree/main/interpretability/explanation_methods/explainers/"
    click Analysis "https://github.com/B-cos/B-cos-v2/blob/main/interpretability/analyses/localisation.py"
    click Vis "https://github.com/B-cos/B-cos-v2/blob/main/interpretability/analyses/utils.py"
    click ExpMgmt "https://github.com/B-cos/B-cos-v2/tree/main/bcos/experiments/utils/experiment_utils/"
    click Config "https://github.com/B-cos/B-cos-v2/blob/main/bcos/experiments/utils/config_utils.py"
    click ModelZoo "https://github.com/B-cos/B-cos-v2/blob/main/bcos/models/pretrained.py"
    click ExpLog "https://github.com/B-cos/B-cos-v2/blob/main/bcos/training/callbacks/explanation_logger.py"
    click MetTrack "https://github.com/B-cos/B-cos-v2/blob/main/bcos/training/callbacks/metricstracker.py"
```
