Develop

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [master, develop]
+  pull_request:
+
+jobs:
+  docs:
+    name: Build docs (strict)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -r docs/requirements.txt
+      - run: mkdocs build --strict
+
+  package:
+    name: Package sanity (min Python)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          # The minimum supported version — guards against syntax newer than the
+          # declared floor (e.g. 3.11+ features slipping in) breaking `crab setup`.
+          python-version: "3.10"
+      - run: pip install -e .
+      - name: Syntax-check the package
+        run: python -m compileall -q src/
+      - name: Smoke-test the CLI entry point
+        run: crab --help

.gitignore

@@ -1,7 +1,20 @@
 .venv/
 __pycache__/
 *.pyc
-data/
-benchark_mix.txt
-tui_node_file
-benchmarks/
+.env
+hosts
+/data/
+.todo.md
+*.egg-info/
+
+# CRAB Setup & Benchmarks
+/benchmarks/
+/config/environments/
+
+# Generated dashboard exports (contain embedded data, should not be committed)
+crab_export.html
+*_export.html
+
+# Documentation build output
+/site/
+

.readthedocs.yaml

@@ -0,0 +1,15 @@
+# Read the Docs configuration. See:
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - requirements: docs/requirements.txt

Makefile

@@ -0,0 +1,56 @@
+.PHONY: install setup clean venv _install_core _check_python
+
+.DEFAULT_GOAL := install
+
+VENV_DIR = .venv
+PIP = $(VENV_DIR)/bin/pip
+CRAB_BIN = $(VENV_DIR)/bin/crab
+
+# 0. The Guardrail (Fails instantly if Python is too old)
+_check_python:
+	@python3 -c 'import sys; sys.exit(1) if sys.version_info < (3, 10) else sys.exit(0)' || \
+	(echo "============================================================"; \
+	 echo "[!] ERROR: CRAB requires Python 3.10 or higher."; \
+	 echo "    You are currently using: $$(python3 --version 2>&1)"; \
+	 echo ""; \
+	 echo "    Suggestion: Run \`module load python\` or activate a modern"; \
+	 echo "    Python environment before running \`make\` again."; \
+	 echo "============================================================"; exit 1)
+
+# 1. The Virtual Environment Builder
+venv: _check_python
+	python3 -m venv $(VENV_DIR)
+	$(PIP) install --upgrade pip
+	$(PIP) install argcomplete
+	@echo 'eval "$$(register-python-argcomplete crab)"' >> $(VENV_DIR)/bin/activate
+	@echo 'register-python-argcomplete --shell fish crab | source' >> $(VENV_DIR)/bin/activate.fish
+
+# 2. The Traffic Cop (Checks if already installed)
+install:
+	@if [ -x "$(CRAB_BIN)" ]; then \
+	    echo "============================================================"; \
+	    echo "[!] CRAB is already installed in this directory."; \
+	    echo ""; \
+	    echo "To configure new benchmarks, activate your environment:"; \
+	    echo "    source $(VENV_DIR)/bin/activate"; \
+	    echo "    crab setup"; \
+	    echo ""; \
+	    echo "To completely reinstall, run \`make clean\` first."; \
+	    echo "============================================================"; \
+	else \
+	    $(MAKE) _install_core; \
+	fi
+
+# 3. The Actual Installation
+_install_core: venv
+	$(PIP) install -e .
+	@echo "[✔] CRAB core installed in virtual environment."
+	@echo "Launching setup wizard to configure benchmarks..."
+	$(CRAB_BIN) setup
+
+setup:
+	$(CRAB_BIN) setup
+
+clean:
+	@echo "Cleaning up build artifacts..."
+	rm -rf build/ dist/ *.egg-info $(VENV_DIR)

README.md

