Problem Formulations

The public problem type is qiskit_addon_opt_mapper.problems.OptimizationProblem. Pass an unconstrained binary polynomial problem to haiqu.build_lr_qaoa_circuit, optionally haiqu.state_compression, then haiqu.run and haiqu.postprocess. Both quadratic QUBO and native higher-order HUBO objectives are supported. Solvers always minimize; a maximize OptimizationProblem is converted internally, and returned postprocess costs use the original objective of the found bitstring. Every OptimizationProblem uses the polynomial_problem payload, regardless of objective degree. CPLEX LP is used only when callers pass the deprecated Haiqu QUBO class. haiqu.solve_qubo remains as a deprecated convenience wrapper around the modular path. Constrained applications must be penalty-folded first:

from qiskit_addon_opt_mapper.applications import NumberPartition
from haiqu.sdk.optimization import is_constrained, to_unconstrained_problem

op = NumberPartition([1, 2, 3]).to_optimization_problem()
if is_constrained(op):
    op = to_unconstrained_problem(op)
circuit = haiqu.build_lr_qaoa_circuit(op)
job = haiqu.run(circuit, shots=1000)
costs, counts = haiqu.postprocess(counts=job.result()[0], problem=op)

Native higher-order objectives can be built directly:

from qiskit_addon_opt_mapper.problems import OptimizationProblem

hubo = OptimizationProblem("cubic")
hubo.binary_var_list(3)
hubo.minimize(higher_order={3: {(0, 1, 2): -1.0}})
circuit = haiqu.build_lr_qaoa_circuit(hubo)

haiqu.sdk.optimization.QUBO and community qiskit-optimization types (QuadraticProgram, from_docplex_mp from that package) are deprecated and will be removed in a future release. Public combinatorial-optimization intake around OptimizationProblem. Haiqu accepts unconstrained binary OptimizationProblem instances of any polynomial degree (QUBO or native HUBO). Supported OptimizationProblem inputs use the polynomial_problem payload. Only the deprecated Haiqu QUBO compatibility surface uses the legacy CPLEX LP wire.

haiqu.sdk.optimization.problem.from_hamiltonian(H, offset=0.0)

Create an unconstrained quadratic OptimizationProblem from a 2-local Ising Hamiltonian. Converts spin variables

s_i \in \{-1,+1\}

to binary

x_i \in \{0,1\}

via

s_i = 1 - 2 x_i

. Higher-order Hamiltonians are refused: reduce the objective to QUBO first (that reduction adds extra variables). This helper reconstructs only quadratic objectives.

Parameters:
- H (SparsePauliOp) — Diagonal Ising Hamiltonian (I/Z/ZZ terms only).
- offset (float) — Constant added to the objective. Defaults to 0.0.
Returns: Unconstrained quadratic OptimizationProblem ready for haiqu.build_lr_qaoa_circuit, haiqu.run, and haiqu.postprocess.

Raises:
- TypeError — If H is not a SparsePauliOp.
- ValueError — If H contains X/Y, complex coefficients, or Pauli weight greater than 2.

Return type: OptimizationProblem

haiqu.sdk.optimization.problem.has_higher_order(op)

True if op.objective.higher_order contains any terms.

Parameters: op (Any)
Return type: bool

haiqu.sdk.optimization.problem.is_constrained(op)

True if linear, quadratic, or higher-order constraints are present on op.

Parameters: op (Any)
Return type: bool

haiqu.sdk.optimization.problem.max_pauli_weight(hamiltonian)

Max number of non-I Paulis in any term (0 if empty).

Parameters: hamiltonian (SparsePauliOp)
Return type: int

haiqu.sdk.optimization.problem.to_unconstrained_problem(op, *, penalty=None)

Fold constraints into penalties and return an unconstrained OptimizationProblem. Uses opt-mapper OptimizationProblemToQubo. The returned objective is a penalized proxy of the original constrained problem, not the same objective. Feasibility checking stays classical / application-specific. penalty: : * None (default) — opt-mapper chooses its default penalty scale.

float — forwarded to OptimizationProblemToQubo(penalty=...).

Parameters:
- op (OptimizationProblem)
- penalty (float | None)
Return type: OptimizationProblem

haiqu.sdk.optimization.problem.uses_polynomial_wire(problem)

True for supported OptimizationProblem inputs, regardless of degree.

Parameters: problem (Any)
Return type: bool

haiqu.sdk.optimization.problem.validate_optimization_problem(op)

