README.md

---
license: mit
base_model: microsoft/bitnet-b1.58-2B-4T-bf16
tags:
  - quantum-computing
  - bitnet
  - lora
  - peft
  - algorithm-recommendation
  - research-prototype
library_name: peft
pipeline_tag: text-generation
---

# 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

```python
# 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`](https://github.com/microsoft/BitNet) 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

```bibtex
@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`).