Blocks

AbstractBlock{D}

Abstract type for quantum circuit blocks. while D is the number level in each qudit.

Required Methods

• apply!.
• mat.
• occupied_locs.
• print_block

Optional Methods

• content
• chcontent
• subblocks.
• chsubblocks.
• Base.hash
• Base.:(==)
• nlevel.
• getiparams.
• setiparams!.
• parameters.
• nparameters.
• iparams_eltype.
• parameters_eltype.
• dispatch!.
• render_params.
• apply_back!.
• mat_back!.

PrimitiveBlock{D} <: AbstractBlock{D}

Abstract type that all primitive block will subtype from. A primitive block is a concrete block who can not be decomposed into other blocks. All composite block can be decomposed into several primitive blocks.

Required Methods

• apply!
• mat
• print_block
• Base.hash
• Base.:(==)

Optional Methods

• nlevel.
• getiparams.
• setiparams!.
• parameters.
• nparameters.
• iparams_eltype.
• parameters_eltype.
• dispatch!.
• render_params.
• apply_back!.
• mat_back!.

CompositeBlock{D} <: AbstractBlock{D}

Abstract supertype which composite blocks will inherit from. Composite blocks are blocks composited from other AbstractBlocks, thus it is a AbstractBlock as well.

Required Methods

• apply!
• mat
• occupied_locs.
• subblocks.
• chsubblocks.

Optional Methods

• nlevel.
• getiparams.
• setiparams!.
• parameters.
• nparameters.
• iparams_eltype.
• parameters_eltype.
• dispatch!.
• render_params.
• apply_back!.
• mat_back!.

GeneralMatrixBlock{D, MT} <: PrimitiveBlock{D}
GeneralMatrixBlock{D}(m, n, A, tag="matblock(...)")
GeneralMatrixBlock(A; nlevel=2, tag="matblock(...)")

General matrix gate wraps a matrix operator to quantum gates. This is the most general form of a quantum gate.

Arguments

• m and n are the number of dits in row and column.
• A is a matrix.
• tag is the printed information.
• D and nlevel are the number of levels in each qudit.

IdentityGate{D} <: TrivialGate{D}

The identity gate.

Measure{D,K, OT, LT, PT, RNG} <: PrimitiveBlock{D}
Measure(n::Int; rng=Random.GLOBAL_RNG, operator=ComputationalBasis(), locs=1:n, resetto=nothing, remove=false, nlevel=2, error_prob=0.0)

Measurement block.

Fields

• n::Int: number of qubits.
• rng::RNG: random number generator.
• operator::OT: operator to measure, by default it is ComputationalBasis().
• locations::LT: locations to measure, by default it is 1:n.
• postprocess::PT: postprocess to apply to the measurement result, e.g. ResetTo to reset the measured qubits to a specific state.
• error_prob::Float64: error probability, by default it is 0.0. This is only supported for 2-level systems, and the operator must be ComputationalBasis or a single qubit operator.
• results::Any: measurement results, by default it is undef.

Measure(n::Int; rng=Random.GLOBAL_RNG, operator=ComputationalBasis(), locs=AllLocs(), resetto=nothing, remove=false, error_prob=0.0)

Create a Measure block with number of qudits n.

Examples

You can create a Measure block on given basis (default is the computational basis).

julia> Measure(4)
Measure(4)

Or you could specify which qudits you are going to measure

julia> Measure(4; locs=1:3)
Measure(4;locs=(1, 2, 3))

by default this will collapse the current register to measure results.

julia> r = normalize!(arrayreg(bit"000") + arrayreg(bit"111"))
ArrayReg{2, ComplexF64, Array...}
    active qubits: 3/3
    nlevel: 2

julia> state(r)
8×1 Matrix{ComplexF64}:
 0.7071067811865475 + 0.0im
                0.0 + 0.0im
                0.0 + 0.0im
                0.0 + 0.0im
                0.0 + 0.0im
                0.0 + 0.0im
                0.0 + 0.0im
 0.7071067811865475 + 0.0im

julia> r |> Measure(3)
ArrayReg{2, ComplexF64, Array...}
    active qubits: 3/3
    nlevel: 2

julia> state(r)
8×1 Matrix{ComplexF64}:
 0.0 + 0.0im
 0.0 + 0.0im
 0.0 + 0.0im
 0.0 + 0.0im
 0.0 + 0.0im
 0.0 + 0.0im
 0.0 + 0.0im
 1.0 + 0.0im

But you can also specify the target bit configuration you want to collapse to with keyword resetto.

```jldoctest; setup=:(using Yao) julia> m = Measure(4; resetto=bit"0101") Measure(4;postprocess=ResetTo{BitStr{4,Int64}}(0101 ₍₂₎))

julia> m.postprocess ResetTo{BitStr{4,Int64}}(0101 ₍₂₎)```

PhaseGate

Global phase gate.

struct Projector{D, T, AT<:(AbstractArrayReg{D, T})} <: PrimitiveBlock{D}

Projection operator to target state psi.

Definition

projector(s) defines the following operator.