Validate an unconstrained binary OptimizationProblem for Haiqu solvers. Accepts quadratic QUBO and native higher-order (HUBO) objectives. Optional helper: haiqu.build_lr_qaoa_circuit and haiqu.postprocess already run this validation, so callers can pass an unconstrained OptimizationProblem directly. Constrained applications must be penalty-folded with to_unconstrained_problem first.

Parameters: op (OptimizationProblem) — Unconstrained binary OptimizationProblem of any polynomial degree.

Raises:
- TypeError — If op is not an OptimizationProblem.
- ValueError — If the problem has constraints or non-binary variables.

Return type: None

class haiqu.sdk.optimization.qubo.QUBO

Deprecated adapter for quadratic unconstrained binary optimization (QUBO) problems. The public problem type is qiskit_addon_opt_mapper.problems.OptimizationProblem. Pass that object to haiqu.build_lr_qaoa_circuit, optional haiqu.state_compression, haiqu.run, and haiqu.postprocess; it uses the polynomial_problem payload. This deprecated class remains as a thin adapter that serializes itself to the legacy LP compatibility wire. Historical constructors (all deprecated):

From a Docplex model / CPLEX file
From an Ising-like Hamiltonian (SparsePauliOp)
From a community qiskit_optimization.QuadraticProgram
From an official OptimizationProblem (from_optimization_problem)

cost(bitstring)

Compute the QUBO objective for a given bitstring. Uses the formula:

f(x) = c + a^T x + \sum_{i<j} Q_{ij} x_i x_j

where

x_i \in \{0, 1\}

are binary variables. Note on Qiskit’s Quadratic Coefficient Storage: : Qiskit’s QuadraticExpression stores coefficients in upper-triangle format only:

f(x) = c + \sum_i a_i x_i + \sum_i \sum_{j>i} Q_{ij} x_i x_j

Only $Q_{ij}$ for $i < j$ are stored (via to_dict())
Each stored $Q_{ij}$ is the full coefficient (not doubled)
Example: If to_dict() returns {(0,1): 0.5}, the contribution is 0.5 * x_0 * x_1

Important: When you pass a symmetric matrix to minimize(quadratic=[[...]]), Qiskit sums symmetric entries. For instance, [[0,1],[1,0]] stores Q[0,1]=2.

Parameters: bitstring (str) — Bitstring in Qiskit convention (little-endian, rightmost bit = qubit 0).
Returns: The objective value for the given bitstring.
Return type: float

NOTE

Bitstrings use Qiskit convention: rightmost bit = qubit 0. Example: “101” means x0=1, x1=0, x2=1 (for var_names=[‘x0’,‘x1’,‘x2’]).

classmethod from_docplex(docplex_model)

Create from a DOcplex model (docplex.mp.model.Model).

Deprecated

Deprecated since version 1.6.0: The method haiqu.sdk.optimization.qubo.QUBO.from_docplex() is deprecated as of haiqu-sdk 1.6.0. It will be removed no sooner than 3 months after the release date. Instead, use an unconstrained quadratic qiskit_addon_opt_mapper.problems.OptimizationProblem with haiqu.build_lr_qaoa_circuit, optional haiqu.state_compression, haiqu.run, and haiqu.postprocess.

Return type: QUBO

classmethod from_file(path)

Load a problem from a CPLEX/LP file and convert it to QUBO form.

Deprecated

Deprecated since version 1.6.0: The method haiqu.sdk.optimization.qubo.QUBO.from_file() is deprecated as of haiqu-sdk 1.6.0. It will be removed no sooner than 3 months after the release date. Instead, use an unconstrained quadratic qiskit_addon_opt_mapper.problems.OptimizationProblem with haiqu.build_lr_qaoa_circuit, optional haiqu.state_compression, haiqu.run, and haiqu.postprocess.

Parameters: path (str)
Return type: QUBO

classmethod from_hamiltonian(H, offset=0.0)

Create QUBO from an Ising Hamiltonian represented as a Pauli operator. Higher-order Hamiltonians must be reduced to QUBO first (extra variables); this path does not perform that reduction. This method converts an Ising model Hamiltonian (with spin variables sᵢ ∈ ) to QUBO formulation (with binary variables xᵢ ∈ ) using the mapping sᵢ = 1 - 2·xᵢ. Input Format: : The Hamiltonian is given as a SparsePauliOp containing Pauli Z operators:

Single Z terms (e.g., ‘Z’, ‘IZI’) represent local fields hᵢ
Products of Zs (e.g., ‘ZZ’, ‘IZZI’) represent couplings Jᵢⱼ
Pauli X or Y operators are not supported (pure Ising model)

