Constrained Quantum Optimizer - Isang Qiskit Function ni Aqarios

Tingnan ang sanggunian sa API

tala

Ang Qiskit Functions ay isang experimental feature na available lamang sa mga user ng IBM Quantum® Premium Plan, Flex Plan, at On-Prem (sa pamamagitan ng IBM Quantum Platform API) Plan. Nasa preview release status pa ito at maaaring magbago.

Pangkalahatang-ideya

Sa Constrained Quantum Optimizer ni Aqarios, malulutas mo ang mga constrained binary optimization problem sa IBM® quantum hardware nang walang manual reformulation at circuit mapping. Sapat nang magbigay ng problema bilang LP file, MPS file, o Luna Model. Awtomatikong inaasikaso ng function ang reformulation, circuit synthesis, transpilation, at hardware execution. Ginagamit ng solver ang iterative warm-starting [1] ng FlexQAOA algorithm, isang constraint-native extension ng Quantum Approximate Optimization Algorithm (QAOA).

Tinatarget ng optimizer ang mga binary problem na may constraints. Sa partikular, ang one-hot constraints at set-packing constraints ay maaaring i-enforce nang natively gamit ang XY-mixers. Ang ibang uri ng constraint ay awtomatikong nire-reformulate bilang penalty terms.

Mga sinusuportahang uri ng variable

Discrete na mga problema lang ang nalulutas ng function. Ang bawat decision variable ay dapat binary, o integer na may tahasang lower at upper bound, para ma-encode ito sa mga qubit. Hindi sinusuportahan ang mga continuous (real-valued) na variable: ang modelong may ganoon ay tinatanggihan gamit ang error code na 4710.

Deskripsyon

Paalala

Maaaring depende ang performance sa parehong problem instance at sa mga susunod na processing step. Sa ilang kaso, ang classical samples at quantum-generated samples ay maaaring magkaroon ng magkatulad na final solution quality matapos ang equivalent post-processing. Kaya dapat isaalang-alang ng evaluation ang kabuuang optimization workflow.

Ipinapatupad ng Constrained Quantum Optimizer ang Iterative warm-start XY-mixer QAOA (IWS-QAOA) [1]. Pinapatakbo ng algorithm ang fixed-angle QAOA circuits sa quantum hardware at ina-update ang paunang warm-start probabilities ng bawat circuit gamit ang measurement outcomes mula sa nakaraang iteration. Walang kinakailangang variational parameter training; sa halip, isang fixed linear ramp parametrization ang ginagamit.

Sa paggamit ng XY-mixers para i-enforce ang one-hot constraints, malaki ang maipapabuti mo sa solution quality ng mga constrained problem, dahil praktikal na nababawasan ang search space patungo sa mas maliit na feasible subspace — at walang idinadagdag na komplikasyon, dahil sa penalty terms, sa optimization landscape.

Daloy ng Gawain

Inilalarawan sa ibaba ang daloy ng gawain ng function:

1. Preprocessing: Bago ang circuit synthesis, sinusuri ng optimizer ang constraint structure ng input problem:

   • Graph preprocessing: Kapag naaangkop sa problema, sinusuri ito bilang graph, kung saan tinutukoy ng mga edge ang relasyon sa pagitan ng mga variable. Ang graph analysis na ito ay nagbibigay-daan sa dalawang preprocessing enhancement. Una, ang mga single constraint ay maaaring pagsamahin sa isang malaking constraint gamit ang clique merging, para irepresenta ang mga ito ng iisang XY-mixer. Pangalawa, ang mga variable na may iisang neighbor lamang ay maaaring i-fix nang deterministiko, na binabawasan ang laki at komplikasyon ng problema.

   • Constraint resolution: Inaasikaso ng preprocessor ang bawat constraint nang hiwalay: Kung ang constraint ay one-hot constraint, maaari itong i-enforce sa pamamagitan ng XY-mixers. Kung ito ay set-packing constraint, iko-convert muna ito sa one-hot constraint. Ang equality constraints ay inaasikaso sa pamamagitan ng quadratic penalties, at ang inequality constraints sa pamamagitan ng unbalanced penalization.

   • Penalty derivation: Ang mga constraint na hindi maipapahayag bilang one-hot equality constraints ay kino-convert sa penalty terms. Awtomatikong kinukuha ng optimizer ang penalty strength batay sa structure ng problema.

