Blocks
Blocks are the basic building blocks of a quantum circuit in Yao. It simply means a quantum operator, thus, all the blocks have matrices in principal and one can get its matrix by mat
. The basic blocks required to build an arbitrary quantum circuit is defined in the component package YaoBlocks
.
Block Tree serves as an intermediate representation for Yao to analysis, optimize the circuit, then it will be lowered to instructions like for simulations, blocks will be lowered to instruct!
calls.
The structure of blocks is the same with a small type system, it consists of two basic kinds of blocks: CompositeBlock
(like composite types), and PrimitiveBlock
(like primitive types). By combining these two kinds of blocks together, we'll be able to construct a quantum circuit and represent it in a tree data structure.
Primitive Blocks
Primitive blocks are subtypes of PrimitiveBlock
, they are the leaf nodes in a block tree, thus primitive types do not have subtypes.
We provide the following primitive blocks:
YaoBlocks.GeneralMatrixBlock
— TypeGeneralMatrixBlock{D, MT} <: PrimitiveBlock{D}
General matrix gate wraps a matrix operator to quantum gates. This is the most general form of a quantum gate.
YaoBlocks.IdentityGate
— TypeIdentityGate{D} <: TrivialGate{D}
The identity gate.
YaoBlocks.Measure
— TypeMeasure{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)
Measure operator, currently only qudits are supported.
YaoBlocks.Measure
— MethodMeasure(n::Int; rng=Random.GLOBAL_RNG, operator=ComputationalBasis(), locs=AllLocs(), resetto=nothing, remove=false)
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 ₍₂₎)```
YaoBlocks.PhaseGate
— TypePhaseGate
Global phase gate.
YaoBlocks.RotationGate
— TypeRotationGate{D,T,GT<:AbstractBlock{D}} <: PrimitiveBlock{D}
RotationGate, with GT both hermitian and isreflexive.
Definition
Expression rot(G, θ)
defines the following gate
\[\mathbf{I} \cos(θ / 2) - i \sin(θ / 2) G\]
YaoBlocks.ShiftGate
— TypeShiftGate <: PrimitiveBlock
Phase shift gate.
YaoBlocks.TimeEvolution
— TypeTimeEvolution{D, TT, GT} <: PrimitiveBlock{D}
TimeEvolution, where GT is block type. input matrix should be hermitian.
TimeEvolution
contructor check hermicity of the input block by default, but sometimes it can be slow. Turn off the check manually by specifying optional parameter check_hermicity = false
.
Composite Blocks
Composite blocks are subtypes of CompositeBlock
, they are the composition of blocks.
We provide the following composite blocks:
YaoBlocks.Add
— TypeAdd{D} <: CompositeBlock{D}
Add(blocks::AbstractBlock...) -> Add
Type for block addition.
julia> X + X
nqubits: 1
+
├─ X
└─ X
YaoBlocks.CachedBlock
— TypeCachedBlock{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.
YaoBlocks.ChainBlock
— TypeChainBlock{D} <: CompositeBlock{D}
ChainBlock
is a basic construct tool to create user defined blocks horizontically. It is a Vector
like composite type.
YaoBlocks.Daggered
— TypeDaggered{BT, D} <: TagBlock{BT,D}
Wrapper block allowing to execute the inverse of a block of quantum circuit.
YaoBlocks.Daggered
— MethodDaggered(x)
Create a Daggered
block with given block x
.
Example
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
YaoBlocks.KronBlock
— TypeKronBlock{D,M,MT<:NTuple{M,Any}} <: CompositeBlock{D}
composite block that combine blocks by kronecker product.
YaoBlocks.PutBlock
— TypePutBlock{D,C,GT<:AbstractBlock} <: AbstractContainer{GT,D}
Type for putting a block at given locations.
YaoBlocks.RepeatedBlock
— TypeRepeatedBlock{D,C,GT<:AbstractBlock} <: AbstractContainer{GT,D}
Repeat the same block on given locations.
YaoBlocks.Scale
— TypeScale{S <: Union{Number, Val}, D, BT <: AbstractBlock{D}} <: TagBlock{BT, D}
Scale
a block with scalar. it can be either a Number
or a compile time Val
.
Example
julia> 2 * X
[scale: 2] X
julia> im * Z
[+im] Z
julia> -im * Z
[-im] Z
julia> -Z
[-] Z
YaoBlocks.Subroutine
— TypeSubroutine{D, BT <: AbstractBlock, C} <: AbstractContainer{BT, D}
Subroutine node on given locations. This allows you to shoehorn a smaller circuit to a larger one.
YaoBlocks.UnitaryChannel
— TypeUnitaryChannel(operators[, weights])
Create a unitary channel, optionally weighted from an list of weights. The unitary channel is defined as below in Kraus representation
\[ϕ(ρ) = \sum_i U_i ρ U_i^†\]
Unitary channel will only normalize the weights when calculating the matrix form, thus you should be careful when you need this condition for other purpose.
when applying a UnitaryChannel
on the register, a unitary will be sampled uniformly or optionally from given weights, then this unitary will be applied to the register.
Examples
julia> UnitaryChannel([X, Y, Z])
nqubits: 1
unitary_channel
├─ [1.0] X
├─ [1.0] Y
└─ [1.0] Z
Or with weights
julia> UnitaryChannel([X, Y, Z], [0.1, 0.2, 0.7])
nqubits: 1
unitary_channel
├─ [0.1] X
├─ [0.2] Y
└─ [0.7] Z
Error and Exceptions
YaoBlocks.islocs_conflict
— Methodislocs_conflict(locs) -> Bool
Check if the input locations has conflicts.
YaoBlocks.islocs_inbounds
— Methodislocs_inbounds(n, locs) -> Bool
Check if the input locations are inside given bounds n
.
YaoBlocks.@assert_locs_inbounds
— Macro@assert_locs_inbounds <number of total qudits> <locations list> [<msg>]
Assert if all the locations are inbounds.
YaoBlocks.@assert_locs_safe
— Macro@assert_locs_safe <number of total qudits> <locations list> [<msg>]
Assert if all the locations are: - inbounds. - do not have any conflict.
Extending Blocks
Blocks are defined as a sub-type system inside Julia, you could extend it by defining new Julia types by subtyping abstract types we provide. But we also provide some handy tools to help you create your own blocks.
Define Custom Constant Blocks
Constant blocks are used quite often and in numerical simulation we would expect it to be a real constant in the program, which means it won't allocate new memory when we try to get its matrix for several times, and it won't change with parameters.
In Yao, you can simply define a constant block with @const_gate
, with the corresponding matrix:
julia> @const_gate Rand = rand(ComplexF64, 4, 4)
This will automatically create a type RandGate{T}
and a constant binding Rand
to the instance of RandGate{ComplexF64}
, and it will also bind a Julia constant for the given matrix, so when you call mat(Rand)
, no allocation will happen.
julia> @allocated mat(Rand)
ERROR: UndefVarError: mat not defined
If you want to use other data type like ComplexF32
, you could directly call Rand(ComplexF32)
, which will create a new instance with data type ComplexF32
.
julia> Rand(ComplexF32)
ERROR: UndefVarError: Rand not defined
But remember this won't bind the matrix, it only binds the matrix you give
julia> @allocated mat(Rand(ComplexF32))
ERROR: UndefVarError: Rand not defined
so if you want to make the matrix call mat
for ComplexF32
to have zero allocation as well, you need to do it explicitly.
julia> @const_gate Rand::ComplexF32
ERROR: LoadError: UndefVarError: @const_gate not defined in expression starting at REPL[1]:1
Define Custom Blocks
Primitive blocks are the most basic block to build a quantum circuit, if a primitive block has a certain structure, like containing tweakable parameters, it cannot be defined as a constant, thus create a new type by subtyping PrimitiveBlock
is necessary
using YaoBlocks
mutable struct PhaseGate{T <: Real} <: PrimitiveBlock{1}
theta::T
end
If your insterested block is a composition of other blocks, you should define a CompositeBlock
, e.g
struct ChainBlock{N} <: CompositeBlock{N}
blocks::Vector{AbstractBlock{N}}
end
Besides types, there are several interfaces you could define for a block, but don't worry, they should just error if it doesn't work.
Define the matrix
The matrix form of a block is the minimal requirement to make a custom block functional, defining it is super simple, e.g for phase gate:
mat(::Type{T}, gate::PhaseGate) where T = exp(T(im * gate.theta)) * Matrix{Complex{T}}(I, 2, 2)
Or for composite blocks, you could just calculate the matrix by call mat
on its subblocks.
mat(::Type{T}, c::ChainBlock) where T = prod(x->mat(T, x), reverse(c.blocks))
The rest will just work, but might be slow since you didn't define any specification for this certain block.
Define how blocks are applied to registers
Although, having its matrix is already enough for applying a block to register, we could improve the performance or dispatch to other actions by overloading apply!
interface, e.g we can use specialized instruction to make X gate (a builtin gate defined @const_gate
) faster:
function apply!(r::ArrayReg, x::XGate)
nactive(r) == 1 || throw(QubitMismatchError("register size $(nactive(r)) mismatch with block size $N"))
instruct!(matvec(r.state), Val(:X), (1, ))
return r
end
In Yao, this interface allows us to provide more aggressive specialization on different patterns of quantum circuits to accelerate the simulation etc.
Define Parameters
If you want to use some member of the block to be parameters, you need to declare them explicitly
niparams(::Type{<:PhaseGate}) = 1
getiparams(x::PhaseGate) = x.theta
setiparams!(r::PhaseGate, param::Real) = (r.theta = param; r)
Define Adjoint
Since blocks are actually quantum operators, it makes sense to call their adjoint
as well. We provide Daggered
for general purpose, but some blocks may have more specific transformation rules for adjoints, e.g
Base.adjoint(x::PhaseGate) = PhaseGate(-x.theta)
Define Cache Keys
To enable cache, you should define cache_key
, e.g for phase gate, we only cares about its phase, instead of the whole instance
cache_key(gate::PhaseGate) = gate.theta
APIs
Base.:|>
— Method|>(register, circuit) -> register
Apply a quantum circuits to register, which modifies the register directly.
Example
julia> arrayreg(bit"0") |> X |> Y
Base.kron
— Methodkron(n, blocks::Pair{<:Any, <:AbstractBlock}...)
Return a KronBlock
, with total number of qubits n
and pairs of blocks.
Examples
Use kron
to construct a KronBlock
, it will put an X
gate on the 1
st qubit, and a Y
gate on the 3
rd qubit.
julia> kron(4, 1=>X, 3=>Y)
nqubits: 4
kron
├─ 1=>X
└─ 3=>Y
Base.kron
— Methodkron(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
Base.kron
— Methodkron(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)...))
Base.repeat
— Methodrepeat(x::AbstractBlock, locs)
Lazy curried version of repeat
.
Base.repeat
— Methodrepeat(n, x::AbstractBlock[, locs]) -> RepeatedBlock{n}
Create a RepeatedBlock
with total number of qubits n
and the block to repeat on given location or on all the locations.
Example
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)
LinearAlgebra.ishermitian
— Methodishermitian(op::AbstractBlock) -> Bool
Returns true if op
is hermitian.
YaoAPI.chcontent
— Methodchcontent(x, blk)
Create a similar block of x
and change its content to blk.
YaoAPI.chsubblocks
— Methodchsubblocks(composite_block, itr)
Change the sub-blocks of a CompositeBlock
with given iterator itr
.
YaoAPI.content
— Methodcontent(x)
Returns the content of x
.
YaoAPI.dispatch!
— Methoddispatch!(x::AbstractBlock, collection)
Dispatch parameters in collection to block tree x
.
it will try to dispatch the parameters in collection first.
YaoAPI.expect
— Methodexpect(op::AbstractBlock, reg) -> Vector
expect(op::AbstractBlock, reg => circuit) -> Vector
expect(op::AbstractBlock, density_matrix) -> Vector
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.
For batched register, expect(op, reg=>circuit)
returns a vector of size number of batch as output. However, one can not differentiate over a vector loss, so expect'(op, reg=>circuit)
accumulates the gradient over batch, rather than returning a batched gradient of parameters.
YaoAPI.getiparams
— Methodgetiparams(block)
Returns the intrinsic parameters of node block
, default is an empty tuple.
YaoAPI.iparams_eltype
— Methodiparams_eltype(block)
Return the element type of getiparams
.
YaoAPI.mat
— Methodmat([T=ComplexF64], blk)
Returns the matrix form of given block.
YaoAPI.mat
— Methodmat(A::GeneralMatrixBlock)
Return the matrix of general matrix block.
Instead of converting it to the default data type ComplexF64
, this will return its contained matrix.
YaoAPI.operator_fidelity
— Methodoperator_fidelity(b1::AbstractBlock, b2::AbstractBlock) -> Number
Operator fidelity defined as
\[F^2 = \frac{1}{d^2}\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.
YaoAPI.parameters
— Methodparameters(block)
Returns all the parameters contained in block tree with given root block
.
YaoAPI.parameters_eltype
— Methodparameters_eltype(x)
Return the element type of parameters
.
YaoAPI.setiparams!
— Functionsetiparams!([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
.
YaoAPI.subblocks
— Methodsubblocks(x)
Returns an iterator of the sub-blocks of a composite block. Default is empty.
YaoBlocks.Rx
— MethodYaoBlocks.Ry
— MethodYaoBlocks.Rz
— MethodYaoBlocks.apply
— Methodapply(register, block)
The non-inplace version of applying a block (of quantum circuit) to a quantum register. Check apply!
for the faster inplace version.
YaoBlocks.applymatrix
— Methodapplymatrix(g::AbstractBlock) -> Matrix
Transform the apply! function of specific block to dense matrix.
YaoBlocks.cache
— Functioncache(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.
Example
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
YaoBlocks.cache_key
— Methodcache_key(block)
Returns the key that identify the matrix cache of this block. By default, we use the returns of parameters
as its key.
YaoBlocks.cache_type
— Methodcache_type(::Type) -> DataType
Return the element type that a CacheFragment
will use.
YaoBlocks.chain
— Methodchain(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
YaoBlocks.chain
— Methodchain()
Return an lambda n->chain(n)
.
YaoBlocks.chain
— Methodchain(blocks...)
Return a ChainBlock
which chains a list of blocks with same nqudits
. If there is lazy evaluated block in blocks
, chain can infer the number of qudits and create an instance itself.
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
YaoBlocks.chmeasureoperator
— Methodchmeasureoperator(m::Measure, op::AbstractBlock)
change the measuring operator
. It will also discard existing measuring results.
YaoBlocks.cnot
— Methodcnot([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))
YaoBlocks.collect_blocks
— Methodcollect_blocks(block_type, root)
Return a ChainBlock
with all block of block_type
in root.
YaoBlocks.control
— Methodcontrol(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))
YaoBlocks.control
— Methodcontrol(n, ctrl_locs, target)
Return a ControlBlock
with number of active qubits n
and control locs ctrl_locs
, and control target in Pair
.
Example
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
YaoBlocks.cunmat
— Functioncunmat(nbit::Int, cbits::NTuple{C, Int}, cvals::NTuple{C, Int}, U0::AbstractMatrix, locs::NTuple{M, Int}) where {C, M} -> AbstractMatrix
control-unitary matrix
YaoBlocks.cz
— Methodcz([n, ]ctrl_locs, location)
Return a speical 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
YaoBlocks.decode_sign
— Methoddecode_sign(ctrls...)
Decode signs into control sequence on control or inversed control.
YaoBlocks.dispatch
— Methoddispatch(x::AbstractBlock, collection)
Dispatch parameters in collection to block tree x
, the generic non-inplace version.
it will try to dispatch the parameters in collection first.
YaoBlocks.dump_gate
— Functiondump_gate(blk::AbstractBlock) -> Expr
convert a gate to a YaoScript expression for serization. The fallback is GateTypeName(fields...)
YaoBlocks.eigenbasis
— Methodeigenbasis(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.
YaoBlocks.gate_expr
— Methodgate_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.
YaoBlocks.getcol
— Methodgetcol(csc::SDparseMatrixCSC, icol::Int) -> (View, View)
get specific col of a CSC matrix, returns a slice of (rowval, nzval)
YaoBlocks.igate
— Methodigate(n::Int; nlevel=2)
The constructor for identity gate.
Examples
julia> igate(2)
igate(2)
julia> igate(2; nlevel=3)
igate(2;nlevel=3)
YaoBlocks.map_address
— Functionmap_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
YaoBlocks.matblock
— Methodmatblock(m::AbstractMatrix; nlevel=2)
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`.
YaoBlocks.matblock
— Methodmatblock(m::AbstractMatrix; nlevel=2)
Create a GeneralMatrixBlock
with a matrix m
.
YaoBlocks.num_nonzero
— Functionnum_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.
YaoBlocks.parameters!
— Methodparameters!(out, block)
Append all the parameters contained in block tree with given root block
to out
.
YaoBlocks.parameters_range
— Methodparameters_range(block)
Return the range of real parameters present in block
.
It may not be the case that length(parameters_range(block)) == nparameters(block)
.
Example
julia> YaoBlocks.parameters_range(RotationGate(X, 0.1))
1-element Vector{Tuple{Float64, Float64}}:
(0.0, 6.283185307179586)
YaoBlocks.parse_block
— Functionparse_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.
YaoBlocks.phase
— Methodphase(theta)
Returns a global phase gate. Defined with following matrix form:
\[e^{iθ} \mathbf{I}\]
Examples
You can create a global phase gate with a phase (a real number).
julia> phase(0.1)
phase(0.1)
YaoBlocks.popdispatch!
— Methodpopdispatch!(block, list)
Pop the first nparameters
parameters of list, then dispatch them to the block tree block
. See also dispatch!
.
YaoBlocks.popdispatch!
— Methodpopdispatch!(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!
.
YaoBlocks.postwalk
— Methodpostwalk(f, src::AbstractBlock)
Walk the tree and call f
after the children are visited.
YaoBlocks.prewalk
— Methodprewalk(f, src::AbstractBlock)
Walk the tree and call f
once the node is visited.
YaoBlocks.print_annotation
— Methodprint_annotation(io, root, node, child, k)
Print the annotation of k
-th child
of node, aka the k
-th element of subblocks(node)
.
YaoBlocks.print_prefix
— Methodprint_prefix(io, depth, charset, active_levels)
print prefix of a tree node in a single line.
YaoBlocks.print_subtypetree
— Functionprint_subtypetree(::Type[, level=1, indent=4])
Print subtype tree, level
specify the depth of the tree.
YaoBlocks.print_title
— Methodprint_title(io, block)
Print the title of given block
of an AbstractBlock
.
YaoBlocks.print_tree
— Functionprint_tree(io, root, node[, depth=1, active_levels=()]; kwargs...)
Print the block tree.
Keywords
maxdepth
: max tree depth to printcharset
: default is ('├','└','│','─'). See alsoBlockTreeCharSet
.title
: control whether to print the title,true
orfalse
, default istrue
YaoBlocks.print_tree
— Methodprint_tree([io=stdout], root)
Print the block tree.
YaoBlocks.projector
— Methodprojector(x)
Return projector on 0
or projector on 1
.
YaoBlocks.pswap
— Methodpswap(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)
YaoBlocks.put
— MethodYaoBlocks.put
— Methodput(total::Int, pair)
Create a PutBlock
with total number of active qubits, and a pair of location and block to put on.
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
.
It is better to use subroutine
instead of put
for large blocks, since put will use the matrix of its contents directly instead of making use of what's in it. put
is more efficient for small blocks.
YaoBlocks.rand_hermitian
— Methodrand_hermitian([T=ComplexF64], N::Int) -> Matrix
Create a random hermitian matrix.
julia> ishermitian(rand_hermitian(2))
true
YaoBlocks.rand_unitary
— Methodrand_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})
YaoBlocks.rmlines
— Methodrmlines(ex)
Remove LineNumberNode
from an Expr
.
YaoBlocks.rot
— Methodrot(U, theta)
Return a RotationGate
on U axis.
YaoBlocks.setcol!
— Methodsetcol!(csc::SparseMatrixCSC, icol::Int, rowval::AbstractVector, nzval) -> SparseMatrixCSC
set specific col of a CSC matrix
YaoBlocks.setiparams
— Functionsetiparams([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
.
YaoBlocks.shift
— Methodshift(θ)
Create a ShiftGate
with phase θ
.
\[\begin{pmatrix} 1 & 0\\ 0 & \exp^{iθ} \end{pmatrix}\]
Examples
julia> shift(0.1)
shift(0.1)
YaoBlocks.simple_commute_eachother
— MethodReturn true if operators commute to each other.
YaoBlocks.sprand_hermitian
— Methodsprand_hermitian([T=ComplexF64], N, density)
Create a sparse random hermitian matrix.
YaoBlocks.sprand_unitary
— Methodsprand_unitary([T=ComplexF64], N::Int, density) -> SparseMatrixCSC
Create a random sparse unitary matrix.
YaoBlocks.subroutine
— Methodsubroutine(block, locs) -> f(n)
Lazy curried version of subroutine
.
YaoBlocks.subroutine
— Methodsubroutine(n, block, locs)
Create a Subroutine
block with total number of current active qubits n
, which concentrates given wire location together to length(locs)
active qubits, and relax the concentration afterwards.
Example
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
YaoBlocks.swap
— Methodswap(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
YaoBlocks.swap
— Methodswap(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))
YaoBlocks.time_evolve
— Methodtime_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.
Arguments
H
the hamiltonian represented as anAbstractBlock
.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
YaoBlocks.u1ij!
— Functionu1ij!(target, i, j, a, b, c, d)
single u1 matrix into a target matrix.
For coo, we take an additional parameter * ptr: starting position to store new data.
YaoBlocks.unmat
— Methodunmat(nbit::Int, U::AbstractMatrix, locs::NTuple) -> AbstractMatrix
Return the matrix representation of putting matrix at locs.
YaoBlocks.@yao_str
— Macro@yao_str
yao"..."
The mark up language for quantum circuit.