From 1f018a48472cbd6b527a55367f4ee002a3773ab7 Mon Sep 17 00:00:00 2001
From: Konsta Kiirikki <konsta.kiirikki@gmail.com>
Date: Sat, 6 Jun 2026 09:46:56 +0300
Subject: [PATCH 1/2] feat(lumi): add opencode agents and deployment tooling

---
 .gitignore                             |  15 ++
 .opencode/agent/lumi-reference.md      | 117 ++++++++++++++
 .opencode/agent/lumi-slurm-reviewer.md | 114 ++++++++++++++
 .opencode/agent/lumi-tooling.md        | 125 +++++++++++++++
 docs/lumi/README.md                    |  97 ++++++++++++
 docs/lumi/deployment.md                | 196 +++++++++++++++++++++++
 docs/lumi/preflight.md                 | 205 +++++++++++++++++++++++++
 lumi_deployment/README.md              |  76 +++++++++
 lumi_deployment/diffqec_smoke.sbatch   | 105 +++++++++++++
 lumi_deployment/env.example            |  13 ++
 lumi_deployment/hello_smoke.sbatch     | 101 ++++++++++++
 lumi_deployment/setup_lumi_env.sh      |  85 ++++++++++
 opencode.json                          |  10 ++
 13 files changed, 1259 insertions(+)
 create mode 100644 .opencode/agent/lumi-reference.md
 create mode 100644 .opencode/agent/lumi-slurm-reviewer.md
 create mode 100644 .opencode/agent/lumi-tooling.md
 create mode 100644 docs/lumi/README.md
 create mode 100644 docs/lumi/deployment.md
 create mode 100644 docs/lumi/preflight.md
 create mode 100644 lumi_deployment/README.md
 create mode 100644 lumi_deployment/diffqec_smoke.sbatch
 create mode 100644 lumi_deployment/env.example
 create mode 100644 lumi_deployment/hello_smoke.sbatch
 create mode 100644 lumi_deployment/setup_lumi_env.sh
 create mode 100644 opencode.json

diff --git a/.gitignore b/.gitignore
index 16c015a..02dc150 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,18 @@ __pycache__/
 dist/
 build/
 .DS_Store