2. Iterative warm-starting: Pinapatakbo ng optimizer ang maraming parallel warm-start chains. Ang bawat chain ay may hawak na probability distribution sa mga variable assignment, na ginagamit bilang starting probability ng QAOA circuit (warm-start state). Sa bawat iteration, kumukuha ang chain ng samples mula sa quantum circuit, nag-aaplay ng classical postprocessing, at ina-update ang distribution nito batay sa paglitaw ng mga sample. Sa magkakasunod na iteration, tinutuunan nito ang paghahanap sa mga high-quality solution nang walang variational optimization loop.

Ang bilang ng chains (num_parallel), ang total shot budget kada chain (total_shots), at ang bilang ng QAOA repetitions (reps) ang pangunahing mga kontrol para sa pagbabalanse ng solution quality laban sa runtime.

Mga Benchmark

Ipinapakita ng mga benchmark sa ibaba na kayang makahanap ng Constrained Quantum Optimizer Qiskit Function ng high-quality at feasible na mga solusyon para sa constrained optimization problem na may higit na higit sa 100 binary variable. Ang accuracy ay ang ratio ng nakitang objective value sa kilalang optimum. Ang runtime ay ang wall-clock time mula sa pag-invoke ng function hanggang sa paghahatid ng resulta. Ang QPU usage ay ang billable Quantum Compute time.

Dalawang problema ang sinuri: ang Maximum Independent Set (MIS) problem at ang Max-$k$-Cut, na isang extension ng kilalang MaxCut problem sa higit sa dalawang kategorya. Ang Max-$k$-Cut ay katumbas din na optimization problem ng graph coloring decision problem (kapag naputol ang lahat ng edge, ang graph ay $k$-colorable).

Problema	Mga Variable	Mga Constraint	Mga Qubit	Accuracy	Feasibility	Kabuuang runtime (s)	Paggamit ng QPU (s)	Kabuuang shots
MIS es60fst02	186	280	124	100.0%	True	940.2	147.0	25.0k
MIS sloane_2dc_128	128	5173	74	100.0%	True	347.6	106.0	12.5k
Max-3-Cut Karate Club	99	33	99	98.7%	True	279.5	166.0	25.0k
Max-4-Cut Karate Club	132	33	132	100.0%	True	258.3	200.0	25.0k

Mga Tala sa Benchmark

• Ang mga resulta sa itaas ay nakuha gamit ang ibm_marrakesh Heron r2 processor na may default options at naka-enable ang use_session. Para sa sloane_2dc_128 instance, ginamit ang total_shots=12500.

• Ang nabawasang bilang ng qubit para sa mga MIS instance (74 at 124 kumpara sa 128 at 186 na variable) ay resulta ng variable fixing sa preprocessing.

• Ang mga problem instance para sa MIS ay kinuha mula sa Quantum Optimization Benchmarking Library. - Ang instance para sa Max-$k$-Cut problem ay ang Zachary Karate Club graph, na may chromatic number na 5.

Magsimula

Ipinapakita ng gabay na ito ang basic usage ng Constrained Quantum Optimizer sa pamamagitan ng pagpapakita kung paano i-load ang function at magpatakbo ng simpleng mga problema. Para sa mas detalyadong tutorial, tingnan ang Hanapin ang Maximum Independent Set gamit ang Aqarios Constrained Quantum Optimizer.

Mag-authenticate gamit ang iyong IBM Quantum API key at instance CRN, pagkatapos ay i-load ang function mula sa catalog.

tala

Ipinapalagay ng sumusunod na code na na-save mo na ang iyong credentials. Para i-set up ang mga ito, sundin ang mga instruction sa I-save ang iyong mga kredensyal sa IBM Cloud account.

