# QuDotPy Tutorial

Welcome to the QuDotPy Tutorial! This is meant to be an interactive tutorial where you learn about the QuDotPy library through examples. Please see the README file for installation instructions, the only external dependency is numpy. Once you have QuDotPy on your machine its time to start exploring quantum computation! This is not an introduction to quantum computing or quantum mechanics (Although that is something I am working on, stay tuned...). This is meant to show you how to use QuDotPy to DO quantum computing. QuDotPy can be used to explore basic qubits, build arbitrary quantum states, emulate measurement/collapse, apply quantum gates to quantum states, build your own gates and to build quantum circuits. So lets get started and import qudotpy:

In :
from qudotpy import qudot


## Fun with QuBits¶

The most fundamental property of quantum computing is the qubit. This is a two level quantum system which is a bunch of fancy words for saying it is something that can have two possible values. You can call those two values what you like, but the standard is to call them |0> and |1> (The Computational Basis) or |+> and |-> (The Hadamard Basis). QuDotPy supports qubits through the QuBit class. We support both the computation and Hadamard basis. The QuBit class is meant to represent a single-qubit system. Multiple-qubit systems are described further down this tutorial. QuDotPy displays qubits using Dirac Notation. They are stored as numpy arrays and the underlying array can be access with the ket and bra properties.

#### Computational Basis¶

In :
print qudot.ZERO

|0>


In :
print qudot.ZERO.ket

[
]


In :
print qudot.ZERO.bra

[[1 0]]


In :
print qudot.ONE

|1>


In :
print qudot.ONE.ket

[
]


In :
print qudot.ONE.bra

[[0 1]]



In :
print qudot.PLUS

|+>


In :
print qudot.PLUS.ket

[[ 0.70710678]
[ 0.70710678]]


In :
print qudot.PLUS.bra

[[ 0.70710678  0.70710678]]


In :
print qudot.MINUS

|->


In :
print qudot.MINUS.ket

[[ 0.70710678]
[-0.70710678]]


In :
print qudot.MINUS.bra

[[ 0.70710678 -0.70710678]]


###### QuDotPy also has overidden equality operators for qubits so you can use == and != to test them¶
In :
print qudot.PLUS == qudot.PLUS
print qudot.PLUS == qudot.ONE
print qudot.ONE != qudot.MINUS
print qudot.ONE != qudot.ONE
print qudot.ONE == qudot.QuBit("1")
print qudot.MINUS == qudot.QuBit("-")

True
False
True
False
True
True



## Fun with Quantum Gates¶

Quantum gates are the main logical units in quantum computing, much like the logic gates of classical computing (AND, OR, XOR etc). QuDotPy has predefined gates:

• qudot.X: Pauli-X Gate
• qudot.Z: Pauli-Z Gate
• qudot.Y: Pauli-Y Gate
• qudot.CNOT: CNOT Gate

Also, you can create custom quantum gates via the QuGate class. There are multiple ways to initialize a custom QuGate. You can initialize through a string representation of the gate, through a multiplication of existing gates, or through a tensor product of existing gates. For example, the string representation for the Z gate is ("1 0; 0 -1"). We do require that quantum gates are unitary transformations. This is again fancy talk that says the gate changes (transforms) the qubit into another qubit but preserves the angle between qubits. A QuGate is represented as a numpy matrix. You can access two properties: matrix and dagger. matrix returns the matrix representation of the gate and dagger returns the Hermitian of the matrix.

You apply a gate to a qubit or a quantum state (quantum states are covered later). To apply a gate to a qubit and return the result use the module level apply_gate method. This will apply the gate to the input and return a new state as output. Lastly, we override the == and != operators so you can test gate equality.

In :
print qudot.H.matrix

[[ 0.70710678+0.j  0.70710678+0.j]
[ 0.70710678+0.j -0.70710678+0.j]]


In :
H_zero = qudot.apply_gate(qudot.H, qudot.ZERO)
print H_zero
print H_zero == qudot.PLUS

