quantum-gps-navigator 1.0.0

Quantum-Inspired GPS Navigator: directional-diffusion GPU pathfinder using a 4-channel (N/E/S/W) amplitude metaphor. 100% classical.

Quantum-Inspired GPS Navigator

Tagline: Directional-diffusion GPU navigator; 4-channel (N/E/S/W) amplitude metaphor; 100% classical. No qubits, no superposition, no entanglement.

Disclaimer — does NOT use quantum computing. This project is a classical pathfinder on a 2D raster. The name "quantum-inspired" refers only to the 4-channel amplitude metaphor (N/E/S/W directional components with a wave-propagation flavour) used by the directional-diffusion update. There are no qubits, no superposition, no entanglement, and no dependency on any quantum-computing library (Qiskit, Cirq, PennyLane, etc.). The core math is the classical Eikonal equation |grad T| * v = 1, solved with either a GPU shader pass or a reference CPU fast-marching method.

Install

pip install quantum-gps-navigator             # core (NumPy + Pillow)
pip install "quantum-gps-navigator[gpu]"      # + moderngl, glfw
pip install "quantum-gps-navigator[osm]"      # + osmnx
pip install "quantum-gps-navigator[dev]"      # + pytest, build, twine

CLI

qgps info                                     # show version + backend availability
qgps demo --seed 0                            # 64x64 synthetic demo, ASCII route
qgps plan --speed grid.npy --sx 1 --sy 1 \
           --tx 100 --ty 100 --out route.npy  # offline planner on a .npy speed grid
qgps --help

Python API

import numpy as np
from qgps import plan_path

speed = np.ones((128, 128), dtype=np.float32)
route = plan_path(speed, source=(4, 4), target=(120, 120))
print(len(route.path), route.total_time)

How it works

1. Eikonal arrival-time field. Given a local-speed raster v(x, y) and a source cell, we solve |grad T| * v = 1 for the scalar field T(x, y) = minimum travel time from the source.
2. Solvers:
   • src/qgps/reference_eikonal.py - classical Sethian fast-marching on a binary heap (pure NumPy, CPU, no GPU required).
   • src/qgps/gpu_eikonal_solver.py (optional [gpu] extra) - a directional-diffusion GPU pass using a 4-channel (N/E/S/W) amplitude raster. The channel metaphor is wave-inspired; the update is a plain upwind operator.
3. Path extraction. Steepest descent on T from target to source, then reversed.

    source o----->----->----->----->-----o target
             Eikonal T(x,y) field solved in O(N log N) (FMM)
             or O(N) GPU sweeps (directional diffusion)

Graceful fallback

If moderngl / glfw / osmnx are unavailable at import time, the library falls back to the pure-NumPy reference solver and logs a clear message. qgps info prints exactly which optional backends are available.

Tests

pip install -e .[dev]
pytest -v

The test suite runs entirely on CPU. Coverage includes the fast-marching solver against the analytic point-source solution on a 128x128 grid (relative error < 5%), the high-level planner (monotonicity, detours, path length), the HTTP tile cache (stdlib http.server mock), and the CLI.

Layout

src/qgps/
    __init__.py
    reference_eikonal.py   # CPU fast-marching (validation oracle)
    navigator.py           # plan_path, Route
    tile_manager.py        # HTTP tile cache (stdlib urllib)
    cli.py                 # qgps plan / demo / info
tests/
    test_eikonal_correctness.py
    test_navigator.py
    test_tile_manager.py
    test_cli.py

License

Apache-2.0 (c) 2026 Francisco Angulo de Lafuente.

Citation

Angulo de Lafuente, F. (2026). Quantum-Inspired GPS Navigator (v1.0.0).
https://github.com/Agnuxo1/Quantum-GPS-Unified-Navigation-System