# lens-tugraz/apex architecture

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

- Interactive diagram: https://gitdiagram.com/lens-tugraz/apex
- Repository: https://github.com/lens-tugraz/apex

## Overview

##### Project type and purpose
- Type: An open-source Python framework/tool (APEX) for automated parameter exploration and optimization in low-power wireless protocols.
- Purpose: Given user-defined application requirements (ARs) and protocol parameter ranges, schedule experiments (either using pre-recorded data or the D-Cube testbed), collect results, fit surrogate models, and select the next test points to converge on optimal protocol settings.

##### File structure
- Top-level:
- APEX/: core modules (test environments, algorithms, utilities)
- config/: YAML files specifying ARs, parameter constraints, termination criteria, D-Cube API key
- Binaries/: firmware images + metadata (used by DCubeTestEnvironment)
- Results/: recorded and evaluation outputs, organized by protocol and algorithm (EI, GP-LCB, etc.)
- Main.py: entry point orchestrator
- Patterns:
- Strategy/Factory pattern for TestEnvironment (AbstractTestEnvironment → Recorded / DCube)
- Modular “next point selection” algorithms in Next_Testpoint_Selection.py
- ResultsStorage abstraction for writing JSON results

##### README for additional insights
- The README confirms the two environment options, lists the algorithms (EI, GP-LCB, GEL, GUC, RL, SVM), and details user configuration and execution steps.

