# BenchRust

A delightfully sarcastic CPU benchmarking tool that doesn't take itself too seriously.

Stop wondering if your CPU is actually fast or just expensive. BenchRust measures your silicon's performance with scientific precision and just enough sarcasm to keep things interesting.

[![Rust](https://img.shields.io/badge/rust-000000?style=for-the-badge&logo=rust&logoColor=white)](https://www.rust-lang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)

## What the fuck is this?

BenchRust is a CPU benchmarking tool that tells it like it is. No marketing bullshit, no inflated numbers, just cold hard silicon truth. Whether you're running a beast mode gaming rig or a potato from 2015, we'll measure your CPU's performance and rate it accordingly.

### Features That Actually Matter

- **Multi-core & Single-core Benchmarks** - Because not everything scales perfectly
- **Statistical Analysis** - Real metrics, not just "bigger number = better"
- **Gorgeous CLI Output** - Because ugly terminals are a crime against humanity
- **Scaling Efficiency** - Find out if your cores actually cooperate
- **Thread Pinning** - For when you want serious benchmarking
- **JSON Export** - For automation nerds and data hoarders
- **Multiple Workloads** - Integer math, floating-point, memory access, and more

## Quick Start

### Installation

```bash
# From crates.io (when we publish it)
cargo install benchrust

# Or build from source (for the impatient)
git clone https://git.gostacks.org/iwasforcedtobehere/benchrust
cd benchrust
cargo build --release
```

### Basic Usage

```bash
# Run all benchmarks (recommended for first-timers)
benchrust

# Test specific workload with verbose output
benchrust --workload math-int --verbose

# Multicore performance test
benchrust --cores 0 --iterations 5

# Export results to JSON (for the data nerds)
benchrust --output json > my_cpu_results.json

# Single-core baseline (for comparison purposes)
benchrust --cores 1 --workload all
```

## Command Line Options

Because reading `--help` is for mere mortals:

| Flag | Description | Default | Example |
|------|-------------|---------|---------|
| `-c, --cores` | CPU cores to torture (0 = all available) | 0 | `--cores 4` |
| `-w, --workload` | Which benchmark to run | `all` | `--workload primes` |
| `-i, --iterations` | Number of runs (more = better stats) | 3 | `--iterations 10` |
| `-o, --output` | Output format (`text` or `json`) | `text` | `--output json` |
| `-t, --threads` | Thread count (defaults to core count) | auto | `--threads 8` |
| `-v, --verbose` | Verbose output (information overload) | false | `--verbose` |
| `--pin-cores` | Pin threads to specific cores | false | `--pin-cores` |
| `--warmup` | Warm-up iterations | 1 | `--warmup 3` |

### Workload Types

- **`all`** - The full fucking monty (recommended)
- **`math-int`** - Integer arithmetic (your CPU's bread and butter)
- **`math-float`** - Floating-point operations (for when precision matters)
- **`memory`** - Memory-intensive workloads (RAM goes brrr)
- **`compute`** - Pure CPU computation (silicon stress test)
- **`primes`** - Prime number calculation (math nerds rejoice)
- **`matrix`** - Matrix multiplication (linear algebra at light speed)

## Understanding Your Results

### Performance Ratings

BenchRust rates your CPU's consistency and speed:

- **Excellent** - Fast and consistent (< 1% variance)
- **Good** - Solid performance (1-3% variance)  
- **Fair** - Somewhat variable (3-5% variance)
- **Poor** - Inconsistent results (5-10% variance)
- **Terrible** - Wildly inconsistent (> 10% variance)

### CPU Ratings

Based on overall performance and reliability:

- **Beast Mode** - Your CPU doesn't fuck around
- **Solid Performer** - Respectable speed with good consistency
- **Decent** - Gets the job done, nothing fancy
- **Mediocre** - It's trying its best, bless its silicon heart
- **Struggling** - Maybe it's time for an upgrade?
- **Potato Quality** - This CPU is having an existential crisis

### Key Metrics Explained

- **Operations/sec** - Higher is better (obviously)
- **Speedup** - How much faster multicore is vs single-core
- **Efficiency** - How well your cores cooperate (perfect = 100%)
- **Coefficient of Variation** - Lower means more consistent results

## Advanced Usage

### For Serious Benchmarking

```bash
# Maximum reliability setup
sudo cpupower frequency-set --governor performance
benchrust --cores 0 --iterations 10 --pin-cores --warmup 3 --verbose

# Compare single vs multicore scaling
benchrust --cores 1 --workload all --output json > single_core.json
benchrust --cores 0 --workload all --output json > multi_core.json
```

### Environment Optimization

For the most reliable results:

1. **Set CPU governor to performance mode**:
   ```bash
   sudo cpupower frequency-set --governor performance
   ```

2. **Close unnecessary applications** (Discord, Chrome with 47 tabs, etc.)

3. **Use core pinning** for consistent thread placement:
   ```bash
   benchrust --pin-cores --iterations 10
   ```

4. **Run multiple iterations** to smooth out variance:
   ```bash
   benchrust --iterations 20 --warmup 5
   ```

## Building from Source

```bash
# Clone the repo
git clone https://git.gostacks.org/iwasforcedtobehere/benchrust
cd benchrust

# Build release version (optimized)
cargo build --release

# Run tests (because quality matters)
cargo test

# Install locally
cargo install --path .
```

### Dependencies

BenchRust uses these excellent crates:

- **clap** - CLI argument parsing that doesn't suck
- **rayon** - Data parallelism made easy
- **colored** - Because monochrome terminals are depressing
- **serde** - JSON serialization that just works
- **indicatif** - Progress bars with personality
- **core_affinity** - Thread pinning for the obsessive

## FAQ

### Why another benchmarking tool?

Because existing tools are either:
- Too fucking complicated for normal humans
- Produce meaningless marketing numbers
- Have the personality of a wet paper bag
- Don't properly handle modern multicore scaling

BenchRust gives you useful metrics with enough personality to be actually readable.

### Is this scientifically accurate?

Yes! Despite the sarcasm, BenchRust uses proper statistical methods:
- Multiple iterations with warm-up phases
- Standard deviation and coefficient of variation
- Proper thread synchronization and timing
- Realistic workloads that stress different CPU subsystems

### Why Rust?

Because:
- Zero-cost abstractions mean accurate timing
- Memory safety prevents benchmark corruption
- Excellent performance and parallelism support
- The ecosystem is fucking amazing

### My results seem inconsistent. Help?

Check these common issues:
- Background processes eating CPU
- Thermal throttling (check your temps)
- Power management interfering (use performance governor)
- Insufficient iterations (try `--iterations 10`)
- OS thread scheduling (try `--pin-cores`)

## Contributing

Found a bug? Want to add a new workload? Contributions welcome!

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-new-thing`)
3. Make your changes
4. Add tests (please!)
5. Submit a pull request

### Development Setup

```bash
# Install Rust (if you haven't already)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://git.gostacks.org/iwasforcedtobehere/benchrust
cd benchrust
cargo build

# Run tests
cargo test

# Check formatting (because clean code matters)
cargo fmt --check
```

**Remember**: Benchmarks are like statistics - they can be used to prove anything. Use responsibly!

### Example Output

```
BenchRust Results
──────────────────────────────────────────────────

MATH-INT
   Consistency: Excellent (very consistent)
   Average Time: 45.32ms
   Operations/sec: 22,068
   Cores Used: 8
   Speedup: 7.2x
   Efficiency: 90.0%

MEMORY
   Consistency: Good (consistent)
   Average Time: 123.45ms
   Operations/sec: 8,103
   Cores Used: 8
   Speedup: 4.1x
   Efficiency: 51.3%

Performance Summary
──────────────────────────────────────────────────
CPU Rating: Solid Performer 
Overall Score: 15,086 ops/sec
Fastest Workload: math-int
Slowest Workload: matrix
Most Scalable: math-float

Thanks for benchmarking responsibly!
```