This repository provides the supplementary code and generated experiment artifacts for Q-Residual Physics: Hamiltonian-Structured Quantum Residual Learning for Embodied Dynamics.
Q-Residual Physics (QRP) augments a nominal dynamics model with structured residual modes inspired by Hamiltonian interaction terms. The artifact includes dataset adapters, residual-dynamics models, rollout evaluators, diagnostic experiments, ablation utilities, table/figure generation scripts, and the paper-facing result exports used for review.
The benchmark data are not included in the repository because the raw releases
are large. Reviewers can inspect all generated tables and figures immediately,
run smoke tests without downloading the full benchmark suite, or reproduce the
full pipeline after placing the benchmark files under data/ as described in
docs/benchmark_setup.md.
QRP keeps explicit physics as the nominal predictor and learns only the structured residual needed to correct the remaining dynamics error. The residual layer is conditioned on physics-error features and uses interpretable residual modes as the quantum/circuit bottleneck.
Inputs at time t
+--------------------------------------------------------------------+
| state x_t, action u_t, optional observation o_t |
+--------------------------------------------------------------------+
|
v
+------------------------------+ +----------------------------+
| Context encoder E_phi | | Nominal physics Phi_phys |
| proprioception / contact / | | first-order dynamics |
| object / optional sensors | | x_tilde_{t+1}=Phi(x_t,u_t) |
+------------------------------+ +----------------------------+
| |
+--------------+-------------+
|
v
+--------------------------------------------------------------------+
| Physics-error context e_t |
| [x_t, u_t, x_tilde_{t+1}, constraint, energy, contact, friction, h]|
+--------------------------------------------------------------------+
|
v
+--------------------------------------------------------------------+
| Residual compressor C_psi |
| s_t = C_psi(e_t) |
+--------------------------------------------------------------------+
|
v
+--------------------------------------------------------------------+
| Hamiltonian-structured quantum residual layer |
| |
| residual modes as qubits: |
| contact impulse | friction | slip | compliance | torsion | damping |
| perception error | mass / inertia mismatch |
| |
| G_omega(s_t) emits coefficients: |
| Z_i activation, Z_i Z_j coupling, X_i switching, |
| X_i X_j + Y_i Y_j exchange, sparse Z_i Z_j Z_k interactions |
| |
| Trotterized circuit blocks -> measurements z_t^Q |
+--------------------------------------------------------------------+
|
v
+--------------------------------------------------------------------+
| Lightweight residual decoder D_eta |
| residual correction r_t = D_eta(z_t^Q) |
+--------------------------------------------------------------------+
|
v
+--------------------------------------------------------------------+
| Corrected dynamics prediction |
| x_hat_{t+1} = Integrate(Phi_phys(x_t,u_t), r_t) |
| additive case: x_hat_{t+1} = x_tilde_{t+1} + r_t |
+--------------------------------------------------------------------+
The residual modes correspond to interpretable physical error channels rather than raw state coordinates. Hamiltonian terms restrict interactions to physically meaningful couplings, while the decoder remains lightweight so the main residual representation passes through the structured bottleneck.
QRP-review/
├── README.md # Overview, quickstart, and headline results
├── INSTALL.md # Environment setup and data placement
├── REPRODUCE.md # Step-by-step commands for tables and figures
├── environment.yml # Conda environment specification
├── requirements.txt # Pip dependency list
├── pyproject.toml # Python package metadata and dependencies
├── Makefile # Convenience commands
├── LICENSE
├── src/qrp/ # Core implementation
│ ├── data/ # Dataset loaders and benchmark adapters
│ ├── models/ # Physics, neural, recurrent, graph, and quantum residual models
│ ├── physics/ # Contact, friction, energy, and integration utilities
│ ├── evaluation/ # Metrics, rollout evaluation, OOD/few-shot/transfer utilities
│ ├── experiments/ # Experiment orchestration logic
│ └── reporting/ # Tables, plots, schemas, and paper export utilities
├── scripts/ # Command-line entry points
│ ├── prepare_data.py # Dataset verification and setup checks
│ ├── run_experiment.py # Main dynamics benchmark
│ ├── run_diagnostics.py # OOD and few-shot diagnostics
│ ├── run_contact_diagnostics.py # Event/contact diagnostic evaluation
│ ├── run_transfer_diagnostics.py # Domain-transfer evaluation
│ ├── run_model_ablations.py # Model ablation suite
│ ├── make_tables.py # CSV/LaTeX table generation
│ ├── make_figures.py # Paper figure generation
│ └── make_final_report.py # Consolidated report generation
├── configs/ # Benchmark, model, sweep, and experiment configs
├── experiments/ # Reproduction shell scripts
│ └── reproduce_paper.sh # End-to-end paper pipeline
├── docs/ # Dataset setup, metrics, protocol, and reproducibility notes
├── tests/ # Unit and smoke tests
├── data/ # Lightweight metadata only
└── results/ # Generated paper-facing artifacts
├── tables/ # CSV and LaTeX tables
├── figures/ # PDF figures
├── paper_exports/ # Manuscript-ready table/figure copies
└── reports/ # Final report and reproducibility manifest
See INSTALL.md for detailed setup and REPRODUCE.md for the table/figure
reproduction map.
# 1. Create the environment
conda env create -f environment.yml
conda activate qrp
# 2. Install the local package
pip install -e .
# 3. Verify imports and repository configuration
PYTHONPATH=src python -m qrp.cli sanity
python scripts/sanity_check_repo.py
# 4. Inspect the already-generated paper tables
python scripts/make_final_report.py
# 5. Run a small smoke experiment after data are available
python scripts/run_experiment.py \
--datasets d4rl_hopper_medium \
--methods constant_state,linear_dynamics,mode_residual \
--seeds 0 \
--rank 8 \
--sample-limit 2000 \
--results-dir results/smokeThe repository already contains the generated paper-facing tables and figures
under results/. The smoke command is intended only to verify that the local
environment and a single benchmark file are configured correctly.
See REPRODUCE.md for the complete artifact map. The full experiment pipeline
is exposed through:
bash experiments/reproduce_paper.shThe same pipeline can be run step by step:
python scripts/prepare_data.py --dataset all --verify-only
python scripts/run_experiment.py --datasets all_available --seeds 0,1,2 --rank 8 --sample-limit 0 --results-dir results/full_file_validation --no-readme
python scripts/run_experiment.py --datasets all_available --methods mode_residual --seeds 0,1,2 --rank 4 --sample-limit 0 --results-dir results/rank_ablation/rank4 --no-readme
python scripts/run_experiment.py --datasets all_available --methods mode_residual --seeds 0,1,2 --rank 16 --sample-limit 0 --results-dir results/rank_ablation/rank16 --no-readme
python scripts/make_rank_ablation.py
python scripts/run_diagnostics.py --datasets all_available --seeds 0,1,2 --rank 8 --fewshot-ratios 0.01,0.05,0.10,0.25 --incremental
python scripts/run_contact_diagnostics.py --datasets all_available --seeds 0,1,2 --rank 8 --incremental
python scripts/run_transfer_diagnostics.py --seeds 0,1,2 --rank 8
python scripts/run_model_ablations.py --datasets all_available --seeds 0,1,2 --sample-limit 120000 --incremental
python scripts/make_tables.py
python scripts/make_figures.py
python scripts/make_final_report.pyGenerated artifacts are written to results/tables/, results/figures/, and
results/reports/. Manuscript-ready copies are stored in
results/paper_exports/.
Expected runtimes depend on local data availability and CPU throughput:
| Run mode | Purpose | Approximate runtime |
|---|---|---|
| Import/config checks | Verify package and configs | < 1 minute |
| Single-dataset smoke run | Verify local data and evaluator | < 5 minutes |
| Main dynamics sweep | Full-file transition prediction | 1-3 hours |
| Diagnostics and ablations | OOD, few-shot, contact, transfer, rank/cost studies | Several hours |
The main dynamics table reports physical-scale normalized RMSE. Lower is
better. Gains are relative to the linear_dynamics baseline at the same source
and horizon.
| Source | Method | Datasets | 1-step | 5-step | 10-step | 25-step | 10-step gain | 25-step gain |
|---|---|---|---|---|---|---|---|---|
| d4rl | constant_state | 5 | 0.4809 | 0.7161 | 0.8621 | 1.0911 | -262.9% | -358.8% |
| d4rl | linear_dynamics | 5 | 0.2109 | 0.3355 | 0.4056 | 0.4929 | +0.0% | +0.0% |
| d4rl | mode_residual | 5 | 0.1980 | 0.3057 | 0.3684 | 0.4755 | +8.2% | +3.7% |
| maniskill2 | constant_state | 3 | 0.0152 | 0.0302 | 0.0514 | 0.1021 | -162.2% | -188.3% |
| maniskill2 | linear_dynamics | 3 | 0.0047 | 0.0119 | 0.0197 | 0.0355 | +0.0% | +0.0% |
| maniskill2 | mode_residual | 3 | 0.0042 | 0.0104 | 0.0172 | 0.0339 | +12.7% | +3.9% |
| robomimic | constant_state | 4 | 0.0947 | 0.1428 | 0.1568 | 0.2241 | -83.5% | -151.0% |
| robomimic | linear_dynamics | 4 | 0.0592 | 0.0815 | 0.0861 | 0.1106 | +0.0% | +0.0% |
| robomimic | mode_residual | 4 | 0.0589 | 0.0824 | 0.0945 | 0.1409 | -5.5% | -11.0% |
Additional generated results are provided in:
| Experiment | Table | Figure/report |
|---|---|---|
| Main dynamics prediction | results/tables/main_results.csv |
results/figures/exp01_rollout_horizon_error.pdf |
| Dataset-level dynamics | results/tables/dataset_results.csv |
results/figures/exp02_main_results_heatmap.pdf |
| Event/contact diagnostics | results/tables/contact_results.csv |
results/figures/exp03_contact_slip_dual_axis.pdf |
| OOD diagnostics | results/tables/ood_results.csv |
results/figures/exp05_ood_generalization_heatmap.pdf |
| Few-shot adaptation | results/tables/fewshot_results.csv |
results/figures/exp06_fewshot_adaptation_curve.pdf |
| Domain transfer | results/tables/sim2real_results.csv |
results/figures/exp07_sim2real_dual_axis.pdf |
| Rank and model ablations | results/tables/rank_ablation.csv and ablation CSVs |
results/figures/exp08_hamiltonian_ablation_dumbbell.pdf |
| Compute trade-off | results/tables/compute_cost.csv |
results/figures/exp11_cost_accuracy_scatter.pdf |
The consolidated numerical summary is available at
results/reports/final_experiment_report.md.
Large benchmark files are excluded from this repository. To reproduce training and evaluation runs, place the benchmark assets under:
data/raw/d4rl/
data/raw/robomimic/
data/raw/maniskill2/
data/raw/physion/
data/raw/omnipush/
data/processed/maniskill2_state/
data/splits/
The implemented loaders cover D4RL HDF5 transition files, ManiSkill2 state
demonstrations, and robomimic low-dimensional demonstrations. Physion and
OmniPush metadata are included for benchmark accounting; full reproduction on
those sources requires object-state transition data in the layouts documented
in docs/benchmark_setup.md.
Check the local data layout with:
python scripts/prepare_data.py --dataset all --verify-only| Component | Recommendation | Used for |
|---|---|---|
| CPU | Modern multi-core CPU | All included experiments |
| GPU | Optional CUDA GPU | Optional neural baselines and larger sweeps |
| RAM | 16-32 GB | Full-file sweeps over low-dimensional trajectories |
| Disk | Repository < 100 MB; benchmark data external | Raw benchmark files and generated outputs |
The included residual and quantum-circuit utilities can run on CPU. Runtime is dominated by the number of benchmark files, seeds, rollout horizons, and diagnostic sweeps.
Use these commands to regenerate and validate the paper-facing artifacts:
python scripts/make_tables.py
python scripts/make_figures.py
python scripts/make_final_report.py
python scripts/make_reproducibility_manifest.py
python -m py_compile $(find src scripts -name '*.py' | sort)The reproducibility manifest records the command sequence and expected artifact paths:
results/reports/reproducibility_manifest.md
For questions about the submission, please use the review discussion forum.