uniqc.algorithms.workflows.vqe_workflow module

Lightweight VQE workflow built on ansatz fragments + pauli_expectation.

Unlike uniqc.algorithms.core.training.vqe_torch, this workflow does not require torch or torchquantum: it uses scipy.optimize for the classical minimisation step and uniqc.simulator for the quantum part.

Use this when you want a zero-extras VQE driver. Use the torch-based version when you want autodiff parameter-shift gradients and PyTorch interop.

class uniqc.algorithms.workflows.vqe_workflow.VQEResult(energy, params, history=<factory>, n_iter=0, success=True, message='')[source]

Bases: object

Outcome of run_vqe_workflow().

Variables:

  • energy (float) – Final (minimum) energy ⟨H⟩.

  • params (numpy.ndarray) – Optimal ansatz parameters (numpy array).

  • history (list[float]) – Per-iteration energies in evaluation order. Useful for convergence plots.

  • n_iter (int) – Number of objective evaluations.

  • success (bool) – Whether the underlying scipy optimiser reported success.

  • message (str) – Optimiser termination message.

Parameters:
energy: float
history: list[float]
message: str = ''
n_iter: int = 0
params: ndarray
success: bool = True
uniqc.algorithms.workflows.vqe_workflow.run_vqe_workflow(hamiltonian, *, n_qubits=None, ansatz=None, depth=1, ansatz_type='hea', ansatz_options=None, init_params=None, shots=None, method='COBYLA', options=None)[source]

Run a scipy-driven VQE on hamiltonian.

Parameters:

  • hamiltonian (Sequence[tuple[str, float]]) – Iterable of (pauli_string, coefficient) pairs. The Pauli string length must match n_qubits.

  • n_qubits (int | None) – Number of qubits. Required when ansatz is None; inferred from the first term’s pauli length otherwise.

  • ansatz (Callable[[ndarray], Circuit] | None) – Optional params -> Circuit builder. If None the workflow uses the ansatz_type with ansatz_options.

  • depth (int) – Layers in the default ansatz. Ignored when ansatz is supplied.

  • ansatz_type (str) – Type of ansatz to use when ansatz is None. Options: "hea" (default), "hva", "uccsd".

  • ansatz_options (dict | None) – Additional options passed to the ansatz builder. For HEA: supports rotation_gates, entangling_gate, topology, custom_edges, backend_info.

  • init_params (ndarray | None) – Optional initial parameter vector. If None a small uniform random vector in [-π/8, π/8] is sampled.

  • shots (int | None) – Shots per Pauli-term expectation. None uses the analytic statevector estimator (recommended for early development).

  • method (str) – scipy.optimize.minimize method. COBYLA and Powell are good gradient-free choices; switch to L-BFGS-B only when you supply a custom analytical gradient via options.

  • options (dict | None) – Optional dict forwarded to scipy.optimize.minimize. Defaults to {"maxiter": 200, "rhobeg": 0.1} for COBYLA.

Returns:

VQEResult with the minimum energy and parameters.

Return type:

VQEResult

Example

>>> # H = -1.0523 ZZ + 0.39793 ZI - 0.39793 IZ + 0.18093 XX
>>> H = [("ZZ", -1.0523), ("ZI", 0.39793),
...      ("IZ", -0.39793), ("XX", 0.18093)]
>>> result = run_vqe_workflow(H, n_qubits=2, depth=2)
>>> result.energy < -1.0
True

With enhanced HEA options: >>> result = run_vqe_workflow( … H, n_qubits=2, depth=2, … ansatz_type=”hea”, … ansatz_options={“rotation_gates”: [“rx”, “ry”], “entangling_gate”: “cz”}, … )

uniqc.algorithms.workflows.vqe_workflow.run_vqe_workflow_example()[source]

Tiny H2-like 2-qubit Hamiltonian, used in tests/docs.

Returns the VQEResult from a cheap analytic-shot run.

Return type:

VQEResult