(0.707106781187+0j)|0> + (0.707106781187+0j)|1>
True


In :
H_one = qudot.apply_gate(qudot.H, qudot.ONE)
print H_one
print H_one == qudot.MINUS

(0.707106781187+0j)|0> + (-0.707106781187+0j)|1>
True



But the Hadamard Gate is its own inverse, so we should be able to run the computation again and get back the original result

In :
H_one = qudot.apply_gate(qudot.H, H_one)
print H_one
print H_one == qudot.ONE

(1+0j)|1>
True



YAY! Quantum computing works!

#### Pauli Gates¶

In :
print qudot.X.matrix

[[ 0.+0.j  1.+0.j]
[ 1.+0.j  0.+0.j]]


In :
print qudot.Y.matrix

[[ 0.+0.j  0.-1.j]
[ 0.+1.j  0.+0.j]]


In :
print qudot.Y.dagger

[[ 0.-0.j  0.-1.j]
[ 0.+1.j  0.-0.j]]


In :
X_zero = qudot.apply_gate(qudot.X, qudot.ZERO)
print X_zero
print X_zero == qudot.ONE

(1+0j)|1>
True


In :
X_plus = qudot.apply_gate(qudot.X, qudot.PLUS)
print X_plus
print X_plus == qudot.PLUS

(0.707106781187+0j)|0> + (0.707106781187+0j)|1>
True


In :
Z_zero = qudot.apply_gate(qudot.Z, qudot.ZERO)
print Z_zero

(1+0j)|0>


In :
Z_one = qudot.apply_gate(qudot.Z, qudot.ONE)
print Z_one

(-1+0j)|1>



#### Custom Gates¶

Now the quantum computing books tell you that these identites are true:

• HXH = Z
• HZH = X
• HYH = -Y

Shall we test this? I think so:

In :
test_1 = qudot.QuGate.init_from_mul([qudot.H, qudot.X, qudot.H])
print test_1 == qudot.Z

True


In :
test_2 = qudot.QuGate.init_from_mul([qudot.H, qudot.Z, qudot.H])
print test_2 == qudot.X

True


In :
minus_Y = qudot.QuGate.init_from_str('0 1j; -1j 0')
test_3 = qudot.QuGate.init_from_mul([qudot.H, qudot.Y, qudot.H])
print minus_Y == test_3
print test_3 == qudot.Y

True
False



Well, I guess they were right...

## Fun with QuState: the Arbitrary Quantum State¶

So far we have been working with single-qubit systems represented by the QuBit class, such as |0> or |+>. Now it's time to have some real fun with multiple-qubit systems. Multiple-qubit systems are combinations of single-qubit systems, a|001> + b|100> + c|111> is an example of such a system. QuDotPy has a class called QuState to represent such systems. QuState is the main workhorse of QuDotPy, it supports creating multiple-qubit states from various input, can make measurement predictions, can measure and collapse the state, and can apply a gate to the state. There are two basic properties that give you information about the size of the QuState:

• num_qubits: this tells you how many qubits the state is built from. |01000> would be 5 qubits
• hilbert_dimension: this tells you the dimensionality of the associated Hilbert Space, a.k.a how many elements your state vector has

So lets see QuState in action by initializing some quantum states. There are five different ways to init a QuState:

1. init from a state map QuState(state_map): This is the default initialization method as is the most extensible. The input is a map whose keys are the states and values are the probability amplitudes.

2. init from a list of states QuState.init_from_state_list([list_of_states]): This is a convenience class method that will create a QuState with the states specified in list_of_states and equal probability amplitudes.

3. init superposition QuState.init_superposition(dimension): This is a convenience class method that will create a QuState that is a superposition of all states in the Hilbert space of the specified dimension

4. init from vector QuState.init_from_vector(column_vector): This is a convenience class method that will create a QuState from the specified column_vector, which is expected to have the form of a numpy column_vector

5. init zeros QuState.init_zeros(num_bits): This is a convenience class method that will create a QuState which has just one state, the |0...n> state. The number of zeros is determined by num_bits