# Added by doQumentation — installs the packages this notebook needs if they are missing
import importlib.util

_needed = {"luna_model": "luna-model", "networkx": "networkx", "qiskit_addon_opt_mapper": "qiskit-addon-opt-mapper", "qiskit_ibm_catalog": "qiskit-ibm-catalog"}
_missing = [pip for module, pip in _needed.items()
            if importlib.util.find_spec(module) is None]
# One at a time, so a package that fails to install does not block the others
for _pip in _missing:
    %pip install -q {_pip}
if not _missing:
    print("\u2713 All required packages are installed")

from qiskit_ibm_catalog import QiskitFunctionsCatalog

catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")

# Verify that you have access to the function
catalog.list()

[QiskitFunction(aqarios/constrained-quantum-optimizer)]

# Load the function
optimizer = catalog.load("aqarios/constrained-quantum-optimizer")

# Check the list of backends you have access to
catalog.backends()

[<IBMBackend('ibm_pittsburgh')>,
 <IBMBackend('ibm_boston')>,
 <IBMBackend('ibm_phoenix')>,
 <IBMBackend('ibm_fez')>,
 <IBMBackend('ibm_miami')>,
 <IBMBackend('ibm_marrakesh')>,
 <IBMBackend('ibm_kingston')>]

# Select the backend you want to use
backend = catalog.backend("ibm_phoenix")

Halimbawa 1: Isang simpleng constrained problem

Ipinapakita ng unang halimbawa kung paano gamitin ang function gamit ang LP-files, isang karaniwang optimization problem specification na ginagamit sa operations research. Bubuuin mo ang sumusunod na arbitrary optimization problem na may limang binary variable $x_i \in \{0,1\}$ na napapailalim sa dalawang constraint:

$$\min x_1 x_2 + 2 x_2 x_3 - x_3 x_4 - 2 x_4 x_5 - 2 x_1 x_3 - 4 x_2 x_5 \\ \text{s.t.}\quad x_1 + x_2 + x_3 \leq 1 \\ \quad x_3 - x_4 + x_5 = 0$$

1. Bumuo ng problema

Direktang isaad ang mathematical expression bilang sumusunod na LP-string format:

lp_str = """\\Problem name: Example
Minimize
  obj: [ 2 x_1 x_2 + 4 x_2 x_3 - 2 x_3 x_4 - 4 x_4 x_5 - 4 x_1 x_3 - 8 x_2 x_5 ] / 2
Subject To
  c1: x_1 + x_2 + x_3 <= 1
  c2: x_3 - x_4 + x_5 = 0
Binaries
  x_1 x_2 x_3 x_4 x_5
End
"""

Tandaan na ang [ ... ] / 2 ay isang required notation para sa quadratic objectives mula sa LP standard.

2. Patakbuhin ang optimizer

Lutasin ang problema gamit ang optimizer.

# Set up low-resource options for the simple problem
options = {"total_shots": 2000, "num_parallel": 5, "use_session": True}

# Dispatch the job
job_1 = optimizer.run(
    problem=lp_str, backend_name=backend.name, options=options
)

print(f"Job ID: {job_1.job_id}")

Job ID: 2e06a3a8-7c29-4c76-94d7-194293363f4a

# Monitor the job status
job_1.status()

'RUNNING: WAITING_FOR_QPU'

3. Kunin ang resulta

Ang solusyon, na nagma-map ng mga pangalan ng variable sa kanilang kaugnay na assignment, ay ibinibigay ng resulta.

result = job_1.result()

result

