| # Quantum Utilities |
|
|
| A collection of helper functions and common tools used across the Quantum Navigation stack. |
|
|
| ## Modules |
|
|
| ### `paths.py` |
| QUBO index decoding shared by every solver: `decode_position(idx, problem)` reverses |
| the flat variable index into `(row, col, t, robot_num)` (or a node id for graph |
| problems), and `merge_paths()` stitches consecutive windowed-solve segments into one |
| path. See `BaseSolver.decode_path()` for the main caller. |
|
|
| ### `coordinates.py` |
| Conversion between Spooky's native matrix `(row, col)` convention and robotics/ |
| Cartesian `(x, y)` Y-up convention. The core (`map.py`, `pathFormulation.py`, every |
| builder/solver) always works in matrix indices — that never changes. Callers that |
| want cartesian in/out use this at two places: |
|
|
| - `RobotConfig.coordinate_format` (`"matrix"` or `"cartesian"`, per-robot) — calls |
| `to_matrix_rc` once on ingest (`resolve_coordinates`) and `to_robotics_xy` on every |
| read (`format_position`). This is what `/v1/plan`'s `coordinate_format` field and |
| `qubo_cli.py --coordinate-format` are backed by. |
| - `quantum/visualizer.py`'s `convention` param (`"matrix"` or `"robotics"`) — same |
| idea, purely for how a plot's axes are drawn; obstacles and paths get the identical |
| conversion so the rendered picture never becomes inconsistent with itself. |
|
|
| Maps themselves are the one place this *isn't* a runtime choice — a `.h5`/YAML map |
| has no live `coordinate_format` attribute, since it's a baked array, not something |
| reformatted on every read. Authoring a map in cartesian is a one-time, one-directional |
| re-indexing done at generation time instead: see `coordinate_format: cartesian` in |
| `quantum/maps/template.yaml` and `yaml2HDF5.flip_map_config_to_matrix()`. |
|
|
| Call the four functions here (`to_robotics_xy` / `to_matrix_rc` / `path_to_robotics_xy` |
| / `path_to_matrix_rc`) directly for anything outside those two paths — e.g. converting |
| a plain path list before handing it to an external robotics stack. |
|
|
| ### `validation.py` |
| `is_valid_move()` checks whether a move between two positions is adjacent given the |
| problem's grid/graph; used by solvers' post-processing to detect and truncate invalid |
| paths. |
|
|
| ### `logger.py` |
| `VerboseLogger` — a global singleton with levels 0–3 (Silent/Minimal/Standard/Debug). |
| Call `set_verbose_level(n)` once at startup, then `get_logger()` anywhere to log at the |
| current level without threading a logger instance through every call. |
|
|
| ## Usage |
|
|
| These utilities are primarily for internal use by the `builder` and `solver` modules |
| but can be imported for custom extensions. |
|
|
| ```python |
| from quantum.utils.coordinates import to_robotics_xy |
| |
| # Convert a native (row, col) cell to robotics (x, y) for a 5-row grid |
| x, y = to_robotics_xy(row=0, col=2, num_rows=5) |
| ``` |
|
|
