qtiming 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. qtiming/__init__.py +0 -0
  2. qtiming/bench/__init__.py +327 -0
  3. qtiming/bench/diff.py +230 -0
  4. qtiming/bench/report.py +161 -0
  5. qtiming/bench/truth.py +88 -0
  6. qtiming/cli/__init__.py +0 -0
  7. qtiming/cli/cmd_evidence.py +35 -0
  8. qtiming/cli/main.py +398 -0
  9. qtiming/contract/__init__.py +0 -0
  10. qtiming/contract/compat.py +49 -0
  11. qtiming/contract/instances/README.md +30 -0
  12. qtiming/contract/instances/artiq.toml +45 -0
  13. qtiming/contract/instances/ibm_heron.toml +62 -0
  14. qtiming/contract/instances/ibm_heron_snapshot.json +22 -0
  15. qtiming/contract/instances/q1.toml +88 -0
  16. qtiming/contract/instances/qua.toml +65 -0
  17. qtiming/contract/loader.py +355 -0
  18. qtiming/contract/model.py +123 -0
  19. qtiming/contract/schema.py +106 -0
  20. qtiming/contract/target_import.py +46 -0
  21. qtiming/core/__init__.py +0 -0
  22. qtiming/core/ast.py +140 -0
  23. qtiming/core/errors.py +36 -0
  24. qtiming/core/ids.py +34 -0
  25. qtiming/core/labels.py +121 -0
  26. qtiming/core/provenance.py +77 -0
  27. qtiming/core/time.py +96 -0
  28. qtiming/dispatch/__init__.py +22 -0
  29. qtiming/dispatch/artiq.py +70 -0
  30. qtiming/dispatch/ibm.py +83 -0
  31. qtiming/dispatch/q1.py +102 -0
  32. qtiming/dispatch/qua.py +88 -0
  33. qtiming/elab/__init__.py +360 -0
  34. qtiming/evidence/__init__.py +15 -0
  35. qtiming/evidence/ingest.py +235 -0
  36. qtiming/exec/__init__.py +0 -0
  37. qtiming/exec/artiq.py +100 -0
  38. qtiming/exec/engine.py +235 -0
  39. qtiming/exec/explore.py +43 -0
  40. qtiming/exec/ibm.py +117 -0
  41. qtiming/exec/oracle.py +88 -0
  42. qtiming/exec/q1.py +95 -0
  43. qtiming/exec/qua.py +95 -0
  44. qtiming/frontend/__init__.py +40 -0
  45. qtiming/frontend/_shared.py +149 -0
  46. qtiming/frontend/annotations.py +81 -0
  47. qtiming/frontend/lint.py +116 -0
  48. qtiming/frontend/payload.py +113 -0
  49. qtiming/frontend/program.py +51 -0
  50. qtiming/frontend/qasm3_fe.py +341 -0
  51. qtiming/frontend/qiskit_expr.py +89 -0
  52. qtiming/frontend/qiskit_fe.py +220 -0
  53. qtiming/frontend/serialise.py +63 -0
  54. qtiming/frontend/stretch.py +71 -0
  55. qtiming/graph/__init__.py +0 -0
  56. qtiming/graph/builder.py +245 -0
  57. qtiming/graph/export.py +25 -0
  58. qtiming/graph/invariants.py +67 -0
  59. qtiming/graph/lteg.py +153 -0
  60. qtiming/graph/window.py +120 -0
  61. qtiming/oblig/__init__.py +0 -0
  62. qtiming/oblig/generate.py +145 -0
  63. qtiming/oblig/model.py +76 -0
  64. qtiming/py.typed +0 -0
  65. qtiming/qiskit_pass/__init__.py +7 -0
  66. qtiming/qiskit_pass/_common.py +21 -0
  67. qtiming/qiskit_pass/equalize.py +171 -0
  68. qtiming/qiskit_pass/plugin.py +23 -0
  69. qtiming/qiskit_pass/strip.py +42 -0
  70. qtiming/qiskit_pass/timing_check.py +40 -0
  71. qtiming/repair/__init__.py +0 -0
  72. qtiming/repair/suggest.py +146 -0
  73. qtiming/solve/__init__.py +0 -0
  74. qtiming/solve/concrete.py +148 -0
  75. qtiming/solve/dispatcher.py +55 -0
  76. qtiming/solve/interval.py +185 -0
  77. qtiming/solve/smt.py +167 -0
  78. qtiming/solve/smt_o5.py +1 -0
  79. qtiming/solve/synth/__init__.py +0 -0
  80. qtiming/solve/synth/bruteforce_dc.py +156 -0
  81. qtiming/solve/synth/model.py +59 -0
  82. qtiming/solve/synth/relax.py +93 -0
  83. qtiming/solve/synth/rigid.py +33 -0
  84. qtiming/solve/synth/sc.py +55 -0
  85. qtiming/solve/synth/stn.py +74 -0
  86. qtiming/solve/synth/stnu_dc.py +93 -0
  87. qtiming/verdict/__init__.py +0 -0
  88. qtiming/verdict/minimise.py +45 -0
  89. qtiming/verdict/model.py +107 -0
  90. qtiming/verdict/render.py +72 -0
  91. qtiming/verdict/render_html.py +80 -0
  92. qtiming/verdict/render_json.py +12 -0
  93. qtiming/verdict/render_sarif.py +104 -0
  94. qtiming/verdict/replay.py +77 -0
  95. qtiming/verdict/run.py +174 -0
  96. qtiming/verdict/rus.py +53 -0
  97. qtiming-0.1.0.dist-info/METADATA +262 -0
  98. qtiming-0.1.0.dist-info/RECORD +102 -0
  99. qtiming-0.1.0.dist-info/WHEEL +4 -0
  100. qtiming-0.1.0.dist-info/entry_points.txt +6 -0
  101. qtiming-0.1.0.dist-info/licenses/LICENSE +177 -0
  102. qtiming-0.1.0.dist-info/licenses/NOTICE +8 -0
