Anda_Gabriela_Barbu-BS_Thesis

README.md

@@ -76,8 +76,70 @@ python experiment-runner/ <MyRunnerConfig.py>
 
 The results of the experiment will be stored in the directory `RunnerConfig.results_output_path/RunnerConfig.name` as defined by your config variables.
 
+### Portability Across Users and Machines
+
+When sharing experiments across different users or machines, hardcoded paths in configuration files can cause issues. Experiment Runner supports **environment variables** to make your experiments portable without code changes:
+
+#### Available Environment Variables
+
+- **`EXPERIMENT_RUNNER_OUTPUT_PATH`**: Directory where experiment results are stored
+  - Default: `<config-directory>/experiments`
+  - Example: `export EXPERIMENT_RUNNER_OUTPUT_PATH="/path/to/results"`
+
+- **`ENERGIBRIDGE_PATH`**: Path to the EnergiBridge executable (for energy measurements)
+  - Default: `/usr/local/bin/energibridge`
+  - Example: `export ENERGIBRIDGE_PATH="/usr/local/bin/energibridge"`
+
+- **`EXAMPLES_PATH`**: Directory for generating new config templates
+  - Default: `<project-root>/examples`
+  - Example: `export EXAMPLES_PATH="/home/user/my-experiments"`
+
+#### Using Environment Variables
+
+Set environment variables before running your experiment:
+
+```bash
+export EXPERIMENT_RUNNER_OUTPUT_PATH="/data/experiments"
+export ENERGIBRIDGE_PATH="/opt/energibridge/bin/energibridge"
+python experiment-runner/ MyRunnerConfig.py
+```
+
+Your configuration files automatically use these variables if set, with sensible defaults when they are not. This allows the same experiment to run on different machines without any code modifications.
+
 **More information about the profilers and use cases can be found in the [Wiki tab](https://github.com/S2-group/experiment-runner/wiki).**
 
+---
+## Remote distribution
+
+Experiment Runner supports **distributed execution across multiple machines** using a master–worker architecture.
+
+### Architecture Overview
+
+- One machine acts as the **Master (Orchestrator)**
+  - Owns the experiment `run_table`
+  - Assigns runs to workers via a REST API
+  - Tracks progress and persists experiment state
+  - Triggers lifecycle events (e.g. `AFTER_EXPERIMENT`) when finished
+
+- Multiple machines act as **Workers**
+  - Request tasks from the master
+  - Execute runs locally using the configured experiment
+  - Submit results back to the master
+
+- Communication between master and workers is handled via a lightweight **Flask-based HTTP API**
+
+### How to run it
+Start the orchestrator on the master machine:
+ ```bash
+python experiment-runner/ examples/<example-dir>/<RunnerConfig*.py> --distribute master <host host_nr --port port_nr>
+```
+On each worker machine, connect to the master:
+```bash
+experiment-runner/ examples/<example-dir>/<RunnerConfig*.py> --distribute worker --master <orchestor_adress>
+```
+When the experiment finish it, the master would close automatically, the rest of the workers would need manually closing, they would close after 120s
+
+
 ## How to cite Experiment Runner
 
 If Experiment Runner is helping your research, consider to cite it as follows, thank you!

Troubleshoating.md

@@ -0,0 +1,139 @@
+# Troubleshooting
+
+## 1. Python Package Installation Error
+
+When installing and setting up `experiment-runner`, one common issue is running:
+
+```bash
+pip3 install -r requirments.txt
+```
+
+and getting the following error:
+
+```text
+error: externally-managed-environment
+
+× This environment is externally managed
+╰─> To install Python packages system-wide, try apt install
+    python3-xyz
+```
+
+Some Linux distributions (especially Ubuntu 24+, Debian, and Fedora) protect the system Python installation to avoid breaking system packages.
+
+### Solution
+
+Run:
+
+```bash
+pip3 install -r requirments.txt --break-system-packages
+```
+
+### Alternative
+
+Use a Python virtual environment:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+---
+
+## 2. EnergiBridge / JoularCore Permission Error
+
+When using EnergiBridge or JoularCore on Linux systems (especially AMD CPUs), you may encounter the following error when running the experiment:
+
+```text
+thread 'main' (33575) panicked at src/cpu/amd.rs:20:76:
+called `Result::unwrap()` on an `Err` value: Os { code: 13, kind: PermissionDenied, message: "Permission denied" }
+note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
+```
+
+The Rust profiler is trying to access low-level CPU energy counters (MSR / RAPL interfaces), but Linux blocks access for normal users.
+
+### Solution
+
+#### 1. Load the MSR Kernel Module
+
+Run:
+
+```bash
+sudo modprobe msr
+```
+
+Then verify the device exists:
+
+```bash
+ls /dev/cpu/0/msr
+```
+
+Expected output:
+
+```text
+/dev/cpu/0/msr
+```
+
+If the file does not exist, the kernel module did not load correctly.
+
+---
+
+#### 2. Check MSR Permissions
+
+Run:
+
+```bash
+ls -l /dev/cpu/0/msr
+```
+
+If you see something similar to:
+
+```text
+crw------- 1 root root
+```
+
+then only the root user can access the CPU energy counters.
+
+---
+
+#### 3. Grant Read Permissions
+
+Run:
+
+```bash
+sudo chmod o+r /dev/cpu/*/msr
+```
+
+This temporarily allows non-root users to read the MSR registers.
+
+---
+
+#### If Nothing Works
+
+Some Linux systems completely block low-level profiling access.
+
+Run:
+
+```bash
+cat /proc/sys/kernel/perf_event_paranoid
+```
+
+If the value is:
+
+```text
+2
+3
+4
+```
+
+then Linux is blocking low-level performance counters.
+
+#### Temporary Fix
+
+Run:
+
+```bash
+echo -1 | sudo tee /proc/sys/kernel/perf_event_paranoid
+```
+
+This temporarily lowers the kernel restrictions and allows profiling tools to access hardware counters.

examples/hello-world-fibonacci/README.md

@@ -18,6 +18,6 @@ python experiment-runner/ examples/hello-world-fibonacci/RunnerConfig.py
 ## Results
 
 The results are generated in the `examples/hello-world-fibonacci/experiments` folder.
-
+In case there are anomalies such as null, absent, or negative values, a report will be generated in the `examples/hello-world-fibonacci/experiments` folder.
 **!!! WARNING !!!**: COLUMNS IN THE `energibridge.csv` FILES CAN BE DIFFERENT ACROSS MACHINES.
 ADJUST THE DATAFRAME COLUMN NAMES ACCORDINGLY.