CPU Benchmark

A cross-architecture CPU benchmark tool written in pure Python. It measures single-threaded and multi-threaded performance using math-heavy HPC workloads and outputs structured JSON for cross-run and cross-architecture comparison.

Targets AMD64, AArch64, RISC-V, and other architectures. Supports QEMU user-mode emulation to run benchmarks on non-native targets from a single host machine.

Workloads

Workload	Description	Dependencies
matrix_multiplication	Dense NxN floating-point matrix multiply via nested loops	None (pure Python)
fft	Cooley-Tukey radix-2 FFT on a 1-D complex signal	None (pure Python)
numerical_integration	Definite integral of sin(x) over [0, π] using Simpson's rule	None (pure Python)
monte_carlo	Estimate π via random sampling in a unit square	None (pure Python)
sat_solver	Random 3-SAT instance solved with PySAT (Glucose3 CDCL solver)	python-sat (optional)
smt_solver	System of linear arithmetic constraints solved with Z3	z3-solver (optional)
c_compilation	Generates and compiles a non-trivial C source file, timing the compiler	gcc or cc on PATH (optional)

Solver and compiler workloads degrade gracefully — if the required library or tool is unavailable, they return score=0 and the benchmark continues.

Requirements

• Python 3.12+

Installation

# Clone the repository
git clone <repo-url>
cd cpu-benchmark

# (Optional) Install solver libraries for SAT/SMT workloads
pip install python-sat z3-solver

# Install dev dependencies (pytest, hypothesis)
pip install -r requirements-dev.txt

Usage

Run the benchmark directly as a Python module:

# Run all workloads in both single and multi-threaded modes
python -m benchmark

# Single-threaded only
python -m benchmark --mode single

# Multi-threaded with 8 threads
python -m benchmark --mode multi --threads 8

# Save results to a file (also prints to stdout)
python -m benchmark --output results.json

# Run specific workloads
python -m benchmark --workloads matrix_multiplication fft monte_carlo

CLI Options

Option	Description	Default
--mode {single,multi,both}	Execution mode	both
--threads N	Worker threads for multi-thread mode	CPU count
--output FILE	Write JSON report to file	stdout only
--workloads NAME [NAME ...]	Select specific workloads to run	all
--arch ARCH	Target architecture for QEMU emulation	native
--python-path PATH	Python binary for the target --arch	current interpreter

QEMU Emulation

Run benchmarks under QEMU user-mode emulation for cross-architecture testing:

# Run on AArch64 via QEMU
python -m benchmark --arch aarch64 --python-path /path/to/aarch64-python

# Run on RISC-V 64
python -m benchmark --arch riscv64 --python-path /path/to/riscv64-python

Supported architectures: aarch64, arm, mips, ppc64, riscv64, x86_64.

Requires the corresponding qemu-<arch> binary on your PATH.

Output Format

Results are emitted as a JSON object with three top-level keys:

{
  "metadata": {
    "architecture": "x86_64",
    "python_version": "3.12.0",
    "timestamp": "2026-02-24T12:00:00+00:00",
    "hostname": "build-host",
    "thread_config": { "mode": "both", "num_threads": 4 }
  },
  "results": [
    {
      "workload_name": "matrix_multiplication",
      "execution_mode": "single",
      "time_seconds": 1.234,
      "throughput": 51.86,
      "threads_used": 1,
      "availability_status": "not_applicable",
      "skip_reason": null
    }
  ],
  "speedup_ratios": {
    "matrix_multiplication": 3.42
  }
}

speedup_ratios shows single_time / multi_time for each workload that ran in both modes.

Development

# Run all tests
pytest

# Run tests with short tracebacks
pytest --tb=short

# Type checking
mypy benchmark/

Project Structure

benchmark/
  __init__.py
  __main__.py               # Entry point
  cli.py                    # argparse CLI
  orchestrator.py           # Coordinates workload execution
  executor.py               # Single and multi-threaded runners
  reporter.py               # JSON serialization and output
  workload.py               # Workload protocol and data models
  qemu_runner.py            # QEMU user-mode emulation support
  workloads/
    matrix_mul.py            # Dense matrix multiplication
    fft.py                   # Cooley-Tukey FFT
    numerical_integration.py # Simpson's rule integration
    monte_carlo.py           # Monte Carlo π estimation
    sat_solver.py            # PySAT 3-SAT solver
    smt_solver.py            # Z3 SMT solver
    c_compilation.py         # C compiler benchmark
  solver/
    base.py                  # SolverWorkload base class
    checker.py               # Library availability detection
    installer.py             # Auto-install via pip

License

See LICENSE for details.