# xps-thermal-bench(8)

## NAME
xps-thermal-bench - Scientific, power-aware thermal optimizer for Dell XPS laptops

## SYNOPSIS
**xps-thermal-bench** [*OPTIONS*]

## DESCRIPTION
**xps-thermal-bench** is a professional diagnostic utility that automates the generation and deployment of optimized **i8kmon(1)** and **throttled** configurations. It uses scientific thermal resistance modeling and real-world throughput benchmarks to find the perfect balance between performance and acoustics for your specific hardware unit.

### Key Scientific Features:
*   **Environmental Calibration**: Samples your natural ambient idle temperature at startup to anchor fan curves correctly for your specific session (TTY vs. Desktop).
*   **Thermal Resistance ($R_{\theta}$) Modeling**: Calculates the exact cooling efficiency (C/W) of your heatsink to determine sustainable power limits.
*   **Thermal Inertia Tracking**: Measures how fast your laptop sheds heat to dynamically tune fan hysteresis, preventing the high-pitched "RPM hunting" common in thin-and-light chassis.
*   **Silicon Knee Detection**: Identifies your CPU's unique throttling point by monitoring frequency stability jitter during load.
*   **Interactive Deployment**: One-key installation of generated profiles directly to the system with automatic service restarts.

## WORKFLOW
1.  **System Audit**: The tool validates your kernel modules (`dell_smm`), power state (AC is required for accuracy), and interfering services.
2.  **Calibration**: Captures your current environmental thermal floor.
3.  **Benchmarking**: Runs a matrix of loads (25%–100%) against every fan tier.
4.  **Optimization**: Calculates Quiet, Balanced, and Performance profiles using the gathered telemetry.
5.  **Installation**: Press **'i'** in the TUI to deploy your favorite profile and restart services immediately.

## OPTIONS
**-b, --baseline-temp** *CELSIUS*
    Target temperature for the cooling phase between tests. Default: 50.

**-c, --critical-temp** *CELSIUS*
    Safety ceiling at which a test is aborted. Default: 95.

**-C, --i8kmon-conf** *PATH*
    Override the path to the i8kmon configuration. (Default: Auto-discovered via systemd).

**-T, --throttled-conf** *PATH*
    Override the path to the throttled configuration. (Default: Auto-discovered via systemd).

**-e, --export-dir** *DIR*
    Directory to write generated configurations and backups.

**-f, --history-file** *PATH*
    Path to the JSON telemetry database. Default: thermal_history.json.

**-q, --quick**
    Fast-track mode (skips intermediate 50% and 75% load tiers).

**-s, --stressor** *STRESSOR*
    stress-ng workload type (e.g., `matrixprod`, `avx`, `cpu`, `fft`). Default: matrixprod.

**--no-tui**
    Disables the interactive terminal UI for a structured stdout log.

**--skip-checks**
    Bypasses the system audit. Use only if you know your hardware is compatible.

**--reprocess** [*HISTORY_JSON*]
    Generates new profiles and power limits from existing data without hardware tests.

## KEYBINDS (TUI Mode)
**TAB**
    Cycle between Quiet, Balanced, and Performance profile previews.
**i**
    **Install** the currently selected profile to the system and restart services.
**q**
    Quit and restore original system state (governors, frequencies, services).

## SAFETY & CLEANUP
The tool is designed to be "interruption-safe." Even if the program panics or is killed via `Ctrl+C`, it utilizes the Rust `Drop` trait to ensure:
*   Original CPU scaling governors are restored.
*   CPU frequency limits are unlocked.
*   Background power management services (like `auto-cpufreq` or `tlp`) are restarted.

## SETUP
### Prerequisites
- **Kernel**: `dell_smm_hwmon` must be loaded.
- **Power**: AC adapter must be connected.
- **Dependencies**: `stress-ng`, `i8kmon`, and `throttled`.

### Installation
```bash
cargo build --release
sudo ./target/release/xps-thermal-bench
```

## SEE ALSO
**i8kmon(1)**, **throttled(8)**, **stress-ng(1)**