A quantum-inspired geometric transformation toolkit that applies Hamiltonian time evolution to classical datasets.
Quantum Decision Flow applies small quantum circuits as dynamical systems: classical points are encoded into two-qubit quantum states, evolved under a chosen Hamiltonian, and decoded back into deformed coordinates via expectation values. The result is a controllable family of topology-aware dataset deformations parameterized by evolution time t and Hamiltonian type. Different Hamiltonians produce distinct deformation signatures and topology-preservation statistics, enabling “dynamics-as-augmentation” for geometric learning tasks.
quantum-decision-flow/
├── src/
│ ├── __init__.py # Package exports and version
│ ├── deformation.py # Core quantum deformation engine
│ │ ├── HamiltonianType # Enum: ZZ_X, HEISENBERG, ISING, XXZ
│ │ ├── create_hamiltonian() # Hamiltonian factory
│ │ ├── make_expectation_circuit() # Circuit factory (fixes H parameter bug)
│ │ ├── t2_expectations() # Quantum expectation values
│ │ ├── xy_to_angles() # Cartesian → spherical encoding
│ │ ├── deform_points() # Main deformation function
│ │ ├── compute_deformation_field() # Vector field visualization
│ │ └── estimate_topology_preservation() # k-NN metric
│ ├── generator.py # Dataset generation
│ │ ├── DatasetType # Enum: MOONS, CIRCLES, SPIRALS, CONCENTRIC_MOONS
│ │ ├── QuantumMoonsConfig # Configuration dataclass
│ │ ├── generate_classical_dataset()
│ │ ├── generate_quantum_deformed_moons()
│ │ ├── save_dataset()
│ │ └── load_dataset()
│ └── visualization.py # Plotting utilities
│ ├── plot_moons_grid()
│ ├── plot_deformation_field()
│ ├── plot_deformation_comparison()
│ ├── plot_statistics()
│ └── plot_topology_preservation()
├── tests/
│ ├── __init__.py
│ ├── test_deformation.py # 28 unit tests
│ ├── test_generator.py # 18 unit tests
│ └── test_visualization.py # 8 unit tests
├── notebooks/
│ └── quantum-decision-flow.ipynb
├── requirements.txt # Pinned dependencies
├── README.md # This file
├── CHANGELOG.md # Version history and migration guide
├── PHYSICS_NOTES.md # Theoretical background and experimental results
├── CORRECTIONS.md # Original bug fixes documentation
├── QUICK_REFERENCE.md # API cheatsheet
├── run_comparison.py # Hamiltonian comparison experiment (v2.1)
├── run_spiral_viz.py # Spiral + Heisenberg visualization script
├── test_periodicity.py # Extended periodicity hypothesis test
└── test_corrections.py # Legacy validation script
git clone https://github.com/christopher-altman/quantum-decision-flow.git
cd quantum-decision-flow
pip install -r requirements.txtNote: Use python3 to avoid NumPy/matplotlib version conflicts.
from src.generator import QuantumMoonsConfig, DatasetType, generate_quantum_deformed_moons
from src.deformation import HamiltonianType
from src.visualization import plot_moons_grid
import matplotlib.pyplot as plt
# Generate spiral data with Heisenberg dynamics
cfg = QuantumMoonsConfig(
n_samples=400,
dataset_type=DatasetType.SPIRALS,
hamiltonian_type=HamiltonianType.HEISENBERG,
t_values=(0.0, 0.5, 1.0, 2.0, 3.0, 5.0)
)
X_base, y, X_t, metrics = generate_quantum_deformed_moons(cfg, compute_metrics=True)
# Visualize
fig = plot_moons_grid(X_base, y, X_t)
plt.savefig("output.png", dpi=300)| Type | Formula | Character |
|---|---|---|
ZZ_X |
Z₀Z₁ + X₀ | Non-integrable, Rabi oscillations |
HEISENBERG |
X₀X₁ + Y₀Y₁ + Z₀Z₁ | Integrable, SU(2) symmetric |
ISING_TRANSVERSE |
Z₀Z₁ + hX₀ + hX₁ | Phase transition at h≈1 |
XXZ |
X₀X₁ + Y₀Y₁ + ΔZ₀Z₁ | Tunable anisotropy |
| Type | Description |
|---|---|
MOONS |
Two interleaving half-circles |
CIRCLES |
Concentric circles |
SPIRALS |
Interleaving Archimedean spirals |
CONCENTRIC_MOONS |
Multiple nested moon pairs |
Quantify how deformation affects local neighborhood structure:
from src.deformation import estimate_topology_preservation
score = estimate_topology_preservation(X_original, X_deformed, k=5)
# Returns 0-1: 1.0 = perfect preservationDifferent Hamiltonians produce measurably different topology preservation patterns:
| Hamiltonian | Mean | Std | Behavior |
|---|---|---|---|
| ZZ+X (ZZ_X) | 0.817 | 0.034 | Higher variance, distinct phase behavior |
| Heisenberg (HEISENBERG) | 0.828 | 0.025 | More stable; near-zero correlation with ZZ+X (ZZ_X) |
Correlation between Hamiltonians: -0.064 → effectively uncorrelated dynamics.
See PHYSICS_NOTES.md for detailed analysis.
The deformation rule above is applied pointwise to a two-spiral dataset as time evolution progresses.
Quantum deformation of a two-spiral dataset under Heisenberg time evolution. Panels show the induced coordinate deformation as t increases; deformation remains structured and largely topology-preserving across the sweep.
python3 -m pytest tests/ -v
# 54 tests, 100% pass ratepython3 run_comparison.pyOutputs topology preservation scores for ZZ+X vs Heisenberg across t ∈ [0.5, 5.0].
- Python 3.10+
- PennyLane 0.36-0.39
- NumPy <2.0
- Matplotlib, scikit-learn, scipy
- v2.1.0: Fixed Hamiltonian parameter bug (circuit factory pattern)
- v2.0.0: Multiple Hamiltonians, dataset types, topology metrics
- v1.0.0: Initial release
-
C. Altman, J. Pykacz & R. Zapatrin, “Superpositional Quantum Network Topologies,” International Journal of Theoretical Physics 43, 2029–2041 (2004). DOI: 10.1023/B:IJTP.0000049008.51567.ec · arXiv: q-bio/0311016
-
C. Altman & R. Zapatrin, “Backpropagation in Adaptive Quantum Networks,” International Journal of Theoretical Physics 49, 2991–2997 (2010).
DOI: 10.1007/s10773-009-0103-1 · arXiv: 0903.4416
If you use or build on this work, please cite:
Quantum Decision Flow 2.1
@software{quantum_decision_flow_2_1,
author = {Altman, Christopher},
title = {Quantum Decision Flow 2.1},
year = {2025},
url = {https://github.com/christopher-altman/quantum-decision-flow}
}MIT License. See LICENSE for details.
- Website: christopheraltman.com
- Research portfolio: https://lab.christopheraltman.com/
- Portfolio mirror: https://christopher-altman.github.io/
- GitHub: github.com/christopher-altman
- Google Scholar: scholar.google.com/citations?user=tvwpCcgAAAAJ
- Email: [email protected]
Christopher Altman (2025)