Conversion Formula: : Ising Hamiltonian: H = Σ hᵢ·sᵢ + Σ Jᵢⱼ·sᵢ·sⱼ + offset (sᵢ ∈ )
The conversion uses the mapping: sᵢ = 1 - 2·xᵢ where xᵢ ∈
This transforms to QUBO: f(x) = c + Σ aᵢ·xᵢ + Σ Qᵢⱼ·xᵢ·xⱼ
Detailed Conversion for Each Term Type:

Local field term hᵢ·sᵢ (where sᵢ ∈ ):

Substitute sᵢ = 1 - 2·xᵢ: : = hᵢ·(1 - 2·xᵢ) = hᵢ - 2·hᵢ·xᵢ
Contributes: : - Constant: +hᵢ

Linear xᵢ: -2·hᵢ

Coupling term Jᵢⱼ·sᵢ·sⱼ:

Substitute sᵢ = 1-2·xᵢ and sⱼ = 1-2·xⱼ: : = Jᵢⱼ·(1 - 2·xᵢ)·(1 - 2·xⱼ) = Jᵢⱼ·[1 - 2·xᵢ - 2·xⱼ + 4·xᵢ·xⱼ]
Contributes: : - Constant: +Jᵢⱼ

Linear xᵢ: -2·Jᵢⱼ
Linear xⱼ: -2·Jᵢⱼ
Quadratic xᵢ·xⱼ: +4·Jᵢⱼ

Important: When multiple Pauli terms are present, their contributions are summed. For example, if both hᵢ·Zᵢ and Jᵢⱼ·Zᵢ·Zⱼ affect variable xᵢ, the linear coefficients add: aᵢ = -2·hᵢ + (-2·Jᵢⱼ) = -2·(hᵢ + Jᵢⱼ).
Note on Normalization: Qiskit’s from_ising() stores linear terms as diagonal entries in the quadratic matrix (e.g., -2·hᵢ becomes Q[i,i] = -2·hᵢ). These diagonal terms are automatically normalized to linear coefficients by from_quadratic_program(), since for binary variables xᵢ² = xᵢ. Implementation: : Uses Qiskit’s from_ising() function to perform the conversion, which handles the Pauli operator algebra and coefficient transformations automatically. The resulting QuadraticProgram is then normalized via from_quadratic_program().

Deprecated

Deprecated since version 1.6.0: The method haiqu.sdk.optimization.qubo.QUBO.from_hamiltonian() is deprecated as of haiqu-sdk 1.6.0. It will be removed no sooner than 3 months after the release date. Instead, use an unconstrained quadratic qiskit_addon_opt_mapper.problems.OptimizationProblem with haiqu.build_lr_qaoa_circuit, optional haiqu.state_compression, haiqu.run, and haiqu.postprocess.

Parameters:
- H (SparsePauliOp) — Ising Hamiltonian as a SparsePauliOp (must contain only Z operators)
- offset (float) — Additional constant offset to add to the Hamiltonian. Defaults to 0.0.
Returns: QUBO instance representing the same optimization problem

Raises:
- TypeError — If H is not a SparsePauliOp
- ValueError — If H contains Pauli X or Y operators, or any term acts on more than 2 qubits

Return type: QUBO

Example

>>> from qiskit.quantum_info import SparsePauliOp
>>>
>>> # Create simple Ising Hamiltonian: H = 1.0·Z₀·Z₁ (coupling only)
>>> # This represents interaction between spins: J₀₁·s₀·s₁ with J₀₁ = 1.0
>>> H = SparsePauliOp.from_list([('ZZ', 1.0)])
>>> qubo = QUBO.from_hamiltonian(H, offset=0.0)
>>>
>>> # The conversion applies: J₀₁·s₀·s₁ = J₀₁·(1-2x₀)·(1-2x₁)
>>> # Expanding: J₀₁ - 2·J₀₁·x₀ - 2·J₀₁·x₁ + 4·J₀₁·x₀·x₁
>>> # With J₀₁ = 1.0:
>>> #   Constant: +1.0
>>> #   Linear x₀: -2.0 (normalized from diagonal Q[0,0])
>>> #   Linear x₁: -2.0 (normalized from diagonal Q[1,1])
>>> #   Quadratic x₀·x₁: +4.0
>>>
>>> print(qubo._qp.objective.constant)  # 1.0
>>> print(qubo._qp.objective.linear.to_dict())  # {0: -2.0, 1: -2.0}
>>> print(qubo._qp.objective.quadratic.to_dict())  # {(0,1): 4.0}

