paramham

paramham is a research codebase and publication artifact repository for studying implicit differentiation (ID) versus black-box finite differences (FD) in bilevel optimization of parametrized Max-Cut Hamiltonians.

This repository is intentionally trimmed to the final paper-facing experiment suite:

• exactly 8 public experiments
• one clean output tree under output/exp01 to output/exp08
• cache-backed rerender support under output/cache
• a single standard runner interface through paramham-reproduce

pip install -e ".[dev]"

Run from the repository root:

make test
paramham-reproduce all
paramham-reproduce rerender
make final

paramham-reproduce is the canonical suite runner. The Makefile is now a thin wrapper around the same target registry, so make final and make exp03 stay in sync with the Python runner automatically.

The standard environment is handled for both interfaces (PYTHONPATH=src, MPLCONFIGDIR=/tmp/mpl).

All final figures use the shared helper in experiments/plot_style.py.

• fixed publication width: 5.7295 in (0.98\textwidth in the thesis)
• TeX serif typography with 10 pt base font and 11 pt axis labels
• white figure backgrounds
• exact PDF saving without bbox_inches='tight'

Exp 2 is the canonical layout reference for the rest of the suite. The other experiments reuse the same physical sizing rules, footer-legend mechanism, and panel geometry conventions.

There are no legacy wrapper scripts in the public repo surface.

Unless an experiment sweeps over that variable, the final paper runs use:

• budget_evals = 2000
• kind/family = periodic
• periodic_K = 6
• n = 12
• p_edge = 0.45
• lam_min = -5.0
• lam_max = 5.0
• lam0 = 0.8
• graph_seed = 7

Experiment-specific sweep settings are documented in docs/experiments.md.

Versioned paper artifacts live in:

• output/exp01 to output/exp08
• output/cache/exp02 to output/cache/exp08

Each experiment output folder contains:

• final figure PDFs
• CSV and TeX exports where applicable
• SUMMARY.txt

• Experiment Reference
• Reproducibility Guide
• Appendix Reproduction Note

MIT