{"id":30616478,"url":"https://github.com/ghost---shadow/sudoku-backprop-nmr","last_synced_at":"2026-06-20T01:31:57.732Z","repository":{"id":310671275,"uuid":"1040708526","full_name":"Ghost---Shadow/sudoku-backprop-nmr","owner":"Ghost---Shadow","description":"Solving SuDoKu with backprop and take an NMR of it while at it","archived":false,"fork":false,"pushed_at":"2025-08-25T08:01:21.000Z","size":2034,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-30T09:41:36.327Z","etag":null,"topics":["differentiable-programming","differentiable-simulations","nmr-spectroscopy","nuclear-magnetic-resonance","sudoku-solver"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ghost---Shadow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-19T11:44:26.000Z","updated_at":"2025-08-25T08:01:24.000Z","dependencies_parsed_at":"2025-08-19T15:38:20.806Z","dependency_job_id":"c87dcc33-84e9-4f1f-8395-dc418231e882","html_url":"https://github.com/Ghost---Shadow/sudoku-backprop-nmr","commit_stats":null,"previous_names":["ghost---shadow/sudoku-backprop-nmr"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Ghost---Shadow/sudoku-backprop-nmr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ghost---Shadow%2Fsudoku-backprop-nmr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ghost---Shadow%2Fsudoku-backprop-nmr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ghost---Shadow%2Fsudoku-backprop-nmr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ghost---Shadow%2Fsudoku-backprop-nmr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ghost---Shadow","download_url":"https://codeload.github.com/Ghost---Shadow/sudoku-backprop-nmr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ghost---Shadow%2Fsudoku-backprop-nmr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34554511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["differentiable-programming","differentiable-simulations","nmr-spectroscopy","nuclear-magnetic-resonance","sudoku-solver"],"created_at":"2025-08-30T09:40:47.824Z","updated_at":"2026-06-20T01:31:57.708Z","avatar_url":"https://github.com/Ghost---Shadow.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [Sudoku NMR Spectroscopy 🧲](https://claude.ai/share/21cf5d2d-c45d-4e27-9aaa-6b82c3f739b7)\n\n\u003e Neural optimization meets nuclear magnetic resonance: Solving constraint satisfaction problems through the lens of quantum relaxation dynamics.\n\n## Overview\n\nThis project demonstrates a novel approach to Sudoku solving using neural optimization with a unique twist - interpreting the solving process as a **Nuclear Magnetic Resonance (NMR) experiment**. By treating unknown cells as \"nuclear spins\" and optimization as \"magnetic relaxation,\" we can visualize and analyze the solving dynamics through Free Induction Decay (FID) signals and frequency spectra.\n\n## Key Innovation\n\n- **🧲 Bistable Loss Function**: Creates energy minima at 0 and 1, mimicking magnetic field alignment\n- **📡 FID Signal Generation**: Real-time monitoring of \"transverse magnetization\" during optimization  \n- **🔬 Spectral Analysis**: FFT-based frequency domain analysis reveals optimization characteristics\n- **⚡ Vectorized Constraints**: Efficient exclusion loss implementation for Sudoku rules\n\n## Files\n\n- `backprop_solve.py` - Original solver with bistable + exclusion loss functions\n- `backprop_solve_softmax.py` - Simplified softmax-only version (combines both loss functions)\n- `sudoku_nmr_analysis.png` - Generated spectroscopy plots showing FID decay and frequency spectrum\n\n## Physics-Optimization Analogy\n\n| NMR Concept | Sudoku Implementation | Purpose |\n|-------------|----------------------|---------|\n| Nuclear spins | Cell probability distributions | Individual quantum states |\n| Magnetic field (B₀) | Bistable loss `x²(x-1)²` | Drive toward binary states |\n| RF pulse | Uniform initialization | Excitation from equilibrium |\n| T₁ relaxation | Loss minimization | Energy dissipation |\n| T₂ relaxation | Probability sharpening | Decoherence/decision making |\n| FID signal | Uncertainty measure | Transverse magnetization |\n| Frequency spectrum | Optimization dynamics | Characteristic time scales |\n\n## Installation\n\n```bash\n# Clone repository\ngit clone \u003crepository-url\u003e\ncd sudoku-nmr\n\n# Install dependencies\npip install torch numpy matplotlib\n```\n\n## Usage\n\n**Original Version (Bistable + Exclusion):**\n```bash\npython backprop_solve.py\n```\n\n**Simplified Softmax Version:**\n```bash\npython backprop_solve_softmax.py\n```\n\nBoth scripts will:\n1. 🧲 Initialize the \"NMR spectrometer\" \n2. 📡 Apply initial \"RF pulse\" (uniform probability distribution)\n3. 🔬 Record FID signals during optimization\n4. 📊 Generate spectroscopic analysis plots\n5. 💾 Save results to `sudoku_nmr_analysis.png`\n\n## Algorithm Details\n\n### Neural Architecture\n```\nGrid: 9×9×9 tensor (position × position × number_probability)\n├── Known cells: Fixed one-hot vectors\n├── Unknown cells: Learnable probability distributions  \n└── Gradient masking: Only unknown cells participate in optimization\n```\n\n### Loss Functions\n\n#### Original Approach (`backprop_solve.py`)\n\n**Bistable Loss** (Magnetic Field)\n```python\ndef bistable_loss(x):\n    return (x² * (x-1)²).mean()\n```\n\n**Exclusion Loss** (Spin Coupling)\n```python\n# Vectorized constraint enforcement\nrow_loss = Σ(Σ(probs[row, :, number]) - 1)²\ncol_loss = Σ(Σ(probs[:, col, number]) - 1)²  \nbox_loss = Σ(Σ(probs[box, number]) - 1)²\n```\n\n#### Softmax Approach (`backprop_solve_softmax.py`)\n\n**Combined Softmax Loss** (Unified Constraints)\n```python\ndef exclusion_loss(grid_logits):\n    # Softmax inherently combines bistable + exclusion behavior:\n    # - Entropy minimization → drives toward peaked states (bistable effect)\n    # - Normalization per constraint group → ensures sum=1 (exclusion effect)\n    \n    row_entropy = entropy(softmax(grid_logits, dim=1))\n    col_entropy = entropy(softmax(grid_logits, dim=0)) \n    box_entropy = entropy(softmax(box_logits, dim=box_dim))\n    \n    return row_entropy + col_entropy + box_entropy  # Always \u003e= 0\n```\n\n### FID Signal Calculation\n```python\n# Uncertainty as transverse magnetization\nuncertainty = (1.0 - max_probs) / (1.0 - 1/9)\nphases = (preferred_numbers / 9.0) * 2π\n\n# Complex FID signal\nreal = uncertainty * cos(phases)\nimag = uncertainty * sin(phases)\nmagnitude = √(real² + imag²)\n```\n\n## Example Results\n\n### Spectroscopic Analysis\n![Sudoku NMR Analysis](sudoku_nmr_analysis.png)\n\n**Key Observations:**\n- **Fast T₂ relaxation**: Solution found at epoch 1\n- **Clean exponential decay**: High-quality optimization landscape  \n- **Dominant DC component**: Efficient energy dissipation\n- **Critically damped dynamics**: No overshoot or oscillations\n\n### Performance Metrics\n```\n🎯 Solution found: Epoch 1\n📈 Initial FID magnitude: 0.45\n📉 Final FID magnitude: 0.0001\n🔄 Decay ratio: 0.0002\n📊 Peak frequency: 0.0 cycles/epoch\n```\n\n## Advanced Features\n\n### Customizable Parameters\n```python\n# Optimization settings\nlr = 1.0              # \"Magnetic field strength\"\nbistable_weight = 1.0  # B₀ field intensity\nexclusion_weight = 0.1 # Spin coupling strength\n\n# NMR simulation\nnum_epochs = 1000      # Acquisition time\nfid_sampling = 1       # Sampling rate\n```\n\n### Multiple Puzzle Analysis\nEach Sudoku puzzle exhibits unique **spectral fingerprints** based on:\n- Initial constraint density\n- Symmetry properties  \n- Solution pathway complexity\n- Constraint interaction patterns\n\n## Scientific Insights\n\n1. **Neural optimization naturally exhibits relaxation dynamics** similar to quantum systems\n2. **Constraint satisfaction can be viewed as magnetic resonance experiments**\n3. **Different puzzles show unique spectral signatures** revealing their structural properties\n4. **FID analysis provides insight into optimization landscape quality**\n5. **Learning rate controls relaxation time scales** like magnetic field strength\n\n## Applications\n\n- **🧩 Constraint Satisfaction**: General CSP solving with physical intuition\n- **🔬 Optimization Analysis**: Understanding convergence through spectral properties\n- **📡 Neural Dynamics**: Studying training dynamics as physical processes\n- **🎯 Hyperparameter Tuning**: Using relaxation times to guide parameter selection\n\n## Future Directions\n\n- **Multi-pulse sequences**: Implementing spin echo and inversion recovery\n- **2D NMR spectroscopy**: Cross-correlation analysis between constraints\n- **Relaxometry**: Systematic study of T₁/T₂ times vs puzzle complexity\n- **Chemical shift analysis**: Investigating constraint \"environments\"\n\n## Theory\n\nThe fundamental insight is that neural optimization of discrete constraint problems naturally exhibits quantum relaxation dynamics. \n\n**Original Approach**: The bistable loss creates potential wells analogous to nuclear spin states, while constraint coupling mimics magnetic field interactions.\n\n**Softmax Approach**: Softmax naturally combines both effects - entropy minimization drives toward peaked states (bistable effect) while normalization per constraint group ensures sum-to-1 constraints (exclusion effect). This unified approach is mathematically cleaner and naturally bounded at zero.\n\nBoth approaches allow us to:\n\n1. **Visualize optimization** as physical relaxation processes\n2. **Analyze convergence** through established NMR theory\n3. **Understand landscapes** via spectroscopic signatures\n4. **Design better solvers** inspired by magnetic resonance techniques\n\n## Citation\n\n```bibtex\n@misc{sudoku_nmr_2025,\n  title={Sudoku NMR Spectroscopy: Neural Optimization Through Quantum Relaxation Dynamics},\n  author={[Souradeep Nanda]},\n  year={2025},\n  note={GitHub repository demonstrating constraint satisfaction via magnetic resonance analogy}\n}\n```\n\n## License\n\nMIT License - Feel free to explore the magnetic properties of your favorite puzzles! 🧲\n\n---\n\n*\"Every constraint satisfaction problem has its own magnetic personality - the resonance frequency tells the story of how information flows through the solution space.\"*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fghost---shadow%2Fsudoku-backprop-nmr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fghost---shadow%2Fsudoku-backprop-nmr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fghost---shadow%2Fsudoku-backprop-nmr/lists"}