Installation Guide¶

Complete step-by-step setup for A-LEMS. This guide works on any Linux distribution with Intel 6th gen+ processors.

📋 Prerequisites¶

System Requirements¶

Requirement	Minimum	Recommended
OS	Any Linux distribution	Ubuntu 24.04 / Debian 12
CPU	Intel 6th gen+ (RAPL support)	Intel 12th gen+
RAM	8 GB	16 GB
Storage	10 GB free	20 GB free
Python	3.10	3.12

Note: A-LEMS uses Intel RAPL (Running Average Power Limit) for energy measurement. AMD processors are currently not supported.

Automatic Hardware Detection¶

A-LEMS includes intelligent hardware detection that automatically: - 🔍 Detects your CPU model and capabilities - 🌡️ Maps thermal zones dynamically (not hardcoded) - ⚡ Identifies available RAPL domains - 🔧 Configures MSR access for your specific CPU - 🖥️ Works across different Linux distributions

The system adapts to your hardware - no manual configuration needed!

Distribution-Specific Package Installation¶

Choose your distribution:

🐧 Ubuntu / Debian

sudo apt update
sudo apt install -y \
    python3-pip \
    python3-venv \
    git \
    build-essential \
    linux-tools-common \
    linux-tools-generic \
    msr-tools \
    lm-sensors

📦 Fedora / RHEL / CentOS

sudo dnf install -y \
    python3-pip \
    python3-virtualenv \
    git \
    gcc \
    make \
    kernel-tools \
    msr-tools \
    lm_sensors

🏔️ Arch Linux / Manjaro

sudo pacman -S --noconfirm \
    python-pip \
    python-virtualenv \
    git \
    base-devel \
    linux-tools \
    msr-tools \
    lm_sensors

🔄 openSUSE

sudo zypper install -y \
    python3-pip \
    python3-virtualenv \
    git \
    gcc \
    make \
    kernel-tools \
    msr-tools \
    lm_sensors

🚀 Step 1: Clone Repository¶

git clone https://github.com/deepakpanigrahy03/a-lems.git
cd a-lems

🐍 Step 2: Create Virtual Environment¶

python3 -m venv venv
source venv/bin/activate

On some systems, use python instead of python3.

📦 Step 3: Install Python Dependencies¶

# Core requirements (always needed)
pip install -r requirements.txt

# Optional: GUI dashboard (for web interface)
pip install -r requirements-gui.txt

# Optional: Developer tools (for contributors)
pip install -r requirements-tools.txt

¶

🔧 Step 4.1: Build MSR Helper¶

The MSR helper needs to be compiled before running permissions:

cd core/msr_helper
make
cd ../..

**This is just for information but this part is currently incluced in (4.2)

🔧 Step 4.2: Fix Permissions¶

The fix_permissions.sh script grants necessary access to hardware interfaces:

sudo ./scripts/fix_permissions.sh

What this does:

Grants read access to RAPL energy counters (/sys/class/powercap/)
Allows MSR register access for C-state monitoring
Enables turbostat for CPU frequency sampling
Provides access to thermal sensors

You only need to run this once after installation.

🖥️ Step 5: Verify Installation¶

Run the hardware verification tool to check if everything is working:

python scripts/verify_hardware.py

Expected output: All 8 checks should pass with ✅ indicators.

🏗️ Step 6: Hardware Detection¶

A-LEMS automatically detects your hardware configuration:

# First run (requires sudo for MSR/turbostat access)
python scripts/detect_hardware.py --output config/hw_config.json --verbose

# Fix permissions on generated config
sudo ./scripts/fix_permissions.sh

What gets detected:

✅ CPU model, cores, threads, flags (AVX2, AVX512)
✅ GPU model and driver
✅ RAPL energy domains (package, core, uncore, dram)
✅ Thermal zones (dynamic mapping, not hardcoded)
✅ MSR registers and C-state capabilities
✅ System manufacturer and type

The generated config/hw_config.json contains your complete hardware fingerprint.

🌍 Step 7: Environment Detection¶