\[|s⟩ → |s⟩⟨s|\]

ReflectGate{D, T, Tt, AT<:AbstractArrayReg{D, T}} = TimeEvolution{D,Tt,Projector{D,T,AT}}

Let |v⟩ be a quantum state vector, a reflection gate is a unitary operator that defined as the following operation.

\[|v⟩ → 1 - (1-exp(-iθ)) |v⟩⟨v|\]

When $θ = π$, it defines a standard reflection gate $1-2|v⟩⟨v|$.

RotationGate{D,T,GT<:AbstractBlock{D}} <: PrimitiveBlock{D}

RotationGate, with GT both hermitian and isreflexive.

Definition

Expression rot(G, θ) defines the following gate

\[\cos \frac{\theta}{2}I - i \sin \frac{\theta}{2} G\]

ShiftGate <: PrimitiveBlock

Phase shift gate.

TimeEvolution{D, TT, GT} <: PrimitiveBlock{D}

TimeEvolution, where GT is block type. input matrix should be hermitian.

@const_gate <gate name> = <expr>
@const_gate <gate name>::<type> = <expr>
@const_gate <gate>::<type>

This macro simplify the definition of a constant gate. It will automatically bind the matrix form to a constant which will reduce memory allocation in the runtime.

Examples

@const_gate X = ComplexF64[0 1;1 0]

or

@const_gate X::ComplexF64 = [0 1;1 0]

You can bind new element types by simply re-declare with a type annotation.

@const_gate X::ComplexF32

AbstractAdd{D} <: CompositeBlock{D}

The abstract add interface, aimed to support Hamiltonian types.

Required Interfaces

• chsubblocks
• subblocks

Provides

• unsafe_apply! and its backward
• mat and its backward
• adjoint
• occupied_locs
• getindex over dit strings
• ishermitian

Add{D} <: AbstractAdd{D}
Add(blocks::AbstractBlock...) -> Add

Type for block addition.

julia> X + X
nqubits: 1
+
├─ X
└─ X

CachedBlock{ST, BT, D} <: TagBlock{BT, D}

A label type that tags an instance of type BT. It forwards every methods of the block it contains, except mat and apply!, it will cache the matrix form whenever the program has.

ChainBlock{D} <: CompositeBlock{D}

ChainBlock is a basic construct tool to create user defined blocks horizontically. It is a Vector like composite type.

A control block is a composite block that applies a block when the control qubits are all ones.

Fields

• n::Int64

• ctrl_locs::NTuple{C, Int64} where C

• ctrl_config::NTuple{C, Int64} where C

• content::AbstractBlock

• locs::NTuple{M, Int64} where M

Daggered{BT, D} <: TagBlock{BT,D}

Wrapper block allowing to execute the inverse of a block of quantum circuit.

Daggered(block)

Create a Daggered block. Let $G$ be a input block, G' or Daggered(block) in code represents $G^\dagger$.

Examples

The inverse QFT is not hermitian, thus it will be tagged with a Daggered block.

julia> A(i, j) = control(i, j=>shift(2π/(1<<(i-j+1))));

julia> B(n, i) = chain(n, i==j ? put(i=>H) : A(j, i) for j in i:n);

julia> qft(n) = chain(B(n, i) for i in 1:n);

julia> struct QFT <: PrimitiveBlock{2} n::Int end

julia> YaoBlocks.nqudits(q::QFT) = q.n


julia> circuit(q::QFT) = qft(nqubits(q));

julia> YaoBlocks.mat(x::QFT) = mat(circuit(x));

julia> QFT(2)'
 [†]QFT

KronBlock{D,M,MT<:NTuple{M,Any}} <: CompositeBlock{D}

composite block that combine blocks by kronecker product.

OnLevels{D, Ds, T <: AbstractBlock{Ds}} <: TagBlock{T, D}

Define a gate that is applied to a subset of levels.

Fields

• gate: the gate to be applied.
• levels: the levels to apply the gate to.

PSwap = PutBlock{2,2,RotationGate{2,T,G}} where {G<:ConstGate.SWAPGate}
PSwap(n::Int, locs::Tuple{Int,Int}, θ::Real)

Parametrized swap gate that swaps two qubits with a phase, defined as

\[{\rm SWAP}(θ) = e^{-iθ{\rm SWAP}/2}\]

PutBlock{D,C,GT<:AbstractBlock} <: AbstractContainer{GT,D}

Type for putting a block at given locations.

RepeatedBlock{D,C,GT<:AbstractBlock} <: AbstractContainer{GT,D}

Repeat the same block on given locations.

Scale{S <: Union{Number, Val}, D, BT <: AbstractBlock{D}} <: TagBlock{BT, D}
Scale(factor, block)

Multiply a block with a scalar factor, which can be a number or a Val. If the factor is a number, it is regarded as a parameter that can be changed dynamically. If the factor is a Val, it is regarded as a constant.

Examples

julia> 2 * X
[scale: 2] X

julia> im * Z
[+im] Z

julia> -im * Z
[-im] Z

julia> -Z
[-] Z

