5@brief Runs all PQ-WB-KEM experiments in sequence for reproducibility.
8@section run_all_output Output Files
9- `results/experiment_summary.json` - Aggregate run manifest listing every experiment,
10 its output JSON, and its
pass/fail status.
12@section run_all_usage Usage
17@note A missing experiment script
is a hard error,
not a silent skip: the manifest
and
18exit code report exactly which producers ran. Deterministic (seeded) experiments
19regenerate byte-identical outputs; wall-clock
and native-benchmark experiments are
20machine-dependent
and flagged
as such. If liboqs-python
is absent, the native
21ML-KEM-768 baseline
is recorded
as an explicit skip (a host prerequisite,
not a
22deterministic experiment) so the seeded experiments still report success; running
23baseline_benchmark.py on its own still exits non-zero.
28This software
is provided
for academic
and research purposes.
29See LICENSE file
for details.
36from datetime import datetime
37from pathlib import Path
40def get_project_root() -> Path:
42 @brief Return the project root directory.
43 @return Path to the repository root.
45 return Path(__file__).parent.parent.parent
50sys.path.insert(0, str(Path(__file__).parent))
51from wallclock_ci
import detect_env
53WALLCLOCK_OUTPUT = f
"wallclock_statistics_{detect_env()}.json"
61 "baseline_benchmark.py",
62 "baseline_benchmark.json",
63 "ML-KEM-768 reference baseline (liboqs)",
67 "whitebox_reference.py",
68 "whitebox_reference.json",
69 "Base-multiply table footprints + NTT correctness",
73 "whitebox_encoded.py",
74 "whitebox_encoded.json",
75 "Encoding sublayer + encoding-unaware recovery",
79 "share_statistics.py",
80 "share_statistics.json",
81 "Three-share masking uniformity (chi-square)",
86 "dca_simulation.json",
87 "Differential computation analysis resistance",
91 "algebraic_attack_analysis.py",
92 "algebraic_attack_analysis.json",
93 "Algebraic attack + full ML-KEM-768 module recovery",
97 "overhead_calculation.py",
98 "overhead_calculation.json",
99 "White-box vs reference overhead projection",
103 "scaling_analysis.py",
104 "scaling_analysis.json",
105 "ML-KEM-512/768/1024 scaling projections",
109 "entry_determinacy.py",
110 "entry_determinacy.json",
111 "Entry-determinacy dichotomy (d, M*, PRF control)",
115 "table_extraction_witness.py",
116 "table_extraction_witness.json",
117 "Extraction witness on the repo's own builders",
121 "encoding_layer_entropy.py",
122 "encoding_layer_entropy.json",
123 "Encoding sublayer: storage vs entropy",
127 "concrete_security_bounds.py",
128 "concrete_security_bounds.json",
129 "DCA estimate plus the core byte-read footprint",
133 "obfuscation_storage.py",
134 "obfuscation_storage.json",
135 "Shuffle + masking storage; deployment total = core + KB",
141 "Wall-clock overhead mean +/- CI (per environment)",
150LIBOQS_MISSING_EXIT_CODE = 3
155 @brief Run a Python script
as a subprocess.
156 @param script_path Path to the script to execute.
157 @param description Human-readable label
for logging.
158 @return The subprocess exit code (0 on success).
161 print(f
"RUNNING: {description}")
162 print(f
"Script: {os.path.basename(script_path)}")
164 result = subprocess.run([sys.executable, script_path], cwd=
get_project_root())
165 label =
"SUCCESS" if result.returncode == 0
else f
"EXIT {result.returncode}"
166 print(f
"\n[{label}] {description}")
167 return result.returncode
172 @brief Run every experiment
and write the JSON summary.
173 @return 0
if all experiments passed, 1 otherwise.
176 results_dir = project_root / "results"
177 code_dir = project_root /
"code" /
"python"
178 results_dir.mkdir(exist_ok=
True)
181 print(
"PQ-WB-KEM: Reproducible Experiments (White-Box ML-KEM-768)")
182 print(
"Paper: MDPI Mathematics")
184 print(f
"Project root: {project_root}")
185 print(f
"Started: {datetime.now()}")
188 "project":
"PQ-WB-KEM",
189 "paper":
"MDPI Mathematics",
194 for script, output, description, machine_dependent
in EXPERIMENTS:
195 script_path = code_dir / script
196 if not script_path.exists():
197 raise FileNotFoundError(
198 f
"Experiment producer missing: {script_path}. run_all.py does not "
199 f
"silently skip experiments; every cited result must have a committed "
200 f
"producer. Restore {script} or remove it from EXPERIMENTS."
204 if script ==
"baseline_benchmark.py" and returncode == LIBOQS_MISSING_EXIT_CODE:
211 f
"\n[SKIPPED] {description}: liboqs-python not installed; native "
212 f
"baseline omitted (deterministic experiments unaffected)."
214 summary[
"experiments"].append(
219 "machine_dependent": machine_dependent,
222 "skip_reason":
"liboqs-python not installed; native ML-KEM-768 "
223 "baseline unavailable on this host",
229 all_success = all_success
and ok
230 summary[
"experiments"].append(
235 "machine_dependent": machine_dependent,
237 "status":
"passed" if ok
else "failed",
241 print(
"\n" +
"=" * 70)
242 print(
"EXPERIMENT SUMMARY")
244 tag_by_status = {
"passed":
"PASS",
"failed":
"FAIL",
"skipped":
"SKIP"}
245 for exp
in summary[
"experiments"]:
246 tag = tag_by_status[exp[
"status"]]
247 flag =
" (machine-dependent)" if exp[
"machine_dependent"]
else ""
248 print(f
" [{tag}] {exp['name']}{flag}")
252 summary[
"all_success"] = all_success
253 with open(results_dir /
"experiment_summary.json",
"w")
as f:
254 json.dump(summary, f, indent=2)
256 print(f
"\nCompleted: {datetime.now()}")
257 print(f
"Results saved to: {results_dir}")
259 print(
"\n[ALL EXPERIMENTS PASSED]")
261 print(
"\n[SOME EXPERIMENTS FAILED] -- see per-experiment status above.")
262 return 0
if all_success
else 1
265if __name__ ==
"__main__":
main()
Run every experiment and write the JSON summary.
int run_python_script(str script_path, str description)
Run a Python script as a subprocess.
Path get_project_root()
Return the project root directory.