#!/usr/bin/env python3
"""Gumi 2026-10-21: an isotropic point-source model, not a lamp measurement.

Python 3.9+ syntax, standard library for calculations and JSON.
Optional --plot PATH.svg uses Matplotlib and also writes a PNG preview.
"""

import argparse
import json
import math
from pathlib import Path
import platform


def positive(value, name, allow_zero=False):
    if not math.isfinite(value) or value < 0 or (value == 0 and not allow_zero):
        raise ValueError(name + " must be finite and " + ("nonnegative" if allow_zero else "positive"))


def point_lux(flux_lm, distance_m, incidence_deg=0.0):
    positive(flux_lm, "flux_lm", allow_zero=True)
    positive(distance_m, "distance_m")
    if not math.isfinite(incidence_deg) or not 0 <= incidence_deg <= 90:
        raise ValueError("incidence_deg must be between 0 and 90")
    if incidence_deg == 90:
        return 0.0
    intensity_cd = flux_lm / (4.0 * math.pi)
    return intensity_cd * math.cos(math.radians(incidence_deg)) / distance_m**2


def horizontal_lux(flux_lm, height_m, radius_m):
    positive(flux_lm, "flux_lm", allow_zero=True)
    positive(height_m, "height_m")
    positive(radius_m, "radius_m", allow_zero=True)
    intensity_cd = flux_lm / (4.0 * math.pi)
    return intensity_cd * height_m / (height_m**2 + radius_m**2)**1.5


def disk_stats(flux_lm, height_m, area_m2):
    positive(flux_lm, "flux_lm", allow_zero=True)
    positive(height_m, "height_m")
    positive(area_m2, "area_m2")
    radius_m = math.sqrt(area_m2 / math.pi)
    incident_lm = flux_lm / 2.0 * (1.0 - height_m / math.hypot(height_m, radius_m))
    return {
        "source_flux_lm": flux_lm,
        "height_m": height_m,
        "area_m2": area_m2,
        "radius_m": radius_m,
        "incident_flux_lm": incident_lm,
        "mean_lux": incident_lm / area_m2,
        "center_lux": horizontal_lux(flux_lm, height_m, 0.0),
        "edge_lux": horizontal_lux(flux_lm, height_m, radius_m),
    }


def integrate_disk(flux_lm, height_m, radius_m, rings):
    step = radius_m / rings
    return math.fsum(
        horizontal_lux(flux_lm, height_m, (i + 0.5) * step)
        * 2.0 * math.pi * ((i + 0.5) * step) * step
        for i in range(rings)
    )


def require(condition, label):
    if not condition:
        raise RuntimeError("check failed: " + label)