Subroutine{D, BT <: AbstractBlock, C} <: AbstractContainer{BT, D}

Subroutine node on given locations. This allows you to shoehorn a smaller circuit to a larger one.

Swap = PutBlock{2,2,G} where {G<:ConstGate.SWAPGate}
Swap(n::Int, locs::Tuple{Int,Int})

Swap gate, which swaps two qubits.

unsafe_apply!(r, block)

Similar to apply!, but will not check the size of the register and block, this is mainly used for overloading new blocks, use at your own risk.

apply!(register, block)

Apply a block (of quantum circuit) to a quantum register.

Examples

julia> r = zero_state(2)
ArrayReg{2, ComplexF64, Array...}
    active qubits: 2/2
    nlevel: 2

julia> apply!(r, put(2, 1=>X))
ArrayReg{2, ComplexF64, Array...}
    active qubits: 2/2
    nlevel: 2

julia> measure(r;nshots=10)
10-element Vector{DitStr{2, 2, Int64}}:
 01 ₍₂₎
 01 ₍₂₎
 01 ₍₂₎
 01 ₍₂₎
 01 ₍₂₎
 01 ₍₂₎
 01 ₍₂₎
 01 ₍₂₎
 01 ₍₂₎
 01 ₍₂₎

apply(register, block)

The non-inplace version of applying a block (of quantum circuit) to a quantum register. Check apply! for the faster inplace version.

niparam(block) -> Int

Return number of intrinsic parameters in block. See also nparameters.

Examples

julia> niparams(Rx(0.1))
1

getiparams(block)

Returns the intrinsic parameters of node block, default is an empty tuple.

Examples

julia> getiparams(Rx(0.1))
0.1

render_params(r::AbstractBlock, params)

This function renders the input parameter to a consumable type to r. params can be a number or a symbol like :zero and :random.

Examples

julia> collect(render_params(Rx(0.1), :zero))
1-element Vector{Float64}:
 0.0

nparameters(block) -> Int

Return number of parameters in block. See also niparams.

Examples

julia> nparameters(chain(Rx(0.1), Rz(0.2)))
2

occupied_locs(x)

Return a tuple of occupied locations of x.

Examples

julia> occupied_locs(kron(5, 1=>X, 3=>X))
(1, 3)

julia> occupied_locs(kron(5, 1=>X, 3=>I2))
(1,)

print_block(io, block)

Define how blocks are printed as text in one line.

Examples

julia> print_block(stdout, X)
X

julia> print_block(stdout, put(2, 1=>X))
put on (1)

apply_back!((ψ, ∂L/∂ψ*), circuit::AbstractBlock, collector) -> AbstractRegister

back propagate and calculate the gradient ∂L/∂θ = 2Re(∂L/∂ψ⋅∂ψ/∂θ), given ∂L/∂ψ. ψ is the output register, ∂L/∂ψ* should also be register type.

Note: gradients are stored in Diff blocks, it can be access by either diffblock.grad or gradient(circuit). Note2: now apply_back! returns the inversed gradient!

mat_back!(T, rb::AbstractBlock, adjy, collector)

Back propagate the matrix gradients.

|>(register, circuit) -> register

Apply a quantum circuits to register, which modifies the register directly.

Example

julia> arrayreg(bit"0") |> X |> Y

kron(n, locs_and_blocks::Pair{<:Any, <:AbstractBlock}...) -> KronBlock

Returns a n-qudit KronBlock. The inputs contains a list of location-block pairs, where a location can be an integer or a range. It is conceptually a chain of put block without address conflicts, but it has a richer type information that can be useful for various purposes such as more efficient mat function.

Let $I$ be a $2\times 2$ identity matrix, $G$ and $H$ be two $2\times 2$ matrix, the matrix representation of kron(n, i=>G, j=>H) (assume $j > i$) is defined as

\[I^{\otimes n-j} \otimes H \otimes I^{\otimes j-i-1} \otimes G \otimes I^{i-1}\]

For multiple locations, the expression can be complicated.

Examples

Use kron to construct a KronBlock, it will put an X gate on the 1st qubit, and a Y gate on the 3rd qubit.

julia> kron(4, 1=>X, 3=>Y)
nqubits: 4
kron
├─ 1=>X
└─ 3=>Y

kron(blocks::AbstractBlock...)
kron(n, itr)

Return a KronBlock, with total number of qubits n, and blocks should use all the locations on n wires in quantum circuits.

Examples

You can use kronecker product to composite small blocks to a large blocks.

julia> kron(X, Y, Z, Z)
nqubits: 4
kron
├─ 1=>X
├─ 2=>Y
├─ 3=>Z
└─ 4=>Z

kron(blocks...) -> f(n)
kron(itr) -> f(n)

Return a lambda, which will take the total number of qubits as input.

Examples

If you don't know the number of qubit yet, or you are just too lazy, it is fine.

julia> kron(put(1=>X) for _ in 1:2)
(n -> kron(n, ((n  ->  put(n, 1 => X)), (n  ->  put(n, 1 => X)))...))

julia> kron(X for _ in 1:2)
nqubits: 2
kron
├─ 1=>X
└─ 2=>X

