Private types and functions

_errorreason(infos)

Return the reason a remote job errored, or nothing if the server gave none.

The MIMIQ cloud reports it in errorMessage, Quantum Hive in a messages list.

checkvalidinputs(ex, basenames)

Validate that the execution contains exactly one manifest (circuits.json OR optimize.json) AND always request.json. Throws an error if the inputs are invalid.

Basic gates for the ε-net.

abstract type AbstractDAGCircuit{T} <: AbstractCircuit{T} end

Abstract type for all the struct that needs to implement a DAG representation for their circuits. It simply serves as a middle man/type providing the method to build the DAG from the list of instructions.

DecompositionError(msg)

Thrown when decompose or decompose_step cannot rewrite an operation: the rule does not match it, or no rule of the basis leads to its terminal operations, as for noise channels under QASMBasis. msg says which operation and why.

The error prints as Error during decomposition: msg.

LazyArg()

Placeholder for a lazy argument in a LazyExpr.

LazyExpr(type, args)

Helps evaluating expressions lazily.

Evaluation occurs only then the LazyExpr is called with some arguments, and the arguments will be passed to the inner part of the expression.

OperationError(optype, msg)

Thrown when an operation of type optype is built with invalid arguments, for example a PolynomialOracle whose registers do not add up to its number of qubits, or a QFT on zero qubits. msg says what is wrong.

The error prints as optype: msg.

RewriteRule

Abstract type for single-step rewrite rules that transform one operation into a sequence of simpler operations.

A RewriteRule defines how to transform an operation, but not when to stop. For recursive decomposition to a target set of operations, see DecompositionBasis.

Interface

Subtypes must implement:

• matches(rule, op): Return true if this rule can transform op.
• decompose_step!(builder, rule, op, qtargets, ctargets, ztargets): Append the transformed instructions to builder.

Examples

struct MyRewrite <: RewriteRule end

matches(::MyRewrite, ::GateToffoli) = true
matches(::MyRewrite, ::Operation) = false

function decompose_step!(builder, ::MyRewrite, op::GateToffoli, qt, ct, zt)
    # ... append decomposed instructions to builder
    return builder
end

See also CanonicalRewrite, DecompositionBasis.

UndefinedValue(n)

Thrown when a parameter has to be converted to a number but n is still symbolic, for example when sampling a noise channel whose probability is an unbound variable. Bind the variables first with evaluate.

The error prints as Undefined value n..

UnexpectedSymbolics(sym, expr)

Error to be thrown when a unexpected symbolics is present in an expression.

append!(circuit1::AbstractCircuit{T}, circuit2::AbstractCircuit{T})

Append all instructions from circuit2 to circuit1.

Arguments

• circuit1::AbstractCircuit{T}: The target circuit to which instructions will be appended.
• circuit2::AbstractCircuit{T}: The circuit whose instructions will be appended.

Examples

