qellaris 0.5.0__py3-none-any.whl

qellaris/__init__.py

@@ -0,0 +1,40 @@
+"""QAIO cellular demand forecasting and sector-scheduling benchmark.
+
+Three things come out of a run, and they are kept apart on purpose:
+
+* the **schedule and its cost** - energy, unmet demand, switching, the scalar
+  every solver is ranked on (:mod:`~qellaris.experiment`);
+* the **demographic state** - who the population is and what it is doing,
+  never what it received (:mod:`~qellaris.demographics`);
+* the **equity output** - synthetic group diagnostics under named scenario
+  levers (:mod:`~qellaris.equity`, :mod:`~qellaris.equity_scenarios`),
+  not a census fairness claim.
+"""
+
+from .control_env import TransmitterControlEnv
+from .demographics import (ACTIVITIES, DEMOGRAPHIC_AXES, DemographicTracker,
+                           format_state)
+from .equity import (EQUITY_SCENARIOS, EquityScenario, equity_output,
+                     get_equity_scenario)
+from .equity_scenarios import (ScenarioConfig, format_scenarios,
+                               run_equity_scenarios, run_scenario)
+from .experiment import ExperimentConfig, run_experiment
+from .regions import RegionSpec, download_osm_region, find_region
+from .inventory import load_fixed_inventory
+from .rl import SectorPolicy, train_policy
+from .simulation import GridDemandModel
+from .sdk import (BenchmarkState, JobBroker, register_agent,
+                  register_forecaster, score_action, state_from_model)
+from .solvers import SOLVER_NAMES, get_solver
+from ._version import __version__
+
+__all__ = ["ACTIVITIES", "DEMOGRAPHIC_AXES", "EQUITY_SCENARIOS",
+           "BenchmarkState", "ExperimentConfig", "EquityScenario", "GridDemandModel",
+           "DemographicTracker", "RegionSpec", "SOLVER_NAMES", "ScenarioConfig",
+           "JobBroker", "SectorPolicy", "TransmitterControlEnv", "__version__",
+           "download_osm_region", "load_fixed_inventory",
+           "equity_output", "find_region", "format_scenarios", "format_state",
+           "get_equity_scenario", "get_solver", "run_equity_scenarios",
+           "register_agent", "register_forecaster",
+           "run_experiment", "run_scenario",
+           "score_action", "state_from_model", "train_policy"]

qellaris/__main__.py

