UlukaDev/qare-bitnet-lora

QARE — Quantum Algorithm Recommendation Engine (BitNet b1.58 2B + LoRA)

A LoRA adapter for microsoft/bitnet-b1.58-2B-4T-bf16 that recommends a quantum, hybrid, or classical algorithm for a computational problem given hardware constraints, and explains the choice in a fixed format.

Research prototype. Read the Limitations section before using or citing this. Reported accuracy is not a measure of quantum-computing correctness.

⚠️ This model is not standalone

The adapter was trained on prompts that already contain a precomputed resource-requirements block. Prompted without it, the model fabricates requirements — measured: it claimed Grover's Algorithm needs ~2057 qubits for a 20-bit search space (the correct value is 21), then reasoned validly from its own false premise to the wrong recommendation.

QARE is therefore a hybrid system:

Component	Role
knowledge_base.py	Deterministic resource estimation + feasibility — makes the decision
BitNet + this LoRA	Ranking, reasoning, natural-language explanation — narrates the decision

Always use qare_engine.py (included in this repo). It builds the required prompt. Prompting the weights directly is a misuse.

Usage

# files ship with this repo
from qare_engine import QAREEngine

eng = QAREEngine(
    base="microsoft/bitnet-b1.58-2B-4T-bf16",
    adapter="USERNAME/qare-bitnet-lora",
)

out = eng.recommend(
    problem_type="unstructured_search",
    size=20,                  # log2 of the database size
    available_qubits=1000,
    noise="none",
    max_depth=100000,
    hardware="simulator",
    desired_accuracy=0.9,
)
print(out["text"])          # model's explanation
print(out["kb_reference"])  # deterministic KB answer (audit trail)

The engine constructs prompts of this form:

Problem: unstructured search on a 20-item database (log2) instance.
Hardware: simulator
Available qubits: 1000
Noise level: none
Max circuit depth: 100000
Desired accuracy: 0.9

Computed resource requirements (from a resource estimator):
  Grover's Algorithm: needs 21 qubits, depth 805 -> FITS
  Quantum Walk Search: needs 10 qubits, depth 121 -> FITS
  Classical algorithm: 0 qubits, no circuit -> always available

Output format: Primary Algorithm · Confidence Score · Quantum Practical · Reasoning · Alternative Algorithms (ranked) · Estimated Hardware Requirements · Expected Advantages · Expected Limitations · References.

Coverage: Shor, Grover, QAOA, VQE, QPE, HHL, Quantum Walk, Quantum Annealing, Quantum Kernel/VQC, Gaussian Boson Sampling, Trotterization, and classical fallbacks across 11 problem types and 7 hardware families.

Training

Base	microsoft/bitnet-b1.58-2B-4T-bf16 (BF16 master weights)
Method	LoRA r=16, α=32, dropout 0.05, on q/k/v/o/gate/up/down projections
Trainable	21.6M / 2.43B (0.89%)
Data	6,000 synthetic examples (4,796 train / 594 val / 610 test), stratified
Schedule	3 epochs, 900 steps, effective batch 16, lr 1e-4 cosine, maxlen 768
Precision	bf16 (required) — fp16 overflows BitLinear → loss=0, grad_norm=nan
Loss	Completion-only masking (loss on the answer, not the templated prompt)
Hardware	~26 min on a single A100

Dataset

No public problem→quantum-algorithm recommendation dataset exists. Data is synthetic, generated by sampling problem/hardware configurations and labeling them with a deterministic rule-based knowledge base encoding standard complexity and NISQ-era hardware facts (Shor 1994; Grover 1996; Farhi et al. 2014; Peruzzo et al. 2014; Harrow–Hassidim–Lloyd 2009; Preskill 2018; Nielsen & Chuang). No copyrighted text is reproduced — only structured facts. ~60% of labels are "use a classical algorithm," which reflects genuine NISQ-era practicality.

Evaluation — read this carefully

Top-1 accuracy on 30 held-out test examples, vs the untrained base model:

Prompt variant	Zero-shot	Fine-tuned	Δ	McNemar p	95% CI
v1 — no computed requirements	0.233	0.133	−0.10	0.51	[−0.30, +0.10]
v3 — requirements + FITS/BLOCKED verdict	0.700	1.000	+0.30	0.0039	[+0.13, +0.47]

v3 fixed 9 examples and broke 0. The improvement is statistically significant.

🚨 The headline number is inflated by label leakage

The v3 prompt includes the knowledge base's own feasibility verdict (-> FITS / -> BLOCKED). That is the decision. The task partly collapses to "pick the first item marked FITS," solvable without any quantum knowledge — which is exactly why the zero-shot score jumped from 0.233 to 0.700 for a model that knows nothing about QARE.

Do not read 1.00 as quantum-algorithm competence. A cleaner ablation (numbers supplied, verdict withheld, forcing the model to compare rather than derive) is the correct next experiment and has not been run.

The interesting finding

Training loss reached 0.09 while test top-1 was 0.133 — near-perfect loss alongside near-total task failure. Two causes, both instructive:

1. Loss originally included the highly templated prompt, so it was dominated by trivially predictable tokens (fixed via completion-only masking).
2. The model learned the form of technical reasoning long before the content — it produced correctly-structured justifications built on fabricated numbers.

Takeaway: a 2B instruction-tuned model can learn a technical schema without learning the underlying quantitative constraints. Low loss on templated output can mask complete failure. Inspecting raw generations caught what the metric hid.

Limitations

• Not standalone — requires qare_engine.py; otherwise it invents requirements.
• Leaked evaluation — the 1.00 reflects a partly-given answer (see above).
• Circular ground truth — test labels come from the same KB as training data. This measures learning the KB, not objective correctness. A real accuracy claim needs an expert-reviewed test set.
• Small eval — n=30 (BitNet generation in transformers is slow). Wide CIs.
• Order-of-magnitude KB — qubit/depth formulas are approximations, not compiler-exact. Swap in Qiskit / Azure QRE for hardened estimates.
• Not ternary at runtime — this is the BF16 master-weights path, a dense ~2.4B model. transformers has no optimized BitNet kernels; 1.58-bit efficiency requires bitnet.cpp with the packed repo.
• Not hardware-validated — no recommendation here has been checked against a real quantum device. Do not use for research or procurement decisions.

Intended use

Research and educational demonstration of (a) instruction-tuning a 1.58-bit model with LoRA, and (b) hybrid symbolic + LM system design where a deterministic engine owns correctness and the LM owns explanation.

Out of scope: production quantum-algorithm selection, hardware procurement, or any decision where a wrong recommendation carries cost.

Reproducing

Full pipeline (data generation → training → evaluation → significance testing → inference) is in the project's all-in-one Colab notebook.

Citation

@software{qare_bitnet_2026,
  title  = {QARE: A Quantum Algorithm Recommendation Engine via LoRA
            Fine-Tuning of BitNet b1.58},
  year   = {2026},
  note   = {Research prototype. Reported accuracy is affected by
            evaluation label leakage; see model card.}
}

License

MIT (inherited from microsoft/bitnet-b1.58-2B-4T).