Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.haiqu.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Variational optimization with Haiqu SDK

Use haiqu.variational_optimization() to minimize the expectation value of an observable for a parameterized ansatz circuit.
1

Define the variational problem

from qiskit.circuit.library import EfficientSU2
from qiskit.quantum_info import SparsePauliOp
from haiqu.sdk.qml import VariationalProblem

#Build a parameterized QuantumCircuit (ansatz)
num_qubits = 3
ansatz = EfficientSU2(num_qubits=num_qubits, reps=1)

#Define the cost observable as SparsePauliOp
observable = SparsePauliOp.from_list([("Z" * num_qubits, 1.0)])

# Wrap both in VariationalProblem
problem = VariationalProblem(ansatz, observable)
VariationalProblem requires a parameterized ansatz circuit and a SparsePauliOp observable.
2

Configure optimizer and submit the job

from haiqu.sdk import haiqu
from haiqu.sdk.qml import NFTOptimizerOptions

optimizer_options = NFTOptimizerOptions(
    maxiter=100,
    maxfev=2048,
    reset_interval=32,
    randomized_order=False,
)

job = haiqu.variational_optimization(
    problem=problem,
    device_id="aer_simulator",
    shots=1000,
    seed=42,
    optimizer_options=optimizer_options,
    use_mitigation=False,
    use_session=False,
)
3

Track progress and fetch results

job.progress()
result = job.result()

print("Minimum loss:", result.min_loss)
print("Optimal parameters:", result.optimal_parameters)
print("Iterations:", len(result.loss_history))
job.result() returns a VariationalResult with min_loss, optimal_parameters, and loss_history.

​
API details

The variational optimisation function is defined as: 
haiqu.variational_optimization(
    problem,
    shots=1000,
    device=None,
    device_id=None,
    options=None,
    initial_parameters=None,
    seed=None,
    optimizer_options=None,
    use_mitigation=False,
    use_session=False,
)
ArgumentDescription
problemVariationalProblem(ansatz, observable)
device / device_idTarget backend. At least one must be provided.
shotsNumber of shots per circuit evaluation.
seedReproducible random initialization in [-0.1π, 0.1π].
initial_parametersExplicit initial values (length must match ansatz parameters).
optimizer_optionsOptimizer configuration, typically NFTOptimizerOptions(...).
use_mitigationEnables mitigation pipeline in backend execution.
use_sessionEnables Qiskit Runtime Session mode.

​
Optimizer details

Haiqu uses the NFT optimizer by default for variational optimization. NFT, short for Nakanishi-Fujii-Todo, is a gradient-free optimizer designed for parameterized quantum circuits. Instead of estimating a full gradient, NFT updates circuit parameters sequentially. For a common class of ansatz circuits, the cost function as a function of one parameter has a simple trigonometric form, so each parameter update can be minimized efficiently from a small number of cost evaluations. This makes NFT a good default choice for noisy variational workloads:
  • It is gradient-free, so it avoids the high measurement cost of full gradient estimation.
  • It is efficient compared with many general-purpose gradient-free optimizers.
  • Recent scaling studies also rank NFT among the more noise-resilient classical optimizers, while showing that stochastic noise can still create serious scalability challenges for large variational optimization problems; see Scalability challenges in variational quantum optimization under stochastic noise.

​
Requirements and limitations

NFT assumes the variational problem satisfies the following preconditions:
  • Independent parameters: each ansatz parameter should be independent. Reusing the same parameter across multiple rotation gates is not supported by the standard NFT update rule.
  • Supported gate structure: the parameterized circuit should be composed of fixed unitary gates and rotation gates of the form R_j(theta_j) = exp(-i * theta_j * A_j / 2), where A_j^2 = I.
  • Simple expectation-value cost: the objective should be a weighted sum of expectation values, L(theta) = Σ_k w_k <phi_k|U†(theta) H_k U(theta)|phi_k>.
NFT can improve optimizer robustness, but it does not remove the fundamental sampling and noise-scaling challenges of variational quantum algorithms.