=============================================================================== PerformanceDeck 1.0.0 Techlosoft "PC Performance Console" cluster - Pro variant A composite, weighted benchmark suite for the command line. =============================================================================== ONE SENTENCE PerformanceDeck runs four separate subsystem benchmarks - CPU single-thread, CPU multi-thread, memory bandwidth and disk sequential write - and folds them into ONE overall score with a fully transparent per-subsystem breakdown, so that when the number drops you can see which part of the machine did it. HOW THIS DIFFERS FROM ITS SIBLINGS CorePilot - one CPU benchmark. ThermalFlow - one CPU benchmark plus a trend log. SystemPulse - times an external command and detects latency regressions. DiskOps / DriveForge - disk throughput only. PerformanceDeck is the only one in the family that measures several distinct subsystems in a single pass, combines them with explicit weights into one number, and attributes a change in that number to a specific subsystem. ------------------------------------------------------------------------------- 1. INSTALL / BUILD ------------------------------------------------------------------------------- Go standard library only. No third-party dependencies at all. GOPROXY=off go build -o performancedeck . Prebuilt binaries live in dist/: performancedeck-linux-amd64 performancedeck-darwin-amd64 performancedeck-darwin-arm64 performancedeck-windows-amd64.exe ------------------------------------------------------------------------------- 2. COMMANDS ------------------------------------------------------------------------------- performancedeck run [--disk-dir DIR] [--seconds N] [--mem-mib N] [--disk-cap-mib N] [--save FILE] [--json] Runs every applicable subsystem benchmark and prints a table of subsystem / raw measurement with units / normalised subscore / weight / contribution, followed by the overall score and an explanation of how that score was composed. performancedeck compare --baseline FILE [--current FILE] [--disk-dir DIR] [--seconds N] [--mem-mib N] [--disk-cap-mib N] [--threshold-pct P] [--json] Compares a saved run against either another saved run (--current) or a fresh measurement taken right now. Prints per-subsystem percentage change and names the subsystem that moved most. Exits 2 when the DROP in the overall score exceeds --threshold-pct. performancedeck show --result FILE [--json] Prints a previously saved result. `show --result F --json` reproduces the saved file byte for byte. performancedeck help | -h | --help (prints to stdout, exits 0) Any bad invocation prints the error plus the usage block to STDERR and exits 1, matching the rest of the Techlosoft tool family. EXIT CODES 0 success / no regression 1 usage or runtime error 2 regression: overall score dropped by more than --threshold-pct 130 interrupted by SIGINT/SIGTERM (temp files are removed first) ------------------------------------------------------------------------------- 3. THE SCORE - REFERENCE CONSTANTS AND WEIGHTS (NOTHING IS HIDDEN) ------------------------------------------------------------------------------- Every subscore is derived from a real measurement, normalised against a fixed reference constant that is compiled into the build and printed by --help. The references are NOT measured, NOT adaptive, and NOT derived from your machine. A machine that hits a reference exactly scores 100 on that subsystem. Subscores are UNCAPPED: a machine twice as fast as the reference scores 200. REFERENCE CONSTANTS (subscore 100 = exactly this measurement) subsystem what is measured reference --------- ------------------------------------------ ------------- cpu_single 1 thread running a fixed xorshift+LCG 200.00 Mops/s integer mixing kernel; 1 op = 1 loop iteration (3 shift/xor steps + 1 64-bit multiply-add) cpu_multi the identical kernel on one goroutine per 700.00 Mops/s logical CPU, aggregate ops over wall clock memory memcpy bandwidth between two equally sized 12.00 GB/s buffers; each pass counts 2x the buffer size (one read + one write); GB = 1e9 bytes disk sequential 1 MiB writes into a temp file 500.00 MB/s inside --disk-dir, with the final fsync included in the timed window; MB = 1e6 bytes WEIGHTS Weights are held as INTEGER WEIGHT POINTS so that renormalisation is exact in binary floating point: cpu_single 30 pts cpu_multi 30 pts memory 20 pts disk 20 pts total 100 pts weight_i = base_points_i / (sum of base points of the subsystems that were actually MEASURED) Full profile : 30/100, 30/100, 20/100, 20/100 = 0.30, 0.30, 0.20, 0.20 -> sums to exactly 1.0 cpu-mem profile: 30/80, 30/80, 20/80 = 0.375, 0.375, 0.25 -> sums to exactly 1.0 THE ARITHMETIC subscore_i = 100 * measured_i / reference_i (uncapped) contribution_i = weight_i * subscore_i OVERALL SCORE = sum of contribution_i, summed in the fixed order cpu_single, cpu_multi, memory, disk That is the whole formula. Because the summation order is fixed and every intermediate value is written into --json at full float64 precision, an independent reimplementation using the constants above reproduces the tool's overall score BIT FOR BIT. This was verified with python3 against the shipped binary for both profiles. Note: the printed table rounds to 4 decimals for readability, so adding up the PRINTED contributions can differ from the printed total by ~1e-4. The --json values are the exact ones. ------------------------------------------------------------------------------- 4. PROFILES - WHAT HAPPENS WHEN YOU SKIP THE DISK TEST ------------------------------------------------------------------------------- profile = "full" --disk-dir was given. All four subsystems were measured. profile = "cpu-mem" --disk-dir was NOT given. The disk benchmark was skipped. The disk subsystem does NOT appear in the output or in the JSON at all - no fabricated value, no assumed default. The three remaining subsystems keep their weight points (30/30/20) but are now divided by their own total (80), so the weights become 0.375/0.375/0.25 and still sum to exactly 1.0. The run is labelled profile=cpu-mem, the text output prints an explicit "DISK WAS NOT MEASURED" note, and `compare` REFUSES (exit 1) to diff a cpu-mem run against a full run in either direction. A CPU/memory-only score is never silently compared against a score that included disk. ------------------------------------------------------------------------------- 5. DISK BENCHMARK SAFETY ------------------------------------------------------------------------------- * Nothing is written unless you pass --disk-dir. * Exactly one temp file is created, named .performancedeck-bench-*.tmp, inside the directory YOU named. No other path is ever touched. * The file is removed on success, on any error, and on SIGINT/SIGTERM (the signal handler removes registered temp files before exiting 130). * Writing stops at whichever comes first: the --seconds budget or --disk-cap-mib (default 256 MiB). * The tool never removes anything it did not create. ------------------------------------------------------------------------------- 6. WHAT IS IMPLEMENTED ------------------------------------------------------------------------------- [x] CPU single-thread benchmark (fixed integer kernel, ops/s) [x] CPU multi-thread benchmark (one goroutine per logical CPU) [x] Memory copy bandwidth benchmark, buffer size configurable (--mem-mib) [x] Disk sequential write benchmark including fsync, size capped [x] 250 ms untimed CPU warm-up before the first measurement [x] Transparent weighted composite score with printed breakdown [x] Exact, reproducible score arithmetic (verified bit-for-bit externally) [x] Weight renormalisation when disk is skipped, with a distinct profile name [x] Save / show / compare of JSON results, byte-identical round trip [x] Per-subsystem change reporting and "biggest mover" attribution [x] Threshold-gated exit code for CI-style regression gating [x] Automatic notes when CPU count, platform, tool version, buffer size or time budget differ between the two runs being compared [x] Guaranteed temp-file cleanup, including on signals [x] Cross-compiled binaries for linux/amd64, darwin/amd64, darwin/arm64, windows/amd64 ------------------------------------------------------------------------------- 7. WHAT IS *NOT* IMPLEMENTED - READ THIS BEFORE TRUSTING A NUMBER ------------------------------------------------------------------------------- * GPU IS NOT MEASURED AT ALL. There is no graphics, compute or video encode benchmark of any kind. The overall score says nothing about your GPU. * CPU TEMPERATURE AND THERMAL THROTTLING ARE INVISIBLE. Reading core temperatures, power limits or clock throttling needs native, per-platform APIs (MSRs / WMI / IOKit) that this pure-Go standard-library tool does not use. A machine that is thermally throttling simply produces lower numbers with no explanation. * CROSS-MACHINE AND CROSS-VERSION COMPARISON IS NOT SUPPORTED. Scores are comparable only against runs produced by the SAME tool version on the same OS, architecture and logical CPU count. Different Go versions, compilers or operating systems change the kernels' code generation. compare prints a note when it detects such a mismatch, but it cannot correct for it. * THE REFERENCE CONSTANTS ARE ARBITRARY ANCHORS, not an industry standard and not a hardware database. They exist to turn four different units into one comparable scale. A score of 150 means "50% above these constants", nothing more. * DISK READ THROUGHPUT IS NOT MEASURED. Only sequential write plus fsync is. A read-back test on the same file would largely be served from the OS page cache, and defeating the page cache requires platform-specific flags (O_DIRECT, F_NOCACHE) that are out of scope here. Random I/O, IOPS and queue-depth behaviour are also not measured. * MEMORY LATENCY IS NOT MEASURED, only copy bandwidth. Bandwidth depends strongly on --mem-mib: a small buffer lives in cache and reports several times the DRAM figure. Compare only runs that used the same --mem-mib. * NO PROCESS RULES, CPU AFFINITY CONTROL, FAN CURVES OR POWER PROFILES. This is a measurement tool, not a control panel. It changes no system settings. * RUN-TO-RUN NOISE IS REAL, AND IT IS THE MAIN SOURCE OF FALSE POSITIVES. Measured on the shared, containerised Linux host this build was tested on (4 logical CPUs, virtualised storage), with --seconds 3: cpu-mem overall score, 6 consecutive idle pairs: max |change| 6.97% disk throughput, idle runs: 66 MB/s to 890 MB/s, i.e. more than 10x So: the default --threshold-pct 10 is sane for cpu-mem comparisons on a reasonably quiet machine; for full (disk-inclusive) comparisons on virtualised storage use 25 or more, or you will chase phantom regressions. A longer --seconds reduces the noise but cannot remove host contention. Nothing in this tool tries to hide that: the per-subsystem table always shows you whether the movement came from a subsystem you care about. * NO BACKGROUND DAEMON, NO TELEMETRY, NO NETWORK ACCESS. The tool writes only the files you name with --save and the single disk-benchmark temp file. ------------------------------------------------------------------------------- 8. ROADMAP ------------------------------------------------------------------------------- * GPU BENCHMARKING - add a fifth subsystem (compute and/or fill-rate) behind a platform-specific backend, with its own reference constant and weight point allocation, so the composite score finally covers graphics. * THERMAL-AWARE SUSTAINED-LOAD SCORING - run the CPU subsystems long enough to provoke throttling, read core temperature and clock via native APIs, and report a sustained score alongside the burst score, so a machine that looks fast for two seconds and collapses after two minutes is visibly different from one that holds its clocks. * PUBLISHED COMPARISON DATABASE - an opt-in upload of anonymised results plus a public percentile lookup, so "score 150" can become "faster than 62% of submitted machines with this CPU" instead of being relative only to the hard-coded reference constants. ------------------------------------------------------------------------------- 9. EXAMPLES ------------------------------------------------------------------------------- # Full suite, 3 seconds per subsystem, benchmarking the disk in /var/tmp performancedeck run --seconds 3 --disk-dir /var/tmp --save baseline.json # CPU + memory only (no disk writes anywhere) performancedeck run --seconds 3 # Re-measure now and gate on a 20% drop performancedeck compare --baseline baseline.json --disk-dir /var/tmp \ --seconds 3 --threshold-pct 20 echo $? # 0 = within threshold, 2 = regression # Diff two saved runs, machine readable performancedeck compare --baseline a.json --current b.json --json # Reprint a saved run performancedeck show --result baseline.json ===============================================================================