Getting started

To get started, install QCOpt and JuMP, a modeling language layer for optimization. QCOpt also needs a MIP solver such as Gurobi or IBM's CPLEX. If you prefer an open-source MIP solver, install HiGHS from the Julia package manager, though be warned that the run times of QCOpt can be substantially slower using any of the open-source MIP solvers.

User inputs

QCOpt takes two types of user-defined input specifications. The first type of input contains all the necessary circuit specifications. This is given by a dictionary in Julia, which is a collection of key-value pairs, where every key is of the type String, which admits values of various types. Below is the list of allowable keys for the dictionary, given in column 1, and it's respective values with descriptions, given in column 2. This input dictionary is represented as params in all the example circuit decompositions.

If the above-specified elementary_gates contain gates with continuous angle parameters, then the following mandarotry input angle discretizations have to be specified in addition to the above inputs:

In addition, here is a list of optional circuit specifications, which can be added to the above set of inputs, to accelerate the performance of the QCOpt package:

Optimization model inputs

The second set of inputs for QCOpt contains all the optional specifications for the underlying optimization models. This is given by a dictionary in Julia, which is a collection of key-value pairs, where every key is of the type Symbol, which admits values of various types. Below is the list of allowable keys for this dictionary, given in column 1, and it's respective values with descriptions, given in column 2. This input dictionary is an optional one, as it's default values are already set in types.jl correspnding to an optimal performance of the QCOpt package. Further, this dictionary is an optional argument while executing functions, build_QCModel and run_QCModel only.

Sample circuit synthesis

Using the above-described mandatory and optional user inputs, here is a sample circuit decomposition to minimize the total depth for implementing a 2-qubit controlled-Z gate (CZGate), with entangling CNOT gate and the one-qubit, universal rotation gate (U3Gate) with three discretized Euler angles (θ,ϕ,λ):

import QuantumCircuitOpt as QCOpt
using JuMP
using Gurobi

# Target: CZGate
function target_gate()
    return Array{Complex{Float64},2}([1 0 0 0; 0 1 0 0; 0 0 1 0; 0 0 0 -1]) 
end

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

# Optimization model inputs (optional)
model_options = Dict{Symbol, Any}(:model_type => "compact_formulation",
                                  :visualize_solution => true)

qcm_optimizer = JuMP.optimizer_with_attributes(Gurobi.Optimizer, "presolve" => 1)
QCOpt.run_QCModel(params, qcm_optimizer; options = model_options)

If you prefer to decompose a target gate of your choice, update the target_gate() function and the set of elementary_gates accordingly in the above sample code. For more such circuit decompositions, with various types of elementary gates, refer to examples folder.

Extracting results

The run commands (for example, run_QCModel) in QCOpt return detailed results in the form of a dictionary. This dictionary can be saved for further processing as follows,

results = QCOpt.run_QCModel(params, qcm_optimizer)

For example, for decomposing the above controlled-Z gate, the QCOpt's runtime and the optimal objective value (minimum depth) can be accessed using,

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

Also, results["solution"] contains detailed information about the solution produced by the optimization model, which can be utilized for further analysis.

Visualizing results

QCOpt currently supports the visualization of optimal circuit decompositions obtained from the results dictionary (from above), which can be executed using,

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

For example, for the above controlled-Z gate decomposition, the processed QCOpt output is shown below (on Apple M4 Max with Gurobi 12.0.0):

=============================================================================
QuantumCircuitOpt version: 0.6.0

Quantum Circuit Model Data
  Number of qubits: 2
  Total number of elementary gates (after presolve): 72
  Maximum depth of decomposition: 4
  Elementary gates: ["U3_1", "U3_2", "CNot_1_2", "Identity"]
    U3_θ discretization: [-180.0, -90.0, 0.0, 90.0, 180.0]
    U3_ϕ discretization: [-180.0, -90.0, 0.0, 90.0, 180.0]
    U3_λ discretization: [-180.0, -90.0, 0.0, 90.0, 180.0]
  Type of decomposition: exact_optimal
  MIP optimizer: Gurobi

Optimal Circuit Decomposition
  U3_2(-90.0,0.0,0.0) * CNot_1_2 * U3_2(90.0,0.0,0.0) = Target gate
  Minimum optimal depth: 3
  Optimizer run time: 1.31 sec.
=============================================================================