In :
state_1 = qudot.QuState({"0000": .5, "0010": .5, "0100": .5, "0110": .5})
print state_1

0.5|0000> + 0.5|0010> + 0.5|0100> + 0.5|0110>


In :
print state_1.num_qubits
print state_1.hilbert_dimension

4
16


In :
print state_1.ket

[[ 0.5]
[ 0. ]
[ 0.5]
[ 0. ]
[ 0.5]
[ 0. ]
[ 0.5]
[ 0. ]
[ 0. ]
[ 0. ]
[ 0. ]
[ 0. ]
[ 0. ]
[ 0. ]
[ 0. ]
[ 0. ]]


In :
print state_1.bra

[[ 0.5  0.   0.5  0.   0.5  0.   0.5  0.   0.   0.   0.   0.   0.   0.   0.
0. ]]


In :
state_2 = qudot.QuState.init_from_state_list(["0000", "0010", "0100", "0110"])
print state_2

0.5|0000> + 0.5|0010> + 0.5|0100> + 0.5|0110>


In :
print state_1 == state_2

True



QuState is built on top of the computational basis. You can initialize with Hadamard elements |+>, |-> but under the scenes it will be converted to the computational basis. This actually lets us test something in quantum computing books. They claim that the bell states are the same in both computational and Hadamard basis.

So 1/sqrt(2)|++> + 1/sqrt(2)|--> = 1/sqrt(2)|00> + 1/sqrt(2)|++>

I find this hard to believe... I mean common. Let's test it:

In :
bell_1 = qudot.QuState.init_from_state_list(["++","--"])
print bell_1

0.707106781187|00> + 0.707106781187|11>


In :
bell_2 = qudot.QuState({"++": qudot.ROOT2, "--": -qudot.ROOT2})
print bell_2

0.707106781187|01> + 0.707106781187|10>


In :
bell_3 = qudot.QuState.init_from_state_list(["-+", "+-"])
print bell_3

0.707106781187|00> + -0.707106781187|11>


In :
bell_4 = qudot.QuState({"-+": qudot.ROOT2, "+-": -qudot.ROOT2})
print bell_4

0.707106781187|01> + -0.707106781187|10>



Let this be a lesson to you: Nature does not care about your intuition.....

Moving on, sometimes you want an even superposition of all states in a Hilbert space:

In :
super_state = qudot.QuState.init_superposition(1)
print super_state

0.707106781187|0> + 0.707106781187|1>


In :
super_state = qudot.QuState.init_superposition(2)
print super_state

0.5|00> + 0.5|01> + 0.5|10> + 0.5|11>


In :
super_state = qudot.QuState.init_superposition(5)
print super_state

0.176776695297|00000> + 0.176776695297|00001> + 0.176776695297|00010> + 0.176776695297|00011> + 0.176776695297|00100> + 0.176776695297|00101> + 0.176776695297|00110> + 0.176776695297|00111> + 0.176776695297|01000> + 0.176776695297|01001> + 0.176776695297|01010> + 0.176776695297|01011> + 0.176776695297|01100> + 0.176776695297|01101> + 0.176776695297|01110> + 0.176776695297|01111> + 0.176776695297|10000> + 0.176776695297|10001> + 0.176776695297|10010> + 0.176776695297|10011> + 0.176776695297|10100> + 0.176776695297|10101> + 0.176776695297|10110> + 0.176776695297|10111> + 0.176776695297|11000> + 0.176776695297|11001> + 0.176776695297|11010> + 0.176776695297|11011> + 0.176776695297|11100> + 0.176776695297|11101> + 0.176776695297|11110> + 0.176776695297|11111>



And sometimes you just want a bunch of zeros:

In :
zeros = qudot.QuState.init_zeros(1)
print zeros

1|0>


In :
zeros = qudot.QuState.init_zeros(2)
print zeros

1|00>


In :
zeros = qudot.QuState.init_zeros(4)
print zeros

1|0000>


In :
zeros = qudot.QuState.init_zeros(9)
print zeros