{'solutions': [{'x_1': 0, 'x_2': 1, 'x_3': 0, 'x_4': 1, 'x_5': 1}],
 'solution_bitstrings': ['01011'],
 'raw_energy': -6.0,
 'objective_value': -6.0,
 'feasible': True,
 'metadata': {'resource_usage': {'RUNNING: MAPPING': {'CPU': 5.405},
   'RUNNING: OPTIMIZING_FOR_HARDWARE': {'CPU': 9.902},
   'RUNNING: WAITING_FOR_QPU': {'CPU': 25.456},
   'RUNNING: EXECUTING_QPU': {'CPU': 25.202},
   'RUNNING: POST_PROCESSING': {'CPU': 6.481}},
  'circuit_metrics': {'before_transpilation': {'num_qubits': 6,
    'gate_count': 42,
    'depth': 15,
    'two_qubit_gate_count': 12,
    'two_qubit_gate_depth': 7,
    'operations': {'rz': 12,
     'p': 8,
     'ry': 7,
     'rzz': 4,
     'cx': 3,
     'xx_plus_yy': 3,
     'global_phase': 2,
     'cry': 2,
     'x': 1}},
   'after_transpilation': {'num_qubits': 6,
    'gate_count': 254,
    'depth': 100,
    'two_qubit_gate_count': 48,
    'two_qubit_gate_depth': 33,
    'operations': {'rz': 78, 'sx': 122, 'cz': 48, 'measure': 6, 'x': 0}}},
  'solver_info': {'variable_mapping': {'x_1': 0,
    'x_2': 1,
    'x_3': 2,
    'x_4': 3,
    'x_5': 4}}}}

Ang field na solutions sa return dictionary ay naglalaman ng lahat ng degenerate na pinakamahusay na solusyon na natagpuan, bilang mga dictionary na nagmamapa ng bawat pangalan ng variable sa assignment nito. Ibinabalik din ang parehong mga solusyon bilang mga bitstring sa solution_bitstrings; sinasabi ng metadata.solver_info.variable_mapping kung aling posisyon ng karakter ng bitstring ang para sa aling variable. Kasama ng datos ng solusyon, ibinibigay rin ang objective_value, isang feasible flag, at karagdagang metadata.

Halimbawa 2: Maximum Independent Set

Hinahanap ng Maximum Independent Set (MIS) problem ang pinakamalaking subset ng vertices sa isang graph kung saan walang dalawang vertex sa subset ang nagbabahagi ng edge. Nilulutas ng halimbawang ito ang MIS sa 12-node regular graph. Para sa karagdagang impormasyon tungkol sa problema at mas malaking halimbawa, tingnan ang tutorial.

Binuo ang problema gamit ang qiskit-addon-opt-mapper. I-install ang mga kinakailangang package kung kailangan:

# %pip install networkx qiskit-addon-opt-mapper

Hakbang 1: Tukuyin ang problema

Bumuo ng random 3-regular graph at gumawa ng MIS optimization problem. Ang bawat graph node ay nagiging binary variable, at ang bawat edge ay nagdadala ng constraint na tinitiyak na hanggang isang endpoint lamang ang mapipili.

import networkx as nx
from qiskit_addon_opt_mapper.applications import IndependentSet
from qiskit_addon_opt_mapper.translators import to_docplex_mp

# 12-node random 3-regular graph
G = nx.random_regular_graph(3, 12, seed=7)

# Build MIS problem and export as LP string
mis = IndependentSet(G)
mis_problem = mis.to_optimization_problem()
lp_str = to_docplex_mp(mis_problem).export_as_lp_string()

print(lp_str)

\ This file has been generated by DOcplex
\ ENCODING=ISO-8859-1
\Problem name: Independent set

Maximize
 obj: x_0 + x_1 + x_2 + x_3 + x_4 + x_5 + x_6 + x_7 + x_8 + x_9 + x_10 + x_11
Subject To
 c0: x_0 + x_4 <= 1
 c1: x_0 + x_9 <= 1
 c2: x_0 + x_8 <= 1
 c3: x_1 + x_2 <= 1
 c4: x_1 + x_7 <= 1
 c5: x_1 + x_3 <= 1
 c6: x_2 + x_4 <= 1
 c7: x_2 + x_11 <= 1
 c8: x_3 + x_10 <= 1
 c9: x_3 + x_11 <= 1
 c10: x_4 + x_5 <= 1
 c11: x_5 + x_10 <= 1
 c12: x_5 + x_6 <= 1
 c13: x_6 + x_8 <= 1
 c14: x_6 + x_7 <= 1
 c15: x_7 + x_9 <= 1
 c16: x_8 + x_11 <= 1
 c17: x_9 + x_10 <= 1

