Minimise the energy of a Pauli Hamiltonian with a hardware-efficient ansatz and compare with the exact ground energy.
Officially provided by KetQat — method by Peruzzo et al. (2014), McClean et al. (2016) and others. KetQat prepares, verifies and maintains this product; it does not claim to have invented the method. Read the origin statement.
Runs the variational quantum eigensolver as a statevector simulation on your machine. The Hamiltonian is the SDK's approximate two-qubit H2 testbed, a transverse-field Ising chain built from its definition, or your own list of Pauli terms. The ansatz is layers of Ry rotations on every qubit, each followed by a CNOT ladder (or no entangling gates, if you choose a product ansatz). Angles are optimised by coordinate descent from seeded random restarts, and the energy is reported against the exact ground energy from diagonalising the Hamiltonian.
The gap to the exact energy is attributed honestly: when a product ansatz faces an entangled ground state the result says the ansatz cannot represent the state, so the gap is a limit of the hypothesis class rather than of the optimiser.
The H2 coefficients are a testbed for the algorithm, not a chemistry result: the result carries a provenance block stating that they land about 6 mHa from the literature total, roughly four times chemical accuracy.
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].
import json
from ketqat_runner import catalog
record = catalog.run("[email protected]", seed=7, hamiltonian="h2-approximate", qubits=2, layers=2)
result = record.result
print(json.dumps({
"status": record.status,
"energy": round(result["energy"], 6),
"exact_ground_energy": round(result["exact_ground_energy"], 6),
"converged": result["gap"] < 1e-8,
"variational_principle_holds": result["variational_principle_holds"],
}))
{
"energy": -1.851199,
"status": "succeeded",
"converged": true,
"exact_ground_energy": -1.851199,
"variational_principle_holds": true
}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 |
|---|---|---|---|---|
| hamiltonian | string | h2-approximate | enum: h2-approximate, transverse-ising, custom | h2-approximate (the SDK's 2-qubit H2/STO-3G-shaped testbed), transverse-ising (H = -J sum Z_i Z_{i+1} - h sum X_i on an open chain), or custom (give terms). |
| qubits | integer | 2 | maximum: 6; minimum: 1 | Number of qubits. Must be 2 for h2-approximate; the chain length for transverse-ising; the Pauli string length for custom. |
| terms | object[] | null | minItems: 1 | For hamiltonian=custom: objects {"coefficient": number, "pauli": string of I/X/Y/Z of length qubits}. null otherwise. |
| ising_coupling | number | null | maximum: 100; minimum: -100 | J for transverse-ising. null means 1.0. Not accepted with other Hamiltonians. |
| ising_field | number | null | maximum: 100; minimum: -100 | h for transverse-ising. null means 1.0. Not accepted with other Hamiltonians. |
| layers | integer | 2 | maximum: 4; minimum: 1 | Ansatz layers; the parameter count is layers x qubits. |
| entangling | boolean | true | — | true adds a CNOT ladder after each Ry layer; false keeps a product-state ansatz. |
| restarts | integer | 12 | maximum: 50; minimum: 1 | Seeded random restarts of the coordinate descent; the best is reported. |
| iterations | integer | 400 | maximum: 2000; minimum: 1 | Maximum coordinate-descent sweeps per restart (it stops early once the step falls below 1e-9). Requests estimated above 30 s are refused with the estimate. |
| Name | Type | Description |
|---|---|---|
| energy | number | Lowest energy found, <psi(theta)|H|psi(theta)> from the state vector. |
| exact_ground_energy | number | E_0 from dense diagonalisation of H, the reference the energy is measured against. |
| gap | number | energy - exact_ground_energy, never negative for a correct implementation (variational principle). |
| ansatz_can_represent_ground_state | boolean | false when a product ansatz faces an entangled ground state; then the gap is a representational limit, as explanation says. |
| parameters | number[] | Optimised Ry angles, layer by layer, qubit by qubit. |
| h2_provenance | object | For h2-approximate: the testbed's discrepancy from the literature energy and the statement that it is not a chemistry result. |
Approximate H2 testbed, 2 layers with CNOT ladder, 12 restarts: VQE reaches -1.851199124 Ha, the exact ground energy from diagonalisation (gap 0 to 12 decimals); the provenance block records that the coefficients land 6.1 mHa from the literature total and are not a chemistry result.
Generated with
{"terms":null,"layers":2,"qubits":2,"restarts":12,"entangling":true,"iterations":400,"hamiltonian":"h2-approximate","ising_field":null,"ising_coupling":null}{
"gap": 0,
"ansatz": {
"form": "layers of Ry(theta) on every qubit, each followed by a CNOT ladder",
"layers": 2,
"entangling": true,
"parameter_count": 4
},
"energy": -1.851199124124,
"execution": "exact statevector energies; ground energy by dense diagonalisation",
"optimizer": {
"method": "coordinate descent with step halving",
"restarts": 12,
"iterations": 400
},
"parameters": [
1.048224798212,
4.712388920822,
0.818481047682,
4.71238900306
],
"explanation": "Converged to the exact ground energy.",
"hamiltonian": {
"kind": "h2-approximate",
"terms": [
{
"pauli": "II",
"coefficient": -0.4804
},
{
"pauli": "ZI",
"coefficient": 0.3435
},
{
"pauli": "IZ",
"coefficient": -0.4347
},
{
"pauli": "ZZ",
"coefficient": 0.5716
},
{
"pauli": "XX",
"coefficient": 0.091
},
{
"pauli": "YY",
"coefficient": 0.091
}
],
"qubits": 2
},
"h2_provenance": {
"note": "Approximate coefficients. The total lands about 6 mHa from the literature value, roughly four times chemical accuracy (0.0016 Ha). Suitable for testing the algorithm; not suitable for reporting a chemistry result. A published energy curve needs coefficients from a verified electronic-structure calculation.",
"validated": false,
"discrepancy_hartree": 0.006069870302,
"total_energy_hartree": -1.131230129698,
"literature_total_hartree": -1.1373,
"within_chemical_accuracy": false,
"nuclear_repulsion_hartree": 0.719968994426
},
"exact_ground_energy": -1.851199124124,
"ground_state_entangled": true,
"variational_principle_holds": true,
"ansatz_can_represent_ground_state": true
}analytic ground energy
The product reaches, to 1e-6, ground energies known in closed form: -sqrt(J^2 + 4h^2) for the two-qubit transverse-field Ising model, -J(n-1) for the n-qubit chain without a field and -nh without coupling, and the exact H2 testbed energy from diagonalisation.
python/tests/test_catalog_products.py::test_vqe_reaches_analytic_ground_energies
variational principle
On random Hermitian Hamiltonians and random custom Pauli Hamiltonians the reported energy is never below the exact ground energy (a theorem, checked as an inequality, not a tolerance), and the reported gap is non-negative.
python/tests/test_catalog_products.py::test_vqe_energy_never_falls_below_the_exact_ground_energy
representability
A product ansatz on the entangled H2 ground state reports a gap above 1e-3 and ansatz_can_represent_ground_state=false even with more restarts and sweeps; on a product ground state it converges exactly.
python/tests/test_catalog_products.py::test_vqe_product_ansatz_reports_a_representational_gap
input validation
Malformed terms, a Hamiltonian/qubit mismatch, Ising parameters with the wrong Hamiltonian and requests above the time ceiling are refused before anything runs.
python/tests/test_catalog_products.py::test_vqe_rejects_bad_hamiltonians_and_oversized_requests
example execution
The example code is executed verbatim in a clean virtual environment with only the algorithms extra installed.
1.0.01 Nov 2026currentShown on this page
Needs SDK 0.3.0 or later with extras: algorithms.
KetQat implementation of published methods
The variational quantum eigensolver was introduced by Peruzzo et al. (2014) and given its general hybrid framework by McClean, Romero, Babbush and Aspuru-Guzik (2016); the hardware-efficient Ry + CNOT-ladder ansatz follows Kandala et al. (2017). KetQat wrote this NumPy statevector implementation (vqe.py), its coordinate-descent optimiser, the Hamiltonian builders, the 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:34 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.