1|000000000>



The last way to initialize a QuState is with a raw column vector:

In :
state = qudot.QuState.init_from_vector([[qudot.ROOT2],
,
,
[qudot.ROOT2]])

print state

0.707106781187|00> + 0.707106781187|11>



#### QuState Measurements¶

As we all know, the strangest thing about quantum mechanics is measurements. We know that we can only predict probabilistic outcomes of measurements. The QuState incorporates this into it's design. You can ask for the possible measurement of a state and you will get back a map where the key is the possible state and the value is the probability of getting that state. Also, you can ask about the possible measurements of a specific qubit. For example, if your state is a|0100> + b|1101> + c|1111> and you ask the for the possible measurements of qubit 2, you will get |1> with probability 1. Whereas qubit 1 can be |0> or |1>.

Also, you can perform a measurement on the state. A measurement will collapse the state. So after you perform a measurement the QuState will be in a definite state not a superposition. Note that the QuState is designed to respect the probabilities when collapsing. That means if you have an ensemble of QuStates, as the ensembles get larger then the probability of collapsing to a specified state will approach the |amplitude|^2

In :
state = qudot.QuState({"0000": qudot.ROOT2, "0010": .5, "0110": .5})
print state

0.707106781187|0000> + 0.5|0010> + 0.5|0110>


In :
print state.possible_measurements()

{u'|0000>': 0.49999999999999989, u'|0010>': 0.25, u'|0110>': 0.25}


In :
# possible measurements of first qubit
print state.possible_measurements(qubit_index=1)

{u'|0>': 0.99999999999999989}


In :
print state.possible_measurements(2)

{u'|0>': 0.74999999999999989, u'|1>': 0.25}


In :
print state.possible_measurements(3)

{u'|0>': 0.49999999999999989, u'|1>': 0.5}


In :
print state.possible_measurements(4)

{u'|0>': 0.99999999999999989}


In :
state.measure()
print state

1.0|0010>



Now lets explore measuring ensembles. As we noted earlier, as our ensemble gets larger than the probability of measuring a specific state approaches its amplitude magnitude squared. However, if you have very few states then the probabilities will not be exact.

In :
state = qudot.QuState({"0000": qudot.ROOT2, "0010": .5, "0110": .5})
print state

0.707106781187|0000> + 0.5|0010> + 0.5|0110>



Here we expect to see state |0000> 50% of the time, state |0010> 25% of the time and state |0110> 25% of the time

In :
ensemble_10 = [ qudot.QuState({"0000": qudot.ROOT2, "0010": .5, "0110": .5}) for i in range(0, 10)]

In :
def tally_measurements(ensemble):
results_map = {}
for state in ensemble:
state.measure()
key = str(state)
if key in results_map:
results_map[key] = results_map[key] + 1
else:
results_map[key] = 1

return results_map

In :
print tally_measurements(ensemble_10)

{'1.0|0000>': 6, '1.0|0010>': 1, '1.0|0110>': 3}



So, not perfect. We expected 5, 2.5, 2.5 :-) If you do not get this joke think about what quantum mechanics means!

Lets start to see how increasing the ensemble size changes things:

In :
ensemble_100 = [ qudot.QuState({"0000": qudot.ROOT2, "0010": .5, "0110": .5}) for i in range(0, 100)]
print tally_measurements(ensemble_100)
del ensemble_100

{'1.0|0000>': 53, '1.0|0010>': 23, '1.0|0110>': 24}


In :
ensemble_1000 = [ qudot.QuState({"0000": qudot.ROOT2, "0010": .5, "0110": .5}) for i in range(0, 1000)]
print tally_measurements(ensemble_1000)
del ensemble_1000

{'1.0|0000>': 532, '1.0|0010>': 255, '1.0|0110>': 213}


In :
ensemble_10000 = [ qudot.QuState({"0000": qudot.ROOT2, "0010": .5, "0110": .5}) for i in range(0, 10000)]
print tally_measurements(ensemble_10000)
del ensemble_10000