julia> kron(1=>X, 3=>Y)
(n -> kron(n, (1 => X, 3 => Y)...))

repeat(x::AbstractBlock, locs)

Lazy curried version of repeat.

repeat(n, subblock::AbstractBlock[, locs]) -> RepeatedBlock{n}

Create a n-qudit RepeatedBlock block, which is conceptually a [kron] block with all gates being the same. If locs is provided, repeat on locs, otherwise repeat on all locations. Let $G$ be a $2\times 2$ matrix, the matrix representation of repeat(n, X) is

\[X^{\otimes n}\]

The RepeatedBlock can be used to accelerate repeated applying certain gate types: X, Y, Z, S, T, Sdag, and Tdag.

Examples

This will create a repeat block which puts 4 X gates on each location.

julia> repeat(4, X)
nqubits: 4
repeat on (1, 2, 3, 4)
└─ X

You can also specify the location

julia> repeat(4, X, (1, 2))
nqubits: 4
repeat on (1, 2)
└─ X

But repeat won't copy the gate, thus, if it is a gate with parameter, e.g a phase(0.1), the parameter will change simultaneously.

julia> g = repeat(4, phase(0.1))
nqubits: 4
repeat on (1, 2, 3, 4)
└─ phase(0.1)

julia> g.content
phase(0.1)

julia> g.content.theta = 0.2
0.2

julia> g
nqubits: 4
repeat on (1, 2, 3, 4)
└─ phase(0.2)

Repeat over certain gates will provide speed up.

julia> reg = rand_state(20);

julia> @time apply!(reg, repeat(20, X));
  0.002252 seconds (5 allocations: 656 bytes)

julia> @time apply!(reg, chain([put(20, i=>X) for i=1:20]));
  0.049362 seconds (82.48 k allocations: 4.694 MiB, 47.11% compilation time)

ishermitian(op::AbstractBlock) -> Bool

Returns true if op is hermitian.

chcontent(x, blk)

Create a similar block of x and change its content to blk.

chsubblocks(composite_block, itr)

Change the sub-blocks of a CompositeBlock with given iterator itr.

content(x)

Returns the content of x.

dispatch!(x::AbstractBlock, collection)

Dispatch parameters in collection to block tree x.

expect(op::AbstractBlock, reg) -> Real
expect(op::AbstractBlock, reg => circuit) -> Real
expect(op::AbstractBlock, density_matrix) -> Real

Get the expectation value of an operator, the second parameter can be a register reg or a pair of input register and circuit reg => circuit.

expect'(op::AbstractBlock, reg=>circuit) -> Pair expect'(op::AbstractBlock, reg) -> AbstracRegister

Obtain the gradient with respect to registers and circuit parameters. For pair input, the second return value is a pair of gψ=>gparams, with gψ the gradient of input state and gparams the gradients of circuit parameters. For register input, the return value is a register.

getiparams(block)

Returns the intrinsic parameters of node block, default is an empty tuple.

iparams_eltype(block)

Return the element type of getiparams.

mat([T=ComplexF64], blk)

Returns the matrix form of given block.

mat(A::GeneralMatrixBlock)

Return the matrix of general matrix block.

operator_fidelity(b1::AbstractBlock, b2::AbstractBlock) -> Number

Operator fidelity defined as

\[F^2 = \frac{1}{d}\left[{\rm Tr}(b1^\dagger b2)\right]\]

Here, d is the size of the Hilbert space. Note this quantity is independant to global phase. See arXiv: 0803.2940v2, Equation (2) for reference.

parameters(block)

Returns all the parameters contained in block tree with given root block.

parameters_eltype(x)

Return the element type of parameters.

setiparams!([f], block, itr)
setiparams!([f], block, params...)

Set the parameters of block. When f is provided, set parameters of block to the value in collection mapped by f. iter can be an iterator or a symbol, the symbol can be :zero, :random.

subblocks(x)

Returns an iterator of the sub-blocks of a composite block. Default is empty.

Rx(theta)

Return a RotationGate on X axis.

Example

julia> Rx(0.1)
rot(X, 0.1)

Ry(theta)

Return a RotationGate on Y axis.

Example

julia> Ry(0.1)
rot(Y, 0.1)

Rz(theta)

Return a RotationGate on Z axis.

Example

julia> Rz(0.1)
rot(Z, 0.1)

apply(register, block)

The non-inplace version of applying a block (of quantum circuit) to a quantum register. Check apply! for the faster inplace version.

applymatrix(g::AbstractBlock) -> Matrix

Transform the apply! function of specific block to dense matrix.

cache(x[, level=1; recursive=false])

Create a CachedBlock with given block x, which will cache the matrix of x for the first time it calls mat, and use the cached matrix in the following calculations.

Examples

julia> cache(control(3, 1, 2=>X))
nqubits: 3
[cached] control(1)
   └─ (2,) X


julia> chain(cache(control(3, 1, 2=>X)), repeat(H))
nqubits: 3
chain
├─ [cached] control(1)
│     └─ (2,) X
└─ repeat on (1, 2, 3)
   └─ H