```jldoctest julia> c=Circuit() empty circuit

julia> push!(c, GateX(), 1:4) # Applies X to all 4 targets 4-qubit circuit with 4 instructions: ├── X @ q[1] ├── X @ q[2] ├── X @ q[3] └── X @ q[4]

julia> c1 = Circuit() empty circuit

julia> push!(c1, GateH(), 1:4) 4-qubit circuit with 4 instructions: ├── H @ q[1] ├── H @ q[2] ├── H @ q[3] └── H @ q[4]

julia> append!(c,c1) 4-qubit circuit with 8 instructions: ├── X @ q[1] ├── X @ q[2] ├── X @ q[3] ├── X @ q[4] ├── H @ q[1] ├── H @ q[2] ├── H @ q[3] └── H @ q[4]

deleteat!(circuit::AbstractCircuit{T}, index::Integer)
deleteat!(circuit::AbstractCircuit{T}, inds)

Remove the instruction(s) at the given index(es).

Arguments

• circuit::AbstractCircuit{T}: The target circuit.
• index: The index or collection of indices to remove.

Examples

julia> c = Circuit()
empty circuit

julia> push!(c, GateX(), 1:3)
3-qubit circuit with 3 instructions:
├── X @ q[1]
├── X @ q[2]
└── X @ q[3]

julia> deleteat!(c, 2)
3-qubit circuit with 2 instructions:
├── X @ q[1]
└── X @ q[3]

insert!(c::Circuit, i::Integer, operation::Operation{N,M,L}, targets::Vararg{Integer,K})

Insert an operation into the circuit at a specific position, with the given targets.

Arguments

• c::Circuit: The quantum circuit where the operation will be inserted.
• i::Integer: The position in the circuit where the operation will be inserted (1-based index).
• operation::Operation{N,M,L}: The operation to apply, working on N qubits, M classical bits, and L z-variables.
• targets::Vararg{Integer,K}: The target qubits, classical bits, and z-variables, where K must match the number of required targets for the operation.

Errors

• ArgumentError: Raised if the number of targets provided does not match the required qubits, bits, or z-variables for the operation.

Examples

julia> c = Circuit()
empty circuit

julia> push!(c, GateX(), 1:4)
4-qubit circuit with 4 instructions:
├── X @ q[1]
├── X @ q[2]
├── X @ q[3]
└── X @ q[4]

julia> insert!(c, 1, GateCX(), 1, 3)
4-qubit circuit with 5 instructions:
├── CX @ q[1], q[3]
├── X @ q[1]
├── X @ q[2]
├── X @ q[3]
└── X @ q[4]

insert!(c::Circuit, i::Integer, operation_type::Type{T}, targets...)

Insert a non-parametric operation of a specific type into the circuit at a given position.

Arguments

• c::Circuit: The quantum circuit where the operation will be inserted.
• i::Integer: The position (1-based index) in the circuit where the operation will be inserted.
• operation_type::Type{T}: The type of the operation to apply.
• targets: The target qubits, bits, or z-variables for the operation.

Errors

• ArgumentError: Raised if the operation type is parametric (i.e., it requires parameters).

Examples

julia> c = Circuit()
empty circuit

julia> c=Circuit()
empty circuit

julia> push!(c, GateX(), 1:4)        
4-qubit circuit with 4 instructions:
├── X @ q[1]
├── X @ q[2]
├── X @ q[3]
└── X @ q[4]

julia> insert!(c, 3, GateRX(π/2), 5)
5-qubit circuit with 5 instructions:
├── X @ q[1]
├── X @ q[2]
├── RX(π/2) @ q[5]
├── X @ q[3]
└── X @ q[4]

insert!(circuit::AbstractCircuit{T}, index::Integer, instruction::T)

Insert an instruction into the circuit at the specified index.

Arguments

• circuit::AbstractCircuit{T}: The quantum circuit where the instruction will be inserted.
• index::Integer: The position at which the instruction will be inserted.
• instruction::T: The instruction to insert.

Examples

```jldoctest julia> c=Circuit() empty circuit

julia> c=Circuit() empty circuit

julia> push!(c, GateX(), 1:4) 4-qubit circuit with 4 instructions: ├── X @ q[1] ├── X @ q[2] ├── X @ q[3] └── X @ q[4]

julia> insert!(c, 2, Instruction(GateH(), 1)) 4-qubit circuit with 5 instructions: ├── X @ q[1] ├── H @ q[1] ├── X @ q[2] ├── X @ q[3] └── X @ q[4]

insert!(circuit1::AbstractCircuit{T}, index::Integer, circuit2::AbstractCircuit{T})

Insert all instructions from circuit2 into circuit1 at the specified index.

Arguments

• circuit1::AbstractCircuit{T}: The target circuit where instructions will be inserted.
• index::Integer: The position at which the instructions from circuit2 will be inserted.
• circuit2::AbstractCircuit{T}: The circuit whose instructions will be inserted.

Examples