a. Main components
1. User Configuration Layer
– config/*.yaml
2. Orchestrator / Controller
– Main.py
3. Test Environment Interface
– AbstractTestEnvironment
– RecordedTestEnvironment
– DCubeTestEnvironment (uses D-Cube API & Binaries)
4. Next Test Point Selector
– Next_Testpoint_Selection module implementing EI, GP-LCB, GEL, GUC, RL, SVM
5. Model Fitting Module
– model_fitting.py
6. Results Storage Module
– ResultsStorage.py / ResultsStorage_LR.py
7. External Services & Resources
– D-Cube testbed API
– Firmware binaries (Binaries/Crystal, Binaries/RPL)
8. File System Output
– Results/ (recorded, evaluation, synthetic data)

b. Relationships & interactions
1. On startup, Main.py loads config/*.yaml → instantiates the chosen TestEnvironment.
2. Main.py loops:
– Calls TestEnvironment.run_experiment(parameters)
- If Recorded, fetches data from Results/Recorded
- If DCube, pushes firmware & parameters to D-Cube via API, polls for completion, retrieves measurements
– Measurements returned to Main → forwarded to ResultsStorage → writes JSON under Results/…
– ModelFitting fits or updates surrogate model from all stored data.
– Next_Testpoint_Selection takes the surrogate model + ARs → returns next parameter set.
– Repeat until termination criteria (from config) are met.
3. Synthetic data scripts (under Results/Synthetic_Data) can be plugged into RecordedTestEnvironment for offline evaluation.

c. Architectural patterns & principles
– Strategy/Factory: AbstractTestEnvironment with interchangeable concrete test environments
– Iterator/Loop: Main orchestrates repeated experiment→store→model→select cycles
– Separation of concerns: clear layers for configuration, experimentation, modeling, selection, and storage
– Extensibility: add new selection algorithms by extending Next_Testpoint_Selection; add new environments by subclassing AbstractTestEnvironment

d. Key technologies & libraries
– Python 3.x, YAML (PyYAML), JSON
– SciPy/NumPy/Scikit-Learn (for model_fitting)
– D-Cube REST API client (in DCubeTestEnvironment)
– Custom modules in APEX/ (Utilities.py, ResultsStorage, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Configuration Layer
    subgraph "User Configuration Layer"
        direction TB
        config1["crystal_config.yaml"]:::datastore
        config2["RPL_config.yaml"]:::datastore
        config3["dcubeKey.yaml"]:::datastore
    end

    %% Orchestrator
    main["Main.py"]:::internal

    %% Test Environment Interface
    subgraph "Test Environment Interface"
        direction TB
        abstractTE["AbstractTestEnvironment"]:::internal
        recordedTE["RecordedTestEnvironment"]:::internal
        dcubeTE["DCubeTestEnvironment"]:::internal
    end

    %% External Services & Resources
    subgraph "External Resources"
        direction TB
        dCubeAPI["D-Cube API"]:::external
        binCrystal["Binaries/Crystal"]:::external
        binRPL["Binaries/RPL"]:::external
    end

    %% Results Storage Modules
    subgraph "Results Storage"
        direction TB
        resStorage["ResultsStorage"]:::internal
        resStorageLR["ResultsStorage_LR"]:::internal
    end

    %% Utilities
    utils["Utilities.py"]:::internal

    %% Modeling and Selection
    modelFitting["model_fitting.py"]:::internal
    nextSelector["Next_Testpoint_Selection"]:::internal

    %% File System Output
    subgraph "Results File System"
        direction TB
        resTop["Results/"]:::datastore
        resSynth["Results/Synthetic_Data/"]:::datastore
        resEval["Results/Evaluation_Results/"]:::datastore
        resCrystalFile["Results/Crystal_results.json"]:::datastore
        resRPLFile["Results/RPL_results.json"]:::datastore
    end

    %% Connections
    config1 -->|"load config"| main
    config2 -->|"load config"| main
    config3 -->|"load credentials"| main

    main -->|"instantiate"| abstractTE
    abstractTE -->|"Recorded branch"| recordedTE
    abstractTE -->|"DCube branch"| dcubeTE

    recordedTE -->|"measurements"| main
    dcubeTE -->|"deploy & poll"| dCubeAPI
    dcubeTE -->|"use binaries"| binCrystal
    dcubeTE -->|"use binaries"| binRPL
    dCubeAPI -->|"measurements"| main

    main -->|"store results"| resStorage
    main -->|"store LR results"| resStorageLR

    resStorage -->|"writes to"| resTop
    resStorageLR -->|"writes to"| resTop

    resTop --> resSynth
    resTop --> resEval
    resTop --> resCrystalFile
    resTop --> resRPLFile

    resStorage -->|"data for modeling"| modelFitting
    modelFitting -->|"surrogate model"| nextSelector
    nextSelector -->|"next parameters"| main

    main --> utils

    %% Click Events
    click config1 "https://github.com/lens-tugraz/apex/blob/main/config/crystal_config.yaml"
    click config2 "https://github.com/lens-tugraz/apex/blob/main/config/RPL_config.yaml"
    click config3 "https://github.com/lens-tugraz/apex/blob/main/config/dcubeKey.yaml"
    click main "https://github.com/lens-tugraz/apex/blob/main/APEX/Main.py"
    click abstractTE "https://github.com/lens-tugraz/apex/blob/main/APEX/AbstractTestEnvironment.py"
    click recordedTE "https://github.com/lens-tugraz/apex/blob/main/APEX/RecordedTestEnvironment.py"
    click dcubeTE "https://github.com/lens-tugraz/apex/blob/main/APEX/DCubeTestEnvironment.py"
    click nextSelector "https://github.com/lens-tugraz/apex/blob/main/APEX/Next_Testpoint_Selection.py"
    click modelFitting "https://github.com/lens-tugraz/apex/blob/main/APEX/model_fitting.py"
    click resStorage "https://github.com/lens-tugraz/apex/blob/main/APEX/ResultsStorage.py"
    click resStorageLR "https://github.com/lens-tugraz/apex/blob/main/APEX/ResultsStorage_LR.py"
    click utils "https://github.com/lens-tugraz/apex/blob/main/APEX/Utilities.py"
    click binCrystal "https://github.com/lens-tugraz/apex/tree/main/Binaries/Crystal/"
    click binRPL "https://github.com/lens-tugraz/apex/tree/main/Binaries/RPL/"
    click resTop "https://github.com/lens-tugraz/apex/tree/main/Results/"
    click resSynth "https://github.com/lens-tugraz/apex/tree/main/Results/Synthetic_Data/"
    click resEval "https://github.com/lens-tugraz/apex/tree/main/Results/Evaluation_Results/"
    click resCrystalFile "https://github.com/lens-tugraz/apex/blob/main/Results/Crystal_results.json"
    click resRPLFile "https://github.com/lens-tugraz/apex/blob/main/Results/RPL_results.json"

    %% Styles
    classDef internal fill:#AEDFF7,stroke:#000,stroke-width:1px
    classDef external fill:#B7E4C7,stroke:#000,stroke-width:1px
    classDef datastore fill:#F9E79F,stroke:#000,stroke-width:1px
```