cache_key(block)

Returns the key that identify the matrix cache of this block. By default, we use the returns of parameters as its key.

cache_type(::Type) -> DataType

Return the element type that a CacheFragment will use.

chain(n)

Return an empty ChainBlock which can be used like a list of blocks.

Examples

julia> chain(2)
nqubits: 2
chain


julia> chain(2; nlevel=3)
nqudits: 2
chain

chain()

Return an lambda n->chain(n).

chain(blocks...) -> ChainBlock
chain(n) -> ChainBlock

Return a ChainBlock which chains a list of blocks with the same number of qudits. Let $G_i$ be a sequence of n-qudit blocks, the matrix representation of block chain(G_1, G_2, ..., G_m) is

\[G_m G_{m-1}\ldots G_1\]

It is almost equivalent to matrix multiplication except the order is reversed. We make its order different from regular matrix multiplication because quantum circuits can be represented more naturally in this form.

Examples

julia> chain(X, Y, Z)
nqubits: 1
chain
├─ X
├─ Y
└─ Z

julia> chain(2, put(1=>X), put(2=>Y), cnot(2, 1))
nqubits: 2
chain
├─ put on (1)
│  └─ X
├─ put on (2)
│  └─ Y
└─ control(2)
   └─ (1,) X

chmeasureoperator(m::Measure, op::AbstractBlock)

change the measuring operator. It will also discard existing measuring results.

cleanup(entries::EntryTable; zero_threshold=0.0)

Clean up the entry table by 1) sort entries, 2) merge items and 3) clean up zeros. Any value with amplitude ≤ zero_threshold will be regarded as zero.

julia> et = EntryTable([bit"000",bit"011",bit"101",bit"101",bit"011",bit"110",bit"110",bit"011",], [1.0 + 0.0im,-1, 1,1,1,-1,1,1,-1])
EntryTable{DitStr{2, 3, Int64}, ComplexF64}:
  000 ₍₂₎   1.0 + 0.0im
  011 ₍₂₎   -1.0 + 0.0im
  101 ₍₂₎   1.0 + 0.0im
  101 ₍₂₎   1.0 + 0.0im
  011 ₍₂₎   1.0 + 0.0im
  110 ₍₂₎   -1.0 + 0.0im
  110 ₍₂₎   1.0 + 0.0im
  011 ₍₂₎   1.0 + 0.0im


julia> cleanup(et)
EntryTable{DitStr{2, 3, Int64}, ComplexF64}:
  000 ₍₂₎   1.0 + 0.0im
  011 ₍₂₎   1.0 + 0.0im
  101 ₍₂₎   2.0 + 0.0im

cnot([n, ]ctrl_locs, location)

Return a speical ControlBlock, aka CNOT gate with number of active qubits n and locs of control qubits ctrl_locs, and location of X gate.

Examples

julia> cnot(3, (2, 3), 1)
nqubits: 3
control(2, 3)
└─ (1,) X

julia> cnot(2, 1)
(n -> cnot(n, 2, 1))

collect_blocks(block_type, root)

Return a ChainBlock with all block of block_type in root.

control(ctrl_locs, target) -> f(n)

Return a lambda that takes the number of total active qubits as input. See also control.

Examples

julia> control((2, 3), 1=>X)
(n -> control(n, (2, 3), 1 => X))

julia> control(2, 1=>X)
(n -> control(n, 2, 1 => X))

control(n, ctrl_locs, locations => subblock)

Return a n-qubit ControlBlock, where the control locations ctrl_locs and the subblock locations in the third argument can be an integer, a tuple or a range, and the size of the subblock should match the length of locations. Let $I$ be the $2 \times 2$ identity matrix, $G$ be a $2 \times 2$ subblock, $P_0=|0\rangle\langle 0|$ and $P_1=|1\rangle\langle 1|$ be two single qubit projection operators to subspace $|0\rangle$ and $|1\rangle$, $i$ and $j$ be two integers that $i>j$. The matrix representation of control(n, i, j=>G) is

\[\begin{align} &I^{\otimes n-i} P_0 \otimes I^{\otimes i-j-1} \otimes I\otimes I^{\otimes j-1} +\\ & I^{\otimes n-i} P_1 \otimes I^{\otimes i-j-1} \otimes G\otimes I^{\otimes j-1} \end{align}\]

The multi-controlled multi-qubit controlled block is more complicated, it means apply the gate when control qubits are all ones. Each control location can take a negative sign to represent the inverse control, meaning only when this qubit is 0, the controlled gate is applied.

Examples

julia> control(4, (1, 2), 3=>X)
nqubits: 4
control(1, 2)
└─ (3,) X

julia> control(4, 1, 3=>X)
nqubits: 4
control(1)
└─ (3,) X

cunmat(nbit::Int, cbits::NTuple{C, Int}, cvals::NTuple{C, Int}, U0::AbstractMatrix, locs::NTuple{M, Int}) where {C, M} -> AbstractMatrix

control-unitary matrix

cz([n, ]ctrl_locs, location)