{'1.0|0000>': 5079, '1.0|0010>': 2454, '1.0|0110>': 2467}


In :
ensemble_100000 = [ qudot.QuState({"0000": qudot.ROOT2, "0010": .5, "0110": .5}) for i in range(0, 100000)]
print tally_measurements(ensemble_100000)
del ensemble_100000

{'1.0|0000>': 50172, '1.0|0010>': 24755, '1.0|0110>': 25073}



So hopefully this explains how your probabilities approach theory as your ensemble gets larger. Its basically the law of large numbers. This is a summary of the results for state |0000>. The theory predicts we should get this state 50% of the time, as the ensemble gets larger, we get closer to the theoretical result:

• For 10 states: 60%
• For 100 states: 53%
• For 1000 states: 53.2%
• For 10000 states: 50.79%
• For 100000 states: 50.172%

#### Applying QuGates to QuStates¶

Ok great, now we are experts on QuStates! So far we have not done any actual quantum computing with QuStates. Let's remedy that! To do quantum computing we need to start applying gates to QuStates. A QuState has the apply_gate(qu_gate, qubit_list=None) method. This method applies a QuGate (such as qudot.X, qudot.Z) to the entire state OR to specific qubits of the state.

One important thing to note is that apply_gate will automatically scale your QuGate to the appropriate dimension. For example, qudot.X is a 2x2 matrix, but what if your state is 0.707|0000> + 0.5|0010> + 0.5|0110>? This would require qudot.X to be a 16x16 matrix. Don't worry! QuDotPy to the rescue! QuDotPy is smart, it recognizes this fact and tensors the gates with themselves until the appropriate dimension is reached. In a similar way, we are able to build larger matrices to apply a gate to a specific qubits. This way you can apply a QuGate to only the 1st and 3rd qubits if that is what your heart desires. Lets see this in action

In :
state = qudot.QuState({"0000": qudot.ROOT2, "0010": .5, "0110": .5})
print state

0.707106781187|0000> + 0.5|0010> + 0.5|0110>



Now if I apply an X gate to the first qubit:

In :
state.apply_gate(qudot.X, )
print state

(0.707106781187+0j)|1000> + (0.5+0j)|1010> + (0.5+0j)|1110>



Yay! it worked. NOTE THAT THE STATE CHANGED! It does not return a new state! Lets reverse this

In :
state.apply_gate(qudot.X, )
print state

(0.707106781187+0j)|0000> + (0.5+0j)|0010> + (0.5+0j)|0110>


In :
# apply to the whole state
state.apply_gate(qudot.X)
print state

(0.5+0j)|1001> + (0.5+0j)|1101> + (0.707106781187+0j)|1111>


In :
# reverse
state.apply_gate(qudot.X)
print state

(0.707106781187+0j)|0000> + (0.5+0j)|0010> + (0.5+0j)|0110>


In :
# apply to multiple qubits
state.apply_gate(qudot.X, [1, 3])
print state

(0.5+0j)|1000> + (0.707106781187+0j)|1010> + (0.5+0j)|1100>



Now quantum computing books tell us that if we have the state |00> and we apply H to the first qubit, then pass the result through a CNOT gate we will get a bell state |00> + |11>. Is that true?

In :
state = qudot.QuState.init_zeros(2)
print state

1|00>


In :
state.apply_gate(qudot.H, )
state.apply_gate(qudot.CNOT)
print state

(0.707106781187+0j)|00> + (0.707106781187+0j)|11>



sweeeeeet! ship it!

In :
test_input = qudot.QuState.init_zeros(2)
test_input.apply_gate(qudot.H, )
test_input.apply_gate(qudot.CNOT)
test_input.apply_gate(qudot.H, )

print test_input

(0.5+0j)|00> + (0.5+0j)|01> + (0.5+0j)|10> + (-0.5+0j)|11>



That does it for QuState! I think after these last two examples you see how to develop quantum circuits. However, QuDotPy makes it even easier to build circuits! It also allows you to step through a quantum circuit debugger style! Lets see how