@@ -0,0 +1,99 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/svg/crab-outlined-dark.svg">
+    <img alt="CRAB" src="docs/assets/svg/crab-outlined.svg" width="480">
+  </picture>
+</p>
+
+<p align="center"><strong>Co-Running Applications Benchmarking framework</strong></p>
+
+<p align="center">
+  <a href="https://www.python.org/"><img alt="Python Version" src="https://img.shields.io/badge/python-3.10+-blue.svg"></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
+  <a href="https://hlc-crab.readthedocs.io/en/latest/?badge=latest"><img alt="Documentation Status" src="https://readthedocs.org/projects/hlc-crab/badge/?version=latest"></a>
+  <a href="https://github.com/HLC-Lab/CRAB/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/HLC-Lab/CRAB/actions/workflows/ci.yml/badge.svg"></a>
+</p>
+
+**CRAB** runs **multiple HPC applications simultaneously** on Slurm-managed clusters to measure
+their performance and quantify how they **interfere** with one another (network congestion,
+shared-resource contention). Applications are described by small Python **wrappers** that teach
+CRAB how to launch them and parse their output, so results are collected uniformly regardless of
+the application — designate *victims* (measured) and *aggressors* (interference generators), and
+CRAB orchestrates the rest.
+
+![asciicast](https://user-images.githubusercontent.com/11363902/203875389-918931a5-e110-4107-8854-c8c3656ab3e2.gif)
+
+## ✨ Key features
+
+* **Dual interface** — a **Command Line Interface** for automation and a **Textual UI** for interactive use.
+* **System-portable experiments** — the same experiment config runs on any cluster; per-system details live in a centralized **preset** system (`leonardo`, `lumi`, …).
+* **Complex application mixes** — run many applications at once, designating *victims* and *aggressors*.
+* **Automated, converged data collection** — gathers performance data and stops once statistical convergence is reached.
+* **Standard output** — results saved as CSV, ready for pandas or R.
+* **Built-in dashboard** — `crab export` produces a self-contained HTML file with scatter, line, bar, and violin charts, a **Compare** tab for cross-experiment overlays, and dark/light themes. No server needed to share results.
+* **Extensible** — support a new benchmark by adding a Python wrapper; no core changes needed.
+
+## 📖 Documentation
+
+**Full documentation: [hlc-crab.readthedocs.io](https://hlc-crab.readthedocs.io/)** — installation,
+configuring a cluster, writing experiments, extending CRAB with new benchmarks, and the complete
+reference.
+
+Quick links:
+[Tutorial](https://hlc-crab.readthedocs.io/en/latest/tutorial/) ·
+[Concepts](https://hlc-crab.readthedocs.io/en/latest/concepts/system-dependent-vs-independent/) ·
+[Installation & setup](https://hlc-crab.readthedocs.io/en/latest/using/installation/) ·
+[Configuring your cluster](https://hlc-crab.readthedocs.io/en/latest/using/presets/) ·
+[Writing experiment configs](https://hlc-crab.readthedocs.io/en/latest/using/writing-configs/) ·
+[Extending CRAB](https://hlc-crab.readthedocs.io/en/latest/extending/overview/) ·
+[Reference](https://hlc-crab.readthedocs.io/en/latest/reference/configuration/)
+
+To build the docs locally:
+
+```bash
+pip install -r docs/requirements.txt
+mkdocs serve        # → http://127.0.0.1:8000
+```
+
+## 🚀 Quick start
+
+**Prerequisites:** Python 3.10+, Git, and access to a **Slurm** cluster — CRAB submits every run
+with `sbatch`, so Slurm must be available (even the `local` preset, which only changes the
+per-application launcher to `mpirun`).
+
+> 💡 Prefer a guided walkthrough? The **[end-to-end tutorial](https://hlc-crab.readthedocs.io/en/latest/tutorial/)**
+> runs a complete victim-vs-aggressor experiment step by step. The essentials:
+
+```bash
+git clone https://github.com/HLC-Lab/CRAB
+cd CRAB
+make                        # creates .venv, installs CRAB (editable), runs the setup wizard
+source .venv/bin/activate   # activate before using `crab`
+```
+
+Build or locate the benchmarks you want to run:
+
+```bash
+crab setup
+```
+
+Run an experiment, or launch the interactive UI:
+
+```bash
+crab run <config.json> -p <preset>
+crab tui
+```
+
+Results are written under `data/<system>/<name>_<timestamp>/`. Share them as a self-contained
+HTML dashboard:
+
+```bash
+crab export data/<system>/<name>_<timestamp>/ -o results.html
+```
+
+See the [documentation](docs/using/installation.md) for configuring presets, writing experiment
+configs, and adding your own benchmarks.
+
+## 📜 License
+
+Released under the MIT License. See the [`LICENSE`](LICENSE) file for details.