def calculate():
    flux = 800.0
    distances = [{"distance_m": r, "incidence_deg": 0.0, "lux": point_lux(flux, r)}
                 for r in [0.5, 1.0, 2.0]]
    angles = [{"distance_m": 1.0, "incidence_deg": a, "lux": point_lux(flux, 1.0, a)}
              for a in [0.0, 60.0, 80.0, 90.0]]
    disk = disk_stats(flux, 1.0, 1.0)
    numerical = []
    for rings in [2000, 20000]:
        result = integrate_disk(flux, 1.0, disk["radius_m"], rings)
        numerical.append({"rings": rings, "incident_flux_lm": result,
                          "absolute_error_lm": abs(result - disk["incident_flux_lm"])})

    checks = []
    require(math.isclose(point_lux(flux, 2.0) / point_lux(flux, 1.0), 0.25), "inverse-square ratio")
    checks.append("doubling distance gives one quarter at normal incidence")
    require(math.isclose(point_lux(flux, 1.0, 60.0) / point_lux(flux, 1.0), 0.5), "cosine ratio")
    checks.append("60 degree incidence gives one half at fixed distance")
    require(point_lux(0.0, 1.0) == 0.0 and point_lux(flux, 1.0, 90.0) == 0.0,
            "zero flux and grazing incidence")
    checks.append("zero flux and 90 degree incidence give zero direct illuminance")
    require(disk["edge_lux"] < disk["mean_lux"] < disk["center_lux"], "disk ordering")
    checks.append("disk edge < area mean < center")
    require(0 < disk["incident_flux_lm"] < flux / 2, "finite disk interception")
    checks.append("finite disk intercepts less than the downward hemisphere flux")
    require(math.isclose(disk_stats(2 * flux, 1.0, 1.0)["incident_flux_lm"],
                         2 * disk["incident_flux_lm"]), "flux linearity")
    checks.append("doubling source flux doubles the incident disk flux")
    require(numerical[-1]["absolute_error_lm"] < 0.000001, "radial integration")
    checks.append("20000 midpoint rings agree with analytic incident flux within 0.000001 lm")

    invalid_cases = [
        ("negative flux", lambda: point_lux(-1.0, 1.0)),
        ("zero distance", lambda: point_lux(flux, 0.0)),
        ("angle outside modeled front hemisphere", lambda: point_lux(flux, 1.0, 91.0)),
        ("zero height", lambda: disk_stats(flux, 0.0, 1.0)),
        ("zero area", lambda: disk_stats(flux, 1.0, 0.0)),
        ("nonfinite flux", lambda: point_lux(float("nan"), 1.0)),
        ("nonfinite height", lambda: disk_stats(flux, float("inf"), 1.0)),
    ]
    rejected = []
    for label, operation in invalid_cases:
        try:
            operation()
        except ValueError as error:
            rejected.append({"case": label, "error": str(error)})
        else:
            raise RuntimeError("invalid input accepted: " + label)

    return {
        "experiment_date": "2026-10-21",
        "environment": {"python": platform.python_version(),
                        "implementation": platform.python_implementation(),
                        "platform": platform.platform()},
        "scope": "Numerical model only; no physical lamp, room, sensor or lighting standard compliance tested.",
        "assumptions": ["isotropic point source", "steady 800 lm total emitted flux",
                        "no absorption, obstructions, reflections, other sources or ambient light",
                        "local plane angle measured between its normal and the direction toward the source",
                        "disk centered directly below source, horizontal, height 1 m, area 1 square metre"],
        "intensity_cd": flux / (4.0 * math.pi),
        "distance_cases": distances,
        "angle_cases": angles,
        "disk": disk,
        "numerical_integration": numerical,
        "checks_passed": checks,
        "invalid_inputs_rejected": rejected,
        "status": "passed",
    }


def make_plot(output):
    import matplotlib
    matplotlib.use("Agg")
    import matplotlib.pyplot as plt

    disk = disk_stats(800.0, 1.0, 1.0)
    distances = [0.5 + i * 1.5 / 300 for i in range(301)]
    radii = [i * disk["radius_m"] / 200 for i in range(201)]
    with plt.rc_context({"font.size": 11, "svg.fonttype": "none"}):
        fig, axes = plt.subplots(1, 2, figsize=(11, 4.8), layout="constrained")
        axes[0].plot(distances, [point_lux(800.0, r) for r in distances], color="#2563eb", linewidth=2.5)
        axes[0].scatter([0.5, 1, 2], [point_lux(800.0, r) for r in [0.5, 1, 2]], color="#2563eb", zorder=3)
        axes[0].set(title="Normal incidence: distance matters", xlabel="Source-to-point distance (m)",
                    ylabel="Direct illuminance (lx)", xlim=(0.45, 2.05), ylim=(0, 275))
        axes[1].plot(radii, [horizontal_lux(800.0, 1.0, r) for r in radii], color="#2563eb",
                     linewidth=2.5, label="Local illuminance")
        axes[1].axhline(disk["mean_lux"], color="#b45309", linestyle="--", linewidth=2,
                       label="Area mean: {:.2f} lx".format(disk["mean_lux"]))
        axes[1].set(title="A horizontal disk: center is not the mean", xlabel="Distance from disk center (m)",
                    ylabel="Direct illuminance (lx)", xlim=(0, disk["radius_m"]), ylim=(0, 80))
        axes[1].legend(loc="lower left", frameon=False)
        for ax in axes:
            ax.grid(alpha=0.25)
            ax.spines[["top", "right"]].set_visible(False)
        fig.suptitle("800 lm isotropic point source - a model, not a measurement", fontsize=14)
        output.parent.mkdir(parents=True, exist_ok=True)
        fig.savefig(output)
        fig.savefig(output.with_suffix(".png"), dpi=140)
        plt.close(fig)
    return matplotlib.__version__


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--plot", type=Path, help="optional SVG output path; also writes a PNG preview")
    args = parser.parse_args()
    report = calculate()
    if args.plot is not None:
        if args.plot.suffix.lower() != ".svg":
            parser.error("--plot requires an .svg path")
        version = make_plot(args.plot)
        import sys
        print("Plot generated with Matplotlib " + version, file=sys.stderr)
    print(json.dumps(report, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()
