SHDG

Stochastic Hamiltonian Dynamics Gradient (SHDG) is a playground for Hamiltonian-inspired optimizers, innovation controllers, and evaluation tools. The repository bundles training loops for image classification, utilities for running parameter sweeps, and standalone scripts for analyzing stochastic dynamics on fixed potentials.

Getting started

1. Create a virtual environment (Python ≥3.10 recommended).
2. Install dependencies:

   pip install -r requirements.txt

3. (Optional) Download datasets such as MNIST or CIFAR-10. The default configurations expect datasets under ./data.

Repository layout

├── aggregate_runs.py       # Aggregate per-run JSON results into CSV/LaTeX summaries
├── eval_fixed_potential.py # Optimizer playground on analytic potentials
├── mcmc_compare.py         # Mini MCMC harness comparing SGHMC/BAOAB variants
├── run_mnist_suite.sh      # Example bash harness over optimizers × hooks
├── scripts/
│   ├── run_many.py         # Launch a config across multiple seeds and summarize
│   └── run_sweep.py        # Grid sweeps driven by YAML definitions
├── configs/
│   ├── default.yaml        # Toy default configuration
│   ├── energy_innov/       # Innovation-hook presets
│   ├── optim/              # Optimizer defaults (e.g., AdamW)
│   ├── sweep/              # Grid definitions consumed by run_sweep.py
│   └── task/               # End-to-end experiment configs (MNIST/CIFAR, etc.)
├── src/
│   ├── data/               # Dataloaders (MNIST, CIFAR, ...)
│   ├── engines/            # Training/evaluation loops
│   ├── hooks/              # Innovation damping controllers
│   ├── models/             # Networks and potential functions
│   ├── optimizers/         # Symplectic, BAOAB, SGHMC implementations
│   ├── trainers/           # Legacy training helpers
│   └── utils/              # Logging, checkpointing, misc utilities
├── train.py                # Main entry point for supervised tasks
└── requirements.txt

Running experiments

Single run

train.py consumes a YAML task configuration followed by optional key=value overrides:

python train.py configs/task/mnist_innov.yaml seed=0 optim.lr=3e-4 \
  innovation.enabled=true log.dir=runs/mnist_demo

The script merges configs/task/... with the base defaults declared inside the YAML. Overrides support nested keys (e.g., task.model_kwargs.dropout=0.1) and list literals (optim.betas=[0.9,0.999]). Checkpoints, TensorBoard logs, and results.json are written to log.dir/run_name (defaults to <task.name>_seed<seed>).

Multiple seeds with summary tables

Use scripts/run_many.py to execute a config across many seeds and emit CSV and LaTeX summaries:

python scripts/run_many.py \
  --cfg configs/task/mnist_innov.yaml \
  --seeds 0 1 2 3 \
  --prefix cls_mnist \
  --outdir out/mnist_demo \
  --over "optim.name=baoab" "optim.lr=3e-4" "innovation.enabled=true"

After running, inspect out/mnist_demo/ for runs.csv and table.tex. The script expects each run directory to contain a results.json produced by train.py.

Grid sweeps

scripts/run_sweep.py loads combinations from a sweep YAML (see configs/sweep/optimizer_debug.yaml) and fans them out to concurrent train.py invocations. Example:

python scripts/run_sweep.py --sweep configs/sweep/optimizer_debug.yaml --parallel 2

Each job receives a unique run_name so the outputs can coexist under runs/<prefix>_*.

MNIST optimizer × hook suite

run_mnist_suite.sh illustrates how to combine the helpers above in Bash. It runs two innovation-hook settings (plain/innov) against the BAOAB and symplectic optimizers, writing aggregated outputs under out/mnist_suite_debug/. Tweak the CFG, CASES, or optimizer override arrays at the top of the script before executing:

./run_mnist_suite.sh

Post-processing experiment logs

aggregate_runs.py scans a directory tree for results.json files and compiles both per-run and grouped statistics. Typical usage:

python aggregate_runs.py --root runs/mnist_suite \
  --group optim.name innovation.enabled task.model \
  --metrics test_acc_last test_acc_best \
  --outdir out/mnist_suite

The script writes runs.csv, summary.csv, and table.tex into the requested output directory.

Dynamics playgrounds

Two standalone scripts explore stochastic dynamics without the full training stack:

• mcmc_compare.py runs multi-step integrators against analytic targets (e.g., Banana2D, von Mises–Fisher). Enable plotting with --plot and optionally save traces via --trace_csv. The option --noise_scale controls injection of gradient measurement noise error.

  python mcmc_compare.py --target banana --opt baoab --steps 2000 --m 10 \
    --lr 0.1 --gamma 0.9 --beta_inv 1.0 --plot --save_plot visualizations/example_mcmc.png --noise_scale 0.0

• eval_fixed_potential.py measures optimizer behavior on fixed potentials (Lasso, Ackley, Rosenbrock) with optional innovation hooks for BAOAB and symplectic integrators. Use CLI flags to select the potential, optimizer, and plotting options.

Configuration tips

• Task YAMLs in configs/task/ define dataloaders, model builders, engines, and optimizer defaults for end-to-end experiments (e.g., mnist_innov.yaml).
• Sweep YAMLs under configs/sweep/ set up grid searches consumed by scripts/run_sweep.py.
• Innovation hook presets live in configs/energy_innov/hooks/ and can be referenced from task configs via innovation.class_path and innovation.kwargs.

For more details, browse the code under src/, especially the optimizers and hooks that implement the CSHGD dynamics.