feat(qiskit): add calibration-ranked initial_layout for packed jobs

[MatthewPeng57]

Closes #17

Summary

Adds a best_qubits(backend, n) helper and a new initial_layout option (supporting None, "auto", or list[int]) to qiskit_solver.solver_kwargs. Pinning the packed N-qubit circuit to the top-N best-calibrated qubits recovers parallel_qubits=1 fidelity at identical QPU cost.

Diff: 3 files · +215 / −3

Motivation

On real and fake IBM backends, per-qubit readout error varies by up to ~23× across the chip. The transpiler's default layout for packed parallel_qubits=N jobs uses physical qubits 0..N-1, which picks up several poorly-calibrated qubits. Because rel MSE ∝ σ², a 6× higher mean noise compounds to ~36× higher aggregate error.

Approach

best_qubits(backend, n) scores each qubit and returns the n lowest:

score(q) = readout_error(q) + sx_err(q) + 1e-4 / max(T2_μs(q), 1)

• Readout error dominates the score
• sx_err breaks ties between comparably-calibrated qubits
• Short T2 adds a small penalty

The new initial_layout kwarg is threaded through generate_preset_pass_manager(initial_layout=...) in both the serial and _qiskit_run_parallel paths.

Backwards compatibility

Fully back-compat:

• The default initial_layout=None reproduces prior transpiler behaviour exactly.
• best_qubits returns [] when backend.properties() is unavailable, so "auto" falls back to the default cleanly.

Empirical validation

200 independent single-qubit pz-encoding circuits, parallel_qubits=20, shots=1024, FakeSherbrooke:

Layout	rel MSE vs. noiseless
parallel_qubits=1 (qubit 0)	0.134 %
naive packed (0..19)	5.218 %
best_qubits(backend, 20)	0.127 %

Reproducer: stand-alone script hosted as a [gist](https://gist.github.com/MatthewPeng57/4c09a4fd39244ff62c8306fe6a6f96ed) to keep this PR focused on the library change.

Files changed

File	Change
src/qkan/solver/qiskit_solver.py	best_qubits + initial_layout plumbing through the config and both transpiler paths
src/qkan/solver/__init__.py	Export best_qubits
docs/solver_guide.rst	New "Qubit-calibration layout" section with the empirical table and usage examples

Testing

The repo has no existing test suite, so validation is via:

1. Reproducer gist (linked above) — run locally on FakeSherbrooke to reproduce the empirical table.
2. Smoke checks — ast.parse + import qkan.solver.best_qubits pass locally.
3. Manual exercise of initial_layout={None, "auto", [...]} paths on FakeSherbrooke via a trained QKAN forecasting model (rel MSE numbers above).

[MatthewPeng57]

@codex