Bounds
 0 <= x_0 <= 1
 0 <= x_1 <= 1
 0 <= x_2 <= 1
 0 <= x_3 <= 1
 0 <= x_4 <= 1
 0 <= x_5 <= 1
 0 <= x_6 <= 1
 0 <= x_7 <= 1
 0 <= x_8 <= 1
 0 <= x_9 <= 1
 0 <= x_10 <= 1
 0 <= x_11 <= 1

Binaries
 x_0 x_1 x_2 x_3 x_4 x_5 x_6 x_7 x_8 x_9 x_10 x_11
End

Hakbang 2: Patakbuhin ang optimizer

Lutasin ang problema gamit ang optimizer.

options = {"total_shots": 2000, "use_session": True}

# Dispatch the job
job_2 = optimizer.run(
    problem=lp_str, backend_name=backend.name, options=options
)

print(f"Job ID: {job_2.job_id}")

Job ID: f041431c-b42e-4627-afe5-522fea61faf6

# Monitor the job status
job_2.status()

'QUEUED'

Hakbang 3: Kunin at bigyang-kahulugan ang mga resulta

Sa huli, kukunin natin ang solusyon at iva-verify kung tama ito.

result = job_2.result()

print(f"Feasible: {result['feasible']}")
print(f"Independent set size: {int(result['objective_value'])}")

# Extract the selected nodes
solution = result["solutions"][0]
independent_set = [
    int(k.split("_")[1]) for k, v in solution.items() if v == 1
]
print(f"Selected nodes: {sorted(independent_set)}")

# Verify no two selected nodes share an edge
conflicts = [
    (u, v)
    for u, v in G.edges()
    if u in independent_set and v in independent_set
]
print(f"Edge conflicts: {conflicts}")

Feasible: True
Independent set size: 5
Selected nodes: [1, 4, 6, 9, 11]
Edge conflicts: []

Halimbawa 3: Graph 3-coloring (Max-3-Cut)

Hinahati ng Max-$k$-Cut problem ang mga vertex ng graph sa $k$ na grupo para i-maximize ang bilang ng mga edge na ang mga endpoint ay nasa magkaibang grupo. Para sa $k = 3$, katumbas ito ng paghahanap ng 3-coloring na nagpapalaki sa cross-color edges.

Sa pormal na paraan, itinatalaga ang bawat node $i \in V$ sa isa sa $k$ na grupo gamit ang binary variables $x_{i,c}$ para sa kulay $c \in \{1, \ldots, k\}$. Ang one-hot constraint $\sum_c x_{i,c} = 1$ para sa bawat node ay nag-e-enforce ng natatanging assignment. Ang objective ay nagpapalaki sa cross-group edges:

$$\min \sum_{(u,v) \in E} \sum_c x_{u,c} \, x_{v,c}\\ \text{s.t.} \sum_{c} x_{i,c} = 1 \quad \forall i \in V$$

Ang one-hot constraints ay ideal para sa XY-mixers, na hinahawakan ng optimizer nang natively.

Ginagamit ng halimbawang ito ang Zachary Karate Club graph (34 node, 78 edge) at binubuo ang modelo gamit ang Luna Model. I-install ang mga kinakailangang package kung kailangan:

# %pip install networkx matplotlib luna-model

Hakbang 1: Tukuyin ang problema

Una, buuin ang mga binary variable gamit ang luna-model package. Pagkatapos, tukuyin ang objective at idagdag ang mga constraint sa modelo.

import networkx as nx
from luna_model import Model, quicksum

k = 3
G = nx.karate_club_graph()

# Instantiate the Model object
model = Model(name="Max-3-Cut")

# Add binary variables
x = model.add_variables("x", shape=(G.number_of_nodes(), k))

# Add the objective by using the numpy dot abstraction
model.objective = quicksum(x[i].dot(x[j]) for i, j in G.edges)

# Bulk-add the one-hot constraints
model.add_constraints(x.sum(axis=1) == 1)