classmethod from_lp_string(lp_content)

Deserialize QUBO from LP file format string.

Deprecated

Deprecated since version 1.6.0: The method haiqu.sdk.optimization.qubo.QUBO.from_lp_string() is deprecated as of haiqu-sdk 1.6.0. It will be removed no sooner than 3 months after the release date. Instead, use an unconstrained quadratic qiskit_addon_opt_mapper.problems.OptimizationProblem with haiqu.build_lr_qaoa_circuit, optional haiqu.state_compression, haiqu.run, and haiqu.postprocess.

Parameters: lp_content (str) — LP file content as string
Returns: QUBO instance
Return type: QUBO

classmethod from_optimization_problem(op)

Create a QUBO adapter from an official OptimizationProblem. Constrained problems must be penalty-folded with to_unconstrained_problem first. Higher-order objectives must be reduced to QUBO first (extra variables); this path does not perform that reduction.

Deprecated

Deprecated since version 1.6.0: The method haiqu.sdk.optimization.qubo.QUBO.from_optimization_problem() is deprecated as of haiqu-sdk 1.6.0. It will be removed no sooner than 3 months after the release date. Instead, use an unconstrained quadratic qiskit_addon_opt_mapper.problems.OptimizationProblem with haiqu.build_lr_qaoa_circuit, optional haiqu.state_compression, haiqu.run, and haiqu.postprocess.

Parameters: op (OptimizationProblem)
Return type: QUBO

classmethod from_quadratic_program(qp)

Create a QUBO from a community qiskit_optimization.QuadraticProgram. Note on Qiskit’s Quadratic Coefficient Storage: : Qiskit’s QuadraticExpression internally stores quadratic coefficients in upper-triangle format only (i.e., only

Q_{ij}

for

i < j

).
The objective function form is:

f(x) = c + \sum_i a_i x_i + \sum_i \sum_{j>i} Q_{ij} x_i x_j

Important Details:

When you call qp.objective.quadratic.to_dict(), it returns only the upper triangle
Each stored $Q_{ij}$ represents the full coefficient of $x_i x_j$ (not doubled)
When setting coefficients via qp.objective.quadratic[(i,j)], indices are normalized to (min(i,j), max(i,j)), so setting Q[1,0] overwrites Q[0,1]
When passing a full symmetric matrix to minimize(quadratic=[[...]]), Qiskit sums the symmetric entries (e.g., Q[0,1]=1 and Q[1,0]=1 → stored as Q[0,1]=2)

All QUBO methods in this class properly handle Qiskit’s upper-triangle representation.

Deprecated

Deprecated since version 1.6.0: The method haiqu.sdk.optimization.qubo.QUBO.from_quadratic_program() is deprecated as of haiqu-sdk 1.6.0. It will be removed no sooner than 3 months after the release date. Instead, use an unconstrained quadratic qiskit_addon_opt_mapper.problems.OptimizationProblem with haiqu.build_lr_qaoa_circuit, optional haiqu.state_compression, haiqu.run, and haiqu.postprocess.

Parameters: qp (QuadraticProgram)
Return type: QUBO

to_file(path)

Export the QUBO as a CPLEX LP file.

Parameters: path (str)
Return type: str

to_hamiltonian()

Convert QUBO to an Ising Hamiltonian represented as Pauli operators. This method performs the inverse transformation of from_hamiltonian(), converting from QUBO formulation (binary variables xᵢ ∈ ) back to Ising model (spin variables sᵢ ∈ ) using the inverse mapping xᵢ = (1 - sᵢ)/2. Output Format: : Returns a tuple (H, offset) where:

H: SparsePauliOp containing the Ising Hamiltonian as Pauli Z operators
offset: Float constant offset term

Conversion Formula (QUBO → Ising): : QUBO objective: f(x) = c + Σ aᵢ·xᵢ + Σ Qᵢⱼ·xᵢ·xⱼ (xᵢ ∈ )
Using inverse substitution xᵢ = (1 - sᵢ)/2, this becomes:
Ising Hamiltonian expectation: ⟨H⟩ = Σ hᵢ·sᵢ + Σ Jᵢⱼ·sᵢ·sⱼ + offset (sᵢ ∈ )
Where the coefficients are derived by reversing the Ising→QUBO transformation. Implementation: : Uses Qiskit’s QuadraticProgram.to_ising() method to perform the conversion, which handles the variable substitution and Pauli operator construction automatically.

