# bxptr/cerebrum architecture

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

- Interactive diagram: https://gitdiagram.com/bxptr/cerebrum
- Repository: https://github.com/bxptr/cerebrum

## Overview

##### Main Components

A. Data Pipeline Layer:
- Data Loading Component (data_loader.py)
- Data Processing Component (download_and_process_data.py)
- Network Generation Component (generate_network.py)

B. Model Layer:
- Core Neural Components:
- Hodgkin-Huxley Solver (hh_solver.py)
- GNN Model (gnn_model.py)
- Synaptic Plasticity Module (stp.py)
- Integration Components:
- Combined Model (combined_model.py)
- Connectivity Inference Model (connectivity_inference_model.py)
- Integrator (integrator.py)
- Neuron Editor Component (neuron_editor.py)

C. Utility Layer:
- Analysis Tools (analysis.py)
- Metrics System (metrics.py)
- Visualization Engine (visualization.py)
- Training Framework (training.py)
- Logging System (logging_utils.py)

##### Specific Flow Representations

**[Config] → Controls all components**
- ↓
**[Data Pipeline] → [Model Layer] → [Utility Layer]**

The main execution flow should follow:
**[Data Loader] → [GNN Model] → [Combined Model] → [Analysis/Visualization]**

##### Key Design Elements

a. Following architectural patterns:
- Pipeline pattern for data processing
- Modular design for model components
- Observer pattern for logging and metrics

- GNN Model ↔ Connectivity Inference Model
- Combined Model ↔ Integrator
- HH Solver ↔ STP Module

##### Technical Details

- Input/Output formats between components
- Key parameters from config.py affecting each component
- Computational flow during training and inference
- Data transformation stages

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef config fill:#f9f,stroke:#333
    classDef data fill:#aef,stroke:#333
    classDef model fill:#bfb,stroke:#333
    classDef integration fill:#ffb,stroke:#333
    classDef utility fill:#e7d,stroke:#333
    
    %% Config Layer
    Config[Config]:::config
    click Config "https://github.com/bxptr/cerebrum/blob/master/config.py"
    
    %% Data Pipeline Layer
    subgraph DataLayer["Data Pipeline Layer"]
        DataLoader["Data Loader"]:::data
        DataProcessor["Data Processor"]:::data
        NetworkGen["Network Generator"]:::data
        
        DataLoader --> DataProcessor
        DataProcessor --> NetworkGen
    end
    click DataLoader "https://github.com/bxptr/cerebrum/blob/master/data/data_loader.py"
    click DataProcessor "https://github.com/bxptr/cerebrum/blob/master/data/download_and_process_data.py"
    click NetworkGen "https://github.com/bxptr/cerebrum/blob/master/data/generate_network.py"
    
    %% Model Layer
    subgraph ModelLayer["Model Layer"]
        subgraph CoreNeural["Core Neural Components"]
            HHSolver["Hodgkin-Huxley Solver"]:::model
            GNNModel["GNN Model"]:::model
            STPModule["Synaptic Plasticity"]:::model
            
            HHSolver <--> STPModule
            GNNModel <--> STPModule
        end
        
        subgraph Integration["Integration Components"]
            CombinedModel["Combined Model"]:::integration
            ConnInference["Connectivity Inference"]:::integration
            Integrator["Integrator"]:::integration
            NeuronEditor["Neuron Editor"]:::integration
            
            CombinedModel <--> Integrator
            ConnInference <--> GNNModel
            NeuronEditor --> CombinedModel
        end
    end
    click HHSolver "https://github.com/bxptr/cerebrum/blob/master/models/hh_solver.py"
    click GNNModel "https://github.com/bxptr/cerebrum/blob/master/models/gnn_model.py"
    click STPModule "https://github.com/bxptr/cerebrum/blob/master/models/stp.py"
    click CombinedModel "https://github.com/bxptr/cerebrum/blob/master/models/combined_model.py"
    click ConnInference "https://github.com/bxptr/cerebrum/blob/master/models/connectivity_inference_model.py"
    click Integrator "https://github.com/bxptr/cerebrum/blob/master/models/integrator.py"
    click NeuronEditor "https://github.com/bxptr/cerebrum/blob/master/models/neuron_editor.py"
    
    %% Utility Layer
    subgraph UtilityLayer["Utility Layer"]
        Analysis["Analysis Tools"]:::utility
        Metrics["Metrics System"]:::utility
        Visualization["Visualization Engine"]:::utility
        Training["Training Framework"]:::utility
        Logging["Logging System"]:::utility
        
        Analysis --> Visualization
        Metrics --> Analysis
        Training --> Metrics
        Logging --> Metrics
    end
    click Analysis "https://github.com/bxptr/cerebrum/blob/master/utils/analysis.py"
    click Metrics "https://github.com/bxptr/cerebrum/blob/master/utils/metrics.py"
    click Visualization "https://github.com/bxptr/cerebrum/blob/master/utils/visualization.py"
    click Training "https://github.com/bxptr/cerebrum/blob/master/utils/training.py"
    click Logging "https://github.com/bxptr/cerebrum/blob/master/utils/logging_utils.py"
    
    %% Experiment Runner
    ExpRunner["Experiment Runner"]:::config
    click ExpRunner "https://github.com/bxptr/cerebrum/blob/master/run_experiments.py"
    
    %% Connections between layers
    Config --> DataLayer
    Config --> ModelLayer
    Config --> UtilityLayer
    Config --> ExpRunner
    
    DataLayer --> ModelLayer
    ModelLayer --> UtilityLayer
    ExpRunner --> DataLayer
    ExpRunner --> ModelLayer
    ExpRunner --> UtilityLayer
    
    %% Legend
    subgraph Legend
        L1[Config Components]:::config
        L2[Data Components]:::data
        L3[Model Components]:::model
        L4[Integration Components]:::integration
        L5[Utility Components]:::utility
    end
```