# Encode the model to send via API
model_enc = model.encode_b64()

Hakbang 2: Patakbuhin ang optimizer

Lutasin ang problema gamit ang optimizer.

options = {"use_session": True}

# Dispatch the job
job_3 = optimizer.run(
    problem=model_enc, backend_name=backend.name, options=options
)

print(f"Job ID: {job_3.job_id}")

Job ID: df911d83-9df7-44a1-bfad-5d66e08676c3

# Monitor the job status
job_3.status()

'RUNNING: WAITING_FOR_QPU'

Hakbang 3: Kunin at i-visualize ang mga resulta

Kunin at i-visualize ang mga resulta.

result = job_3.result()
solution = result["solutions"][0]

# Map each node to its assigned color group
node_group = {}
for i in G.nodes:
    for c in range(k):
        if solution[f"x{i},{c}"] == 1:
            node_group[i] = c

print(f"Feasible: {result['feasible']}")
print(f"Violations: {int(result['objective_value'])}")

# Visualize the partition
colors = ["tab:blue", "tab:orange", "tab:green"]
node_colors = [colors[node_group[i]] for i in G.nodes()]
nx.draw(G, nx.kamada_kawai_layout(G), node_color=node_colors, node_size=200)

Feasible: True
Violations: 4

Talaan ng mga Pagbabago

[0.4.0] - 2026-09-22

Mga breaking change

• Pinalitan ang pangalan ng input parameter na model para maging problem.
• Pinalitan ang pangalan ng output field na obj_value para maging objective_value.
• Pinalitan ang opsyong postprocessing ng postprocessing_level, na tumatanggap ng integer sa saklaw na [0, 3] sa halip na string. Ang mga dating value ay nagmamapa sa "off" -> 0, "weak" -> 1, "medium" -> 2, at "strong" -> 3, at hindi nagbago ang default na 3.
• Inayos muli ang istruktura ng metadata.circuit_metrics. Ngayon ay nag-uulat ito ng num_qubits, gate_count, depth, two_qubit_gate_count, two_qubit_gate_depth, at operations nang hiwalay para sa before_transpilation at after_transpilation, sa halip na isang flat na dictionary ng mga average na gate count. Ang field ay None kapag nalutas ang problema habang preprocessing at walang circuit na pinatakbo (error code 4712).

Mga feature

• Idinagdag ang opsyong seed_transpiler para maging reproducible ang circuit synthesis at routing sa bawat takbo.
• Idinagdag ang opsyong job_tags para maglagay ng sarili mong mga tag sa bawat Qiskit Runtime job na isinusumite ng function.
• Idinagdag ang output field na solution_bitstrings, na nagbabalik ng parehong mga solusyon gaya ng solutions sa anyong bitstring.
• Idinagdag ang metadata.solver_info.variable_mapping, na nagmamapa ng bawat pangalan ng variable sa posisyon ng karakter nito sa mga entry ng solution_bitstrings.

Dokumentasyon

• Idinokumento na hindi sinusuportahan ang mga continuous (real-valued) na variable at na kailangan ng tahasang bound ng mga integer variable. Pumapalya ang ganoong mga modelo na may error code na 4710.

Kumuha ng suporta

Para sa mga tanong o isyu, makipag-ugnayan sa support@aqarios.com kasama ang iyong job ID.

Mga susunod na hakbang

Mga Rekomendasyon

• Humiling ng access sa Constrained Quantum Optimizer ni Aqarios.
• Bisitahin ang sanggunian sa API para sa kumpletong dokumentasyon ng parameter at output.
• Subukan ang Hanapin ang Maximum Independent Set gamit ang Aqarios Constrained Quantum Optimizer tutorial para sa malalim na pagtingin sa isang totoong QOBLIB benchmark instance.
• Suriin ang publikasyong Constrained Quantum Optimization via Iterative Warm-Start XY-Mixers.

Mga Sanggunian

1. Bucher et al. (2026), Constrained Quantum Optimization via Iterative Warm-Start XY-Mixers 10.1088/1367-2630/ae8ea2