## Fun with QuCircuit¶

Now you should have gotten the idea from last section that it will be very easy to implement a quantum circuit: just use QuState.apply_gate() repeatedly for your design. You are pretty much right, but we can do even better. We would like to abstract away the actual circuit from the input state. That way we can run the circuit on different input states and examine the output. Also, wouldn't it be cool if you can step through a quantum circuit like you step through a debugger in your code? I think so! That is basically how QuCircuit was born.

The main idea behind QuCircuit is that a quantum circuit can be thought of as a list of operations. Each operation tells you to apply a quantum gate to certain qubits or an entire state. So, QuCircuit is initialized with a list of tuples. Each tuple represents a single operation and has the form (QuGate, qubit_list or None). The first element of the tuple is the QuGate to apply. The second argument is either a qubit_list to apply the gate to or None, which will apply the QuGate to the entire state.

To run a QuCircuit you must first set the in_qu_state attribute. This gives the input state that the circuit will run on. Then you just call run_circuit() and in_qu_state will have the result. You can also step through the circuit one operation at a time using the step_circuit() method. This will return your current index on the operations list. You can always check on which operation you are on by inspecting the step_op_index attribute. Also, if you want to reset the circuit to the beginning you can call the reset_circuit() method.

Lets look at an example by making a circuit that produces Bell states. This circuit has the following mappings (excluding normalization constants):

• |00> ---> |00> + |11> a.k.a Phi+
• |10> ---> |00> - |11> a.k.a Phi-
• |01> ---> |01> + |10> a.k.a Psi+
• |11> ---> |01> - |10> a.k.a Psi-
In :
bell_circuit = qudot.QuCircuit([(qudot.H, ), (qudot.CNOT, None)])

In :
input_state = qudot.QuState.init_from_state_list(["00"])
print "in: " + str(input_state)
bell_circuit.in_qu_state = input_state
output = bell_circuit.run_circuit()
print "out: " + str(output)

in: 1.0|00>
out: (0.707106781187+0j)|00> + (0.707106781187+0j)|11>


In :
input_state = qudot.QuState.init_from_state_list(["10"])
print "in: " + str(input_state)
bell_circuit.in_qu_state = input_state
output = bell_circuit.run_circuit()
print "out: " + str(output)

in: 1.0|10>
out: (0.707106781187+0j)|00> + (-0.707106781187+0j)|11>


In :
input_state = qudot.QuState.init_from_state_list(["01"])
print "in: " + str(input_state)
bell_circuit.in_qu_state = input_state
output = bell_circuit.run_circuit()
print "out: " + str(output)

in: 1.0|01>
out: (0.707106781187+0j)|01> + (0.707106781187+0j)|10>


In :
input_state = qudot.QuState.init_from_state_list(["11"])
print "in: " + str(input_state)
bell_circuit.in_qu_state = input_state
output = bell_circuit.run_circuit()
print "out: " + str(output)

in: 1.0|11>
out: (0.707106781187+0j)|01> + (-0.707106781187+0j)|10>



Ship it! now lets show an example of stepping through the circuit:

In :
bell_circuit.in_qu_state = qudot.QuState.init_zeros(2)
print str(bell_circuit.step_op_index) + " " + str(bell_circuit.in_qu_state)
bell_circuit.step_circuit()
print str(bell_circuit.step_op_index) + " " + str(bell_circuit.in_qu_state)
bell_circuit.step_circuit()
print str(bell_circuit.step_op_index) + " " + str(bell_circuit.in_qu_state)

0 1|00>
1 (0.707106781187+0j)|00> + (0.707106781187+0j)|10>
0 (0.707106781187+0j)|00> + (0.707106781187+0j)|11>



When the step_op_index goes back to 0, the circuit is done and back at the beginning.

## Thats All Folks!¶

I had a lot of fun both coding QuDotPy and writing this usage tutorial. I hope you will have just as much fun using it! If you find any errors/typos please email me at psakkaris@gmail.com

Perry Sakkaris