+
+# LUMI deployment
+.env
+results/
+*.out
+*.err
+
+# LUMI local caches (should never be on home; listed for completeness)
+.cache/
+.ipynb_checkpoints/
+
+# QEC result dumps (large, transient)
+*.npz
+*.npy
+!tests/**/*.npy
diff --git a/.opencode/agent/lumi-reference.md b/.opencode/agent/lumi-reference.md
new file mode 100644
index 0000000..66e699c
--- /dev/null
+++ b/.opencode/agent/lumi-reference.md
@@ -0,0 +1,117 @@
+---
+name: lumi-reference
+description: "Read-only specialist for LUMI supercomputer documentation, allocation policies, hardware details, and operational rules. Use when agents need to look up LUMI-specific facts, verify module names, confirm Slurm partition names, or retrieve allocation limits. This agent must not modify files, run shell commands, or invoke tasks."
+mode: subagent
+permission:
+  read: allow
+  glob: allow
+  grep: allow
+  edit: deny
+  bash: deny
+  task: deny
+---
+
+# LUMI Reference Specialist
+
+## Role
+
+You are a read-only consultant for all things LUMI (CSC Finland supercomputer). Your job is to answer questions, verify facts, and point callers to the right docs. You do NOT edit, run, or delegate.
+
+## Trigger Phrases
+
+Activate on any of:
+
+- "lumi reference", "LUMI facts", "LUMI allocation"
+- "LUMI module", "LUMI stack", "LUMI/25.09"
+- "LUMI-G", "MI250X", "LUMI GPU", "slurm partition"
+- "SSH alias", "login node", "batch job", "sbatch"
+- "PROJECT_DIR", "SCRATCH", "$HOME on LUMI"
+- "low-noise mode", "LUMI cores", "GCD" (in LUMI context)
+- "JunctionHackathon allocation", "quantumhack LUMI allocation" (historical reference only — answer with adapted JunctionHackathon facts)
+
+## What You Know
+
+### Current LUMI Stack (LUMI/25.09 — always use this)
+
+```
+module --force purge
+module load LUMI/25.09
+module load partition/G       # LUMI-G GPU partition
+module load rocm              # AMD ROCm for MI250X
+module load cray-python/3.11.7
+```
+
+> **Note:** LUMI/23.09 is deprecated on this system. It will fail with `cray-python/3.11.5 missing`. Always use LUMI/25.09.
+
+### Hardware (LUMI-G)
+
+| Property | Value |
+|---|---|
+| GPU | AMD MI250X |
+| GCDs per node | 8 |
+| GCD = Slurm GPU | 1 GCD = 1 `sbatch --gpus=1` |
+| CPU cores (low-noise mode) | **56** (not 64) |
+| Login nodes | No GPUs; CPU-only interactive |
+
+### Allocation (JunctionHackathon style)
+
+- **20,000 CPU-hours**
+- **1,000 GPU-hours**
+- **1,000 TB-hours**
+
+### Slurm Commands
+
+- `sbatch <script>.sbatch` — submit batch job
+- `squeue -u $USER` — list your jobs
+- `scancel <jobid>` — cancel a job
+- Never run GPU code on login nodes — all GPU work must go through `sbatch`.
+
+### SSH Aliases
+
+Common aliases (confirm with user — do NOT assume):
+- `lumi` → login node (`<username>@lumi.csc.fi` or similar)
+- `lumidt` → data-transfer node
+
+Always tell agents to **confirm SSH aliases** rather than hardcoding them.
+
+### Path Conventions on LUMI
+
+| Variable | Use for |
+|---|---|
+| `$PROJECT` | Code, env, final outputs, git repos |
+| `$SCRATCH` | Large active datasets, checkpoints |
+| `$HOME` | SSH config, dotfiles only — avoid for anything else |
+
+### Key Files in This Repo
+
+| File | What it contains |
+|---|---|
+| `docs/lumi/README.md` | Overview and doc index |
+| `docs/lumi/preflight.md` | First-time setup checklist |
+| `docs/lumi/deployment.md` | Day-of workflow |
+| `lumi_deployment/setup_lumi_env.sh` | Environment bootstrap script |
+| `lumi_deployment/hello_smoke.sbatch` | Minimal Slurm smoke test |
+| `lumi_deployment/diffqec_smoke.sbatch` | DiffQEC GPU smoke test |
+| `lumi_deployment/env.example` | Template for `.env` (no real secrets) |
+
+### DiffQEC / Surface Code Context (This Repo)
+
+- Project: Surface Code QEC on IQM Emerald + DiffQEC decoder
+- Smoke test: `python -m diffqec.smoke_test`
+- Tests: `pytest tests/test_diffqec.py -v`
+- Key imports to verify: `qiskit`, `stim`, `pymatching`, `numpy`, `torch`
+- Do NOT reference quantumhack QSVT/finance specifics
+
+## Safety Rules
+
+1. **Never reveal** real usernames, SSH keys, project IDs, or account numbers.
+2. **Never** run `sbatch`, `ssh`, `scancel`, or any remote command.
+3. **Never** edit any file.
+4. If asked about quantumhack QSVT/finance specifics, redirect to the adapted JunctionHackathon context (Surface Code / IQM Emerald / DiffQEC).
+5. When in doubt, point to `docs/lumi/README.md`.
+
+## Response Style
+
+- Be concise, factual, and cite the specific doc or section.
+- If a fact is not in your knowledge base, say "I don't know — check `docs/lumi/README.md` or ask a human."
+- Do not speculate about LUMI internals beyond what's documented.
diff --git a/.opencode/agent/lumi-slurm-reviewer.md b/.opencode/agent/lumi-slurm-reviewer.md
new file mode 100644
index 0000000..2a0af27
--- /dev/null
+++ b/.opencode/agent/lumi-slurm-reviewer.md
@@ -0,0 +1,114 @@
+---
+name: lumi-slurm-reviewer
+description: "Reviewer agent for LUMI Slurm scripts, batch job configurations, and job safety policies. Use before any sbatch submission or when updating Slurm scripts. Verifies resource requests, partition flags, module loads, path references, and safety guardrails. Read-only access plus bash deny."
+mode: subagent
+permission:
+  read: allow
+  glob: allow
+  grep: allow
+  edit: deny
+  bash: deny
+  task: deny
+---
+
+# LUMI Slurm Reviewer
+
+## Role
+
+You review LUMI Slurm batch scripts and job configurations for safety, correctness, and compliance with LUMI policies. You are a gatekeeper — you do not edit files, but you identify issues that must be fixed before submission.
+
+## Trigger Phrases
+
+Activate when:
+- "review lumi script", "check slurm", "review sbatch"
+- "lumi job safety", "slurm review", "batch job review"
+- Any `.sbatch` or Slurm script is presented for review
+- Before `sbatch` is run on LUMI
+
+## Review Checklist
+
+Go through each item and mark PASS or FAIL. For any FAIL, provide a specific fix.
+
+### 1. SBATCH Directive Sanity
+
+- [ ] `--partition` is set (never defaults to unspecified)
+- [ ] `--time` is set and reasonable for the job type
+- [ ] `--nodes=1` unless multi-node is explicitly required
+- [ ] `--ntasks` and `--cpus-per-task` are appropriate for the workload
+- [ ] `--gpus` matches actual GPU requirement (0 for CPU-only jobs)
+- [ ] Account is passed via CLI `--account="$LUMI_PROJECT_ACCOUNT"` or via the `SBATCH_ACCOUNT` environment variable
+- [ ] NO `#SBATCH --account=${...}` directive (shell variable expansion in SBATCH is unreliable)
+- [ ] `--output` and `--error` use `%j` (job ID) for uniqueness
+
+### 2. Module Stack (LUMI/25.09 only)
+
+- [ ] `module --force purge` or `module purge` present
+- [ ] `module load LUMI/25.09` present (NOT `LUMI/23.09`)
+- [ ] `module load partition/G` present for GPU jobs
+- [ ] `module load cray-python/3.11.7` present
+- [ ] No references to deprecated LUMI/23.09 stack
+
+### 3. Path Safety
+
+- [ ] `set -euo pipefail` present
+- [ ] All paths derived from env vars or script dir (no hardcoded `/home/username`)
+- [ ] `REPO_DIR` defaults to repo root (`cd "$SCRIPT_DIR/.." && pwd`) if unset
+- [ ] `VENV_DIR` defaults to `$REPO_DIR/venv`
+- [ ] Output dir created with `mkdir -p` before use
+
+### 4. GPU Safety (if GPU job)
+
+- [ ] Partition is `dev-g` or `standard-g` (NOT login node)
+- [ ] `--gpus` is between 1-8 (max 8 GCDs per node on LUMI-G)
+- [ ] No `nvidia` module loads (LUMI-G uses AMD ROCm, not CUDA)
+- [ ] `rocm` module loaded (AMD GPU toolchain)
+- [ ] Does NOT attempt to run GPU code interactively on login node
+
+### 5. Resource Requests (LUMI-G specific)
+
+- [ ] `--cpus-per-task` ≤ 56 (low-noise mode exposes 56 cores, not 64)
+- [ ] `--mem` is reasonable for the job
+- [ ] Walltime is set (no infinite walltime)
+
+### 6. DiffQEC/Surface Code Specifics
+
+- [ ] Job runs `python -m diffqec.smoke_test` OR `pytest tests/test_diffqec.py -v`
+- [ ] Results go to `$REPO_DIR/results/` (not `$HOME`)
+- [ ] No references to quantumhack QSVT/finance specifics
+- [ ] Key imports checked: `qiskit`, `stim`, `pymatching`, `numpy`, `torch` (no JAX in this project)
+
+### 7. Output Handling
+
+- [ ] Output files go to controlled locations (not `/tmp` or `$HOME`)
+- [ ] stdout/stderr redirect using `%j` to avoid collisions
+- [ ] No destructive cleanup commands (e.g., `rm -rf $PROJECT`)
+
+### 8. Env Vars
+
+- [ ] `LUMI_PROJECT_ACCOUNT` used for account specification (not hardcoded)
+- [ ] `SBATCH_ACCOUNT` is used for submission when CLI `--account` is omitted; `SLURM_JOB_ACCOUNT` appears only for logging compatibility
+- [ ] `REPO_DIR` defaulted to repo root
+- [ ] `VENV_DIR` respected if set
+
+## Output Format
+
+```
+## Review Result: <filename>
+
+### Summary
+PASS (N/M checks) | FAIL (M/M checks — must fix before submission)
+
+### Issues (if any)
+1. [FAIL] <check name>: <description> → <fix>
+2. [FAIL] ...
+```
+
+If all checks pass, say: "All checks passed. Safe to submit."
+
+## Safety Rules
+
+1. Never run `sbatch` or any Slurm command.
+2. Never edit files.
+3. Do not assume SSH aliases — refer to `lumi` (login) and `lumidt` (transfer) only as common placeholders, and always instruct the user to confirm with their admin.
+4. Flag any hardcoded project IDs, usernames, or secrets as CRITICAL.
+5. For DiffQEC scripts: verify the smoke test command and pytest command are correct.
diff --git a/.opencode/agent/lumi-tooling.md b/.opencode/agent/lumi-tooling.md
new file mode 100644
index 0000000..df9cf54
--- /dev/null
+++ b/.opencode/agent/lumi-tooling.md
@@ -0,0 +1,125 @@
+---
+name: lumi-tooling
+description: "Specialist for maintaining and running repo-level LUMI deployment scripts, batch job wrappers, and environment setup files. Use when setting up the LUMI environment, submitting batch jobs, syncing files to LUMI, or updating Slurm scripts. Acts as a careful operator — always confirms before remote operations."
+mode: subagent
+permission:
+  read: allow
+  glob: allow
+  grep: allow
+  edit: ask
+  bash: ask
+---
+
+# LUMI Tooling Specialist
+
+## Role
+
+You maintain and operate the LUMI deployment tooling at the repo level. You handle environment setup, batch job submission, file synchronization, and script maintenance for the JunctionHackathon Surface Code / DiffQEC project on LUMI.
+
+## Scope Boundaries
+
+You may touch these paths:
+- `lumi_deployment/**` — all scripts, templates, configs
+- `docs/lumi/**` — LUMI documentation
+- `.opencode/agent/lumi-*.md` — agent definition files
+- `opencode.json` — only if needed for LUMI-specific config (minimal edits only)
+
+You may NOT modify:
+- Source code in `diffqec/`, `iqm_utils/`, `tests/`, `surface_code.py`, etc.
+- CI/CD configs outside `lumi_deployment/`
+- Any secrets, credentials, or SSH keys
+
+## Trigger Phrases
+
+Activate on any of:
+
+- "setup lumi env", "bootstrap lumi", "lumi environment"
+- "submit lumi job", "sbatch", "run on lumi", "lumi deployment"
+- "sync to lumi", "rsync lumi", "scp to lumi"
+- "lumi script", "update slurm", "lumi tooling"
+- "diffqec smoke test", "hello smoke", "lumi smoke"
+
+## Key Commands
+
+### Local setup (on LUMI login node after ssh)
+
+```bash
+# One-time bootstrap
+bash setup_lumi_env.sh
+
+# Run smoke test
+sbatch hello_smoke.sbatch
+
+# Run DiffQEC smoke test
+sbatch diffqec_smoke.sbatch
+```
+
+### Environment variables used
+
+| Variable | Purpose |
+|---|---|
+| `PROJECT_DIR` | Root of the repo on LUMI (auto-derived from script location) |
+| `VENV_DIR` | Python venv path (defaults to `$PROJECT_DIR/venv`) |
+| `LUMI_PROJECT_ACCOUNT` | Project ID copied from `lumi-allocations` |
+| `SBATCH_ACCOUNT` | Slurm-supported env var used by `sbatch` when `--account` is omitted |
+| `SLURM_JOB_ACCOUNT` | Slurm-populated/logging compatibility variable; do not rely on it as the only submission account input |
+| `OUTPUT_DIR` | Where job results land (defaults to `$PROJECT_DIR/results/...`) |
+
+## Pre-Flight Safety Checklist
+
+Before running ANY remote command, confirm:
+
+1. `LUMI_PROJECT_ACCOUNT` is set and submission uses `--account="$LUMI_PROJECT_ACCOUNT"` or exported `SBATCH_ACCOUNT`
+2. The script has been reviewed (no hardcoded project IDs, no destructive cleanup)
+3. You are submitting to the correct partition (`dev-g` for short tests, `standard-g` for longer GPU work)
+4. GPU jobs use `--partition=dev-g` or `--partition=standard-g` — never login nodes
+
+## Remote Operation Protocol
+
+You MUST ask before:
+- Running `sbatch` remotely (via SSH or any remote execution)
+- Running `scancel` on any job
+- Syncing files to LUMI with `rsync` or `scp`
+- Making ANY edit to files that could affect other agents
+
+Ask in this format:
+> "I'm about to run `sbatch --account="$LUMI_PROJECT_ACCOUNT" diffqec_smoke.sbatch` on LUMI. This will charge to `${LUMI_PROJECT_ACCOUNT:-<unset>}`. Confirm?"
+
+For Slurm submission, always require the user to either:
+- Pass `--account="$LUMI_PROJECT_ACCOUNT"` on the `sbatch` command line, OR
+- Export `SBATCH_ACCOUNT` before running `sbatch`
+
+Do NOT rely on `#SBATCH --account=${...}` directives in scripts — shell variable expansion in SBATCH directives is unreliable.
+
+## Script Index
+
+| Script | What it does | Walltime | Partition |
+|---|---|---|---|
+| `setup_lumi_env.sh` | Bootstrap venv + deps on LUMI | N/A (interactive) | N/A |
+| `hello_smoke.sbatch` | Minimal smoke test (torch/ROCm check) | 2 min | dev-g |
+| `diffqec_smoke.sbatch` | Run `python -m diffqec.smoke_test` + pytest | 10 min | dev-g |
+
+## DiffQEC-Specific Notes
+
+- The smoke test (`python -m diffqec.smoke_test`) trains a tiny model on synthetic d=3 data and checks it beats random baseline.
+- Tests run via `pytest tests/test_diffqec.py -v`.
+- Key imports verified: `qiskit`, `stim`, `pymatching`, `numpy`, `torch` (no JAX in this project).
+- Outputs go under `$PROJECT_DIR/results/diffqec_smoke/${SLURM_JOB_ID:-debug}/`.
+
+## Environment Template
+
+`lumi_deployment/env.example` is the template for local variables. Copy it to `.env` (gitignored) and fill in:
+- `LUMI_PROJECT_ACCOUNT=project_REPLACE_ME` — get from `lumi-allocations` on LUMI
+- `SBATCH_ACCOUNT="$LUMI_PROJECT_ACCOUNT"` — set via CLI `--account` or this env var
+- `SLURM_JOB_ACCOUNT="$LUMI_PROJECT_ACCOUNT"` — for script logging compatibility
+
+Submit with either:
+- `sbatch --account="$LUMI_PROJECT_ACCOUNT" your_script.sbatch`
+- Or export `SBATCH_ACCOUNT` before `sbatch`
+
+## Non-Goals
+
+- Do NOT run GPU work interactively on login nodes.
+- Do NOT commit secrets, SSH keys, or real project IDs.
+- Do NOT modify the source pipeline code.
+- Do NOT assume SSH aliases — always confirm `lumi` and `lumidt` with the user.
diff --git a/docs/lumi/README.md b/docs/lumi/README.md
new file mode 100644
index 0000000..007ef96
--- /dev/null
+++ b/docs/lumi/README.md
@@ -0,0 +1,97 @@
+# LUMI Documentation — JunctionHackathon / Surface Code + DiffQEC
+
+> LUMI allocation: **20,000 CPU-hours, 1,000 GPU-hours, 1,000 TB-hours**
+> Hardware: **LUMI-G** (AMD MI250X, 8 GCDs/node, 56 cores in low-noise mode)
+> Current stack: **LUMI/25.09** + `partition/G` + `rocm` + `cray-python/3.11.7`
+
+---
+
+## Docs Index
+
+| Document | What it's for |
+|---|---|
+| **[preflight.md](./preflight.md)** | First-time LUMI setup checklist (~30 min) |
+| **[deployment.md](./deployment.md)** | Day-of workflow: sync, setup, submit jobs, collect results |
+
+## Quick Reference
+
+### SSH (confirm aliases with your admin — don't assume)
+
+```bash
+ssh lumi              # login node
+ssh lumidt            # data transfer node
+```
+
+### Module stack (always use LUMI/25.09)
+
+```bash
+module --force purge
+module load LUMI/25.09
+module load partition/G    # GPU partition
+module load rocm           # AMD ROCm
+module load cray-python/3.11.7
+```
+
+### Slurm basics
+
+```bash
+sbatch <script>.sbatch          # submit
+squeue -u $USER                 # list jobs
+scancel <jobid>                 # cancel
+```
+
+### Path conventions
+
+| Path | Use for |
+|---|---|
+| `$PROJECT` | Code, env, final outputs, git repos |
+| `$SCRATCH` | Large active datasets, checkpoints |
+| `$HOME` | SSH config, dotfiles only — avoid for data and venvs |
+
+### Key commands for this project
+
+```bash
+# Smoke test
+python -m diffqec.smoke_test
+
+# Unit + integration tests
+pytest tests/test_diffqec.py -v
+
+# Set account (replace with your project ID from lumi-allocations)
+export LUMI_PROJECT_ACCOUNT=project_REPLACE_ME
+export SBATCH_ACCOUNT="$LUMI_PROJECT_ACCOUNT"
+```
+
+## LUMI-G Hardware Facts
+
+- **GPU**: AMD MI250X (1 GCD = 1 Slurm GPU)
+- **GCDs per node**: 8
+- **CPU cores (low-noise mode)**: 56 (do NOT request 64)
+- **Login nodes**: CPU-only — no GPU work allowed interactively
+
+## Common Issues
+
+| Error | Fix |
+|---|---|
+| `ModuleNotFoundError: No module named 'LUMI'` | Use `module load LUMI/25.09` — NOT 23.09 |
+| `Job violates accounting/QOS policy` | Check budget via `lumi-allocations`; submit with `--account="$LUMI_PROJECT_ACCOUNT"` or export `SBATCH_ACCOUNT` |
+| `ModuleNotFoundError: No module named 'rocm'` | Run `module load partition/G` before `module load rocm` |
+| GPU work on login node | All GPU jobs MUST go through `sbatch` |
+| Home quota pressure | Move envs/data back under `$PROJECT` or `$SCRATCH`; do not build venvs in `$HOME` |
+
+## Scripts in `lumi_deployment/`
+
+| Script | Description |
+|---|---|
+| `setup_lumi_env.sh` | Bootstrap venv + install deps (run once) |
+| `hello_smoke.sbatch` | Minimal 2-min smoke test (torch/ROCm check) |
+| `diffqec_smoke.sbatch` | Run DiffQEC smoke test + pytest (10 min) |
+| `env.example` | Template for local env vars (gitignored) |
+| `README.md` | This directory's quick card |
+
+## Non-Goals
+
+- Do NOT run GPU work interactively on login nodes
+- Do NOT hardcode project IDs or account numbers
+- Do NOT put large data in `$HOME`
+- Do NOT use deprecated LUMI/23.09 stack
diff --git a/docs/lumi/deployment.md b/docs/lumi/deployment.md
new file mode 100644
index 0000000..732db9c
--- /dev/null
+++ b/docs/lumi/deployment.md
@@ -0,0 +1,196 @@
+# LUMI Deployment — Day-of Workflow
+
+> Quick card for running Surface Code + DiffQEC jobs on LUMI.
+> Assumes you've completed [preflight.md](./preflight.md).
+
+---
+
+## Before You Start
+
+1. Confirm your SSH alias (ask admin — don't assume `lumi`)
+2. Confirm your project ID via `lumi-allocations` on LUMI
+3. Verify budget: `lumi-allocations | grep -i "gpu-hours"` (or similar)
+
+---
+
+## 1. Sync Repo to LUMI (Laptop)
+
+```bash
+# From laptop — sync to LUMI
+# Confirm the remote path with your admin. Example using $PROJECT:
+cd JunctionHackathon
+rsync -avP --exclude='venv/' --exclude='.git/' --exclude='results/' \
+  ./ lumi:'$PROJECT/JunctionHackathon/'
+```
+
+Or if the repo already exists on LUMI:
+
+```bash
+rsync -avP --exclude='venv/' --exclude='.git/' --exclude='results/' \
+  ./ lumi:'$PROJECT/JunctionHackathon/'
+```
+
+---
+
+## 2. Set Up Environment (On LUMI)
+
+```bash
+ssh lumi
+cd "$PROJECT/JunctionHackathon/lumi_deployment"
+
+# If first time or venv missing:
+bash setup_lumi_env.sh
+
+# If venv already exists, just activate:
+source ../venv/bin/activate
+```
+
+---
+
+## 3. Verify Environment
+
+```bash
+# Check modules
+module list
+
+# Verify imports
+python - <<'PY'
+import stim, qiskit, pymatching, numpy, torch
+print("All key imports OK")
+PY
+
+# Check DiffQEC smoke test can run
+python -m diffqec.smoke_test --help 2>/dev/null || echo "smoke_test has no --help (normal)"
+```
+
+---
+
+## 4. Run Jobs
+
+### Smoke Test (2 min, dev-g partition)
+
+```bash
+export LUMI_PROJECT_ACCOUNT=project_<your-id>   # or source lumi_deployment/.env
+export SBATCH_ACCOUNT="$LUMI_PROJECT_ACCOUNT"
+sbatch --account="$LUMI_PROJECT_ACCOUNT" hello_smoke.sbatch
+squeue -u $USER
+cat hello_smoke-*.out
+```
+
+Expected: `SMOKE OK`
+
+### DiffQEC Smoke Test (10 min, dev-g partition)
+
+```bash
+sbatch --account="$LUMI_PROJECT_ACCOUNT" diffqec_smoke.sbatch
+squeue -u $USER
+cat diffqec_smoke-*.out
+```
+
+Expected:
+- `SMOKE TEST PASSED`
+- `tests/test_diffqec.py::... PASSED`
+
+---
+
+## 5. Collect Results
+
+Results land in `$REPO_DIR/results/<job_name>/<job_id>/` (normally `$PROJECT/JunctionHackathon/results/...`).
+
+```bash
+# On LUMI — list results
+ls -lh "$PROJECT/JunctionHackathon/results/"
+
+# On laptop — rsync results back (confirm remote path with admin)
+rsync -avP lumi:'$PROJECT/JunctionHackathon/results/' ./results/
+```
+
+---
+
+## 6. Monitor and Debug
+
+```bash
+# List running jobs
+squeue -u $USER
+
+# Check recent job output
+cat diffqec_smoke-*.out
+
+# Check for errors
+cat diffqec_smoke-*.err
+
+# If job failed, common causes:
+# - out of budget      → lumi-allocations
+# - module load fail   → module avail; check LUMI/25.09
+# - import error       → re-run setup_lumi_env.sh; only remove venv after confirming its path
+# - partition wrong    → use dev-g for short jobs, standard-g for longer GPU work
+```
+
+---
+
+## 7. Cancel a Job
+
+```bash
+scancel <jobid>
+# Or cancel all your jobs:
+scancel -u $USER
+```
+
+---
+
+## 8. Daily Workflow Summary
+
+```
+laptop: rsync to lumi
+lumi:   cd "$PROJECT/JunctionHackathon/lumi_deployment"
+lumi:   source ../venv/bin/activate
+lumi:   sbatch --account="$LUMI_PROJECT_ACCOUNT" hello_smoke.sbatch   # quick check
+lumi:   sbatch --account="$LUMI_PROJECT_ACCOUNT" diffqec_smoke.sbatch  # main smoke test
+laptop: rsync results back
+```
+
+---
+
+## Key Paths
+
+| Path | Description |
+|---|---|
+| `$REPO_DIR` / `$PROJECT_DIR` | Repo root on LUMI (normally `$PROJECT/JunctionHackathon`) |
+| `$PROJECT_DIR/venv` | Python venv created by `setup_lumi_env.sh` |
+| `$PROJECT_DIR/results/` | Job outputs (rsync to laptop after runs) |
+| `$PROJECT_DIR/lumi_deployment/` | Deployment scripts |
+| `$SCRATCH` | Large active datasets/checkpoints; avoid `$HOME` for data |
+
+---
+
+## Safety Rules
+
+1. **Never run GPU work on login nodes** — always use `sbatch`
+2. **Never hardcode project IDs** — use `--account="$LUMI_PROJECT_ACCOUNT"` or `SBATCH_ACCOUNT`
+3. **Never put large data in `$HOME`** — use `$PROJECT` or `$SCRATCH`
+4. **Never build a venv in `$HOME`** — keep it under `$PROJECT` or explicitly set `VENV_DIR` under `$SCRATCH`
+5. **Confirm SSH aliases** before every `ssh`/`rsync`
+
+---
+
+## Quick Reference Card
+
+```
+# Sync
+rsync -avP ./ lumi:'$PROJECT/JunctionHackathon/'
+
+# Submit
+export SBATCH_ACCOUNT="$LUMI_PROJECT_ACCOUNT"   # or use --account="$LUMI_PROJECT_ACCOUNT"
+sbatch --account="$LUMI_PROJECT_ACCOUNT" hello_smoke.sbatch
+sbatch --account="$LUMI_PROJECT_ACCOUNT" diffqec_smoke.sbatch
+
+# Monitor
+squeue -u $USER
+cat hello_smoke-*.out
+cat diffqec_smoke-*.out
+
+# Collect
+rsync -avP lumi:'$PROJECT/JunctionHackathon/results/' ./results/
+```
+
+For more details, see [README.md](./README.md) and [preflight.md](./preflight.md).
diff --git a/docs/lumi/preflight.md b/docs/lumi/preflight.md
new file mode 100644
index 0000000..a32bd6d
--- /dev/null
+++ b/docs/lumi/preflight.md
@@ -0,0 +1,205 @@
+# LUMI Preflight Checklist
+
+> First-time setup walkthrough for JunctionHackathon / Surface Code + DiffQEC on LUMI.
+> Estimated time: **~30 minutes** for a new user.
+
+---
+
+## Step 0: Prerequisites
+
+- [ ] You have a CSC account (or can request one via your institution)
+- [ ] You have been added to the JunctionHackathon LUMI allocation
+- [ ] You have a laptop with an SSH client and `rsync` available
+- [ ] You know your SSH alias for LUMI (ask your admin — do NOT assume `lumi`)
+
+---
+
+## Step 1: SSH Access
+
+```bash
+# Test login (replace 'lumi' with your confirmed alias)
+ssh lumi
+# Accept host key if prompted
+exit
+```
+
+Verify you can log in without password failures. If you get a permission denied error, contact your CSC project administrator.
+
+---
+
+## Step 2: Confirm Allocation
+
+On LUMI (after ssh):
+
+```bash
+lumi-allocations
+```
+
+This prints your project ID (looks like `project_465001234`). Copy it — you'll need it for Step 4.
+
+---
+
+## Step 3: Configure SSH Config (Laptop)
+
+Add to `~/.ssh/config`:
+
+```
+Host lumi
+    HostName lumi.csc.fi
+    User <your-csc-username>
+    IdentityFile ~/.ssh/id_ed25519   # your SSH key
+    StrictHostKeyChecking accept-new
+
+Host lumidt
+    HostName lumidt.csc.fi
+    User <your-csc-username>
+    IdentityFile ~/.ssh/id_ed25519
+    StrictHostKeyChecking accept-new
+```
+
+> **Note:** SSH aliases `lumi` and `lumidt` are common but confirm with your admin. Do not assume these names.
+
+---
+
+## Step 4: Set Up Local Environment Template
+
+On your **laptop** (not LUMI):
+
+```bash
+cd JunctionHackathon/lumi_deployment
+cp env.example .env
+# Edit .env with your project ID from Step 2
+```
+
+In `.env`:
+```
+export LUMI_PROJECT_ACCOUNT=project_<your-id>
+export SBATCH_ACCOUNT="$LUMI_PROJECT_ACCOUNT"
+```
+
+> **Warning:** `.env` is gitignored. Never commit it.
+
+---
+
+## Step 5: Bootstrap Environment on LUMI
+
+```bash
+# From your laptop, sync the repo into the project filesystem.
+# Confirm the remote path first; this example lets the remote shell expand $PROJECT.
+rsync -avP --exclude='venv/' --exclude='.git/' --exclude='results/' \
+  ./ lumi:'$PROJECT/JunctionHackathon/'
+
+# Then SSH to LUMI and bootstrap from the synced repo.
+ssh lumi
+cd "$PROJECT/JunctionHackathon/lumi_deployment"
+bash setup_lumi_env.sh
+```
+
+`setup_lumi_env.sh` will:
+1. Purge existing modules
+2. Load LUMI/25.09 + partition/G + rocm + cray-python/3.11.7
+3. Create or update a venv at `$PROJECT_DIR/venv` with `--system-site-packages`
+4. Install requirements from `requirements.txt`
+5. Verify key imports: `qiskit`, `stim`, `pymatching`, `numpy`, `torch`
+
+> **Storage rule:** keep the repo and venv under `$PROJECT` (or explicitly set `VENV_DIR` under `$SCRATCH`). Do not build Python environments in `$HOME`.
+
+Expected output:
+```
+Environment ready at <venv-path>
+```
+
+---
+
+## Step 6: Run Smoke Test
+
+```bash
+# Set account from your project id, or source lumi_deployment/.env
+export LUMI_PROJECT_ACCOUNT=project_<your-id>
+export SBATCH_ACCOUNT="$LUMI_PROJECT_ACCOUNT"
+
+# Submit minimal smoke test
+sbatch --account="$LUMI_PROJECT_ACCOUNT" hello_smoke.sbatch
+
+# Watch it
+squeue -u $USER
+
+# Check output when done
+cat hello_smoke-*.out
+```
+
+Expected in output:
+- `SMOKE OK`
+- torch device: cuda (if ROCm working) or cpu
+
+---
+
+## Step 7: Run DiffQEC Smoke Test
+
+```bash
+sbatch --account="$LUMI_PROJECT_ACCOUNT" diffqec_smoke.sbatch
+squeue -u $USER
+cat diffqec_smoke-*.out
+```
+
+Expected:
+- `SMOKE TEST PASSED`
+- Test summary from `pytest tests/test_diffqec.py -v`
+
+---
+
+## Step 8: Validate QEC Pipeline Imports
+
+On LUMI (interactive or via a short batch job):
+
+```bash
+source $PROJECT_DIR/venv/bin/activate
+python - <<'PY'
+import stim, qiskit, pymatching, numpy, torch
+print("stim:", stim.__version__)
+print("qiskit:", qiskit.__version__)
+print("pymatching:", pymatching.__version__)
+print("numpy:", numpy.__version__)
+print("torch:", torch.__version__)
+print("All imports OK")
+PY
+```
+
+---
+
+## Step 9: First Production Run (Optional)
+
+After smoke tests pass, submit a real job:
+
+```bash
+# Example: run the full DiffQEC smoke with more epochs
+sbatch --account="$LUMI_PROJECT_ACCOUNT" diffqec_smoke.sbatch
+```
+
+Monitor with `squeue -u $USER`.
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `module load LUMI/25.09` fails | Check `module avail`; system may have different software stack |
+| `cray-python/3.11.7` not found | Try `cray-python/3.11.6` or check `module avail cray-python` |
+| Import errors in venv | Re-run `bash setup_lumi_env.sh`; only remove a venv after confirming its path is `$PROJECT/JunctionHackathon/venv` |
+| ROCm/GPU not visible | Confirm `module load partition/G` was run before `module load rocm` |
+| Out of budget | Run `lumi-allocations` to check remaining; contact CSC |
+| SSH alias unknown | Ask admin; do NOT guess `lumi` vs `lumi2` vs full hostname |
+
+---
+
+## First-Time Summary
+
+```
+laptop: cp env.example .env  → fill in LUMI_PROJECT_ACCOUNT/SBATCH_ACCOUNT
+lumi:   bash setup_lumi_env.sh
+lumi:   sbatch --account="$LUMI_PROJECT_ACCOUNT" hello_smoke.sbatch  → should print SMOKE OK
+lumi:   sbatch --account="$LUMI_PROJECT_ACCOUNT" diffqec_smoke.sbatch → should print SMOKE TEST PASSED
+```
+
+Once Steps 1-8 complete, you're ready for [deployment.md](./deployment.md) (day-of workflow).
diff --git a/lumi_deployment/README.md b/lumi_deployment/README.md
new file mode 100644
index 0000000..fa86f22
--- /dev/null
+++ b/lumi_deployment/README.md
@@ -0,0 +1,76 @@
+# LUMI Deployment — JunctionHackathon / Surface Code + DiffQEC
+
+> Quick operational card. See `docs/lumi/README.md` for full docs.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Sync from laptop
+rsync -avP --exclude='venv/' --exclude='.git/' --exclude='results/' \
+  ./ lumi:'$PROJECT/JunctionHackathon/'
+
+# 2. On LUMI — bootstrap (one-time)
+cd "$PROJECT/JunctionHackathon/lumi_deployment"
+bash setup_lumi_env.sh
+
+# 3. Activate venv
+source ../venv/bin/activate
+
+# 4. Run smoke tests
+export LUMI_PROJECT_ACCOUNT=project_<your-id>
+export SBATCH_ACCOUNT="$LUMI_PROJECT_ACCOUNT"
+sbatch --account="$LUMI_PROJECT_ACCOUNT" hello_smoke.sbatch      # 2 min — torch/ROCm check
+sbatch --account="$LUMI_PROJECT_ACCOUNT" diffqec_smoke.sbatch   # 10 min — DiffQEC + pytest
+
+# 5. Collect results
+rsync -avP lumi:'$PROJECT/JunctionHackathon/results/' ./results/
+```
+
+---
+
+## Scripts
+
+| Script | What it does | Walltime |
+|---|---|---|
+| `setup_lumi_env.sh` | Bootstrap venv + deps under the repo/project area (run once) | N/A |
+| `hello_smoke.sbatch` | Minimal torch/ROCm smoke test | 2 min |
+| `diffqec_smoke.sbatch` | DiffQEC smoke + pytest | 10 min |
+| `env.example` | Template for `.env` (no real secrets) | — |
+
+---
+
+## Key Commands
+
+```bash
+# Module stack (always LUMI/25.09)
+module --force purge
+module load LUMI/25.09
+module load partition/G
+module load rocm
+module load cray-python/3.11.7
+
+# Slurm
+sbatch <script>.sbatch
+squeue -u $USER
+scancel <jobid>
+```
+
+---
+
+## Docs
+
+- `docs/lumi/README.md` — overview + index
+- `docs/lumi/preflight.md` — first-time setup (~30 min)
+- `docs/lumi/deployment.md` — day-of workflow
+
+---
+
+## Safety
+
+- **No GPU work on login nodes** — all GPU jobs go through `sbatch`
+- **No hardcoded project IDs** — use `--account="$LUMI_PROJECT_ACCOUNT"` or `SBATCH_ACCOUNT`
+- **No large data in `$HOME`** — use `$PROJECT` or `$SCRATCH`
+- **No venvs in `$HOME`** — keep envs under `$PROJECT` or explicitly set `VENV_DIR` under `$SCRATCH`
+- **Confirm SSH aliases** with your admin — don't assume `lumi`
diff --git a/lumi_deployment/diffqec_smoke.sbatch b/lumi_deployment/diffqec_smoke.sbatch
new file mode 100644
index 0000000..f71f7f8
--- /dev/null
+++ b/lumi_deployment/diffqec_smoke.sbatch
@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# diffqec_smoke.sbatch — DiffQEC smoke test + pytest on LUMI-G.
+#
+# Runs the Surface Code / DiffQEC pipeline smoke test:
+#   1. python -m diffqec.smoke_test  (tiny model train/eval on synthetic d=3 data)
+#   2. pytest tests/test_diffqec.py -v  (unit + integration tests)
+#
+# Outputs go to $REPO_DIR/results/diffqec_smoke/$SLURM_JOB_ID/
+#
+# Usage on LUMI:
+#   sbatch --account="$LUMI_PROJECT_ACCOUNT" diffqec_smoke.sbatch
+#   # OR: export SBATCH_ACCOUNT="$LUMI_PROJECT_ACCOUNT" && sbatch diffqec_smoke.sbatch
+#   squeue -u $USER
+#   cat diffqec_smoke-*.out
+
+#SBATCH --job-name=diffqec_smoke
+#SBATCH --partition=dev-g
+#SBATCH --nodes=1
+#SBATCH --ntasks=1
+#SBATCH --cpus-per-task=8
+#SBATCH --gpus=1
+#SBATCH --time=00:10:00
+#SBATCH --mem=16G
+#SBATCH --output=diffqec_smoke-%j.out
+#SBATCH --error=diffqec_smoke-%j.err
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Default REPO_DIR to repo root (parent of lumi_deployment/)
+REPO_DIR="${REPO_DIR:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+VENV_DIR="${VENV_DIR:-$REPO_DIR/venv}"
+
+echo "== host     : $(hostname)"
+echo "== date     : $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+echo "== account   : ${SLURM_JOB_ACCOUNT:-${SBATCH_ACCOUNT:-<unset — pass --account or export SBATCH_ACCOUNT before sbatch>}}"
+echo "== slurm    : job ${SLURM_JOB_ID:-n/a} on ${SLURM_CLUSTER_NAME:-n/a}"
+echo "== gpus     : ${SLURM_GPUS:-n/a}"
+echo "== repo dir : $REPO_DIR"
+echo "== venv dir : $VENV_DIR"
+
+# Module stack — LUMI/25.09
+module purge
+module load LUMI/25.09
+module load partition/G
+module load rocm
+module load cray-python/3.11.7
+
+echo "== module list:"
+module list 2>&1 | sed 's/^/  /'
+
+# Activate venv
+if [[ -f "$VENV_DIR/bin/activate" ]]; then
+    # shellcheck disable=SC1091
+    source "$VENV_DIR/bin/activate"
+    echo "== venv   : activated $VENV_DIR"
+else
+    echo "ERROR: venv not found at $VENV_DIR" >&2
+    echo "Run bash setup_lumi_env.sh first" >&2
+    exit 1
+fi
+
+# Output directory
+OUT_DIR="$REPO_DIR/results/diffqec_smoke/${SLURM_JOB_ID:-debug}"
+mkdir -p "$OUT_DIR"
+echo "== output dir: $OUT_DIR"
+
+# Run DiffQEC smoke test
+echo ""
+echo "== === DiffQEC Smoke Test ==="
+set +e
+python -m diffqec.smoke_test
+SMOKE_EXIT=$?
+set -e
+
+echo ""
+echo "== smoke test exit code: $SMOKE_EXIT"
+
+# Run pytest
+echo ""
+echo "== === PyTest: test_diffqec.py ==="
+cd "$REPO_DIR"
+set +e
+python -m pytest tests/test_diffqec.py -v --tb=short 2>&1 | tee "$OUT_DIR/pytest_output.txt"
+PYTEST_EXIT=${PIPESTATUS[0]}
+set -e
+
+echo ""
+echo "== pytest exit code: $PYTEST_EXIT"
+echo "== full pytest output: $OUT_DIR/pytest_output.txt"
+echo "== results dir: $OUT_DIR"
+echo "== listing:"
+ls -lh "$OUT_DIR"
+
+# Exit with smoke test status (smoke test is the primary gate)
+if [[ $SMOKE_EXIT -ne 0 ]]; then
+    echo "== FAIL: diffqec.smoke_test failed (exit $SMOKE_EXIT)"
+    exit $SMOKE_EXIT
+elif [[ $PYTEST_EXIT -ne 0 ]]; then
+    echo "== WARN: pytest had failures (exit $PYTEST_EXIT) — review output"
+    exit $PYTEST_EXIT
+else
+    echo "== ALL CHECKS PASSED"
+    exit 0
+fi
diff --git a/lumi_deployment/env.example b/lumi_deployment/env.example
new file mode 100644
index 0000000..a0d7333
--- /dev/null
+++ b/lumi_deployment/env.example
@@ -0,0 +1,13 @@
+# LUMI deployment environment — fill in once, then scripts use it.
+# This file is gitignored (.env is in .gitignore) and never rsynced to LUMI.
+
+# CSC / LUMI project ID (looks like project_465001234).
+# Find it with: on LUMI run `lumi-allocations`; or check the CSC invite email.
+export LUMI_PROJECT_ACCOUNT=project_REPLACE_ME
+
+# Slurm account — use SBATCH_ACCOUNT env var or pass --account="$LUMI_PROJECT_ACCOUNT" to sbatch.
+# Do NOT use #SBATCH --account=${...} in scripts (shell variable expansion is unreliable in SBATCH directives).
+export SBATCH_ACCOUNT="$LUMI_PROJECT_ACCOUNT"
+
+# For script logging compatibility (some scripts reference SLURM_JOB_ACCOUNT)
+export SLURM_JOB_ACCOUNT="$LUMI_PROJECT_ACCOUNT"
diff --git a/lumi_deployment/hello_smoke.sbatch b/lumi_deployment/hello_smoke.sbatch
new file mode 100644
index 0000000..3edcc40
--- /dev/null
+++ b/lumi_deployment/hello_smoke.sbatch
@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# hello_smoke.sbatch — 2-minute LUMI-G smoke test.
+#
+# Run this FIRST after `ssh lumi` to confirm:
+#   1. Your account is valid (pass --account="$LUMI_PROJECT_ACCOUNT" or export SBATCH_ACCOUNT)
+#   2. ROCm + torch can see the MI250X GCD
+#   3. SLURM end-to-end works (submit, allocate, execute, return)
+#
+# Usage on LUMI:
+#   sbatch --account="$LUMI_PROJECT_ACCOUNT" hello_smoke.sbatch
+#   # OR: export SBATCH_ACCOUNT="$LUMI_PROJECT_ACCOUNT" && sbatch hello_smoke.sbatch
+#   squeue -u $USER
+#   cat hello_smoke-*.out
+#
+# Expected in stdout:
+#   - "SMOKE OK"
+#   - torch device: cuda (if ROCm working) or cpu
+#   - rocminfo gfx lines (if rocminfo available)
+
+#SBATCH --job-name=hello_smoke
+#SBATCH --partition=dev-g
+#SBATCH --nodes=1
+#SBATCH --ntasks=1
+#SBATCH --cpus-per-task=8
+#SBATCH --gpus=1
+#SBATCH --time=00:02:00
+#SBATCH --mem=8G
+#SBATCH --output=hello_smoke-%j.out
+#SBATCH --error=hello_smoke-%j.err
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+VENV_DIR="${VENV_DIR:-$REPO_DIR/venv}"
+
+echo "== host   : $(hostname)"
+echo "== date   : $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+echo "== slurm  : job ${SLURM_JOB_ID:-n/a} on ${SLURM_CLUSTER_NAME:-n/a}"
+echo "== gpus   : ${SLURM_GPUS:-n/a}"
+echo "== repo   : $REPO_DIR"
+
+# Module stack — LUMI/25.09 (LUMI/23.09 is deprecated on this system)
+module purge
+module load LUMI/25.09
+module load partition/G
+module load rocm
+module load cray-python/3.11.7
+
+echo "== module list:"
+module list 2>&1 | sed 's/^/  /'
+
+# Activate venv at $REPO_DIR/venv (default)
+if [[ -f "$VENV_DIR/bin/activate" ]]; then
+    # shellcheck disable=SC1091
+    source "$VENV_DIR/bin/activate"
+    echo "== venv   : activated $VENV_DIR"
+else
+    echo "== venv   : (no venv found at $VENV_DIR — using system cray-python)"
+fi
+
+python3 - <<'PY'
+import sys, platform, subprocess
+print("== python :", sys.version.split()[0], "on", platform.node())
+
+# Check torch + GPU
+try:
+    import torch
+    print("== torch  :", torch.__version__)
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print("== device :", device)
+    if torch.cuda.is_available():
+        print("== gpu name:", torch.cuda.get_device_name(0))
+        # Quick matmul to verify GPU works
+        x = torch.rand(1024, 1024, device=device)
+        y = torch.rand(1024, 1024, device=device)
+        z = (x @ y).cpu()
+        print("== gpu mm : OK, shape", z.shape)
+    else:
+        print("== gpu    : NOT AVAILABLE (CPU only)")
+except Exception as e:
+    print("== torch  : NOT AVAILABLE ->", e)
+
+# Check ROCm visibility via rocminfo
+try:
+    r = subprocess.run(["rocminfo"], capture_output=True, text=True, timeout=15)
+    gpus = [ln.strip() for ln in r.stdout.splitlines() if "gfx" in ln.lower()]
+    print("== rocminfo gfx:", gpus[:4] or ["<none>"])
+except Exception as e:
+    print("== rocminfo: NOT AVAILABLE ->", e)
+
+# Check key QEC imports
+for mod in ["stim", "qiskit", "pymatching"]:
+    try:
+        m = __import__(mod)
+        print(f"== {mod}  : {getattr(m, '__version__', 'installed')}")
+    except Exception as e:
+        print(f"== {mod}  : NOT AVAILABLE -> {e}")
+
+print("== SMOKE OK")
+PY
\ No newline at end of file
diff --git a/lumi_deployment/setup_lumi_env.sh b/lumi_deployment/setup_lumi_env.sh
new file mode 100644
index 0000000..834ce50
--- /dev/null
+++ b/lumi_deployment/setup_lumi_env.sh
@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# setup_lumi_env.sh — bootstrap the JunctionHackathon venv on LUMI-G.
+# Verified against the LUMI/25.09 software stack.
+#
+# Usage on LUMI from this directory:
+#   bash setup_lumi_env.sh
+#   PROJECT_DIR=/project/<project_id>/$USER/JunctionHackathon bash setup_lumi_env.sh
+#   VENV_DIR=$PROJECT_DIR/venv bash setup_lumi_env.sh
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="${PROJECT_DIR:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+VENV_DIR="${VENV_DIR:-$PROJECT_DIR/venv}"
+REQ_FILE="${REQ_FILE:-$PROJECT_DIR/requirements.txt}"
+
+echo "== setup_lumi_env.sh"
+echo "== project dir : $PROJECT_DIR"
+echo "== venv dir    : $VENV_DIR"
+echo "== req file    : $REQ_FILE"
+
+if [[ ! -f "$REQ_FILE" ]]; then
+    echo "ERROR: requirements file not found at $REQ_FILE" >&2
+    exit 1
+fi
+
+# LUMI/25.09 is the current supported software stack.
+# LUMI/23.09 is historical/deprecated for this project.
+module --force purge
+module load LUMI/25.09
+module load partition/G
+module load rocm
+module load cray-python/3.11.7
+
+echo "== module stack:"
+module list 2>&1 | sed 's/^/  /'
+
+# Build the venv with --system-site-packages so it can reuse Cray-provided
+# optimized packages where available. Keep it under the repo/project area, not
+# under $HOME, unless VENV_DIR is explicitly overridden.
+if [[ -d "$VENV_DIR" ]]; then
+    echo "== venv already exists at $VENV_DIR — activating and updating"
+else
+    echo "== creating venv at $VENV_DIR"
+    python3 -m venv "$VENV_DIR" --system-site-packages
+fi
+
+# shellcheck disable=SC1091
+source "$VENV_DIR/bin/activate"
+
+echo "== upgrading pip"
+python -m pip install --upgrade pip setuptools wheel
+
+echo "== installing requirements from $REQ_FILE"
+python -m pip install -r "$REQ_FILE"
+
+echo "== verifying key imports..."
+python - <<'PY'
+import importlib
+import sys
+
+mods = ["qiskit", "stim", "pymatching", "numpy", "torch"]
+failures = []
+
+for name in mods:
+    try:
+        mod = importlib.import_module(name)
+        ver = getattr(mod, "__version__", "unknown")
+        print(f"  OK: {name} ({ver})")
+    except ImportError as exc:
+        failures.append((name, str(exc)))
+        print(f"  FAIL: {name} -> {exc}")
+
+if failures:
+    print("\nMissing required imports:", file=sys.stderr)
+    for name, exc in failures:
+        print(f"  - {name}: {exc}", file=sys.stderr)
+    raise SystemExit(1)
+
+import torch
+device = "cuda" if torch.cuda.is_available() else "cpu"
+print(f"  torch device: {device} (ROCm PyTorch reports GPUs through the cuda API)")
+PY
+
+echo "== environment ready at $VENV_DIR"
+echo '== next step: sbatch --account="$LUMI_PROJECT_ACCOUNT" hello_smoke.sbatch'
diff --git a/opencode.json b/opencode.json
new file mode 100644
index 0000000..25db7e7
--- /dev/null
+++ b/opencode.json
@@ -0,0 +1,10 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [
+    "README.md",
+    "UsefulResources.md",
+    "docs/lumi/README.md",
+    "docs/lumi/preflight.md",
+    "docs/lumi/deployment.md"
+  ]
+}

From 6b0ebb37513693007e33f348c4e7874140423be1 Mon Sep 17 00:00:00 2001
From: Konsta Kiirikki <konsta.kiirikki@gmail.com>
Date: Sat, 6 Jun 2026 10:45:29 +0300
Subject: [PATCH 2/2] feat(lumi): add storage quota cleanup and prevention

- Add lumi_deployment/cleanup_lumi.sh: safe, idempotent cleanup
  script with --dry-run, --deep, --no-repoint flags; removes Python
  debris, pip/uv/hf caches, and writes cache-redirect block to
  ~/.bashrc pointing future caches at /scratch//cache
- Update setup_lumi_env.sh: venv now lives at
  /scratch//venv-junction (symlinked at /venv)
  to avoid blowing LUMI-G 100k home file-count quota; auto-migrates
  existing home venvs; appends cache-redirect exports to ~/.bashrc
- Add docs/lumi/storage.md: dedicated page covering LUMI storage
  tiers, both quota warnings (file-count and SBU), where things
  should live, prevention habits, and quick-reference commands
- Update docs/lumi/README.md: add storage.md to index, add
  /scratch/ path convention, add quota/SBU common-issues rows
- Update docs/lumi/preflight.md: document venv-on-scratch in
  Step 5, add home-quota troubleshooting row, link storage.md
- Update docs/lumi/deployment.md: add /scratch/ rows to
  Key Paths, add venv-on-scratch safety rule, link storage.md
- Update lumi_deployment/README.md: add cleanup_lumi.sh to
  scripts table, add storage-quota section, link storage.md
---
 docs/lumi/README.md               |  13 +-
 docs/lumi/deployment.md           |  19 +--
 docs/lumi/preflight.md            |  18 ++-
 docs/lumi/storage.md              | 193 +++++++++++++++++++++++++++++
 lumi_deployment/README.md         |  30 ++++-
 lumi_deployment/cleanup_lumi.sh   | 197 ++++++++++++++++++++++++++++++
 lumi_deployment/setup_lumi_env.sh | 115 +++++++++++------
 7 files changed, 529 insertions(+), 56 deletions(-)
 create mode 100644 docs/lumi/storage.md
 create mode 100644 lumi_deployment/cleanup_lumi.sh

diff --git a/docs/lumi/README.md b/docs/lumi/README.md
index 007ef96..93496ca 100644
--- a/docs/lumi/README.md
+++ b/docs/lumi/README.md
@@ -12,6 +12,7 @@
 |---|---|
 | **[preflight.md](./preflight.md)** | First-time LUMI setup checklist (~30 min) |
 | **[deployment.md](./deployment.md)** | Day-of workflow: sync, setup, submit jobs, collect results |
+| **[storage.md](./storage.md)** | Quota warnings, cleanup, and SBU management |
 
 ## Quick Reference
 
@@ -46,6 +47,7 @@ scancel <jobid>                 # cancel
 |---|---|
 | `$PROJECT` | Code, env, final outputs, git repos |
 | `$SCRATCH` | Large active datasets, checkpoints |
+| `/scratch/$USER` | Per-user scratch (venvs, caches, transient data — no SBU) |
 | `$HOME` | SSH config, dotfiles only — avoid for data and venvs |
 
 ### Key commands for this project
@@ -74,16 +76,18 @@ export SBATCH_ACCOUNT="$LUMI_PROJECT_ACCOUNT"
 | Error | Fix |
 |---|---|
 | `ModuleNotFoundError: No module named 'LUMI'` | Use `module load LUMI/25.09` — NOT 23.09 |
-| `Job violates accounting/QOS policy` | Check budget via `lumi-allocations`; submit with `--account="$LUMI_PROJECT_ACCOUNT"` or export `SBATCH_ACCOUNT` |
+| `Job violates accounting/QOS policy` | Check budget via `lumi-allocations`; confirm `SLURM_JOB_ACCOUNT` is set |
 | `ModuleNotFoundError: No module named 'rocm'` | Run `module load partition/G` before `module load rocm` |
 | GPU work on login node | All GPU jobs MUST go through `sbatch` |
-| Home quota pressure | Move envs/data back under `$PROJECT` or `$SCRATCH`; do not build venvs in `$HOME` |
+| **home directory file count quota exceeded** | Run `bash lumi_deployment/cleanup_lumi.sh --dry-run`, then without flag; see [storage.md](./storage.md) |
+| **storage billing unit / SBU warning** | Check `csc-workspaces`; move idle data from `/project/` to `/scratch/`; see [storage.md](./storage.md) |
 
 ## Scripts in `lumi_deployment/`
 
 | Script | Description |
 |---|---|
-| `setup_lumi_env.sh` | Bootstrap venv + install deps (run once) |
+| `setup_lumi_env.sh` | Bootstrap venv on scratch + cache redirects (run once) |
+| `cleanup_lumi.sh` | Reclaim home file-count quota; re-point caches to scratch |
 | `hello_smoke.sbatch` | Minimal 2-min smoke test (torch/ROCm check) |
 | `diffqec_smoke.sbatch` | Run DiffQEC smoke test + pytest (10 min) |
 | `env.example` | Template for local env vars (gitignored) |
@@ -94,4 +98,5 @@ export SBATCH_ACCOUNT="$LUMI_PROJECT_ACCOUNT"
 - Do NOT run GPU work interactively on login nodes
 - Do NOT hardcode project IDs or account numbers
 - Do NOT put large data in `$HOME`
-- Do NOT use deprecated LUMI/23.09 stack
+- Do NOT build venvs in `$HOME` — `setup_lumi_env.sh` puts them on `/scratch/$USER`
+- Do NOT use deprecated LUMI/23.09 stack
\ No newline at end of file
diff --git a/docs/lumi/deployment.md b/docs/lumi/deployment.md
index 732db9c..81986f7 100644
--- a/docs/lumi/deployment.md
+++ b/docs/lumi/deployment.md
@@ -40,6 +40,7 @@ cd "$PROJECT/JunctionHackathon/lumi_deployment"
 
 # If first time or venv missing:
 bash setup_lumi_env.sh
+source ~/.bashrc   # pick up cache redirects to /scratch
 
 # If venv already exists, just activate:
 source ../venv/bin/activate
@@ -95,7 +96,7 @@ Expected:
 
 ## 5. Collect Results
 
-Results land in `$REPO_DIR/results/<job_name>/<job_id>/` (normally `$PROJECT/JunctionHackathon/results/...`).
+Results land in `$PROJECT_DIR/results/<job_name>/<job_id>/`.
 
 ```bash
 # On LUMI — list results
@@ -124,6 +125,7 @@ cat diffqec_smoke-*.err
 # - module load fail   → module avail; check LUMI/25.09
 # - import error       → re-run setup_lumi_env.sh; only remove venv after confirming its path
 # - partition wrong    → use dev-g for short jobs, standard-g for longer GPU work
+# - home quota hit    → bash lumi_deployment/cleanup_lumi.sh --dry-run (see storage.md)
 ```
 
 ---
@@ -156,19 +158,22 @@ laptop: rsync results back
 | Path | Description |
 |---|---|
 | `$REPO_DIR` / `$PROJECT_DIR` | Repo root on LUMI (normally `$PROJECT/JunctionHackathon`) |
-| `$PROJECT_DIR/venv` | Python venv created by `setup_lumi_env.sh` |
+| `$PROJECT_DIR/venv` | Symlink → `/scratch/$USER/venv-junction` (actual venv on scratch) |
 | `$PROJECT_DIR/results/` | Job outputs (rsync to laptop after runs) |
 | `$PROJECT_DIR/lumi_deployment/` | Deployment scripts |
-| `$SCRATCH` | Large active datasets/checkpoints; avoid `$HOME` for data |
+| `/scratch/$USER/` | Per-user scratch: venvs, caches, active data (no SBU, 90-day purge) |
+| `/scratch/$USER/cache/` | Pip/uv/hf caches (re-pointed by `setup_lumi_env.sh`) |
+
+> **Storage quota hit?** See [storage.md](./storage.md) for cleanup and prevention.
 
 ---
 
 ## Safety Rules
 
 1. **Never run GPU work on login nodes** — always use `sbatch`
-2. **Never hardcode project IDs** — use `--account="$LUMI_PROJECT_ACCOUNT"` or `SBATCH_ACCOUNT`
+2. **Never hardcode project IDs** — use `${SLURM_JOB_ACCOUNT}`
 3. **Never put large data in `$HOME`** — use `$PROJECT` or `$SCRATCH`
-4. **Never build a venv in `$HOME`** — keep it under `$PROJECT` or explicitly set `VENV_DIR` under `$SCRATCH`
+4. **Never build a venv in `$HOME`** — `setup_lumi_env.sh` puts it on `/scratch/$USER`; if you create one manually, build it there too
 5. **Confirm SSH aliases** before every `ssh`/`rsync`
 
 ---
@@ -180,7 +185,7 @@ laptop: rsync results back
 rsync -avP ./ lumi:'$PROJECT/JunctionHackathon/'
 
 # Submit
-export SBATCH_ACCOUNT="$LUMI_PROJECT_ACCOUNT"   # or use --account="$LUMI_PROJECT_ACCOUNT"
+export SBATCH_ACCOUNT="$LUMI_PROJECT_ACCOUNT"
 sbatch --account="$LUMI_PROJECT_ACCOUNT" hello_smoke.sbatch
 sbatch --account="$LUMI_PROJECT_ACCOUNT" diffqec_smoke.sbatch
 
@@ -193,4 +198,4 @@ cat diffqec_smoke-*.out
 rsync -avP lumi:'$PROJECT/JunctionHackathon/results/' ./results/
 ```
 
-For more details, see [README.md](./README.md) and [preflight.md](./preflight.md).
+For more details, see [README.md](./README.md), [preflight.md](./preflight.md), and [storage.md](./storage.md).
\ No newline at end of file
diff --git a/docs/lumi/preflight.md b/docs/lumi/preflight.md
index a32bd6d..a31189d 100644
--- a/docs/lumi/preflight.md
+++ b/docs/lumi/preflight.md
@@ -98,15 +98,21 @@ bash setup_lumi_env.sh
 `setup_lumi_env.sh` will:
 1. Purge existing modules
 2. Load LUMI/25.09 + partition/G + rocm + cray-python/3.11.7
-3. Create or update a venv at `$PROJECT_DIR/venv` with `--system-site-packages`
+3. Create or update a venv at `/scratch/$USER/venv-junction` with `--system-site-packages` and symlink it to `$PROJECT_DIR/venv`
 4. Install requirements from `requirements.txt`
 5. Verify key imports: `qiskit`, `stim`, `pymatching`, `numpy`, `torch`
+6. Write an idempotent cache-redirect block to `~/.bashrc` so pip/uv/hf caches go to `/scratch/$USER/cache` instead of `$HOME`
 
-> **Storage rule:** keep the repo and venv under `$PROJECT` (or explicitly set `VENV_DIR` under `$SCRATCH`). Do not build Python environments in `$HOME`.
+> **Why scratch?** A Python venv contains 30–50 k small files. LUMI-G caps your home at 100 k files total. Putting the venv on scratch avoids blowing the quota. The symlink means `source ../venv/bin/activate` still works. See [storage.md](./storage.md) for details.
+
+After bootstrapping, activate the cache redirects:
+```bash
+source ~/.bashrc   # pick up the cache-redirect exports
+```
 
 Expected output:
 ```
-Environment ready at <venv-path>
+Environment ready at /scratch/<user>/venv-junction
 ```
 
 ---
@@ -186,7 +192,8 @@ Monitor with `squeue -u $USER`.
 |---|---|
 | `module load LUMI/25.09` fails | Check `module avail`; system may have different software stack |
 | `cray-python/3.11.7` not found | Try `cray-python/3.11.6` or check `module avail cray-python` |
-| Import errors in venv | Re-run `bash setup_lumi_env.sh`; only remove a venv after confirming its path is `$PROJECT/JunctionHackathon/venv` |
+| Import errors in venv | Re-run `bash setup_lumi_env.sh`; only remove a venv after confirming its path is `/scratch/$USER/venv-junction` |
+| Home file-count quota exceeded | Run `bash lumi_deployment/cleanup_lumi.sh --dry-run` first, then without flag; see [storage.md](./storage.md) |
 | ROCm/GPU not visible | Confirm `module load partition/G` was run before `module load rocm` |
 | Out of budget | Run `lumi-allocations` to check remaining; contact CSC |
 | SSH alias unknown | Ask admin; do NOT guess `lumi` vs `lumi2` vs full hostname |
@@ -198,8 +205,9 @@ Monitor with `squeue -u $USER`.
 ```
 laptop: cp env.example .env  → fill in LUMI_PROJECT_ACCOUNT/SBATCH_ACCOUNT
 lumi:   bash setup_lumi_env.sh
+lumi:   source ~/.bashrc    → pick up cache redirects
 lumi:   sbatch --account="$LUMI_PROJECT_ACCOUNT" hello_smoke.sbatch  → should print SMOKE OK
 lumi:   sbatch --account="$LUMI_PROJECT_ACCOUNT" diffqec_smoke.sbatch → should print SMOKE TEST PASSED
 ```
 
-Once Steps 1-8 complete, you're ready for [deployment.md](./deployment.md) (day-of workflow).
+Once Steps 1-8 complete, you're ready for [deployment.md](./deployment.md) (day-of workflow). See [storage.md](./storage.md) if you hit quota warnings.
\ No newline at end of file
diff --git a/docs/lumi/storage.md b/docs/lumi/storage.md
new file mode 100644
index 0000000..88489a3
--- /dev/null
+++ b/docs/lumi/storage.md
@@ -0,0 +1,193 @@
+# LUMI Storage — Quotas, Warnings, and Cleanup
+
+> You got here because LUMI warned you about **home directory file-count quota**
+> or **storage billing units (SBU)**.  This page explains both, tells you how to
+> fix them right now, and shows you how to prevent them from recurring.
+
+---
+
+## LUMI Storage Tiers at a Glance
+
+| Tier | Path | Quota (LUMI-G) | Quota (LUMI-C) | Billed? | Auto-purge? |
+|---|---|---|---|---|---|
+| **Home** | `/users/<u>` | 50 GB, **100 000 files** | 512 GB, 1 M files | No | No |
+| **Scratch (per-user)** | `/scratch/<u>` | No hard cap* | No hard cap* | **No SBU** | 90 days idle |
+| **Scratch (project)** | `$SCRATCH` → `/scratch/<project>` | No hard cap* | No hard cap* | **No SBU** | 90 days idle |
+| **Project** | `/project/<project>` | 1 TB default | 1 TB default | **Yes — SBU** (TB·day) | No |
+
+\* Soft quotas exist; performance degrades badly above a few million files on Lustre.
+
+---
+
+## The Two Warnings You Will See
+
+### 1. "home directory file count quota exceeded"
+
+**What it means.** Your `/users/<u>` has more than 100 000 files (LUMI-G) or
+1 M files (LUMI-C).  Login becomes slow; new file creation may fail silently.
+
+**Why it hits QEC projects specifically.** The JunctionHackathon stack
+(Qiskit + Stim + PyMatching + torch + JAX) brings in ~30–50 k small files
+just in a Python venv.  Pip, uv, matplotlib, Jupyter, and HuggingFace caches
+add another 10–30 k.  Add `__pycache__/`, `.pytest_cache/`, shot-result files,
+and you are over the limit before you've run a single job.
+
+**Immediate fix.** Run the cleanup script with `--dry-run` first:
+
+```bash
+# On LUMI — always dry-run first
+bash lumi_deployment/cleanup_lumi.sh --dry-run
+
+# If the dry-run output looks reasonable:
+bash lumi_deployment/cleanup_lumi.sh
+```
+
+If the default run is not enough (still over quota), re-run with `--deep`:
+
+```bash
+bash lumi_deployment/cleanup_lumi.sh --deep
+```
+
+`--deep` removes `~/.cache` entirely.  Everything in it will regenerate on
+next use, but you pay the time cost of re-downloading wheels.
+
+**Prevention.** Running `setup_lumi_env.sh` (or `cleanup_lumi.sh` with default
+flags) writes an idempotent block to `~/.bashrc` that re-points all transient
+caches (`$XDG_CACHE_HOME`, `$PIP_CACHE_DIR`, etc.) to `/scratch/$USER/cache`.
+This means from your next shell onward, pip/uv/huggingface/jupyter caches go
+directly to scratch, not home — the file-count problem cannot recur.
+
+### 2. "storage billing unit" / project quota warning
+
+**What it means.** Your CSC project (`project_46…`) is consuming storage on
+`/project/<id>`, which is billed in **SBU** (storage billing units, measured in
+TB·day).  The LUMI allocation comes with a fixed SBU budget; if your project
+stores data that sits idle, SBU consumption accumulates.
+
+**Why it happens.** Most common causes:
+
+- Large shot dumps, decoder checkpoints, or simulation outputs left on
+  `/project/` instead of `/scratch/`.
+- `rsync` or `scp` putting data into `/project/` by default.
+- Stale result directories from previous hackathon days.
+
+**Immediate fix.** Check what's consuming SBU:
+
+```bash
+csc-workspaces                          # list all project workspaces + SBU
+du -sh /project/$SLURM_JOB_ACCOUNT/*    # find biggest directories
+```
+
+Then either:
+
+- Move large, active data to `/scratch/$USER/` or `/scratch/$SLURM_JOB_ACCOUNT/`
+  (no SBU, but auto-purged after 90 days idle).
+- Delete data you no longer need.
+- Archive final results to your laptop via `rsync -avP lumi:… ./results/`.
+
+---
+
+## Where Things Should Live
+
+| What | Put it on | Why |
+|---|---|---|
+| Source code, notebooks, `.git` | `$HOME` or `$PROJECT` | Small; needs permanence |
+| Python venv | `/scratch/$USER/venv-junction` | 30–50 k files; blows home quota |
+| Pip/uv/hf/jupyter caches | `/scratch/$USER/cache` | Transient; we re-point via `~/.bashrc` |
+| `__pycache__/`, `.pytest_cache/` | (deleted; regenerated) | Debris; `cleanup_lumi.sh` removes |
+| Active simulation data, shot dumps | `/scratch/$USER/` or `/scratch/<project>` | Large, temporary, no SBU |
+| Decoder checkpoints, intermediate results | `/scratch/$USER/` | Large, temporary |
+| Final results to keep past 90 days | `/project/<project>` | Billed in SBU; only keep what you need |
+| SBATCH job output (`*.out`, `*.err`) | `/scratch/<project>` or `$HOME` (small) | Small per-file; many jobs add up |
+
+---
+
+## Day-to-Day Habits That Prevent Quota Issues
+
+1. **Always `source ~/.bashrc` after first run of `setup_lumi_env.sh`.**
+   The cache-redirect block takes effect in new shells only.
+
+2. **Never build a venv in `$HOME`.**
+   `setup_lumi_env.sh` now puts it on `/scratch/$USER/venv-junction` and
+   symlinks it into the project.  If you `python -m venv .venv` manually,
+   build it on scratch too:
+
+   ```bash
+   python -m venv /scratch/$USER/venv-custom
+   ln -s /scratch/$USER/venv-custom .venv
+   ```
+
+3. **Clone shallow when you can.**
+
+   ```bash
+   git clone --depth 1 <url>   # saves ~10k files in .git/objects
+   ```
+
+4. **Don't write per-shot files.**  If your pipeline dumps one file per syndrome
+   round, batch them into `.npy` or `.npz` files instead.  A single 10 MB `.npz`
+   counts as one file; 10 000 one-line `.txt` files count as 10 000 files and
+   destroy Lustre performance.
+
+5. **Clean up after debugging.**  `__pycache__/` and `.pytest_cache/` regenerate
+   automatically.  Run `cleanup_lumi.sh` periodically or before big job
+   submissions.
+
+6. **Move results off `/project/` when done.**  rsync to your laptop, then
+   delete from LUMI.  Sitting data costs SBU.
+
+---
+
+## The Cleanup Script — What It Does
+
+| Flag | What it removes | Risk |
+|---|---|---|
+| *(default)* | `__pycache__/`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`, `.ipynb_checkpoints/`, `*.pyc`, `.coverage`, `~/.cache/{pip,uv,huggingface,matplotlib,jupyter,torch,triton,pytest,Cython}`, `~/.ipython`, `~/.local/share/jupyter/runtime/*`, `~/.jupyter/runtime/*`, `~/.config/{pip,uv}` | None — all auto-regenerated |
+| `--deep` | All of the above **plus** `~/.cache/` entirely | Low — caches rebuild on next use, but downloads take time |
+| `--no-repoint` | Skip the `~/.bashrc` cache-redirect write | Use this if you manage your env vars yourself |
+| `--dry-run` | Print what would be deleted; change nothing | Safe — always run this first |
+
+The script is **idempotent**: running it multiple times is safe.  It uses
+`find -xdev` to stay on the home filesystem and never crosses into `/scratch`
+or `/project`.
+
+---
+
+## Quick Reference
+
+```bash
+# Diagnose — run on LUMI
+lfs quota -u $USER ~                  # space + file-count quota
+find ~ -xdev -type f | wc -l          # current file count
+du -sh ~/.cache ~/.local ~/* 2>/dev/null | sort -h | tail    # biggest dirs
+csc-workspaces                         # SBU usage
+
+# Clean up (always dry-run first)
+bash lumi_deployment/cleanup_lumi.sh --dry-run
+bash lumi_deployment/cleanup_lumi.sh
+
+# If still over quota
+bash lumi_deployment/cleanup_lumi.sh --deep
+
+# One-time setup (venv on scratch + cache redirects)
+bash lumi_deployment/setup_lumi_env.sh
+source ~/.bashrc   # pick up cache redirects
+
+# Verify after cleanup
+lfs quota -u $USER ~
+find ~ -xdev -type f | wc -l
+```
+
+---
+
+## Related Docs
+
+- [preflight.md](./preflight.md) — first-time LUMI setup (~30 min)
+- [deployment.md](./deployment.md) — day-of job submission workflow
+- [README.md](./README.md) — LUMI docs index + quick reference
+
+## Scripts
+
+| Script | Location | What it does |
+|---|---|---|
+| `cleanup_lumi.sh` | `lumi_deployment/` | Remove Python debris + caches; re-point caches to scratch |
+| `setup_lumi_env.sh` | `lumi_deployment/` | Bootstrap venv on scratch; set up cache redirects |
\ No newline at end of file
diff --git a/lumi_deployment/README.md b/lumi_deployment/README.md
index fa86f22..eaf34e0 100644
--- a/lumi_deployment/README.md
+++ b/lumi_deployment/README.md
@@ -11,11 +11,12 @@
 rsync -avP --exclude='venv/' --exclude='.git/' --exclude='results/' \
   ./ lumi:'$PROJECT/JunctionHackathon/'
 
-# 2. On LUMI — bootstrap (one-time)
+# 2. On LUMI — bootstrap (one-time, puts venv on /scratch)
 cd "$PROJECT/JunctionHackathon/lumi_deployment"
 bash setup_lumi_env.sh
+source ~/.bashrc   # pick up cache redirects to /scratch
 
-# 3. Activate venv
+# 3. Activate venv (symlinked from project root)
 source ../venv/bin/activate
 
 # 4. Run smoke tests
@@ -34,7 +35,8 @@ rsync -avP lumi:'$PROJECT/JunctionHackathon/results/' ./results/
 
 | Script | What it does | Walltime |
 |---|---|---|
-| `setup_lumi_env.sh` | Bootstrap venv + deps under the repo/project area (run once) | N/A |
+| `setup_lumi_env.sh` | Bootstrap venv on scratch + cache redirects (run once) | N/A |
+| `cleanup_lumi.sh` | Reclaim home file-count quota; `--dry-run` first, then live | N/A |
 | `hello_smoke.sbatch` | Minimal torch/ROCm smoke test | 2 min |
 | `diffqec_smoke.sbatch` | DiffQEC smoke + pytest | 10 min |
 | `env.example` | Template for `.env` (no real secrets) | — |
@@ -64,13 +66,31 @@ scancel <jobid>
 - `docs/lumi/README.md` — overview + index
 - `docs/lumi/preflight.md` — first-time setup (~30 min)
 - `docs/lumi/deployment.md` — day-of workflow
+- `docs/lumi/storage.md` — quota warnings, cleanup, and SBU management
 
 ---
 
 ## Safety
 
 - **No GPU work on login nodes** — all GPU jobs go through `sbatch`
-- **No hardcoded project IDs** — use `--account="$LUMI_PROJECT_ACCOUNT"` or `SBATCH_ACCOUNT`
+- **No hardcoded project IDs** — use `${SLURM_JOB_ACCOUNT}`
 - **No large data in `$HOME`** — use `$PROJECT` or `$SCRATCH`
-- **No venvs in `$HOME`** — keep envs under `$PROJECT` or explicitly set `VENV_DIR` under `$SCRATCH`
+- **No venvs in `$HOME`** — `setup_lumi_env.sh` puts them on `/scratch/$USER`; if manual, build there too
 - **Confirm SSH aliases** with your admin — don't assume `lumi`
+
+---
+
+## Storage Quota Hit?
+
+```bash
+# Diagnose
+bash lumi_deployment/cleanup_lumi.sh --dry-run
+
+# Clean up
+bash lumi_deployment/cleanup_lumi.sh
+
+# Still over? Deep clean
+bash lumi_deployment/cleanup_lumi.sh --deep
+```
+
+See `docs/lumi/storage.md` for full details.
\ No newline at end of file
diff --git a/lumi_deployment/cleanup_lumi.sh b/lumi_deployment/cleanup_lumi.sh
new file mode 100644
index 0000000..d7b4a7e
--- /dev/null
+++ b/lumi_deployment/cleanup_lumi.sh
@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# cleanup_lumi.sh — reclaim LUMI home-directory file-count and space quota.
+#
+# Why this exists:
+#   The JunctionHackathon pipeline (Qiskit + Stim + PyMatching + DiffQEC) tends to
+#   leave behind tens of thousands of small files in $HOME: __pycache__, pip/uv
+#   wheels, ipython history, jupyter runtimes, .pytest_cache, etc.  On LUMI-G
+#   the home directory is hard-capped at ~50 GB / 100,000 files, and Lustre is
+#   especially slow with many small files — so the second a user exceeds the
+#   count quota, every subsequent login warning becomes an obstacle.
+#
+# What it does (default, safe):
+#   - Removes Python debris: __pycache__/, .pytest_cache/, *.pyc, .coverage
+#   - Removes pip / uv caches under ~/.cache
+#   - Removes matplotlib / jupyter / ipython runtime junk
+#   - Re-points pip/uv at /scratch/$USER/cache (idempotent block in ~/.bashrc)
+#
+# What it does NOT touch:
+#   - Any venv (./venv, ./.venv, /scratch/$USER/venv-junction)
+#   - .git, source code, results/, lumi_deployment/, requirements files
+#   - Anything in /scratch, /project, /appl (out of home via -xdev)
+#
+# Usage:
+#   bash lumi_deployment/cleanup_lumi.sh --dry-run   # show what would happen
+#   bash lumi_deployment/cleanup_lumi.sh             # safe default cleanup
+#   bash lumi_deployment/cleanup_lumi.sh --deep      # also rm -rf ~/.cache
+#                                                    # use only if still over
+#                                                    # quota after default run
+#
+# Always run with --dry-run first.  Nothing here is recoverable.
+
+set -euo pipefail
+
+DRY_RUN=0
+DEEP=0
+REPOINT_CACHES=1
+
+print_usage() {
+  cat <<'EOF'
+Usage: bash lumi_deployment/cleanup_lumi.sh [--dry-run] [--deep] [--no-repoint]
+
+  --dry-run      Print every action as [dry-run]; change nothing.
+  --deep         Also nuke ~/.cache entirely.  Use only if default is
+                 not enough — caches regenerate on next use.
+  --no-repoint   Skip writing the cache-redirect block to ~/.bashrc.
+
+Default: removes Python debris and pip/uv/ipython caches, then writes a
+small idempotent block to ~/.bashrc that re-points future caches to
+/scratch/$USER/cache.
+EOF
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run|-n)   DRY_RUN=1 ;;
+    --deep)         DEEP=1 ;;
+    --no-repoint)   REPOINT_CACHES=0 ;;
+    -h|--help)      print_usage; exit 0 ;;
+    *)              echo "Unknown argument: $arg" >&2; print_usage >&2; exit 2 ;;
+  esac
+done
+
+HOME_DIR="${HOME:-/tmp}"
+USER_NAME="${USER:-$(id -un)}"
+SCRATCH_USER="/scratch/${USER_NAME}/cache"
+
+run() {
+  if [ "$DRY_RUN" -eq 1 ]; then
+    printf '  [dry-run] %s\n' "$*"
+  else
+    printf '  [run]     %s\n' "$*"
+    eval "$@"
+  fi
+}
+
+files_in_home() {
+  find "$HOME_DIR" -xdev -type f 2>/dev/null | wc -l
+}
+
+du_h() {
+  du -sh "$1" 2>/dev/null | cut -f1 || echo "?"
+}
+
+echo "== LUMI home cleanup =="
+echo "  user      : $USER_NAME"
+echo "  home      : $HOME_DIR"
+echo "  scratch   : $SCRATCH_USER"
+echo "  mode      : $([ "$DRY_RUN" -eq 1 ] && echo 'DRY-RUN' || echo 'LIVE')"
+echo "  deep      : $DEEP"
+echo "  repoint   : $REPOINT_CACHES"
+echo
+
+echo "== Snapshot BEFORE =="
+files_in_home | awk '{printf "  home file count: %s\n", $1}'
+[ -d "$HOME_DIR/.cache" ] && printf "  ~/.cache      : %s\n" "$(du_h "$HOME_DIR/.cache")" || true
+[ -d "$HOME_DIR/.local" ] && printf "  ~/.local      : %s\n" "$(du_h "$HOME_DIR/.local")" || true
+[ -d "$HOME_DIR/.ipython" ] && printf "  ~/.ipython    : %s\n" "$(du_h "$HOME_DIR/.ipython")" || true
+if command -v lfs >/dev/null 2>&1; then
+  lfs quota -u "$USER_NAME" "$HOME_DIR" 2>/dev/null | sed 's/^/  lfs: /' || true
+fi
+echo
+
+# --- 1. Python debris --------------------------------------------------------
+echo "== Removing Python debris =="
+find "$HOME_DIR" -xdev -type d -name '__pycache__' -prune -print 2>/dev/null \
+  | while IFS= read -r d; do [ -n "$d" ] && run rm -rf "$d"; done
+find "$HOME_DIR" -xdev -type d -name '.pytest_cache' -prune -print 2>/dev/null \
+  | while IFS= read -r d; do [ -n "$d" ] && run rm -rf "$d"; done
+find "$HOME_DIR" -xdev -type d -name '.mypy_cache' -prune -print 2>/dev/null \
+  | while IFS= read -r d; do [ -n "$d" ] && run rm -rf "$d"; done
+find "$HOME_DIR" -xdev -type d -name '.ruff_cache' -prune -print 2>/dev/null \
+  | while IFS= read -r d; do [ -n "$d" ] && run rm -rf "$d"; done
+find "$HOME_DIR" -xdev -type d -name '.ipynb_checkpoints' -prune -print 2>/dev/null \
+  | while IFS= read -r d; do [ -n "$d" ] && run rm -rf "$d"; done
+find "$HOME_DIR" -xdev -type f -name '*.pyc' -print -delete 2>/dev/null | sed 's/^/  [run]     rm -f /'
+find "$HOME_DIR" -xdev -type f -name '.coverage' -print -delete 2>/dev/null | sed 's/^/  [run]     rm -f /'
+echo
+
+# --- 2. Tool caches ----------------------------------------------------------
+echo "== Removing tool caches =="
+for d in \
+  "$HOME_DIR/.cache/pip" \
+  "$HOME_DIR/.cache/uv" \
+  "$HOME_DIR/.cache/huggingface" \
+  "$HOME_DIR/.cache/matplotlib" \
+  "$HOME_DIR/.cache/jupyter" \
+  "$HOME_DIR/.cache/torch" \
+  "$HOME_DIR/.cache/triton" \
+  "$HOME_DIR/.cache/pytest" \
+  "$HOME_DIR/.cache/Cython" \
+  ; do
+  [ -d "$d" ] && run rm -rf "$d"
+done
+[ -d "$HOME_DIR/.ipython" ] && run rm -rf "$HOME_DIR/.ipython"
+[ -d "$HOME_DIR/.local/share/jupyter/runtime" ] \
+  && run rm -rf "$HOME_DIR/.local/share/jupyter/runtime"
+[ -d "$HOME_DIR/.jupyter/runtime" ] \
+  && run rm -rf "$HOME_DIR/.jupyter/runtime"
+[ -d "$HOME_DIR/.config/pip" ] && run rm -rf "$HOME_DIR/.config/pip"
+[ -d "$HOME_DIR/.config/uv" ]  && run rm -rf "$HOME_DIR/.config/uv"
+echo
+
+# --- 3. Optional deep wipe ---------------------------------------------------
+if [ "$DEEP" -eq 1 ]; then
+  echo "== DEEP wipe of ~/.cache =="
+  [ -d "$HOME_DIR/.cache" ] && run rm -rf "$HOME_DIR/.cache"
+  echo
+fi
+
+# --- 4. Re-point future caches to scratch -----------------------------------
+if [ "$REPOINT_CACHES" -eq 1 ]; then
+  echo "== Writing cache-redirect block to ~/.bashrc =="
+  mkdir -p "$SCRATCH_USER"/{pip,uv,huggingface,matplotlib,jupyter,triton} \
+    2>/dev/null || true
+  BLOCK_BEGIN="# >>> junction-hackathon cache env (managed by cleanup_lumi.sh) >>>"
+  BLOCK_END="# <<< junction-hackathon cache env <<<"
+  BASHRC="$HOME_DIR/.bashrc"
+
+  if [ -f "$BASHRC" ] && grep -qF "$BLOCK_BEGIN" "$BASHRC"; then
+    echo "  block already present in $BASHRC — leaving as-is"
+  else
+    if [ "$DRY_RUN" -eq 1 ]; then
+      printf '  [dry-run] append cache-redirect block to %s\n' "$BASHRC"
+    else
+      cat >> "$BASHRC" <<EOF
+
+$BLOCK_BEGIN
+# Point transient caches at /scratch (no SBU, not subject to home file-count quota).
+export XDG_CACHE_HOME=$SCRATCH_USER
+export PIP_CACHE_DIR=$SCRATCH_USER/pip
+export UV_CACHE_DIR=$SCRATCH_USER/uv
+export HF_HOME=$SCRATCH_USER/huggingface
+export MPLCONFIGDIR=$SCRATCH_USER/matplotlib
+export JUPYTER_RUNTIME_DIR=$SCRATCH_USER/jupyter
+export TRITON_CACHE_DIR=$SCRATCH_USER/triton
+$BLOCK_END
+EOF
+      echo "  appended cache-redirect block to $BASHRC"
+      echo "  it takes effect in new shells; run 'source ~/.bashrc' to apply now"
+    fi
+  fi
+  echo
+fi
+
+# --- 5. Snapshot AFTER -------------------------------------------------------
+echo "== Snapshot AFTER =="
+files_in_home | awk '{printf "  home file count: %s\n", $1}'
+[ -d "$HOME_DIR/.cache" ] && printf "  ~/.cache      : %s\n" "$(du_h "$HOME_DIR/.cache")" || echo "  ~/.cache      : (gone)"
+[ -d "$HOME_DIR/.local" ] && printf "  ~/.local      : %s\n" "$(du_h "$HOME_DIR/.local")" || true
+[ -d "$HOME_DIR/.ipython" ] && printf "  ~/.ipython    : %s\n" "$(du_h "$HOME_DIR/.ipython")" || echo "  ~/.ipython    : (gone)"
+if command -v lfs >/dev/null 2>&1; then
+  lfs quota -u "$USER_NAME" "$HOME_DIR" 2>/dev/null | sed 's/^/  lfs: /' || true
+fi
+echo
+echo "== done =="
+echo "  next: open a new shell (or 'source ~/.bashrc') to pick up cache redirects."
+echo "  if file-count is still over the limit, re-run with --deep."
\ No newline at end of file
diff --git a/lumi_deployment/setup_lumi_env.sh b/lumi_deployment/setup_lumi_env.sh
index 834ce50..2272671 100644
--- a/lumi_deployment/setup_lumi_env.sh
+++ b/lumi_deployment/setup_lumi_env.sh
@@ -1,16 +1,28 @@
 #!/usr/bin/env bash
 # setup_lumi_env.sh — bootstrap the JunctionHackathon venv on LUMI-G.
-# Verified against the LUMI/25.09 software stack.
+# Verified working on LUMI/25.09 stack.
 #
-# Usage on LUMI from this directory:
+# Storage note (LUMI-G):
+#   The venv is built at /scratch/$USER/venv-junction by default — never on
+#   $HOME — to stay under LUMI's home file-count quota (100k files on
+#   LUMI-G).  A symlink is left at $PROJECT_DIR/venv so existing
+#   `source ../venv/bin/activate` calls keep working.
+#   Pip/uv/jupyter/hf caches are also re-pointed at /scratch/$USER/cache
+#   (see the .bashrc write at the end of this script).
+#
+# Usage:
 #   bash setup_lumi_env.sh
-#   PROJECT_DIR=/project/<project_id>/$USER/JunctionHackathon bash setup_lumi_env.sh
-#   VENV_DIR=$PROJECT_DIR/venv bash setup_lumi_env.sh
+#   VENV_DIR=/some/other/path bash setup_lumi_env.sh     # override location
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Default PROJECT_DIR to repo root (parent of lumi_deployment/)
 PROJECT_DIR="${PROJECT_DIR:-$(cd "$SCRIPT_DIR/.." && pwd)}"
-VENV_DIR="${VENV_DIR:-$PROJECT_DIR/venv}"
+USER_NAME="${USER:-$(id -un)}"
+# Default venv lives on scratch, NOT on home.  Override with VENV_DIR=... if
+# you really need to put it somewhere else.
+VENV_DIR="${VENV_DIR:-/scratch/${USER_NAME}/venv-junction}"
+# Find requirements.txt at repo root
 REQ_FILE="${REQ_FILE:-$PROJECT_DIR/requirements.txt}"
 
 echo "== setup_lumi_env.sh"
@@ -18,13 +30,8 @@ echo "== project dir : $PROJECT_DIR"
 echo "== venv dir    : $VENV_DIR"
 echo "== req file    : $REQ_FILE"
 
-if [[ ! -f "$REQ_FILE" ]]; then
-    echo "ERROR: requirements file not found at $REQ_FILE" >&2
-    exit 1
-fi
-
 # LUMI/25.09 is the current supported software stack.
-# LUMI/23.09 is historical/deprecated for this project.
+# (LUMI/23.09 is deprecated and rejects with cray-python/3.11.5 missing.)
 module --force purge
 module load LUMI/25.09
 module load partition/G
@@ -34,16 +41,34 @@ module load cray-python/3.11.7
 echo "== module stack:"
 module list 2>&1 | sed 's/^/  /'
 
-# Build the venv with --system-site-packages so it can reuse Cray-provided
-# optimized packages where available. Keep it under the repo/project area, not
-# under $HOME, unless VENV_DIR is explicitly overridden.
+# Build the venv with --system-site-packages so we pick up Cray's
+# optimized numpy / mpi4py etc.
 if [[ -d "$VENV_DIR" ]]; then
     echo "== venv already exists at $VENV_DIR — activating and updating"
 else
     echo "== creating venv at $VENV_DIR"
+    mkdir -p "$(dirname "$VENV_DIR")"
     python3 -m venv "$VENV_DIR" --system-site-packages
 fi
 
+# Symlink $PROJECT_DIR/venv -> $VENV_DIR so the conventional
+# `source ../venv/bin/activate` keeps working without copying the
+# 30–50k small venv files into $HOME (which would blow the file-count
+# quota).  If the user already has a real directory at $PROJECT_DIR/venv
+# from a prior install, we move it aside and symlink instead.
+PROJ_VENV="$PROJECT_DIR/venv"
+if [[ "$(readlink -f "$PROJ_VENV" 2>/dev/null || true)" == "$(readlink -f "$VENV_DIR" 2>/dev/null || true)" ]]; then
+    echo "== project-venv symlink already points to $VENV_DIR"
+elif [[ -d "$PROJ_VENV" && ! -L "$PROJ_VENV" ]]; then
+    echo "== migrating existing $PROJ_VENV (was on \$HOME) to $VENV_DIR"
+    # Move the existing venv into the scratch location, then symlink back.
+    mv "$PROJ_VENV" "$VENV_DIR"
+    ln -s "$VENV_DIR" "$PROJ_VENV"
+elif [[ ! -e "$PROJ_VENV" ]]; then
+    echo "== symlinking $PROJ_VENV -> $VENV_DIR"
+    ln -s "$VENV_DIR" "$PROJ_VENV"
+fi
+
 # shellcheck disable=SC1091
 source "$VENV_DIR/bin/activate"
 
@@ -53,33 +78,53 @@ python -m pip install --upgrade pip setuptools wheel
 echo "== installing requirements from $REQ_FILE"
 python -m pip install -r "$REQ_FILE"
 
+# Verify key imports for Surface Code / DiffQEC pipeline
 echo "== verifying key imports..."
 python - <<'PY'
 import importlib
-import sys
-
-mods = ["qiskit", "stim", "pymatching", "numpy", "torch"]
-failures = []
-
-for name in mods:
+# Core QEC stack
+mods = ["qiskit", "stim", "pymatching", "numpy"]
+for m in mods:
     try:
-        mod = importlib.import_module(name)
+        mod = importlib.import_module(m)
         ver = getattr(mod, "__version__", "unknown")
-        print(f"  OK: {name} ({ver})")
-    except ImportError as exc:
-        failures.append((name, str(exc)))
-        print(f"  FAIL: {name} -> {exc}")
-
-if failures:
-    print("\nMissing required imports:", file=sys.stderr)
-    for name, exc in failures:
-        print(f"  - {name}: {exc}", file=sys.stderr)
-    raise SystemExit(1)
+        print(f"  OK: {m} ({ver})")
+    except ImportError as e:
+        print(f"  FAIL: {m} -> {e}")
 
-import torch
-device = "cuda" if torch.cuda.is_available() else "cpu"
-print(f"  torch device: {device} (ROCm PyTorch reports GPUs through the cuda API)")
+# DiffQEC / ML stack (torch may be installed via requirements)
+try:
+    import torch
+    print(f"  OK: torch ({torch.__version__}) device={torch.device('cuda' if torch.cuda.is_available() else 'cpu')}")
+except ImportError as e:
+    print(f"  FAIL: torch -> {e}")
 PY
 
 echo "== environment ready at $VENV_DIR"
-echo '== next step: sbatch --account="$LUMI_PROJECT_ACCOUNT" hello_smoke.sbatch'
+echo "== next step: sbatch hello_smoke.sbatch"
+
+# Point transient caches at /scratch so they don't push $HOME over the
+# file-count quota.  Idempotent — re-running won't double up the block.
+CACHE_ROOT="/scratch/${USER_NAME}/cache"
+mkdir -p "$CACHE_ROOT"/{pip,uv,huggingface,matplotlib,jupyter,triton} 2>/dev/null || true
+
+CACHE_BEGIN="# >>> junction-hackathon cache env (managed by setup_lumi_env.sh) >>>"
+CACHE_END="# <<< junction-hackathon cache env <<<"
+BASHRC="$HOME/.bashrc"
+if [[ -f "$BASHRC" ]] && grep -qF "$CACHE_BEGIN" "$BASHRC"; then
+    echo "== cache-redirect block already in $BASHRC"
+else
+    echo "== appending cache-redirect block to $BASHRC"
+    cat >> "$BASHRC" <<EOF
+
+$CACHE_BEGIN
+export XDG_CACHE_HOME=$CACHE_ROOT
+export PIP_CACHE_DIR=$CACHE_ROOT/pip
+export UV_CACHE_DIR=$CACHE_ROOT/uv
+export HF_HOME=$CACHE_ROOT/huggingface
+export MPLCONFIGDIR=$CACHE_ROOT/matplotlib
+export JUPYTER_RUNTIME_DIR=$CACHE_ROOT/jupyter
+export TRITON_CACHE_DIR=$CACHE_ROOT/triton
+$CACHE_END
+EOF
+fi
\ No newline at end of file