Simulate Grover's search on up to 20 qubits and get the exact success probability plus seeded measurement counts.
Officially provided by KetQat — method by Grover (1996), Boyer et al. (1998) and others. KetQat prepares, verifies and maintains this product; it does not claim to have invented the method. Read the origin statement.
Runs Grover's quantum search algorithm as a statevector simulation on your machine. You choose the register size and the marked basis states; the product prepares the uniform superposition, applies the phase oracle and the diffusion operator the requested number of times (by default the textbook optimum floor(pi/4 * sqrt(N/M))), and reads the Born-rule distribution off the final state vector.
It is for students checking the amplitude-amplification picture against a real simulation, and for researchers who want an exact, reproducible baseline (success probability from the state vector, plus seeded shot counts) to compare other implementations against.
This is not the older grover-search runner family in this SDK, which samples shots from the analytic success probability without simulating a circuit.
Installs the KetQat SDK from commit 2cedabbd814f, the exact version whose product definition this page shows. The SDK is not on PyPI yet, so pip install ketqat alone will not work.
pip install "ketqat[algorithms] @ git+https://github.com/ketqat/ketqat-sdk@2cedabbd814fd199b1989c8ceb1e9efa1744c2c0#subdirectory=python"Save it as example.py and run python example.py. Or use the CLI: ketqat catalog run [email protected] --param n_qubits=N_QUBITS --param marked=MARKED.
import json
from ketqat_runner import catalog
record = catalog.run("[email protected]", seed=7, n_qubits=5, marked=[3, 17], shots=1000)
result = record.result
print(json.dumps({
"status": record.status,
"iterations": result["iterations"],
"success_probability": round(result["success_probability"], 6),
"analytic_success_probability": round(result["analytic_success_probability"], 6),
}))
{
"status": "succeeded",
"iterations": 3,
"success_probability": 0.961319,
"analytic_success_probability": 0.961319
}Verified with
ketqat report RUN_ID sends an opt-in usage report: product, version, succeeded/failed, time and SDK version only. It shows you the exact payload first and needs an API token from Settings. Nothing is sent unless you run it.
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
| n_qubits | integer | required | maximum: 20; minimum: 2 | Register size n; the search space has N = 2^n states. Larger requests are refused with the memory they would need. |
| marked | integer[] | required | minItems: 1; itemMinimum: 0; uniqueItems: true | Marked basis states as integers in [0, 2^n - 1]; at least one, all distinct, fewer than 2^n. |
| iterations | integer | null | maximum: 100000; minimum: 0 | Number of Grover iterations k. null uses floor(pi/4 * sqrt(N/M)). |
| shots | integer | 1000 | maximum: 10000000; minimum: 1 | Measurement samples drawn from the final state. |
| Name | Type | Description |
|---|---|---|
| success_probability | number | Sum of |amplitude|^2 over the marked states of the simulated final state vector (exact up to floating point). |
| analytic_success_probability | number | sin^2((2k+1) theta) with sin(theta) = sqrt(M/N), reported beside the simulated value as a cross-check. |
| iterations | integer | Iterations actually applied, and iterations_rule saying whether they were chosen by the user or by the formula. |
| counts | object | Seeded measurement counts, bitstring (most significant qubit first) to count; only non-zero outcomes. |
| observed_success_fraction | number | Fraction of shots that landed on a marked state. |
5 qubits, marked states 3 and 17, 3 iterations (the optimum): the simulated success probability is 0.961319, equal to the analytic value; 955 of 1000 seeded shots hit a marked state.
Generated with
{"shots":1000,"marked":[3,17],"n_qubits":5,"iterations":null}{
"shots": 1000,
"counts": {
"10000": 2,
"10001": 474,
"10010": 4,
"10101": 2,
"11000": 2,
"11001": 1,
"11010": 3,
"11011": 2,
"11100": 1,
"11101": 1,
"11110": 1,
"11111": 2,
"00000": 1,
"00001": 3,
"00010": 2,
"00011": 481,
"00100": 3,
"00110": 2,
"00111": 2,
"01000": 1,
"01001": 1,
"01010": 1,
"01100": 1,
"01101": 1,
"01110": 1,
"01111": 5
},
"marked": [
3,
17
],
"n_qubits": 5,
"iterations": 3,
"iterations_rule": "floor(pi/4*sqrt(N/M))",
"success_probability": 0.9613189697265623,
"observed_success_count": 955,
"observed_success_fraction": 0.955,
"analytic_success_probability": 0.9613189697265625
}analytic agreement
Simulated success probability equals sin^2((2k+1) theta), sin(theta) = sqrt(M/N), to 1e-10 for every n in 2..10, several marked-set sizes M and k from 0 past the optimum.
python/tests/test_catalog_products.py::test_grover_matches_the_analytic_success_probability
operator equivalence
The closed-form diffusion operator equals the gate construction H^n (2|0><0| - I) H^n on random states.
python/tests/test_catalog_products.py::test_grover_diffusion_equals_its_gate_construction
resource guard
Requests above 20 qubits are refused with the state-vector memory they would need.
python/tests/test_catalog_products.py::test_grover_refuses_large_registers_with_a_memory_estimate
example execution
The example code is executed verbatim in a clean virtual environment with only this product's extras installed.
1.0.029 Oct 2026currentShown on this page
Needs SDK 0.3.0 or later with extras: algorithms.
KetQat implementation of published methods
Grover's algorithm was introduced by Lov K. Grover (1996); the multiple-marked-state analysis follows Boyer, Brassard, Hoyer and Tapp (1998). KetQat wrote this NumPy statevector implementation, its validation tests and this catalog entry. KetQat did not invent the method.
Apache-2.0 — see Licensing.
People credited for this product. KetQat publishes and maintains it; contributors are credited for their work and are not sellers.
No usage reports yet
Distinct signed-in accounts that chose to send at least one usage report (ketqat report) for this product in the last 90 days. KetQat staff, test and bot accounts are excluded. Reports are opt-in, so this is not a count of all users.
Computed 10 Nov 2026, 17:24 UTC.
Not yet rated
Be the first to rate this product after you run it.
Mean of visible reviews. Hidden reviews and reviews by KetQat staff, test and bot accounts are excluded. Pro status gives no extra weight.
Sign in to review this product. One review per person; you can edit it later.
No reviews yet.