Capture your software environment for reproducibility:

python scripts/detect_environment.py --verbose

What gets tracked:

✅ Python version and implementation
✅ Git commit hash and branch
✅ Dependency versions (numpy, torch, etc.)
✅ OS name and kernel version

This creates config/environment.json with a unique env_hash for your environment.

✅ Installation Complete!¶

Your A-LEMS installation is now ready. Next steps:

📘 Quick Start Guide - Run your first experiment in 5 minutes
🔑 Configuration Guide - Set up API keys for cloud models
📊 Understanding Metrics - Learn what the numbers mean

🔄 Post-Installation Workflow¶

After installation, your daily workflow is simple:

cd a-lems
source venv/bin/activate
# Load API keys (if using cloud models)
source .env

# Run experiments
python -m core.execution.tests.run_experiment --tasks gsm8k_basic --repetitions 3

⚠️ Troubleshooting¶

Issue	Likely Cause	Solution
Permission denied	Hardware access restricted	Run `sudo ./scripts/fix_permissions.sh`
`ModuleNotFoundError`	Virtual env not activated	`source venv/bin/activate`
RAPL not found	CPU doesn't support RAPL	Check: `cat /proc/cpuinfo \\| grep rapl`
MSR access failed	msr module not loaded	`sudo modprobe msr`
Turbostat missing	linux-tools not installed	Install kernel-tools package for your distro
No thermal zones	Sensors not detected	Install lm-sensors and run `sudo sensors-detect`
GPU not detected	Missing drivers	Install appropriate GPU drivers

Still having issues?¶

Run the diagnostic tool:

python scripts/tools/issue_tracer.py

This will automatically check your system and suggest fixes.

Note: A-LEMS is designed to work on any Linux system with Intel processors. The hardware detection automatically adapts to your specific configuration - no manual tweaking required!

Environment Variables¶

Copy to and add your API keys. Run ================================================================= A-LEMS Universal Permission Fixer =================================================================

[1/4] Fixing RAPL permissions... ✅ RAPL systemd service created

[1.5/4] Fixing uncore frequency permissions... Reading paths from config/hw_config.json... ✅ Already correct: /sys/devices/system/cpu/intel_uncore_frequency/package_00_die_00/current_freq_khz ✅ Already correct: /sys/devices/system/cpu/intel_uncore_frequency/package_00_die_00/initial_max_freq_khz ✅ Already correct: /sys/devices/system/cpu/intel_uncore_frequency/package_00_die_00/initial_min_freq_khz ✅ Already correct: /sys/devices/system/cpu/intel_uncore_frequency/package_00_die_00/max_freq_khz ✅ Already correct: /sys/devices/system/cpu/intel_uncore_frequency/package_00_die_00/min_freq_khz ✅ Uncore frequency permissions fixed from config ✅ Uncore frequency systemd service created

[2/4] Fixing MSR permissions... ✅ Group 'a-lems' ensured ✅ Udev rule created ✅ Permissions applied to existing MSR devices ✅ Udev rules reloaded ✅ rdmsr capabilities set ✅ turbostat capabilities set

[3/4] Fixing perf_event permissions... ✅ perf_event_paranoid set to -1

[4/4] Setting turbostat capabilities on REAL binary... Found real turbostat at: /usr/lib/linux-tools/6.17.0-19-generic/turbostat ✅ turbostat capabilities set on REAL binary

[2.5/4] Compiling MSR helper binary... ✅ MSR helper already exists ✅ Binary found at core/msr_helper/msr_read

[2.6/4] Setting SUID on MSR helper binary... ✅ SUID set on core/msr_helper/msr_read -rwsrwxr-x 1 root root 16560 Mar 21 11:52 core/msr_helper/msr_read

================================================================= ✅ PERMISSIONS FIXED! =================================================================

⚠️ IMPORTANT: Log out and log back in NOW!

After logging back in, run detection: python scripts/detect_hardware.py --output config/hw_config.json --merge --verbose ================================================================= to compile the MSR helper.