Returns: A tuple containing: : - SparsePauliOp: The Ising Hamiltonian with Pauli Z operators
- float: The constant offset term
Return type: Tuple[SparsePauliOp, float]

Example

>>> # Create QUBO with linear and quadratic terms
>>> from qiskit_optimization import QuadraticProgram
>>> qp = QuadraticProgram()
>>> qp.binary_var('x0')
>>> qp.binary_var('x1')
>>> qp.minimize(linear={'x0': 0.5}, quadratic={('x0', 'x1'): 1.0})
>>> qubo = QUBO.from_quadratic_program(qp)
>>> H, offset = qubo.to_hamiltonian()
>>> # H is a SparsePauliOp like: 0.5*Z_0 + 1.0*Z_0*Z_1
>>> # offset is the constant term
>>> # Can now use with Qiskit quantum algorithms:
>>> from qiskit_algorithms import QAOA
>>> qaoa = QAOA(sampler=sampler, optimizer=optimizer)
>>> result = qaoa.compute_minimum_eigenvalue(H)

to_lp_string()

Serialize QUBO to LP file format string.

Returns: LP file content as string
Return type: str

Core platform functions

Data loading

Middleware

Circuit Execution

Optimization

Variational Algorithms

SKQD

Problem Formulations

haiqu.sdk.optimization.problem.from_hamiltonian(H, offset=0.0)

haiqu.sdk.optimization.problem.has_higher_order(op)

haiqu.sdk.optimization.problem.is_constrained(op)

haiqu.sdk.optimization.problem.max_pauli_weight(hamiltonian)

haiqu.sdk.optimization.problem.to_unconstrained_problem(op, *, penalty=None)

haiqu.sdk.optimization.problem.uses_polynomial_wire(problem)

haiqu.sdk.optimization.problem.validate_optimization_problem(op)

class haiqu.sdk.optimization.qubo.QUBO

cost(bitstring)

NOTE

classmethod from_docplex(docplex_model)

Deprecated

classmethod from_file(path)

Deprecated

classmethod from_hamiltonian(H, offset=0.0)

Deprecated

Example

classmethod from_lp_string(lp_content)

Deprecated

classmethod from_optimization_problem(op)

Deprecated

classmethod from_quadratic_program(qp)

Deprecated

to_file(path)

to_hamiltonian()

Example

SEE ALSO

to_lp_string()

​haiqu.sdk.optimization.problem.from_hamiltonian(H, offset=0.0)

​haiqu.sdk.optimization.problem.has_higher_order(op)

​haiqu.sdk.optimization.problem.is_constrained(op)

​haiqu.sdk.optimization.problem.max_pauli_weight(hamiltonian)

​haiqu.sdk.optimization.problem.to_unconstrained_problem(op, *, penalty=None)

​haiqu.sdk.optimization.problem.uses_polynomial_wire(problem)

​haiqu.sdk.optimization.problem.validate_optimization_problem(op)

​class haiqu.sdk.optimization.qubo.QUBO

​cost(bitstring)

​NOTE

​classmethod from_docplex(docplex_model)

​Deprecated

​classmethod from_file(path)

​Deprecated

​classmethod from_hamiltonian(H, offset=0.0)

​Deprecated

​Example

​classmethod from_lp_string(lp_content)

​Deprecated

​classmethod from_optimization_problem(op)

​Deprecated

​classmethod from_quadratic_program(qp)

​Deprecated

​to_file(path)

​to_hamiltonian()

​Example

​SEE ALSO

​to_lp_string()

haiqu.sdk.optimization.problem.from_hamiltonian(H, offset=0.0)

haiqu.sdk.optimization.problem.has_higher_order(op)

haiqu.sdk.optimization.problem.is_constrained(op)

haiqu.sdk.optimization.problem.max_pauli_weight(hamiltonian)

haiqu.sdk.optimization.problem.to_unconstrained_problem(op, *, penalty=None)

haiqu.sdk.optimization.problem.uses_polynomial_wire(problem)

haiqu.sdk.optimization.problem.validate_optimization_problem(op)

class haiqu.sdk.optimization.qubo.QUBO

cost(bitstring)

NOTE

classmethod from_docplex(docplex_model)

Deprecated

classmethod from_file(path)

Deprecated

classmethod from_hamiltonian(H, offset=0.0)

Deprecated

Example

classmethod from_lp_string(lp_content)

Deprecated

classmethod from_optimization_problem(op)

Deprecated

classmethod from_quadratic_program(qp)

Deprecated

to_file(path)

to_hamiltonian()

Example

SEE ALSO

to_lp_string()