Return a special ControlBlock, aka CZ gate with number of active qubits n and locs of control qubits ctrl_locs, and location of Z gate. See also cnot.

Examples

julia> cz(2, 1, 2)
nqubits: 2
control(1)
└─ (2,) Z

decode_sign(ctrls...)

Decode signs into control sequence on control or inversed control.

dispatch(x::AbstractBlock, collection)

Dispatch parameters in collection to block tree x, the generic non-inplace version.

dump_gate(blk::AbstractBlock) -> Expr

convert a gate to a YaoScript expression for serization. The fallback is GateTypeName(fields...)

eigenbasis(op::AbstractBlock)

Return the eigenvalue and eigenvectors of target operator. By applying eigenvector' to target state, one can swith the basis to the eigenbasis of this operator. However, eigenvalues does not have a specific form.

gate_expr(::Val{G}, args, info)

Obtain the gate constructior from its YaoScript expression. G is a symbol for the gate type, the default constructor is G(args...). info contains the informations about the number of qubit and Yao version.

getcol(csc::SDparseMatrixCSC, icol::Int) -> (View, View)

get specific col of a CSC matrix, returns a slice of (rowval, nzval)

igate(n::Int; nlevel=2)

The constructor for IdentityGate. Let $I_d$ be a $d \times d$ identity matrix, igate(n; nlevel=d) is defined as $I_d^{\otimes n}$.

Examples

julia> igate(2)
igate(2)

julia> igate(2; nlevel=3)
igate(2;nlevel=3)

isclean(entries::EntryTable; zero_threshold=0.0)

Return true if the entries are ordered, unique and amplitudes are nonzero. Any value with amplitude ≤ zero_threshold will be regarded as zero.

isnoisy(block::AbstractBlock)

Check if a circuit contains any noisy channel.

map_address(block::AbstractBlock, info::AddressInfo) -> AbstractBlock

map the locations in block to target locations.

Example

map_address can be used to embed a sub-circuit to a larger one.

julia> c = chain(5, repeat(H, 1:5), put(2=>X), kron(1=>X, 3=>Y))
nqubits: 5
chain
├─ repeat on (1, 2, 3, 4, 5)
│  └─ H
├─ put on (2)
│  └─ X
└─ kron
   ├─ 1=>X
   └─ 3=>Y


julia> map_address(c, AddressInfo(10, [6,7,8,9,10]))
nqubits: 10
chain
├─ repeat on (6, 7, 8, 9, 10)
│  └─ H
├─ put on (7)
│  └─ X
└─ kron
   ├─ 6=>X
   └─ 8=>Y

matblock(mat_or_block; nlevel=2, tag="matblock(...)")

Create a GeneralMatrixBlock with a matrix m.

Examples

julia> matblock(ComplexF64[0 1;1 0])
matblock(...)

!!!warn

Instead of converting it to the default data type `ComplexF64`,
this will return its contained matrix when calling `mat`.

noisy_simulation(reg::ArrayReg, circuit::AbstractBlock)

Simulate a circuit with noise.

Arguments

• reg::ArrayReg: the initial state of the system.
• circuit::AbstractBlock: the circuit to simulate.

Returns

• DensityMatrix: the final state of the system.

Examples

Add noise after each single-qubit gate and simulate the circuit.

julia> circ = Optimise.replace_block(chain(2, put(1=>X), control(2, 1=>X))) do block
           n = nqubits(block)
           if block isa PutBlock && length(block.locs) == 1
               return chain(block, put(n, block.locs => quantum_channel(BitFlipError(0.1))))  # add noise after each single-qubit gate
           elseif block isa ControlBlock && length(block.ctrl_locs) == 1 && length(block.locs) == 1
               return chain(block, put(n, (block.ctrl_locs..., block.locs...) => kron(quantum_channel(BitFlipError(0.1)), quantum_channel(BitFlipError(0.1)))))  # add noise after each control gate
           else
               return block
           end
       end
nqubits: 2
chain
├─ chain
│  ├─ put on (1)
│  │  └─ X
│  └─ put on (1)
│     └─ mixed_unitary_channel
│        ├─ [0.9] I2
│        └─ [0.1] X
└─ chain
   ├─ control(2)
   │  └─ (1,) X
   └─ put on (2, 1)
      └─ mixed_unitary_channel
         ├─ [0.81] kron
         │  ├─ 1=>I2
         │  └─ 2=>I2
         ├─ [0.09000000000000001] kron
         │  ├─ 1=>I2
         │  └─ 2=>X
         ├─ [0.09000000000000001] kron
         │  ├─ 1=>X
         │  └─ 2=>I2
         └─ [0.010000000000000002] kron
            ├─ 1=>X
            └─ 2=>X

julia> noisy_simulation(zero_state(2), circ)
DensityMatrix{2, ComplexF64, Array...}
    active qubits: 2/2
    nlevel: 2

num_nonzero(nbits, nctrls, U, [N])

Return number of nonzero entries of the matrix form of control-U gate. nbits is the number of qubits, and nctrls is the number of control qubits.

parameters!(out, block)

