# kebab-mai-haddi/eeg_simulator architecture

> Architecture diagram of the GitHub repository kebab-mai-haddi/eeg_simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kebab-mai-haddi/eeg_simulator
- Repository: https://github.com/kebab-mai-haddi/eeg_simulator

## Overview

##### Project Type and Purpose
- This is a research-oriented Python library implementing the Kinetic LGN model to simulate EEG readings.
- It ingests real EEG recordings, preprocesses them, runs a simulation, alters parameters for new brain states, and compares/plots results.

##### Main Architectural Components
a. Data Sources
- Sample Emotiv Recordings (folder: sample_emotiv_recordings)
- Stored simulation and real-EEG artifacts (folder: objects)
- Research documentation (folder: research_papers)
b. Data Preprocessing
- preprocessing_eeg.py cleans and normalizes raw EEG data before comparison
c. Simulation Engine
- simulation_model.py implements the Kinetic LGN model
- train_simulator_for_new_state_of_brain.xml and eeg_simulator_architecture.xml (configuration/architecture metadata)
d. Parameter Alteration
- altering.py adjusts model parameters to fit a new activity (e.g., gaming)
e. Testing & Visualization
- running_tests.py plots standard vs. simulated signals for validation
f. Configuration & Dependencies
- requirements.txt lists Python libraries (e.g., NumPy, Matplotlib)
- XML files (eeg_simulator_flow_of_control.xml) describe internal control flow

##### Relationships and Data Flow
1. Real EEG Input → Preprocessor
2. Simulation Engine ← Parameters
3. Comparison & Validation
4. Artifacts Storage
- simulation outputs and real EEG arrays stored/loaded in objects/

##### Architectural Patterns & Principles
- Pipeline pattern: Data flows through stages (Load → Preprocess → Simulate → Analyze)
- Single Responsibility: Each script has one clear purpose (simulation, alteration, preprocessing, testing)
- Config-Driven: XML files define parameters and control flow, enabling experimentation without code changes

##### Essential Elements
- Clear labels for each Python script and directory.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources
    subgraph "Data Sources"
        sample_emotiv["Sample Emotiv Recordings"]:::datastore
        objects["Objects (EEG & Simulation Artifacts)"]:::datastore
        research_papers["Research Documentation"]:::research
    end

    %% Processing Modules
    subgraph "Processing Pipeline"
        preprocess["preprocessing_eeg.py"]:::module
        simulator["simulation_model.py"]:::module
        altering["altering.py"]:::module
        tester["running_tests.py"]:::module
    end

    %% Configuration & Dependencies
    subgraph "Configuration & Dependencies"
        xml_arch["eeg_simulator_architecture.xml"]:::config
        xml_flow["eeg_simulator_flow_of_control.xml"]:::config
        xml_train["train_simulator_for_new_state_of_brain.xml"]:::config
        req["requirements.txt"]:::config
    end

    %% Data Flow
    sample_emotiv -->|"raw EDF files"| preprocess
    preprocess -->|"cleaned time-series"| objects
    objects -->|"access real EEG arrays"| tester

    xml_arch -->|"model config"| simulator
    xml_flow -->|"control flow"| simulator
    xml_train -->|"training parameters"| simulator
    altering -->|"parameter overrides"| simulator
    simulator -->|"simulated EEG output"| objects

    objects -->|"access simulated EEG arrays"| tester
    tester -->|"insights for tuning"| altering

    %% Optional Research Docs
    research_papers -.-> preprocess
    research_papers -.-> simulator
    research_papers -.-> altering

    %% Click Events
    click sample_emotiv "https://github.com/kebab-mai-haddi/eeg_simulator/tree/master/sample_emotiv_recordings/"
    click objects "https://github.com/kebab-mai-haddi/eeg_simulator/tree/master/objects/"
    click research_papers "https://github.com/kebab-mai-haddi/eeg_simulator/tree/master/research_papers/"
    click preprocess "https://github.com/kebab-mai-haddi/eeg_simulator/blob/master/preprocessing_eeg.py"
    click simulator "https://github.com/kebab-mai-haddi/eeg_simulator/blob/master/simulation_model.py"
    click xml_arch "https://github.com/kebab-mai-haddi/eeg_simulator/blob/master/eeg_simulator_architecture.xml"
    click xml_flow "https://github.com/kebab-mai-haddi/eeg_simulator/blob/master/eeg_simulator_flow_of_control.xml"
    click xml_train "https://github.com/kebab-mai-haddi/eeg_simulator/blob/master/train_simulator_for_new_state_of_brain.xml"
    click altering "https://github.com/kebab-mai-haddi/eeg_simulator/blob/master/altering.py"
    click tester "https://github.com/kebab-mai-haddi/eeg_simulator/blob/master/running_tests.py"
    click req "https://github.com/kebab-mai-haddi/eeg_simulator/blob/master/requirements.txt"

    %% Styles
    classDef datastore fill:#e0ffe0,stroke:#2d8f2d,color:#2d8f2d;
    classDef module fill:#e0f0ff,stroke:#1a4fa0,color:#1a4fa0;
    classDef config fill:#fff4e0,stroke:#a05a1a,color:#a05a1a;
    classDef research fill:none,stroke:#aaa,stroke-dasharray: 5 5,color:#aaa;
```
