#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""A CPU timing-boundary demonstration; Python 3.10+, no dependencies.

Run: python3 timing-boundaries.py > my-timing-report.json
No network, models, accelerators, or external programs are used. All timings
include the same output check. This is not an AI-discovered optimization or a
GPU benchmark. See the article for how accelerator measurement differs.
"""

import datetime
import gc
import hashlib
import json
import platform
import statistics
import sys
import time
from pathlib import Path


def loop_sum(values):
    total = 0
    for value in values:
        total += value
    return total


def main():
    size, iterations, repeats, warmups = 20_000, 50, 20, 3
    values = list(range(size))
    payload = json.dumps(values, separators=(",", ":"))
    expected = size * (size - 1) // 2
    cases = [([], 0), ([0], 0), ([-3, 2, 1], 0),
             ([10**30, 1, -(10**30)], 1), (values, expected)]
    for data, answer in cases:
        for candidate in (loop_sum, sum):
            if candidate(data) != answer:
                raise RuntimeError("Correctness check failed")

    jobs = {
        "operation_loop": lambda: loop_sum(values),
        "operation_builtin": lambda: sum(values),
        "job_loop": lambda: loop_sum(json.loads(payload)),
        "job_builtin": lambda: sum(json.loads(payload)),
    }

    def measure(job):
        start = time.perf_counter_ns()
        for _ in range(iterations):
            if job() != expected:
                raise RuntimeError("Timed output check failed")
        return (time.perf_counter_ns() - start) / iterations / 1_000_000

    for job in jobs.values():
        for _ in range(warmups):
            measure(job)
    samples = {name: [] for name in jobs}
    orders = []
    names = list(jobs)
    for repeat in range(repeats):
        # Rotate each variant through all four positions equally often.
        order = names[repeat % len(names):] + names[:repeat % len(names)]
        orders.append(order)
        for name in order:
            samples[name].append(measure(jobs[name]))
    summaries = {
        name: {"min": min(times), "median": statistics.median(times),
               "max": max(times)}
        for name, times in samples.items()
    }
    report = {
        "measured_at_utc": datetime.datetime.now(datetime.timezone.utc).isoformat(),
        "scope": "CPU demonstration of measurement boundaries, not a GPU or AI benchmark",
        "environment": {
            "python": sys.version, "implementation": platform.python_implementation(),
            "os": platform.system(), "os_version": platform.release(),
            "architecture": platform.machine(), "gc_enabled": gc.isenabled(),
            "clock": "perf_counter_ns", "clock_resolution_seconds": time.get_clock_info("perf_counter").resolution,
            "limitations": "Shared developer machine; no CPU affinity, clock lock, thermal or competing-load control",
        },
        "source_sha256": hashlib.sha256(Path(__file__).read_bytes()).hexdigest(),
        "input": {"construction": "list(range(20000)); compact JSON encoding",
                  "elements": size, "expected_sum": expected,
                  "json_bytes": len(payload.encode()),
                  "json_sha256": hashlib.sha256(payload.encode()).hexdigest()},
        "protocol": {"iterations_per_batch": iterations, "batches_per_variant": repeats,
                     "warmup_batches_per_variant": warmups,
                     "operation_boundary": "sum prebuilt list and check output",
                     "job_boundary": "decode in-memory JSON, sum, and check output; decoded-list disposal included",
                     "excluded": "process startup, imports, input generation, file/network I/O, report serialization",
                     "batch_order": orders},
        "correctness_cases_passed_per_candidate": len(cases),
        "samples_ms_per_call": samples,
        "summary_ms_per_call": summaries,
        "ratio_of_medians": {
            "operation_speedup": summaries["operation_loop"]["median"] / summaries["operation_builtin"]["median"],
            "job_speedup": summaries["job_loop"]["median"] / summaries["job_builtin"]["median"],
        },
    }
    print(json.dumps(report, indent=2))


if __name__ == "__main__":
    main()