Append all the parameters contained in block tree with given root block to out.

parameters_range(block)

Return the range of real parameters present in block.

Example

julia> YaoBlocks.parameters_range(RotationGate(X, 0.1))
1-element Vector{Tuple{Float64, Float64}}:
 (0.0, 6.283185307179586)

parse_block(n, ex)

This function parse the julia object ex to a quantum block, it defines the syntax of high level interfaces. ex can be a function takes number of qubits n as input or it can be a pair.

paulipropagation2yao(n::Int, circ::AbstractVector{Gate}, thetas::AbstractVector)
paulipropagation2yao(pc::PauliCircuit)

Convert a Pauli propagation circuit to a Yao circuit. You must using PauliPropagation before using this function.

Arguments

• n::Int: Number of qubits.
• circ::AbstractVector{Gate}: Pauli propagation circuit.
• thetas::AbstractVector: Vector of parameters.

Or:

• pc::PauliCircuit: A PauliCircuit intermediate representation.

phase(theta)

Returns a global phase gate. Defined with following matrix form:

\[e^{iθ} I\]

Examples

You can create a global phase gate with a phase (a real number).

julia> phase(0.1)
phase(0.1)

popdispatch!(block, list)

Pop the first nparameters parameters of list, then dispatch them to the block tree block. See also dispatch!.

popdispatch!(f, block, list)

Pop the first nparameters parameters of list, map them with a function f, then dispatch them to the block tree block. See also dispatch!.

postwalk(f, src::AbstractBlock)

Walk the tree and call f after the children are visited.

prewalk(f, src::AbstractBlock)

Walk the tree and call f once the node is visited.

print_annotation(io, root, node, child, k)

Print the annotation of k-th child of node, aka the k-th element of subblocks(node).

print_prefix(io, depth, charset, active_levels)

print prefix of a tree node in a single line.

print_subtypetree(::Type[, level=1, indent=4])

Print subtype tree, level specify the depth of the tree.

print_title(io, block)

Print the title of given block of an AbstractBlock.

print_tree(io, root, node[, depth=1, active_levels=()]; kwargs...)

Print the block tree.

Keywords

• maxdepth: max tree depth to print
• charset: default is ('├','└','│','─'). See also YaoBlocks.BlockTreeCharSet.
• title: control whether to print the title, true or false, default is true

print_tree([io=stdout], root)

Print the block tree.

projection(y::AbstractMatrix, op::AbstractMatrix) -> typeof(y)

Project op to sparse matrix with same sparsity as y.

projector(v::AbstractArrayReg) -> Projector

Create a Projector with an quantum state vector v.

Example

julia> projector(rand_state(3))
|s⟩⟨s|, nqudits = 3

projector(x)

Return projector on 0 or projector on 1.

pswap(n::Int, i::Int, j::Int, α::Real)
pswap(i::Int, j::Int, α::Real) -> f(n)

parametrized swap gate.

Examples

julia> pswap(2, 1, 2, 0.1)
nqubits: 2
put on (1, 2)
└─ rot(SWAP, 0.1)

put(pair) -> f(n)

Lazy curried version of put.

Examples

julia> put(1=>X)
(n -> put(n, 1 => X))

put(n::Int, locations => subblock) => PutBlock

Create a n-qudit PutBlock. The second argument is a pair of locations and subblock, where the locations can be a tuple, an integer or a range and the subblock size should match the length of locations. Let $I$ be a $2\times 2$ identity matrix and $G$ be a $2\times 2$ matrix, the matrix representation of put(n, i=>G) is defined as

\[I^{\otimes n-i} \otimes G \otimes I^{\otimes i-1}\]

For multiple locations, the expression can be complicated, which corresponds to the matrix representation of multi-qubit gate applied on n-qubit space in quantum computing.

Examples

julia> put(4, 1=>X)
nqubits: 4
put on (1)
└─ X

If you want to put a multi-qubit gate on specific locations, you need to write down all possible locations.

julia> put(4, (1, 3)=>kron(X, Y))
nqubits: 4
put on (1, 3)
└─ kron
   ├─ 1=>X
   └─ 2=>Y

The outter locations creates a scope which make it seems to be a contiguous two qubits for the block inside PutBlock.

quantum_channel(error::AbstractErrorType)

Convert an error type to a quantum channel. The output type can be KrausChannel, MixedUnitaryChannel.

rand_hermitian([T=ComplexF64], N::Int) -> Matrix

Create a random hermitian matrix.

julia> ishermitian(rand_hermitian(2))
true

rand_unitary([T=ComplexF64], N::Int) -> Matrix

Create a random unitary matrix.

Examples

julia> isunitary(rand_unitary(2))
true

julia> eltype(rand_unitary(ComplexF32, 2))
ComplexF32 (alias for Complex{Float32})

reflect(
    v::AbstractArrayReg
) -> ReflectGate{D, T, Irrational{:π}, AT} where {D, T, AT<:(AbstractArrayReg{D, T})}
reflect(
    v::AbstractArrayReg,
    θ::Real
) -> ReflectGate{_A, T, Tt, AT} where {_A, Tt<:Real, T, AT<:(AbstractArrayReg{_A, T})}

