#!/usr/bin/env python3
"""Reconstruct and reconcile Run 04 offline from checked-in inputs."""
import argparse
from collections import Counter
import csv
import hashlib
import io
import json
import math
from pathlib import Path
import sys
from tempfile import NamedTemporaryFile
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))
from mbi.run04 import CASES, FERROUS, build_balance
from mbi.run04_reconciliation import compare_balance, load_historical, parse_historical
BASELINE = Path("research/run04/baseline.json")
OUTPUT = ROOT / "build/run04"
BALANCE_FIELDS = (
"boundary", "equipment_id", "component", "material", *CASES, "quantity",
"method", "source", "ledger_id", "view", "host_material",
)
RECONCILIATION_FIELDS = (
"boundary", "material", "endpoint", "historical_t", "historical_status",
"reconstructed_t", "reconstructed_status", "delta_t", "tolerance_t", "status",
)
def verify_preservation(root, baseline):
"""Verify original Git blob IDs from disk without a Git dependency."""
for name, expected in baseline["blobs"].items():
try:
raw = (root / name).read_bytes()
except FileNotFoundError as exc:
raise ValueError(f"Missing historical file: {name}") from exc
blob = f"blob {len(raw)}\0".encode("ascii") + raw
if hashlib.sha1(blob).hexdigest() != expected:
raise ValueError(f"Changed historical file: {name}")
return {
"original_commit": baseline["commit"],
"files_checked": len(baseline["blobs"]),
"exclusions": baseline.get("exclusions", {}),
"method": "Git SHA-1 blob ID computed from raw local file bytes",
"status": "identical",
}
def validate_envelope(envelope, context):
values = [envelope[case] for case in CASES]
if (any(type(value) not in (int, float) or not math.isfinite(value) for value in values)
or not 0 <= values[0] <= values[1] <= values[2]):
raise ValueError(f"Invalid low/base/high mass envelope for {context}: {values}")
def validate_balance(balance):
for row in balance["rows"]:
validate_envelope(row, f'{row["equipment_id"]}/{row["component"]}/{row["material"]}')
scenarios = {"base design": balance, **balance["alternatives"]}
for design, scenario in scenarios.items():
for boundary, materials in scenario["subtotals"].items():
for material, envelope in materials.items():
validate_envelope(envelope, f"{design}/{boundary}/{material}")
def json_bytes(value):
return (json.dumps(value, ensure_ascii=False, sort_keys=True, indent=2, allow_nan=False) + "\n").encode("utf-8")
def csv_bytes(rows, columns):
stream = io.StringIO()
writer = csv.DictWriter(stream, fieldnames=columns, lineterminator="\n")
writer.writeheader()
writer.writerows(rows)
return stream.getvalue().encode("utf-8")
def format_mass(value):
if value is None:
return "—"
if abs(value) < 0.005:
return "0"
return f"{value:,.2f}".rstrip("0").rstrip(".")
def top_contributors(rows, materials):
totals = Counter()
boundaries = {}
for row in rows:
if row["view"] == "physical" and row["material"] in materials:
equipment = row["equipment_id"]
totals[equipment] += row["base"]
boundaries[equipment] = row["boundary"]
return [(equipment, boundaries[equipment], mass)
for equipment, mass in sorted(totals.items(), key=lambda item: (-item[1], item[0]))[:5]]
def findings(balance, reconciliation):
counts = Counter(row["status"] for row in reconciliation["rows"])
lines = [
"# Run 04 reconstructed equipment mass balance", "",
f'Run identity: `{balance["identity"]}`. Quantity snapshot: `{balance["quantity_snapshot"]}`. '
f'Configuration: `{balance["configuration"]}`.', "",
"All quantities are metric tonnes per canonical 1 GW of commissioned IT. The base design "
"covers incremental B1 compute, B2 facility equipment, and modeled B3 enabling equipment. "
"B1–B3 sums those increments once. Low, base, and high are coherent input "
"constructions with fixed equipment counts. Other feasible designs could fall outside "
"their range. Transfer from retained product and geometry proxies to the target campus is low "
"confidence. The results are scenario estimates with partial campus coverage.", "",
"Elemental lithium is a nested view of host compounds. Aggregate ferrous includes disjoint "
"ferrous classes. Summing every material label would count some stock twice.", "",
"## Cumulative modeled equipment stocks (B1–B3)", "",
"| Material | Low (t) | Base (t) | High (t) |",
"| --- | ---: | ---: | ---: |",
]
base_totals = balance["subtotals"]["B1-B3"]
for material, label in (
("copper", "Copper-grade stock"), ("aluminum", "Aluminum stock and named alloys"),
("ferrous", "Disjoint ferrous, linked total"), ("lithium", "Elemental lithium, nested view"),
):
tonnes = [f"{base_totals[material][case]:,.1f}" for case in CASES]
lines.append("| " + " | ".join([label, *tonnes]) + " |")
lines.extend([
"", "## Largest equipment contributors in the base case", "",
"Component stocks are summed per equipment population. Ferrous combines the disjoint "
"ferrous classes.", "",
"| Stock | Boundary | Equipment population | Base (t) |",
"| --- | --- | --- | ---: |",
])
for label, materials in (("Copper", ("copper",)), ("Aluminum", ("aluminum",)), ("Ferrous", FERROUS)):
for equipment, boundary, mass in top_contributors(balance["rows"], materials):
lines.append(f"| {label} | {boundary} | `{equipment}` | {mass:,.1f} |")
lines.extend([
"",
"## Historical reconciliation", "",
"The historical figures are transcribed from a truncated, unverified report excerpt. "
"Reconstruction coefficients and ledger quantities are evaluated independently of that "
"table. Agreement here uses historical display precision. The archived report's marginal "
"material endpoints and the reconstructed joint cases have different uncertainty semantics.", "",
f'Across low, base, and high, {counts["within_display_rounding"]} endpoints agree at '
f'historical display precision, {counts["different"]} differ, and '
f'{counts["not_comparable"]} lack a value on one or both sides.', "",
"Delta is reconstructed minus historical. Missing estimates are shown as —. The CSV and "
"JSON include all endpoints and historical display tolerances.", "",
"| Boundary | Material | Reconstructed base (t) | Historical base (t) | Delta (t) |",
"| --- | --- | ---: | ---: | ---: |",
])
for row in reconciliation["rows"]:
if row["endpoint"] == "base":
lines.append(
f'| {row["boundary"]} | {row["material"]} | {format_mass(row["reconstructed_t"])} | '
f'{format_mass(row["historical_t"])} | {format_mass(row["delta_t"])} |'
)
comparable = [
row for row in reconciliation["rows"]
if row["boundary"] == "B1-B3" and row["endpoint"] == "base"
and row["historical_t"] and row["status"] == "different"
]
lines.extend([
"", "The table compares labels and published scope. Differences include effects of "
"component coverage, assumed dimensions, product transfer, and case definitions. The "
"archived material envelopes do not supply the calculation inputs needed to attribute "
"a difference to any one coefficient.", "",
])
for row in sorted(comparable, key=lambda row: abs(row["delta_t"]), reverse=True)[:3]:
percentage = 100 * row["delta_t"] / row["historical_t"]
increments = [
increment for increment in reconciliation["rows"]
if increment["boundary"] in ("B1", "B2", "B3")
and increment["endpoint"] == "base" and increment["material"] == row["material"]
and increment["delta_t"] is not None
]
largest = max(increments, key=lambda increment: abs(increment["delta_t"]), default=None)
driver = (
f' The largest incremental difference is {largest["boundary"]} '
f'({format_mass(largest["delta_t"])} t).' if largest else ""
)
lines.append(
f'- B1–B3 {row["material"].replace("_", " ")} base differs by '
f'{format_mass(row["delta_t"])} t ({percentage:+.1f}% of the historical base).{driver}'
)
lines.extend([
"", "## Replacement designs and gaps", "",
"Replacement cases in the reconstructed balance apply to the named assemblies. The historical "
"alternative deltas are carried in the reconciliation as reported claims with their own scope.", "",
"| Replacement | B1–B3 copper Δ (t) | B1–B3 aluminum Δ (t) | B1–B3 ferrous Δ (t) |",
"| --- | ---: | ---: | ---: |",
])
for identity, scenario in balance["alternatives"].items():
totals = scenario["subtotals"]["B1-B3"]
deltas = [
format_mass(totals[material]["base"] - base_totals[material]["base"])
for material in ("copper", "aluminum", "ferrous")
]
lines.append("| " + " | ".join([identity, *deltas]) + " |")
lines.extend([
"",
f'The coverage register lists {len(balance["coverage"])} modeled scopes and '
f'{len(balance["gaps"])} gap records. Gaps remain outside the quantified sum. See coverage.json '
"for ledger links, physical per-unit masses, budget residuals, missing inputs, and scope notes.", "",
"Read budget residuals as accounting constraints and keep them out of the stock totals. "
"The low and high battery module and cabinet budget endpoints are marginal envelopes. "
"Adding those endpoints does not yield a joint 590 kg partition. Modeled battery stock "
"passes the shared 590 kg gross-budget check.", "",
"Installed conductor routes and sections, equipment-specific transformer drawings and masses, "
"and selected cooling and battery equipment bills of materials would constrain high-volume "
"metal and chemical-stock estimates. Building shells, foundations, roads, earthworks, and "
"unallocated offsite infrastructure are outside this equipment scope.", "",
"Run `python scripts/reproduce_run04.py` to regenerate these findings and the supporting tables "
"offline. The manifest records SHA-256 hashes of inputs and outputs. The preservation audit "
"compares frozen file bytes with the Run 03 Git tree.", "",
])
return "\n".join(lines).encode("utf-8")
def reproduce(root, output):
baseline = json.loads((root / BASELINE).read_text(encoding="utf-8"))
preservation = verify_preservation(root, baseline)
balance = build_balance(root)
validate_balance(balance)
if parse_historical(root) != load_historical(root):
raise ValueError("Retained historical excerpt and transcription differ")
reconciliation = compare_balance(balance, root=root)
source_paths = set()
for source in balance["provenance"].values():
source_paths.add(Path(source["path"]))
source_paths.update(Path(capture["path"]) for capture in source.get("primary_captures", []))
generated = {
"balance.json": json_bytes(balance),
"balance.csv": csv_bytes(balance["rows"], BALANCE_FIELDS),
"reconciliation.json": json_bytes(reconciliation),
"reconciliation.csv": csv_bytes(reconciliation["rows"], RECONCILIATION_FIELDS),
"coverage.json": json_bytes({"modeled": balance["coverage"], "gaps": balance["gaps"]}),
"provenance.json": json_bytes({
"reconstruction_sources": balance["provenance"],
"historical_excerpt": reconciliation["source"],
}),
"preservation.json": json_bytes(preservation),
"findings.md": findings(balance, reconciliation),
}
input_paths = {
BASELINE, Path("data/run04/model.json"), Path("data/run04/historical_reported.json"),
Path("research/run04/historical_findings.md"), Path("mbi/run04.py"),
Path("mbi/run04_reconciliation.py"), Path("scripts/reproduce_run04.py"),
} | source_paths
generated["manifest.json"] = json_bytes({
"identity": balance["identity"],
"prior_input_audit": "preservation.json",
"inputs": {path.as_posix(): hashlib.sha256((root / path).read_bytes()).hexdigest()
for path in input_paths},
"outputs": {name: hashlib.sha256(payload).hexdigest() for name, payload in generated.items()},
})
protected = {(root / name).resolve() for name in baseline["blobs"]}
protected.update((root / path).resolve() for path in input_paths)
for name in generated:
target = output / name
if target.is_symlink() or target.resolve() in protected:
raise ValueError(f"Refusing to overwrite an input or historical file: {target}")
output.mkdir(parents=True, exist_ok=True)
for name, payload in generated.items():
stream = NamedTemporaryFile(dir=output, delete=False)
temporary = Path(stream.name)
try:
with stream:
stream.write(payload)
temporary.replace(output / name)
finally:
temporary.unlink(missing_ok=True)
return generated
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--output-dir", type=Path, default=OUTPUT)
args = parser.parse_args()
try:
reproduce(ROOT, args.output_dir)
except (OSError, ValueError) as exc:
parser.exit(1, f"{exc}\n")
if __name__ == "__main__":
main()
Source details
Run 04 research. Equipment material estimates with documented assumptions and scope. Web prose uses current site terminology; downloadable records preserve original wording. Hashes identify the downloadable records.
Source: scripts/reproduce_run04.py
SHA-256: c184a9d68d145b56611c1060da1326e1f04e89e914aa03c5098b41871b2d9352
Download research file
Optional: tell Sid you’re reading
The document is open; sharing your name/email is optional.