Quick Start Guide

Framework

Building on Julia, JuMP, and mixed-integer programming (MIP) solvers, QuantumCircuitOpt (QCOpt) is an open-source toolkit for optimal quantum circuit design. QCOpt provides an abstraction layer with two primary goals:

1. Capture a target quantum computation, the available hardware-native gates, and circuit-design requirements in a JuMP optimization model.
2. Extract, analyze, and validate the optimizer solution as an exact, globally phase-equivalent, or approximate circuit decomposition.

The optimization model searches over discrete gate choices and circuit depths, allowing QCOpt to certify global optimality for objectives such as circuit depth, CNOT count, and T-gate count.

Presentations

• May 2024: The CPAIOR 2024 Master Class slide deck discusses how emerging quantum computing technology can impact Constraint Programming (CP), Artificial Intelligence (AI), and Operations Research (OR), and vice versa.

• November 2022: Presentation link from the Third Quantum Computing Software Workshop, held in conjunction with the International Conference on Supercomputing (SC22). This presentation introduces the role of nonlinear programming formulations in optimal quantum circuit design. Additional technical details are available in the associated paper.

• July 2022: The JuliaCon 2022 presentation introduces the package and demonstrates its principal features. The conference program is available here.

• November 2021: Presentation from the Second Quantum Computing Software Workshop, held in conjunction with the International Conference on Supercomputing (SC21). It presents the technical foundations of QuantumCircuitOpt, which are also described in the associated paper.

Getting started

Install QCOpt, JuMP, and a compatible MIP solver. Gurobi is recommended for computationally difficult instances. IBM CPLEX and the open-source HiGHS solver are also supported.

User inputs

Circuit specifications are passed as a Dict{String,Any} named params in the examples.

If elementary_gates contains gates with continuous angle parameters, supply the corresponding discretizations:

U1Gate and U2Gate are available as matrix constructors. For discretized elementary-gate inputs, use the equivalent PhaseGate or U3Gate parameterizations.

Optimization model inputs

Model settings are passed through the optional options::Dict{Symbol,Any} keyword argument to build_QCModel or run_QCModel. Defaults are defined in get_default_options.

Sample circuit synthesis

This example minimizes the depth of a controlled-Z decomposition using CNOT and discretized U3 gates:

import QuantumCircuitOpt as QCOpt
using Gurobi
using JuMP

params = Dict{String,Any}(
    "num_qubits" => 2,
    "maximum_depth" => 4,
    "elementary_gates" => ["U3_1", "U3_2", "CNot_1_2", "Identity"],
    "target_gate" => ComplexF64[
        1 0 0 0
        0 1 0 0
        0 0 1 0
        0 0 0 -1
    ],
    "objective" => "minimize_depth",
    "decomposition_type" => "exact_optimal",
    "U3_θ_discretization" => -π:(π / 2):π,
    "U3_ϕ_discretization" => -π:(π / 2):π,
    "U3_λ_discretization" => -π:(π / 2):π,
)

model_options = Dict{Symbol,Any}(
    :model_type => "compact_formulation",
    :visualize_solution => true,
    :optimizer_log => false,
)

optimizer = optimizer_with_attributes(Gurobi.Optimizer, "Presolve" => 1)
results = QCOpt.run_QCModel(params, optimizer; options = model_options)

Change target_gate and elementary_gates to synthesize another circuit. See the examples directory for more decompositions.

Extracting results

run_QCModel returns a Dict{String,Any}. Common result fields include:

• optimizer
• termination_status and primal_status
• objective and objective_lb
• solve_time
• solution, which maps model variable names to their values

For example:

results["solve_time"]
results["objective"]

Visualizing results

run_QCModel prints a feasible decomposition by default. To render a saved result explicitly:

data = QCOpt.get_data(params)
QCOpt.visualize_solution(results, data)

The example produces the following output with Gurobi Optimizer 13.0.0:

=============================================================================
QuantumCircuitOpt version: 0.6.3

Quantum Circuit Data
  Number of qubits      : 2
  Maximum circuit depth : 4
  Decomposition type    : exact_optimal
  MIP optimizer         : Gurobi
  Number of input gates : 72 (presolved)
  Input gates : Qubits
      CNot : {1,2}
        U3 : 1,2
    U3_ϕ : [-180.0, -90.0, 0.0, 90.0, 180.0]
    U3_θ : [-180.0, -90.0, 0.0, 90.0, 180.0]
    U3_λ : [-180.0, -90.0, 0.0, 90.0, 180.0]

Optimal Circuit
  depth 1 : I ⊗ U3(90.0,0.0,180.0)
  depth 2 : CNot_{1,2}
  depth 3 : I ⊗ U3(90.0,0.0,180.0)

  Optimal number of gates : 3
  Optimal circuit depth   : 3
  Optimizer run time      : 1.7 sec.
=============================================================================