@@ -0,0 +1,161 @@
1
+ """`qtiming-bench report RESULTS_DIR --tables DIR`: tables (markdown and CSV) from a run's rows.
2
+
3
+ Reads only `results.jsonl` (and, optionally, `diff.json` / a ground-truth file); nothing is typed
4
+ in by hand. Tables: verdict distribution per contract (17.5), tier mix, assumption census (cells
5
+ by weakest provenance class), portability (verdict per program across contracts, H4), the
6
+ non-certified-number count behind the headline, and H1 / H2 summaries when their inputs exist.
7
+ Figures need matplotlib and are skipped, with a message, when it is not installed.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import argparse
13
+ import csv
14
+ import json
15
+ from collections import Counter
16
+ from pathlib import Path
17
+ from typing import Any
18
+
19
+ VERDICTS = ("PROVED", "PROVED-UNDER", "REFUTED", "UNKNOWN", "unsupported", "timeout", "error")
20
+
21
+
22
+ def _write(d: Path, name: str, header: list[str], rows: list[list[Any]], title: str) -> None:
23
+ with open(d / f"{name}.csv", "w", encoding="utf-8", newline="") as fh:
24
+ w = csv.writer(fh, lineterminator="\n")
25
+ w.writerow(header)
26
+ w.writerows(rows)
27
+ md = [f"### {title}", "", "| " + " | ".join(header) + " |",
28
+ "| " + " | ".join("---" for _ in header) + " |"]
29
+ md += ["| " + " | ".join(str(x) for x in r) + " |" for r in rows]
30
+ (d / f"{name}.md").write_text("\n".join(md) + "\n", encoding="utf-8")
31
+
32
+
33
+ def tables(rows: list[dict[str, Any]], truth: dict[str, Any] | None,
34
+ diff: dict[str, Any] | None) -> dict[str, tuple[str, list[str], list[list[Any]]]]:
35
+ t: dict[str, tuple[str, list[str], list[list[Any]]]] = {}
36
+ contracts = sorted({r["contract"] for r in rows})
37
+
38
+ by_c = {c: Counter(r["status"] for r in rows if r["contract"] == c) for c in contracts}
39
+ t["verdicts_per_contract"] = (
40
+ "Verdict distribution per contract (cells = program x policy)", ["contract", *VERDICTS],
41
+ [[c, *(by_c[c].get(v, 0) for v in VERDICTS)] for c in contracts])
42
+
43
+ by_p = {p: Counter(r["status"] for r in rows if r["policy"] == p)
44
+ for p in sorted({r["policy"] for r in rows})}
45
+ t["verdicts_per_policy"] = (
46
+ "Verdict distribution per policy", ["policy", *VERDICTS],
47
+ [[p, *(by_p[p].get(v, 0) for v in VERDICTS)] for p in by_p])
48
+
49
+ tiers: Counter[str] = Counter()
50
+ for r in rows:
51
+ tiers.update(r.get("tiers") or {})
52
+ t["tier_mix"] = ("Obligations by the tier that resolved them (cells with a verdict)",
53
+ ["tier", "obligations"], [[k, v] for k, v in sorted(tiers.items())])
54
+
55
+ census: Counter[str] = Counter(r.get("weakest_class") or "none" for r in rows
56
+ if r["status"] in ("PROVED", "PROVED-UNDER", "REFUTED",
57
+ "UNKNOWN"))
58
+ t["assumption_census"] = ("Assumption census: cells by weakest provenance class of the "
59
+ "latency bounds they rest on", ["weakest class", "cells"],
60
+ [[k, v] for k, v in sorted(census.items())])
61
+
62
+ uncert = sum(r.get("uncertified", 0) for r in rows)
63
+ ph = sum(r.get("placeholders", 0) for r in rows)
64
+ rest = sum(1 for r in rows if r.get("uncertified"))
65
+ t["headline_provenance"] = (
66
+ "Headline: verdicts resting on non-certified numbers",
67
+ ["cells with a verdict", "cells resting on a non-certified number",
68
+ "non-certified assumptions (total)", "of which placeholders"],
69
+ [[sum(1 for r in rows if r["status"] in VERDICTS[:4]), rest, uncert, ph]])
70
+
71
+ progs = sorted({(r["family"], r["program"]) for r in rows})
72
+ cells = {(r["family"], r["program"], r["contract"], r["policy"]): r["status"] for r in rows}
73
+ pols = sorted({r["policy"] for r in rows})
74
+ port = []
75
+ differing = 0
76
+ for f, p in progs:
77
+ vs = [cells.get((f, p, c, pol), "-") for pol in pols for c in contracts]
78
+ decided = {v for v in vs if v in VERDICTS[:4]}
79
+ differing += len(decided) > 1
80
+ port.append([f"{f}/{p}", *(cells.get((f, p, c, pols[0]), "-") for c in contracts),
81
+ "yes" if len(decided) > 1 else "no"])
82
+ t["portability"] = (
83
+ f"Portability (H4): verdict at policy {pols[0] if pols else '-'}; last column: verdicts "
84
+ f"differ across contracts/policies ({differing} of {len(progs)} programs)",
85
+ ["program", *contracts, "differs"], port)
86
+
87
+ if diff is not None:
88
+ t["h1_differential"] = (
89
+ f"H1: executor violations on proved programs (runs per cell {diff['runs_per_cell']}, "
90
+ f"seed {diff['seed']})",
91
+ ["personality", "proved cells", "runs", "violating runs"],
92
+ [[k, s["proved_cells"], s["runs"], s["violating_runs"]]
93
+ for k, s in diff["per_personality"].items()])
94
+ if truth is not None:
95
+ gt = truth["truth"]
96
+ c: Counter[tuple[str, bool]] = Counter()
97
+ for r in rows:
98
+ k = f"{r['family']}/{r['program']}|{r['contract']}|{r['policy']}"
99
+ if k in gt:
100
+ c[(r["status"], bool(gt[k]["violated"]))] += 1
101
+ safe = sum(v for (s, bad), v in c.items() if not bad)
102
+ alarm = sum(v for (s, bad), v in c.items() if not bad and s in ("REFUTED", "UNKNOWN"))
103
+ t["h2_precision"] = (
104
+ "H2: verdict against exhaustive per-run ground truth (partial: no O3/O4/O7)",
105
+ ["verdict", "violation reachable", "cells"],
106
+ [[s, "yes" if bad else "no", v] for (s, bad), v in sorted(c.items())]
107
+ + [["false-alarm rate (REFUTED or UNKNOWN, no reachable violation)", "",
108
+ f"{alarm}/{safe}" + (f" = {alarm / safe:.2f}" if safe else "")]])
109
+ return t
110
+
111
+
112
+ def _report(a: argparse.Namespace) -> int:
113
+ from . import read_rows
114
+
115
+ rows = read_rows(a.results)
116
+ base = Path(a.results)
117
+ base = base if base.is_dir() else base.parent
118
+ diff_p = Path(a.diff) if a.diff else base / "diff" / "diff.json"
119
+ truth_p = Path(a.truth)
120
+ diff = json.loads(diff_p.read_text(encoding="utf-8")) if diff_p.is_file() else None
121
+ truth = json.loads(truth_p.read_text(encoding="utf-8")) if truth_p.is_file() else None
122
+ d = Path(a.tables)
123
+ d.mkdir(parents=True, exist_ok=True)
124
+ out = tables(rows, truth, diff)
125
+ for name, (title, header, body) in out.items():
126
+ _write(d, name, header, body, title)
127
+ print(f"{len(rows)} cells -> {len(out)} tables in {d}")
128
+ if a.figures:
129
+ try:
130
+ import matplotlib # type: ignore[import-not-found,unused-ignore]
131
+
132
+ matplotlib.use("Agg")
133
+ import matplotlib.pyplot as plt # type: ignore[import-not-found,unused-ignore]
134
+ except ImportError:
135
+ print("figures skipped: matplotlib is not installed (pip install -e '.[bench]')")
136
+ return 0
137
+ fd = Path(a.figures)
138
+ fd.mkdir(parents=True, exist_ok=True)
139
+ title, header, body = out["verdicts_per_contract"]
140
+ fig, ax = plt.subplots(figsize=(7, 3.5))
141
+ bottom = [0] * len(body)
142
+ for j, v in enumerate(header[1:], start=1):
143
+ vals = [r[j] for r in body]
144
+ ax.bar([r[0] for r in body], vals, bottom=bottom, label=v)
145
+ bottom = [x + y for x, y in zip(bottom, vals, strict=True)]
146
+ ax.set_ylabel("cells")
147
+ ax.legend(fontsize=7)
148
+ fig.tight_layout()
149
+ fig.savefig(fd / "verdicts_per_contract.png", dpi=150)
150
+ print(f"figure -> {fd / 'verdicts_per_contract.png'}")
151
+ return 0
152
+
153
+
154
+ def add_parser(sub: Any) -> None:
155
+ r = sub.add_parser("report", help="verdict, tier, assumption and portability tables")
156
+ r.add_argument("results", help="a run directory (or its results.jsonl)")
157
+ r.add_argument("--tables", required=True, help="directory for the .md and .csv tables")
158
+ r.add_argument("--figures", help="directory for figures (needs matplotlib)")
159
+ r.add_argument("--diff", help="diff.json (default: <results>/diff/diff.json)")
160
+ r.add_argument("--truth", default="benchmarks/families/ground_truth.json")
161
+ r.set_defaults(fn=_report)
qtiming/bench/truth.py ADDED
@@ -0,0 +1,88 @@
1
+ """`qtiming-bench truth`: exhaustive ground truth for small programs (plan 16.4, hypothesis H2).
2
+
3
+ For each (program, contract, policy) cell whose elaborated program is small enough, enumerate every
4
+ outcome assignment times every vertex of the latency box in the reference executor
5
+ (`qtiming.exec.explore.exhaustive`) and record whether ANY execution violates.
6
+
7
+ Scope, stated so the numbers are not over-read: the executor reports per-run violations only
8
+ (RTIO underflow, Q1 stale read / RT underflow, ARTIQ silent drops). Obligations that compare two
9
+ runs (O4 idle-gap variation, O7) or a deadline (O3) are not visible to it, so `violated: false`
10
+ means "no per-run violation reachable", not "the program is safe". Vertices of the latency box are
11
+ exact only for snap-free programs (theorem T10).
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import argparse
17
+ import json
18
+ from pathlib import Path
19
+ from typing import Any
20
+
21
+ from qtiming.core.errors import QtError
22
+
23
+
24
+ def truth_cell(prog: Path, contract: str, policy: str, *, max_bits: int, max_lats: int,
25
+ max_runs: int, assume: tuple[str, ...] = ()) -> dict[str, Any]:
26
+ from qtiming.core.ast import Policy
27
+ from qtiming.elab import elaborate
28
+ from qtiming.exec.explore import exhaustive
29
+ from qtiming.verdict.run import with_policy
30
+
31
+ from . import load_cell
32
+
33
+ c, p = load_cell(prog, contract, assume)
34
+ body = with_policy(p.body, Policy(policy)) # type: ignore[arg-type]
35
+ el = elaborate(body, c)
36
+ kinds: set[str] = set()
37
+ runs = 0
38
+ for _omega, _theta, res in exhaustive(el.body, c, k_max=max_bits, K_max=max_lats):
39
+ runs += 1
40
+ kinds |= {v.kind for v in res.violations} | {f"drop:{d.kind}" for d in res.drops}
41
+ if runs >= max_runs:
42
+ raise QtError("E-EXEC-EXHAUSTIVE", f"more than {max_runs} executions")
43
+ return {"executions": runs, "violated": bool(kinds), "kinds": sorted(kinds)}
44
+
45
+
46
+ def _truth(a: argparse.Namespace) -> int:
47
+ from . import contracts, key, programs
48
+
49
+ truth: dict[str, Any] = {}
50
+ skipped: dict[str, str] = {}
51
+ for prog in programs(Path(a.suite)):
52
+ for c in contracts(a.contracts):
53
+ for pol in a.policies.split(","):
54
+ k = key({"family": prog.parent.name, "program": prog.stem, "contract": c,
55
+ "policy": pol})
56
+ try:
57
+ truth[k] = truth_cell(prog, c, pol, max_bits=a.max_bits, max_lats=a.max_lats,
58
+ max_runs=a.max_runs, assume=tuple(a.assume or ()))
59
+ except QtError as e: # too big, unbounded latency, unsupported, ...
60
+ skipped[k] = e.code
61
+ out = Path(a.out)
62
+ out = out if out.suffix == ".json" else out / "ground_truth.json"
63
+ out.parent.mkdir(parents=True, exist_ok=True)
64
+ doc = {"limits": {"max_bits": a.max_bits, "max_latencies": a.max_lats,
65
+ "max_executions": a.max_runs},
66
+ "scope": "per-run executor violations only; see qtiming.bench.truth",
67
+ "truth": dict(sorted(truth.items())), "skipped": dict(sorted(skipped.items()))}
68
+ out.write_text(json.dumps(doc, indent=1) + "\n", encoding="utf-8")
69
+ reasons: dict[str, int] = {}
70
+ for v in skipped.values():
71
+ reasons[v] = reasons.get(v, 0) + 1
72
+ print(f"{len(truth)} cells with ground truth, {len(skipped)} skipped "
73
+ + (f"({', '.join(f'{k}={v}' for k, v in sorted(reasons.items()))})" if reasons else "")
74
+ + f" -> {out}")
75
+ return 0
76
+
77
+
78
+ def add_parser(sub: Any) -> None:
79
+ t = sub.add_parser("truth", help="exhaustive ground truth for small programs (H2)")
80
+ t.add_argument("--suite", default="benchmarks/families")
81
+ t.add_argument("--contracts", default="all")
82
+ t.add_argument("--policies", default="eq,sync,exp")
83
+ t.add_argument("--max-bits", type=int, default=8, help="skip programs with more outcome bits")
84
+ t.add_argument("--max-lats", type=int, default=6, help="skip programs with more latencies")
85
+ t.add_argument("--max-runs", type=int, default=2048, help="skip programs needing more runs")
86
+ t.add_argument("--assume", action="append", metavar="KEY=VALUE")
87
+ t.add_argument("--out", default="benchmarks/families/")
88
+ t.set_defaults(fn=_truth)
File without changes
@@ -0,0 +1,35 @@
1
+ """`qtiming evidence ingest|report JOBS...` (plan 7.7, 18.3)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import sys
7
+ from pathlib import Path
8
+
9
+ from qtiming.evidence import EvidenceError, ingest, report
10
+
11
+
12
+ def add_parser(sub: argparse._SubParsersAction) -> None: # type: ignore[type-arg]
13
+ p = sub.add_parser("evidence", help="IBM scheduler_timing jobs -> contract patch")
14
+ p.add_argument("action", choices=["ingest", "report"])
15
+ p.add_argument("jobs", nargs="+", metavar="JOBS")
16
+ p.add_argument("--out", help="ingest: write the patch here (default: stdout)")
17
+ p.add_argument("--allow-synthetic", action="store_true",
18
+ help="accept jobs flagged synthetic (test data only; the patch says so)")
19
+ p.set_defaults(func=run)
20
+
21
+
22
+ def run(args: argparse.Namespace) -> int:
23
+ try:
24
+ if args.action == "report":
25
+ sys.stdout.write(report(args.jobs))
26
+ return 0
27
+ text = ingest(args.jobs, allow_synthetic=args.allow_synthetic)
28
+ except (EvidenceError, OSError) as e:
29
+ print(f"error: {e}", file=sys.stderr)
30
+ return 2
31
+ if args.out:
32
+ Path(args.out).write_bytes(text.encode("utf-8")) # bytes: no newline translation
33
+ else:
34
+ sys.stdout.write(text)
35
+ return 0