scripts/prepare_rgbd_scale_experiment.py
#!/usr/bin/env python3
"""Freeze the V6 single-factor training-scale protocol (24 vs 72 TRAIN scenes, CPU only)."""
from __future__ import annotations
import argparse
import datetime
import importlib.metadata
import shutil
import subprocess
import sys
from dataclasses import asdict
from pathlib import Path
import numpy as np
import torch
from mcss.mechanism_pilot.geometry_carrier_experiment import read, validate_split
from mcss.mechanism_pilot.readout_reanalysis import (
PRIMARY_REFERENCE,
READOUTS,
REFERENCES,
reference_values,
)
from mcss.mechanism_pilot.rgbd_evidence_carrier import LOG_SIGMA0, carrier_config
from mcss.mechanism_pilot.rgbd_scale_carrier import (
EXPERIMENT,
PRIMARY_PAIR,
VARIANT_SPECS,
make_carrier,
parameter_hash,
)
from mcss.mechanism_pilot.small_training import sha, write_json
V2 = Path("outputs/EXP-3D-GEOMETRY-AWARE-CARRIER-V2")
V3 = Path("outputs/EXP-3D-DENSE-EVIDENCE-CARRIER-V3")
V4 = Path("outputs/EXP-3D-PLANE-SWEEP-CARRIER-V4")
V5 = Path("outputs/EXP-3D-RGBD-EVIDENCE-CARRIER-V5")
DATA = Path("outputs/EXP-3D-RGBD-FRESH-SCALE-DATA-V1")
COUNTS = {"C0": 5150, "C1": 5150, "C2": 5125}
SEEDS = [20260928, 20260929, 20260930]
THREADS = {"OMP_NUM_THREADS": "1", "OPENBLAS_NUM_THREADS": "1", "MKL_NUM_THREADS": "1"}
def seal_previous(root):
"""Hash every earlier experiment artifact so finalization can prove nothing changed."""
files = {}
for base in (Path("outputs"), Path("docs/experiments")):
for path in sorted(base.rglob("*")):
if path.is_file() and EXPERIMENT not in path.parts:
files[str(path)] = {"sha256": sha(path), "bytes": path.stat().st_size}
write_json(
root / "audit/previous_experiment_seal.json",
{"created_utc": datetime.datetime.now(datetime.UTC).isoformat(), "files": files},
)
return len(files)
def prepare(root):
root = Path(root).resolve()
if root.name != EXPERIMENT:
raise PermissionError("Exact V6 experiment directory required")
if (root / "preregistration.json").exists():
raise FileExistsError("No re-freezing")
if not (root / "PROTOCOL.md").is_file():
raise PermissionError("Frozen V6 protocol text required before freezing")
for earlier in (V2, V3, V4, V5):
if read(earlier / "integrity.json")["status"] != "PASS":
raise PermissionError(f"{earlier.name} must be finalized before V6 freezes")
prior = read(V2 / "train_depth_prior.json")
near, far = prior["near_m"], prior["far_m"]
manifest = read(V5 / "scene_split.json")
train24 = sorted(r["scene_id"] for r in manifest["scenes"] if r["split"] == "TRAIN")
scale = read(DATA / "preparation_integrity.json")
if scale["TRAIN_X"] != 48:
raise PermissionError("Exactly 48 validated TRAIN-X scenes required")
manifest["scenes"] = manifest["scenes"] + read(DATA / "manifest_train_x.json")["scenes"]
train72 = sorted(r["scene_id"] for r in manifest["scenes"] if r["split"] == "TRAIN")
validate_split(manifest)
counts = {s: sum(r["split"] == s for r in manifest["scenes"]) for s in ("TRAIN", "DEV")}
if counts != {"TRAIN": 72, "DEV": 8} or len(train24) != 24:
raise PermissionError(f"Unexpected V2 cohort: {counts}")
write_json(root / "scene_split.json", manifest)
# Geometry-free constants from TRAIN supervision targets only (primary-query GT).
train_depths, train_files = [], {}
for record in sorted(
(r for r in manifest["scenes"] if r["scene_id"] in train24), key=lambda r: r["scene_id"]
):
frames = {f["frame_id"]: f for f in record["frames"]}
for fid in record["roles"]["primary_query"]:
path = Path(frames[fid]["depth"])
train_files[str(path)] = sha(path)
train_depths.append(np.load(path).squeeze().astype(np.float32))
reference = reference_values(train_depths)
write_json(
root / "frame_role_lock.json",
{
"roles": {r["scene_id"]: r["roles"] for r in manifest["scenes"]},
"manifest_sha256": sha(root / "scene_split.json"),
"source": "V2 locked cohort, frame roles and GT-free bounds rule reused unchanged",
"v2_scene_split_sha256": sha(V2 / "scene_split.json"),
"dev_reused_from_v2": True,
"selection_uses_model_outputs": False,
"no_frame_or_bounds_search_after_training": True,
},
)
for name in ("train_depth_prior.json", "data_provenance.json"):
shutil.copyfile(V2 / name, root / name)
hashes = {
seed: {v: parameter_hash(make_carrier(v, seed, "cpu", near, far)) for v in VARIANT_SPECS}
for seed in SEEDS
}
if any(len(set(per_seed.values())) != 1 for per_seed in hashes.values()):
raise AssertionError("Variants must share identical shared parameters per seed")
counts_by_variant = {
v: sum(p.numel() for p in make_carrier(v, SEEDS[0], "cpu", near, far).parameters())
for v in VARIANT_SPECS
}
if counts_by_variant != COUNTS:
raise AssertionError(f"Parameter counts changed: {counts_by_variant}")
write_json(
root / "architecture_contract.json",
{
"variants": {
v: {**spec, "config": asdict(carrier_config())} for v, spec in VARIANT_SPECS.items()
},
"parameter_count": COUNTS,
"shared_parameter_hash_by_seed": {str(s): h["C0"] for s, h in hashes.items()},
"only_difference_C0_C1": "C1 differs from C0 only by its frozen TRAIN set: 72 "
"scenes (the 24 V2-V5 scenes plus 48 validated TRAIN-X scenes, volume disjoint from "
"DEV and FRESH-V1) versus the 24; the frozen V5 C1 recipe (measured-depth bypass, "
"surface loss), per-seed initialization, 6000-step budget, renderer and bounds rule "
"are identical. The data stream differs between TRAIN sets by design.",
"C2_difference_from_C1": "the frozen V5 C0 recipe (RGB only, no depth bypass) on "
"TRAIN72; secondary, never a gate",
"depth_bypass": {
"log_sigma_init": LOG_SIGMA0,
"sampling": "nearest pixel of the full-resolution measured ray-distance map",
"placement": "after the >=2-view support gate: one measured view suffices",
"inputs": "context RGB, measured context depth, context cameras; no query",
},
"anchor_control": "anchor RGB + anchor depth, same full-role context-camera-derived "
"bounds; a single view never reaches the >=2-view lifting support, so an anchor "
"state of C1/C2 carries the single-view depth bypass and learned priors only",
"state": "query-independent; all DEV states sealed before query load; "
">=2 queries/state",
"test_time_input": "RGB+DEPTH+CAMERA for C0/C1; C2 reads RGB+CAMERA only",
"test_time_depth_used": True,
"new_backbone_or_learned_matching": False,
},
)
config = {
"experiment": EXPERIMENT,
"variants": list(VARIANT_SPECS),
"variant_specs": VARIANT_SPECS,
"primary_method": "C1",
"primary_pair": list(PRIMARY_PAIR),
"primary_contrast": "SCALE_GAIN = AbsRel(C0 depth TRAIN24) - AbsRel(C1 depth TRAIN72)",
"secondary_contrast": "DEPTH_AT_SCALE_GAIN = AbsRel(C2 RGB TRAIN72) - AbsRel(C1); "
"descriptive only",
"train_sets": {"TRAIN24": train24, "TRAIN72": train72},
"device": "cpu",
"seeds": SEEDS,
"steps": 6000,
"checkpoint_steps": [100, 200, 300, 500, 750, 1000, 1500, 2000, 3000, 4000, 5000, 6000],
"checkpoint_rationale": "V5 RGB-D DEV curves still improved at 1500-2000 steps; 6000 "
"steps keep 72 scenes from being under-visited, and the V5 schedule is retained",
"learning_rate": 0.001,
"optimizer": "Adam",
"weight_decay": 0,
"lr_schedule": "constant",
"gradient_clip": 1.0,
"batch_scenes": 1,
"batch_rays": 1024,
"precision": "FP32",
"num_threads": 1,
"thread_environment": THREADS,
"cpu_affinity": list(range(8, 24)),
"augmentation": "none",
"image_size": [128, 160],
"train_targets": "TRAIN primary_query2 RGB+ray-distance depth; never carrier input",
"context_input": "context RGB + measured context ray distance + cameras (RGB-D "
"track); query depth never enters construction",
"context_roles": "independent A/B states, equal loss weights",
"sampling": "seeded scene permutation cycled; primary query slot cycles per scene visit; "
"uniform with-replacement rays, identical indices for A/B and all variants",
"initialize": "from scratch; identical per-seed shared parameters for all variants; "
"the depth bypass starts at zero without consuming the RNG",
"parallel_workers": 3,
"execution": "seeds sequential; the C0/C1/C2 runs of one seed concurrently on "
"CPU cores 8-23 (identical contention); no GPU is used or queried (GPU paused by "
"the user); min_free_gpu_mib is unused",
"min_free_gpu_mib": 3072,
"infrastructure_retries": 2,
"infrastructure_failure_policy": "a signal-terminated run, or a run whose log shows a "
"fixed CUDA resource-allocation signature, is moved to audit/failed_attempts with an "
"incident record and rerun from scratch with identical variant/seed/config, at most "
"infrastructure_retries times per run counted across runner invocations; archived "
"checkpoints and DEV curves are never used; any other Python error is never retried; "
"a failed C0/C1 run stops the experiment",
"checkpoint_selection": "independent per variant/seed using the frozen V2 DEV rule; "
"never best seed",
"seed_handling": "all seeds equally weighted within scene; each seed reported",
"statistics": "frozen V2 estimator (geometry_carrier_statistics); its SURFACE_* fields "
"denote the primary C0-C1 contrast, i.e. SCALE in V6",
"dev_reuse": "the 8 DEV scenes were evaluated in V2-V5; V6 is a DEV mechanism "
"diagnostic of training scale, not a qualification round; FRESH-V1 is not used",
"fresh_qualification_included": False,
"writer_updates": False,
"dynamic_ttt_run": False,
}
write_json(root / "training_contract.json", config)
write_json(
root / "loss_contract.json",
{
"C0": "V2 C1 loss: mean_A_B[RGB Charbonnier(eps=.001) + masked depth AbsRel] + "
".1 mean_A_B surface loss",
"C1": "identical to C0",
"C2": "identical to C0 (the frozen V5 C0 recipe also used the V2 C1 surface loss)",
"authority": "mcss.mechanism_pilot.geometry_carrier.training_loss (frozen in V2)",
"v2_loss_contract_sha256": sha(V2 / "loss_contract.json"),
"lambda_surface": 0.1,
"regularization": 0,
"training_track": "RGB-D track: context depth is carrier input for C0/C1 "
"(C2 RGB only); "
"TRAIN query depth is supervision only",
},
)
shutil.copyfile(V2 / "checkpoint_selection_lock.json", root / "checkpoint_selection_lock.json")
write_json(
root / "decision_rules.json",
{
"bootstrap": {
"unit": "physical scene",
"draws": 10000,
"seed": 20260928,
"ci": "percentile95",
},
"SCALE_STATUS": "frozen V2 primary-contrast gate applied to C0-C1: gain>0; CIlo>0; "
">=.75 nonworse; all LOSO>0; positive top1 share<=.5; C1 wrong-scene and shuffle "
"damage CIlo>0; C0/C1 common-mask opacity gate; state audits PASS",
"SCENE_SPECIFICITY_STATUS": "C1 wrong-scene damage CIlo>0 and C1 spatial-shuffle "
"damage CIlo>0 -> SUPPORTED, otherwise NOT_ESTABLISHED",
"STATIC_DEV_STATUS": "frozen V2 static gate for C1",
"DEPTH_AT_SCALE_GAIN": "AbsRel(C2)-AbsRel(C1), descriptive with CI, never a gate",
"GEOMETRY_FREE_REFERENCE": {
"values": reference,
"train_files_sha256": train_files,
"references": list(REFERENCES),
"primary_reference": PRIMARY_REFERENCE,
"readouts": list(READOUTS),
"bootstrap": {"unit": "scene", "draws": 10000, "seed": 20260928},
"labels": "ABOVE (frozen V2 evidence rule) / BELOW (mirror) / "
"NOT_DISTINGUISHABLE per carrier, readout and metric",
"role": "descriptive; never a gate; computed after all states are sealed",
},
"TRAIN_FIT": "last-100-step TRAIN depth AbsRel per variant, descriptive",
"interpretation": {
"A": "SCALE_STATUS=SUPPORTED and C1 RAW AbsRel ABOVE REF_TRAIN_ABSREL_OPTIMAL "
"on the no-hit-excluded scenes (GEOMETRY_FREE_REFERENCE sensitivity)",
"B": "SCALE_GAIN CIlo>0 or C1 ABOVE the reference on the no-hit-excluded "
"scenes, not A",
"C": "otherwise",
},
"fresh_qualification_included": False,
"final_static_status": "NOT_ESTABLISHED",
"dynamic_ttt_next_stage_allowed": False,
},
)
write_json(
root / "audit/environment.json",
{
"python": sys.version,
"torch": torch.__version__,
"cuda": torch.version.cuda,
"gpu": torch.cuda.get_device_name() if torch.cuda.is_available() else None,
"gpu_shared": True,
"packages": {d.metadata["Name"]: d.version for d in importlib.metadata.distributions()},
"commit": subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip(),
},
)
sealed = seal_previous(root)
data_hashes = {}
for r in manifest["scenes"]:
for f in r["frames"]:
for kind in ("rgb", "depth"):
data_hashes[str(Path(f[kind]))] = sha(Path(f[kind]))
write_json(root / "audit/data_hashes.json", data_hashes)
names = (
"scene_split.json",
"frame_role_lock.json",
"training_contract.json",
"architecture_contract.json",
"loss_contract.json",
"checkpoint_selection_lock.json",
"decision_rules.json",
"train_depth_prior.json",
"data_provenance.json",
"PROTOCOL.md",
"audit/data_hashes.json",
"audit/previous_experiment_seal.json",
)
source_paths = sorted(Path("src/mcss").rglob("*.py"))
source_paths += sorted(Path("scripts").glob("*rgbd_scale*.py"))
write_json(
root / "preregistration.json",
{
"status": "FROZEN_BEFORE_FORMAL_TRAINING",
"experiment": EXPERIMENT,
"primary_method": "C1",
"input_sha256": {str((root / n).resolve()): sha(root / n) for n in names},
"source_sha256": {str(p.resolve()): sha(p) for p in source_paths},
"data_sha256": data_hashes,
"fresh_status": "NOT_INCLUDED_DEV_MECHANISM_ROUND",
"formal_training_started": False,
"qualification_opened": False,
},
)
print("FROZEN", counts, "previous_files_sealed", sealed)
if __name__ == "__main__":
p = argparse.ArgumentParser()
p.add_argument("--root", required=True)
a = p.parse_args()
prepare(a.root)