```jldoctest julia> c = Circuit() empty circuit

julia> push!(c, GateX(), 1:4) 4-qubit circuit with 4 instructions: ├── X @ q[1] ├── X @ q[2] ├── X @ q[3] └── X @ q[4]

julia> c1 = Circuit() empty circuit

julia> push!(c1, GateH(), 1:4) 4-qubit circuit with 4 instructions: ├── H @ q[1] ├── H @ q[2] ├── H @ q[3] └── H @ q[4]

julia> insert!(c,1,c1) 4-qubit circuit with 8 instructions: ├── H @ q[1] ├── H @ q[2] ├── H @ q[3] ├── H @ q[4] ├── X @ q[1] ├── X @ q[2] ├── X @ q[3] └── X @ q[4]

julia>

isvalid(ex::OptimizationExperiment)

Whether ex can be submitted: its circuit is non-empty and symbolic, initparams gives a value for exactly the symbols of the circuit, and zregister is at least 1. Returns false instead of throwing when a check fails.

push!(circuit::Circuit, operation::Operation, targets::Vararg{Int})

Add an operation to the circuit with the specified qubit, bit, or zvar targets.

This function allows you to push quantum operations onto a circuit, specifying the exact qubits, classical bits, or zvars (if applicable) that the operation acts on.

Arguments

• circuit::Circuit: The quantum circuit to which the operation will be added.
• operation::Operation{N,M,L}: The operation to apply. It works on N qubits, M classical bits, and L zvars.
• targets::Vararg{Any,K}: The target qubits, bits, or zvars for the operation.

Throws

• ArgumentError: If the wrong number of targets is provided.
• ArgumentError: If any targets are invalid or not distinct.

Examples

julia> c=Circuit()
empty circuit

julia> push!(c, GateCX(), [1, 2], 3)  # Adds `CX @ q1, q3` and `CX @ q2, q3`
3-qubit circuit with 2 instructions:
├── CX @ q[1], q[3]
└── CX @ q[2], q[3]

julia> push!(c, GateX(), 1:4)         # Applies X to all 4 targets
4-qubit circuit with 6 instructions:
├── CX @ q[1], q[3]
├── CX @ q[2], q[3]
├── X @ q[1]
├── X @ q[2]
├── X @ q[3]
└── X @ q[4]

julia> push!(c, GateH(), 8)
8-qubit circuit with 7 instructions:
├── CX @ q[1], q[3]
├── CX @ q[2], q[3]
├── X @ q[1]
├── X @ q[2]
├── X @ q[3]
├── X @ q[4]
└── H @ q[8]

push!(circuit::Circuit, operation_type::Type{T}, targets...)

Add an operation of a specific type to the circuit with the given targets.

Arguments

• circuit::Circuit: The quantum circuit to which the operation will be added.
• operation_type::Type{T}: The type of the operation to apply.
• targets: The target qubits, bits, or zvars for the operation.

Errors

• ArgumentError: Raised if the operation type requires parameters (i.e., it is a parametric operation), but none were provided.

Examples

julia> c = Circuit()
empty circuit

julia> push!(c, GateRX(π/2), 1:4)
4-qubit circuit with 4 instructions:
├── RX(π/2) @ q[1]
├── RX(π/2) @ q[2]
├── RX(π/2) @ q[3]
└── RX(π/2) @ q[4]

push!(circuit::AbstractCircuit{T}, instruction::T)

Add an instruction to the circuit.

Arguments

• circuit::AbstractCircuit{T}: The quantum circuit to which the instruction will be added.
• instruction::T: The instruction to add.

Examples

julia> c=Circuit()
empty circuit

julia> push!(c, Instruction(GateX(),1)) 
1-qubit circuit with 1 instruction:
└── X @ q[1]

julia> push!(c, Instruction(GateCX(),1, 2))
2-qubit circuit with 2 instructions:
├── X @ q[1]
└── CX @ q[1], q[2]

_append_multiplexed_rotation!(circ, G, angles, target, controls)

Append a rotation G(angle) on target, multiplexed over controls: for each control state i (MSB first), G(angles[i]) acts on target. angles has length 2^k with k = length(controls).

_append_multiplexed_unitary!(circ, U0, U1, control, targets)

Appends decomposition of $\operatorname{diag}(U_0, U_1)$ to circ. Returns the common global phase offset.

_build_replacement_instructions(replacement, op_pattern, inst) -> Vector{Instruction}

Build output instructions from a replacement specification, remapping to the actual qubits of inst. Supports three forms:

1. Vector{Instruction} on canonical qubits → remapped to actual qubits.
2. Operation with numqubits == numqubits(matched) → single instruction on all qubits.
3. Operation with numqubits == 1 → broadcast to each qubit individually.

_csd_decomposition(U::AbstractMatrix)

Perform Cosine-Sine Decomposition (CSD) on a unitary matrix U. Returns (L0, L1, R0, R1, theta) such that:

\[U = \begin{pmatrix} L_0 & 0 \\ 0 & L_1 \end{pmatrix} \begin{pmatrix} C & -S \\ S & C \end{pmatrix} \begin{pmatrix} R_0 & 0 \\ 0 & R_1 \end{pmatrix}\]

where $C = \operatorname{diag}(\cos(\theta))$ and $S = \operatorname{diag}(\sin(\theta))$. $L_0, L_1, R_0, R_1$ are unitary matrices of half size. $\theta$ is a vector of angles.

_displayarray(io, A)

Vector or matrix in print layout ([a, b], [a b; c d]), with every entry written through _displaynum.

_displaynum(io, x)

Text of x as print(io, x) writes it. When io is :compact, a floating-point number whose compact text reads back as a different value gets a trailing …, so a shortened number does not look exact. Complex numbers are marked part by part, and numeric Nums are unwrapped first. Integers, rationals and everything else print unchanged, and so do symbolic expressions: numeric literals inside them are not marked.

_displaypi(io, x)

Text for the parameter x in an operation listing: a numeric Num that is a simple rational multiple of π is written in units of π (π/4, 3π/2), any other Num in full. Plain numbers go through _displaynum, so values shortened by a :compact io are marked with ….

_extract_variables(gate::Operation) -> Union{Tuple, Nothing}

Extract symbolic variables from a gate's parameters in order.

Examples

@variables θ
gate = GateRX(θ)
vars = _extract_variables(gate)  # Returns: (θ,)

@variables a b c
gate = GateU(a, 0.1, c)
vars = _extract_variables(gate)  # Returns: (a, nothing, c)

gate = GateRX(0.4)
vars = _extract_variables(gate)  # Returns: (nothing,)

_kak_decomposition(U) -> (φ, (A1, A2), (a, b, c), (B1, B2))

Decompose a 4×4 unitary as $U = e^{iφ} (A_1 ⊗ A_2) \exp(i(a XX + b YY + c ZZ)) (B_1 ⊗ B_2)$, with $A_1$ acting on the first (most significant) qubit.

_kak_synthesis(U; atol=1e-9) -> (ncx, gates)

Synthesize a 4×4 unitary U acting on local qubits 1 and 2 with the fewest CX gates, between zero and three, as (code, parameters, qubits) triples. Single-qubit gates are emitted as GateU, and the global phase of U is reproduced exactly.

_linear_synthesis(A, b) -> (cx, xs)

A circuit on local qubits 1:n implementing $x \mapsto A x \oplus b$ over GF(2): the CX gates cx, as (control, target) pairs, found by Patel-Markov-Hayes elimination, trying every section size up to $\log_2 n$ and keeping the fewest, followed by an X on each qubit in xs, where b is set.

_matches_operation_pattern(op_inst::Operation, op_rule::Operation) -> Bool

Check whether an instruction's operation matches a rule's operation pattern.

• If the rule's operation is symbolic (e.g., GateRXX(θ)), matches any operation of the same type.
• If the rule's operation is concrete (e.g., GateCX()), requires exact equality.

Create a hash for an SU(2) matrix based on discretized elements.

_qsd_decomposition(U::AbstractMatrix)

Perform Quantum Shannon Decomposition (QSD) on an N-qubit unitary $U$. Returns (Circuit, Phase) where Circuit implements $U \cdot e^{-i \cdot \text{Phase}}$.

_resolve_symbolic_replacement(op_inst::Operation, op_rule::Operation, replacement::Operation) -> Operation

Resolve symbolic parameters in replacement by extracting concrete values from op_inst and substituting them according to the pattern in op_rule.

_validate_rule_gate_params(gate::Operation)

Validate that a rule gate's parameters are either concrete values or single symbolic variables. Throws an error if any parameter is a complex symbolic expression.

_zyz_decomposition(U::AbstractMatrix)

Decompose a single qubit unitary matrix U into angles θ, ϕ, λ, γ such that U is equivalent to GateU(θ, ϕ, λ, γ).

Returns a tuple (θ, ϕ, λ, γ).

applyparams(source::Operation, relation::Pair)

Evaluates a relation by extracting parameter values from a source operation and substituting them into the target expression.

A relation has the form variables => target where:

• variables: A single symbolic variable or a tuple of symbolic variables (e.g., θ or (a, b, c))
• target: An operation using these variables (e.g., Depolarizing1(θ / π))

Parameters are matched by position: the i-th variable gets the i-th parameter from source. Variables in the left side must be simple symbolic variables, not expressions.

Arguments

• source: Fully evaluated operation with concrete parameters (e.g., GateRX(0.4))
• relation: A Pair of variables => target (e.g., θ => Depolarizing1(θ / π))

Returns

The evaluated target operation with all symbolic variables substituted

Examples

Single parameter

@variables θ
source = GateRX(0.4)
relation = θ => Depolarizing1(θ / π)
result = applyparams(source, relation)
# Result: Depolarizing1(0.4 / π) ≈ Depolarizing1(0.127)

Multiple parameters

@variables a b c
source = GateU(0.5, 0.3, 0.2)
relation = (a, b, c) => Depolarizing1((a^2 + b^2 + c^2) / (3π^2))
result = applyparams(source, relation)
# Result: Depolarizing1((0.5^2 + 0.3^2 + 0.2^2) / (3π^2))

Using subset of parameters

@variables a b
source = GateU(0.5, 0.3, 0.2)
relation = (a, b) => Depolarizing1(a + b)
result = applyparams(source, relation)
# Result: Depolarizing1(0.8)
# Third parameter (0.2) is ignored

Complex expressions in target

@variables θ
source = GateRX(π/4)
relation = θ => AmplitudeDamping(sin(θ)^2 * 0.01)
result = applyparams(source, relation)
# Result: AmplitudeDamping(0.005)

Invalid: Expression in variable list

@variables a b
source = GateU(0.5, 0.3, 0.2)
relation = (a, b + 1) => Depolarizing1(a)
result = applyparams(source, relation)
# Throws: ArgumentError - left side must be simple variables

axis_angle_to_su2(axis::Vector{Float64}, θ::Float64) -> Matrix{ComplexF64}

Construct an SU(2) matrix from rotation axis and angle. U = cos(θ/2)·I + i·sin(θ/2)·(n·σ)

exponent(poweroperation)

Exponent associated with a power operation

Examples

julia> MimiqCircuitsBase.exponent(power(GateH(), 2))
2

julia> MimiqCircuitsBase.exponent(GateSX())
1//2

extract_rotation_angle(U::Matrix{ComplexF64}) -> Float64

Extract the rotation angle θ from an SU(2) matrix U = exp(iθ n·σ/2). Returns θ ∈ [0, 2π].

extract_rotation_axis(U::Matrix{ComplexF64}) -> Vector{Float64}

Extract the rotation axis n from an SU(2) matrix U = exp(iθ n·σ/2). Returns a unit vector in R³. If U ≈ I, returns [0, 0, 1].

find_nearest_in_net(U::Matrix{ComplexF64}, cache::SKCacheEntry) -> Vector{AbstractGate}

Find the gate sequence in the ε-net that best approximates U. Handles the SU(2) double cover (U and -U represent the same rotation).

find_orthogonal_axes(n::Vector{Float64}) -> Tuple{Vector{Float64}, Vector{Float64}}

Find two orthonormal vectors v, w that are perpendicular to n, such that (v, w, n) form a right-handed coordinate system.

gc_decompose(Δ::Matrix{ComplexF64}) -> Tuple{Matrix{ComplexF64}, Matrix{ComplexF64}}

Decompose an SU(2) matrix Δ (close to identity) into matrices V and W such that the group commutator [V, W] = V W V† W† approximates Δ.

This is the balanced group commutator construction from Dawson-Nielsen. For Δ representing a rotation by angle θ, V and W will be rotations by angle ≈ √θ around carefully chosen axes.

Mathematical Background

For small rotations, if V = exp(iφ v·σ/2) and W = exp(iφ w·σ/2), then [V,W] ≈ exp(i φ² (v×w)·σ/2) to leading order.

To achieve [V,W] ≈ Δ = exp(iθ n·σ/2):

• Choose φ ≈ √θ
• Choose v, w perpendicular to each other such that v×w ∝ n

generate_epsilon_net(basis_gates, max_depth, max_points, min_dist) -> (points, gate_sequences)

Generate an ε-net over SU(2) using Breadth-First Search.

get_pi_factor_or_nothing(val) -> Union{Int, Nothing}

Check if val is a multiple of π/4 and return the factor k ∈ {0,1,...,7}.

Returns nothing if val is symbolic or not a multiple of π/4.

get_sk_cache(basis_gates; max_depth, max_points, min_dist) -> SKCacheEntry

Get or initialize the Solovay-Kitaev lookup tables.

invert_sequence(gates) -> Vector{AbstractGate}

Return the inverse of a gate sequence: (g₁ g₂ ... gₙ)† = gₙ† ... g₂† g₁†

isCPTP(krauschannel)

Whether the Kraus channel is Completely Positive, and Trace Preserving.

If the Kraus operators fulfill $\sum_k E_k^\dagger E_k = I$ then the quantum operation is CPTP. If $\sum_k E_k^\dagger E_k < I$, then it's not CPTP.

Currently, all noise channels are CPTP.

isidentity(operation)

Check if the given operation is equivalent to an isidentity.

isterminal(basis::DecompositionBasis, op::Operation) -> Bool

Return true if op is terminal in the given basis.

Terminal operations are not decomposed further—they represent the target instruction set that decompose reduces circuits to.

Examples

isterminal(CanonicalBasis(), GateU())   # true
isterminal(CanonicalBasis(), GateH())   # false (will be decomposed)

See also DecompositionBasis, decompose.

matrix_to_point(U::Matrix) -> Vector{Float64}

Map an SU(2) matrix to a point in R⁴ (the 3-sphere S³).

For SU(2), a matrix [[a, -b], [b, a]] is determined by its first column [a, b]. We map this to [Re(a), Im(a), Re(b), Im(b)] ∈ S³.

numqbz(insts::Vector{<:Instruction})
numqbz(c::AbstractCircuit) -> Int

Compute the highest index of qubit targets, bit targets and zvar targets in the given vector of instructions or circuit.

Examples

julia> c = Circuit()
empty circuit

julia> push!(c, Measure(), 1:2, 1:2)
2-qubit, 2-bit circuit with 2 instructions:
├── M @ q[1], c[1]
└── M @ q[2], c[2]

julia> numqubits(c)
2

operator_norm_distance(U::Matrix, V::Matrix) -> Float64

Compute the operator norm distance ||U - V||. For SU(2) matrices, this equals 2·sin(θ/2) where θ is the geodesic distance.

sequence_to_matrix(gates) -> Matrix{ComplexF64}

Compute the unitary matrix for a gate sequence.

simplify_sequence(gates, basis_gates) -> Vector{AbstractGate}

Simplify a gate sequence. If basis is standard Clifford+T, use algebraic rules. Otherwise, use generic inverse cancellation.

sk_approximate(U::Matrix{ComplexF64}, depth::Int, basis_gates::Vector{<:AbstractGate}; ...) -> Vector{AbstractGate}

Approximate an SU(2) matrix using the Solovay-Kitaev algorithm.

sk_approximate_memoized(U::Matrix{ComplexF64}, depth::Int; ...) -> Vector{AbstractGate}

Memoized version of sk_approximate.

to_su2(U::AbstractMatrix) -> Matrix{ComplexF64}

Project a 2×2 unitary matrix to SU(2) by removing the global phase.

const DEFAULT_INTERVAL

Default refresh interval for tokens (in seconds)

const QHIVE_CLIENT_ID

Keycloak client the library authenticates as.

const QHIVE_REALM

Keycloak realm authenticating the Quantum Hive services.

struct Tokens

Store access and refresh tokens

_qhivetokens(authuri, realm, clientid, params)

Ask the identity provider for a token with the given grant parameters.

Returns the tokens and the lifetime in seconds of the access token.

_qhiveuploads(files)

Split the uploads of a request into the form fields the API expects and the circuit files it wants uploaded one by one.

Returns the form fields as name => value pairs and the circuits as filename => path pairs.

geturi(connection_type, uri)
geturi(connection)
geturi(connection, parts...)

Get the URI for API calls through a specific connection or service.

refresh(tokens, uri)

Refresh the tokens at the given uri / instance of MIMIQ.

_GridSynth

Internal implementation of the Ross–Selinger gridsynth algorithm.

Notation follows the paper: ω = e^{iπ/4}, λ = 1 + √2, and conj2 is the √2-conjugation (√2 ↦ -√2, written x• in the paper). Gate sequences are returned as Char vectors in matrix-product order (leftmost gate is the leftmost matrix factor, i.e. the last one applied).