@@ -0,0 +1,111 @@
+"""One command for the whole package: ``python -m qellaris <subcommand>``.
+
+Everything the project can do used to be reached three different ways -- a
+console script, a module, or a loose file in the repository root that fixed up
+``sys.path`` and then imported the real code. The root scripts existed only
+because the package was not importable without help, and each carried its own
+copy of the bootstrap.
+
+That bootstrap now lives in :mod:`qellaris.ui` and runs here, so this module
+is the single door in. The root ``run_ui.py`` and friends stay as three-line
+shims that call straight into it, because PyCharm run configurations point at
+them by path.
+
+    python -m qellaris ui
+    python -m qellaris benchmark --geography kensington
+    python -m qellaris equity --scenarios protective neutral
+    python -m qellaris region camden --place "Camden, London" --radius-km 1
+    python -m qellaris template --explain
+
+Each subcommand is the same function its console script points at, so there is
+one implementation and no drift between the two ways of calling it.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def _ui(argv: list[str]) -> None:
+    import argparse
+
+    from .ui import main
+
+    parser = argparse.ArgumentParser(
+        prog="python -m qellaris ui",
+        description="Launch the dashboard in this process, so Stop stops it "
+                    "and breakpoints in the model bind.")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8765)
+    parser.add_argument("--no-browser", action="store_true",
+                        help="do not open a browser window")
+    args = parser.parse_args(argv)
+    main(args.host, args.port, not args.no_browser)
+
+
+#: ``subcommand -> (loader, one-line help)``. Loaders import lazily: starting
+#: the dashboard should not pay for importing the quantum backends, and the
+#: benchmark should not pay for importing Solara.
+def _commands():
+    from . import (cli, hardware_job, menu, netbravo, quantum_zoo, real_data,
+                   region_packages, regions, template)
+
+    return {
+        "menu": (menu.main, "guided menu: answer a few questions, it runs the command"),
+        "ui": (_ui, "launch the interactive dashboard"),
+        "benchmark": (cli.main, "run the forecasting and scheduling benchmark"),
+        "equity": (cli.equity_main, "compare equity scenarios on one population"),
+        "train": (cli.train_main, "train the factored sector-control policy"),
+        "region": (regions.main, "download a study area by bounding box or place"),
+        "region-pack": (region_packages.main, "list, export or import study areas as .zip packages"),
+        "opencellid": (real_data.main, "fetch OpenCellID observations"),
+        "netbravo": (netbravo.main, "fetch the NetBravo observed-signal layer"),
+        "hardware-job": (hardware_job.main, "decode a returned QAOA hardware job"),
+        "template": (template.main, "worked example: register an agent, run it, compare it"),
+        "zoo": (quantum_zoo.main, "Quantum Algorithm Zoo entries, read against this benchmark"),
+    }
+
+
+def usage(commands) -> str:
+    width = max(len(name) for name in commands)
+    lines = ["usage: python -m qellaris <subcommand> [options]", "",
+             "subcommands:"]
+    lines += [f"  {name:<{width}}  {help_text}"
+              for name, (_, help_text) in commands.items()]
+    lines += ["", "Add --help after a subcommand for its own options.",
+              "New here? Run `qellaris menu` and it will ask what you want."]
+    return "\n".join(lines)
+
+
+def bootstrap() -> None:
+    """Make the package importable and drop a foreign environment's packages.
+
+    Each root script used to carry its own copy of this. It runs for every
+    subcommand now, not just the dashboard: a compiled extension built for a
+    different CPython fails with a thoroughly misleading "No module named ..."
+    deep inside an unrelated import, and that is just as confusing from the
+    benchmark as from the UI.
+    """
+    from .ui import drop_foreign_site_packages, ensure_importable
+
+    ensure_importable()
+    for entry in drop_foreign_site_packages():
+        print(f"note: ignoring another environment's packages: {entry}")
+
+
+def main(argv: list[str] | None = None) -> None:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    bootstrap()
+    commands = _commands()
+    if not argv or argv[0] in {"-h", "--help", "help"}:
+        print(usage(commands))
+        return
+    name, rest = argv[0], argv[1:]
+    if name not in commands:
+        raise SystemExit(f"unknown subcommand {name!r}\n\n{usage(commands)}")
+    run, _ = commands[name]
+    run(rest)
+
+
+if __name__ == "__main__":
+    main()

qellaris/_version.py

@@ -0,0 +1,3 @@
+"""Single source for the package version string."""
+
+__version__ = "0.5.0"

qellaris/cli.py

@@ -0,0 +1,230 @@
+"""Command-line entry points for the benchmark and the RL trainer."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from . import paths
+from .experiment import ExperimentConfig, format_leaderboard, run_experiment
+from .forecasting import FORECASTER_NAMES
+from .simulation import SCENARIO_NAMES
+from .solvers import installed_solver_names, solver_names
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        description="Run the demand-forecast / sector-scheduling benchmark.")
+    parser.add_argument("--output", default=paths.runs("baseline"))
+    parser.add_argument("--seed", type=int, default=17)
+    parser.add_argument("--agents", type=int, default=240)
+    parser.add_argument("--train-days", type=int, default=7)
+    parser.add_argument("--horizon", type=int, default=16)
+    parser.add_argument("--intervals-per-day", type=int, default=96)
+    parser.add_argument("--point-forecast", action="store_true",
+                        help="schedule on the point forecast instead of its upper bound")
+    parser.add_argument("--scenario", choices=SCENARIO_NAMES,
+                        default="entertainment_event",
+                        help="'entertainment_event' stages one demand event "
+                             "at the best venue the study area actually has "
+                             "(a stadium if there is one, otherwise a "
+                             "transport hub, high street, campus or park, at "
+                             "a magnitude that fits); an area with none gets "
+                             "no event. A specific venue name (e.g. "
+                             "'park_event') forces that family instead of "
+                             "auto-picking. 'normal' asks for none.")
+    parser.add_argument("--geography", default="synthetic",
+                        help="'synthetic', 'kensington', or a folder from "
+                             "`qellaris region`")
+    parser.add_argument("--inventory", default=None,
+                        help="optional fixed tower/sector JSON "
+                             "(positions + directions; no placement search)")
+    parser.add_argument("--solvers", nargs="+", default=None,
+                        choices=list(solver_names()),
+                        help="default: every solver whose backend is installed")
+    parser.add_argument("--forecasters", nargs="+", default=None,
+                        choices=list(FORECASTER_NAMES),
+                        help="default: seasonal_naive only; pass more than one "
+                             "to run the forecaster x solver factorial "
+                             "(every solver replayed once per forecaster; "
+                             "interface support, not a claimed primary result)")
+    parser.add_argument("--rl-weights", default=None,
+                        help="policy JSON written by `qellaris train`")
+    parser.add_argument("--decision-reference", default="greedy",
+                        choices=list(solver_names()),
+                        help="reference used to attribute forecast and solver decision gaps")
+    parser.add_argument("--no-counterfactual", action="store_true",
+                        help="skip the seed-paired no-event control replay")
+    parser.add_argument("--json", action="store_true",
+                        help="print the full summary instead of the ranked table")
+    parser.add_argument("--list-backends", action="store_true",
+                        help="report which optional quantum packages are installed")
+    parser.add_argument("--seeds", type=int, nargs="+", default=None,
+                        help="replicate over these seeds and report paired "
+                             "bootstrap intervals instead of a single run")
+    parser.add_argument("--metric", default="objective",
+                        help="metric the replication table ranks and pairs on")
+    args = parser.parse_args(argv)
+
+    if args.list_backends:
+        from .quantum import backends
+
+        for backend in backends():
+            state = "installed" if backend.available else f"missing ({backend.detail})"
+            print(f"{backend.name:<16} {backend.package:<22} {state}")
+        print("\nsolvers available:", ", ".join(installed_solver_names()))
+        return
+
+    chosen = tuple(args.solvers) if args.solvers else installed_solver_names()
+    chosen_forecasters = tuple(args.forecasters) if args.forecasters else ("seasonal_naive",)
+
+    if args.seeds:
+        from .evaluation import format_report, run_replications, write_report
+
+        report = run_replications(
+            args.output,
+            ExperimentConfig(
+                agents=args.agents, train_days=args.train_days,
+                horizon=args.horizon, intervals_per_day=args.intervals_per_day,
+                uncertainty_aware=not args.point_forecast, scenario=args.scenario,
+                geography=args.geography, inventory_path=args.inventory,
+                solvers=chosen,
+                forecasters=chosen_forecasters,
+                rl_weights=args.rl_weights,
+                decision_reference=args.decision_reference,
+                paired_counterfactual=not args.no_counterfactual),
+            seeds=tuple(args.seeds),
+            reference=args.decision_reference)
+        print(format_report(report, args.metric))
+        print(f"\nartefacts written to "
+              f"{write_report(args.output, report, args.metric)}")
+        return
+
+    summary = run_experiment(args.output, ExperimentConfig(
+        seed=args.seed, agents=args.agents, train_days=args.train_days,
+        horizon=args.horizon, intervals_per_day=args.intervals_per_day,
+        uncertainty_aware=not args.point_forecast, scenario=args.scenario,
+        geography=args.geography, inventory_path=args.inventory,
+        solvers=chosen,
+        forecasters=chosen_forecasters,
+        rl_weights=args.rl_weights, decision_reference=args.decision_reference,
+        paired_counterfactual=not args.no_counterfactual))
+    if args.json:
+        print(json.dumps(summary, indent=2))
+        return
+    area = summary["study_area"]
+    print(f"{area['name']}: {summary['zones']} demand bins, "
+          f"{summary['transmitters']} sectors, "
+          f"{area['width_km']} x {area['height_km']} km")
+    for name, metrics in summary["forecasts"].items():
+        print(f"forecast[{name}] MAE {metrics['mae']:.3f}, "
+              f"interval coverage {metrics['interval_coverage']:.3f}")
+    print()
+    print(format_leaderboard(summary["leaderboard"]))
+    print(f"\nartefacts written to {args.output}")
+
+
+def equity_main(argv: list[str] | None = None) -> None:
+    """Run the same population under several equity scenarios and compare.
+
+    Writes the equity output per scenario and the demographic state they all
+    shared, as two files, because they are two different things: one says who
+    was out there, the other says what the network did about it.
+    """
+    from .demographics import DEMOGRAPHIC_AXES, format_state
+    from .equity import EQUITY_SCENARIOS
+    from .equity_scenarios import (ScenarioConfig, format_scenarios,
+                                   run_equity_scenarios, write_scenarios)
+
+    parser = argparse.ArgumentParser(
+        description="Compare equity scenarios on one population.")
+    parser.add_argument("--output", default=paths.runs("equity"))
+    parser.add_argument("--scenarios", nargs="+", default=None,
+                        choices=list(EQUITY_SCENARIOS),
+                        help="default: every scenario")
+    parser.add_argument("--reference", default="protective",
+                        choices=list(EQUITY_SCENARIOS),
+                        help="scenario the others are reported against")
+    parser.add_argument("--agents", type=int, default=240)
+    parser.add_argument("--intervals-per-day", type=int, default=96)
+    parser.add_argument("--steps", type=int, default=96,
+                        help="intervals scored, after the warm-up")
+    parser.add_argument("--warmup", type=int, default=96,
+                        help="intervals run before the audit window opens")
+    parser.add_argument("--seed", type=int, default=17)
+    parser.add_argument("--geography", default="kensington",
+                        help="'synthetic', 'kensington', or a folder from "
+                             "`qellaris region`")
+    parser.add_argument("--demand-scenario", choices=SCENARIO_NAMES,
+                        default="entertainment_event")
+    parser.add_argument("--solver", default="greedy", choices=list(solver_names()))
+    parser.add_argument("--capacity-headroom", type=float, default=1.2,
+                        help="site sizing vs. pilot peak demand; below 1.0 forces "
+                             "a genuinely capacity-bound network so bin-weighting "
+                             "scenarios have demand to actually ration")
+    parser.add_argument("--point-forecast", action="store_true")
+    parser.add_argument("--show-demographics", nargs="*", default=None,
+                        metavar="AXIS",
+                        help="also print the demographic state; name axes to "
+                             f"narrow it ({', '.join(DEMOGRAPHIC_AXES)})")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+
+    report = run_equity_scenarios(args.scenarios, ScenarioConfig(
+        agents=args.agents, intervals_per_day=args.intervals_per_day,
+        steps=args.steps, warmup=args.warmup, seed=args.seed,
+        geography=args.geography, demand_scenario=args.demand_scenario,
+        solver=args.solver, uncertainty_aware=not args.point_forecast,
+        capacity_headroom=args.capacity_headroom),
+        reference=args.reference)
+
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        if args.show_demographics is not None:
+            axes = tuple(args.show_demographics) or None
+            print(format_state(report["demographics"], axes))
+        print(format_scenarios(report))
+    print(f"artefacts written to {write_scenarios(args.output, report)}")
+
+
+def train_main(argv: list[str] | None = None) -> None:
+    """Train the factored sector policy against the Gymnasium environment."""
+    from .control_env import TransmitterControlEnv
+    from .rl import SectorPolicy, evaluate_policy, train_policy
+
+    parser = argparse.ArgumentParser(description="Train the RL sector-control policy.")
+    parser.add_argument("--episodes", type=int, default=80)
+    parser.add_argument("--episode-length", type=int, default=48)
+    parser.add_argument("--agents", type=int, default=240)
+    parser.add_argument("--intervals-per-day", type=int, default=96)
+    parser.add_argument("--geography", default="kensington")
+    parser.add_argument("--seed", type=int, default=17)
+    parser.add_argument("--learning-rate", type=float, default=0.05)
+    parser.add_argument("--output", default=paths.runs("rl", "policy.json"))
+    parser.add_argument("--resume", default=None, help="continue from an existing policy JSON")
+    args = parser.parse_args(argv)
+
+    env = TransmitterControlEnv(
+        n_agents=args.agents, intervals_per_day=args.intervals_per_day,
+        episode_length=args.episode_length,
+        warmup_intervals=args.intervals_per_day, seed=args.seed,
+        geography=args.geography)
+    start = SectorPolicy.load(args.resume) if args.resume and Path(args.resume).exists() else None
+
+    def show(episode: int, total: float) -> None:
+        if episode % max(1, args.episodes // 20) == 0:
+            print(f"episode {episode:4d}  return {total:12.1f}")
+
+    policy, report = train_policy(env, episodes=args.episodes, seed=args.seed,
+                                  learning_rate=args.learning_rate, policy=start,
+                                  progress=show)
+    path = policy.save(args.output)
+    print(json.dumps({"weights": path.as_posix(), **report.as_dict(),
+                      "episode_rewards": report.episode_rewards[-5:],
+                      "evaluation": evaluate_policy(policy, env, episodes=3)}, indent=2))
+
+
+if __name__ == "__main__":
+    main()