How lens-tugraz/apex works
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.)