Create a ReflectGate with respect to an quantum state vector v.

Example

julia> reflect(rand_state(3))
Time Evolution Δt = π, tol = 1.0e-7
|s⟩⟨s|, nqudits = 3

rmlines(ex)

Remove LineNumberNode from an Expr.

rot(U, theta)

Return a RotationGate on U axis.

sandwich(bra::AbstractRegister, op::AbstractBlock, ket::AbstracRegister) -> Complex

Compute the sandwich function ⟨bra|op|ket⟩.

setcol!(csc::SparseMatrixCSC, icol::Int, rowval::AbstractVector, nzval) -> SparseMatrixCSC

set specific col of a CSC matrix

setiparams([f], block, itr)
setiparams([f], block, params...)

Set the parameters of block, the non-inplace version. When f is provided, set parameters of block to the value in collection mapped by f. iter can be an iterator or a symbol, the symbol can be :zero, :random.

shift(θ)

Create a ShiftGate with phase θ.

\[\begin{pmatrix} 1 & 0\\ 0 & e^{i\theta} \end{pmatrix}\]

Examples

julia> shift(0.1)
shift(0.1)

Return true if operators commute to each other.

sprand_hermitian([T=ComplexF64], N, density)

Create a sparse random hermitian matrix.

sprand_unitary([T=ComplexF64], N::Int, density) -> SparseMatrixCSC

Create a random sparse unitary matrix.

subroutine(block, locs) -> f(n)

Lazy curried version of subroutine.

subroutine(n, block, locs)

Create a n-qudit Subroutine block, where the subblock is a subprogram of size m, and locs is a tuple or range of length m. It runs a quantum subprogram with smaller size on a subset of locations. While its mathematical definition is the same as the put block, while it is more suited for running a larger chunk of circuit.

Examples

Subroutine is equivalent to put a block on given position mathematically, but more efficient and convenient for large blocks.

julia> r = rand_state(3)
ArrayReg{2, ComplexF64, Array...}
    active qubits: 3/3
    nlevel: 2

julia> apply!(copy(r), subroutine(X, 1)) ≈ apply!(copy(r), put(1=>X))
true

It works for in-contigious locs as well

julia> r = rand_state(4)
ArrayReg{2, ComplexF64, Array...}
    active qubits: 4/4
    nlevel: 2

julia> cc = subroutine(4, kron(X, Y), (1, 3))
nqubits: 4
Subroutine: (1, 3)
└─ kron
   ├─ 1=>X
   └─ 2=>Y

julia> pp = chain(4, put(1=>X), put(3=>Y))
nqubits: 4
chain
├─ put on (1)
│  └─ X
└─ put on (3)
   └─ Y

julia> apply!(copy(r), cc) ≈ apply!(copy(r), pp)
true

swap(n, loc1, loc2)

Create a n-qubit Swap gate which swap loc1 and loc2.

Examples

julia> swap(4, 1, 2)
nqubits: 4
put on (1, 2)
└─ SWAP

swap(loc1, loc2) -> f(n)

Create a lambda that takes the total number of active qubits as input. Lazy curried version of swap(n, loc1, loc2). See also Swap.

Examples

julia> swap(1, 2)
(n -> swap(n, 1, 2))

time_evolve(H, dt[; tol=1e-7, check_hermicity=true])

Create a TimeEvolution block with Hamiltonian H and time step dt. The TimeEvolution block will use Krylove based expv to calculate time propagation. TimeEvolution block can also be used for imaginary time evolution if dt is complex. Let $H$ be a hamiltonian and $t$ be a time, the matrix representation of time_evolve(H, t) is $e^{-iHt}$.

Arguments

• H the hamiltonian represented as an AbstractBlock.
• dt: the evolution duration (start time is zero).

Keyword Arguments

• tol::Real=1e-7: error tolerance.
• check_hermicity=true: check hermicity or not.

Examples

julia> time_evolve(kron(2, 1=>X, 2=>X), 0.1)
Time Evolution Δt = 0.1, tol = 1.0e-7
kron
├─ 1=>X
└─ 2=>X

u1ij!(target, i, j, a, b, c, d)

single u1 matrix into a target matrix.

unmat(::Val{D}, nbit::Int, U::AbstractMatrix, locs::NTuple) -> AbstractMatrix

Return the matrix representation of putting matrix at locs.

yao2paulipropagation(circ::ChainBlock; observable)

Convert a Yao circuit to a Pauli propagation circuit representation. You must using PauliPropagation before using this function.

Arguments

• circ::ChainBlock: Yao circuit in the form of a chain of basic gates.

Keyword Arguments

• observable: A Yao block specifying the observable to measure (required). Must be a sum of Pauli strings, e.g. kron(5, 2=>X, 3=>X) + 2.0 * kron(5, 1=>Z). Will be converted to a PauliSum.

Returns

• PauliPropagationCircuit: An intermediate representation that can be evaluated with propagate(pc).

@yao_str
yao"..."

The mark up language for quantum circuit.