From Learn Quantum Computing with Python and Q# by Sarah Kaiser and Chris Granade This article covers using the Quantum Development Kit to write quantum programs in Q#

---

Take 37% off Learn Quantum Computing with Python and Q# by entering fcckaiser into the discount code box at checkout at manning.com.

---

You can use Python to implement your own software stack to simulate quantum programs. In this article, we’ll be writing more intricate quantum programs that benefit from specialized language features which are hard to implement by embedding our software stack inside Python. As we explore quantum algorithms, it’s helpful to have a language tailor-made for quantum programming at our disposal. We’ll also get started with Q#, Microsoft’s domain-specific language for quantum programming, included with the Quantum Development Kit.

Introducing the Quantum Development Kit

The Quantum Development Kit provides a new language, Q#, for writing quantum programs and simulating them using classical resources. Quantum programs written in Q# are run in a way that the quantum devices act as a kind of accelerator, similar to how you might run code on a graphics card OpenCL, this is a similar model.

---

Figure 1. Q# software stack on a classical computer.

---

Let’s take a look at this software stack for Q#. Our Q# program itself consists of operations and functions that instruct quantum and classical hardware to do certain things. A number of libraries which are provided with Q# are helpful, pre-made operations and functions to use in our programs.

Once the Q# program is written, we need a way for it to pass instructions to the hardware. A classical program, sometimes called a “driver” or a “host program,” is responsible for allocating a target machine and running a Q# operation on that machine.

The Quantum Development Kit provides a plugin for Jupyter Notebook called IQ# which makes it easy to get started with Q# by providing host programs automatically. Using the IQ# plugin for Jupyter Notebook, we can use one of two different target machines to run Q# code. The first is the QuantumSimulator target machine, which is similar to a Python simulator. It’s a lot faster than Python code at simulating qubits.

The second is the ResourcesEstimator target machine which allows us to estimate how many qubits and quantum instructions we need to run it, without having to fully simulate it. This is useful for getting an idea of the resources you need to run a Q# program for your application

---

Figure 2. Getting started with IQ# and Jupyter Notebook

---

To get a sense for how everything works, let’s start by writing out a purely classical Q# “hello, world” application. First, start Jupyter Notebook by running the following in a terminal:

  
 jupyter notebook
  

This automatically opens a new tab in your browser with the home page for your Jupyter Notebook session. From the New ↓ menu, select “Q#” to make a new Q# notebook. Type the following into the first empty cell in the notebook and press Control + Enter or ! + Enter to run it.

  
 function HelloWorld() : Unit {           ❶    
     Message("Hello, classical world!");  ❷
 }
  

❶ This line defines a new function which takes no arguments, and returns the empty tuple, whose type is written as Unit.

❷ The Message function tells the target machine to collect a diagnostic message. The QuantumSimulator target machine prints all diagnostics to the screen, and we can use Message in the same way as print in Python.

You should get a response back listing that the HelloWorld function was successfully compiled. To run our new function, we can use the %simulate command in a new cell.

  
 %simulate HelloWorld
  

In this example, %simulate allocates a target machine for us and sends a Q# function or operation to that new target machine.

The Q# program is sent to the simulator, but in this case, the simulator runs the classical logic, because there’s no quantum instructions to worry about yet.

Functions and Operations in Q#

Now that the Quantum Development Kit is up and running with Jupyter Notebook, let’s use Q# to write some quantum programs. One useful thing to do with a qubit is to generate random numbers one classical bit at a time. Revisiting that application makes a great place to start with Q#, because random numbers are useful if you want to play games.

Long ago in Camelot, Morgana le Fay shared our love for playing games. Being a clever mathematician with skills well beyond her own day, Morgana was even known to use qubits from time to time as a part of her games. One day, as Sir Lancelot lay sleeping under a tree, Morgana trapped him and challenged him to a little game: each of them must try to guess the outcome of measuring one of Morgana’s qubits.

If the result of measuring along the " axis is a 0, then Lancelot wins their game and gets to return to Genevieve. If the result is a 1, though, Morgana wins and Lancelot has to stay and play again. We’ll measure a qubit to generate random numbers for the purpose of playing this game. Morgana and Lancelot could have also flipped a more traditional coin, but where’s the fun in that?

Morgana’s side game

1. Prepare a qubit in the |0# state
2. Apply the Hadamard operation (recall that the unitary operator  takes |0# to |+# and vice versa)
3. Measure the qubit in the ” axis. If the measurement result is a 0, then Lancelot can go home. Otherwise, he must stay and play again!

Sitting at a coffee shop watching the world go by, we can use our laptops to predict what happens in Morgana’s game with Lancelot by writing a quantum program in Q#. Unlike the ClassicalHello function that we wrote above, our new program needs to work with qubits; let’s take a moment to see how to do this with the Quantum Development Kit.

The primary way to interact with qubits in Q# is by calling operations that represent quantum instructions. To understand how these operations work, it’s helpful to understand the difference between Q# operations and the functions that we saw in the ClassicalHello example above.

• Functions in Q# represent predictable classical logic, things like mathematical functions (Sin, Log). Functions always return the same output when given the same input.
• Operations in Q# represent code which can have side effects, such as sampling random numbers, or issuing quantum instructions which modify the state of one or more qubits.

This separation helps the compiler figure out how to automatically transform your code as a part of larger quantum programs; we’ll see more about this later.

For instance, suppose that Morgana and Lancelot prepare their qubit in the |+# state using the Hadamard instruction. We can predict the outcome of their game by writing out the quantum random number generator (QRNG) example listed below.

  
 def qrng(device : QuantumDevice) -> bool:
     with device.using_qubit() as q:
         q.h()
         return q.measure()
  

In Listing 1, we’ll do exactly that, starting by writing an operation called NextRandomBit to simulate each round of Morgana’s game. Note that because NextRandomBit needs to work with qubits, it has to be an operation and not a function. We can ask the target machine for one or more fresh qubits with the using block.

Q# offers one other way to allocate qubits, known as borrowing. Unlike when we allocate qubits with using statements, the borrowing statement lets us borrow qubits which are owned by different operations without knowing what state they start in. The borrowing statement works similarly to the using statement in that it makes it impossible for us to forget that we’ve borrowed a qubit.

By convention, all qubits start off in the |0# state right after we get them, and we promise the target machine that we’ll put them back into the |0# state at the end of the block to be ready for the target machine to give to the next operation that needs them.

  
 operation NextRandomBit() : Result { ❶
     mutable result = Zero;           ❷
     using (qubit = Qubit()) {        ❸
         H(qubit);                    ❹
         set result = M(qubit);       ❺
         Reset(qubit);                ❻
     }
     return result;                   ❼
 }
  

❶ This time, because we want to use a qubit, we declare an operation instead of a function. Because our operation needs to return a result to its caller, we denote by changing the return type to the Q# type Result.

❷ The using keyword in Q# asks the target machine for one or more qubits. Here, we ask for a single value of type Qubit, which we store in the new variable qubit.

❸ Quantum operations such as the Hadamard operation can be found in the Microsoft.Quantum.Intrinsic namespace. For instance, we can call Hadamard using the Microsoft.Quantum.Intrinsic.H operation. After calling H, qubit is in thestate.

❹ Next, we use the M operation to measure our qubit in the  basis, saving the result to the result variable we declared earlier. Because we’re in an equal superposition of  and , result are either Zero or One with equal probability.

❺ Before returning our qubit to the target machine, we use the Microsoft.Quantum.Intrinsic.Reset operation to return it to the  state. Because we’ve already stored the classical data we got from our measurement into the result variable, we can safely reset the qubit without losing any information that we care about.

❻ We finish our operation by returning the measurement result back to the caller.

We finish our operation by returning the measurement result back to to the caller.

Next, we need to see how many rounds it takes for Lancelot to get the Zero he needs to go home. Let’s write an operation to play rounds until we get a Zero. Because this operation simulates playing Morgana’s game, we’ll call it PlayMorganasGame.

  
 operation PlayMorganasGame() : Unit {     mutable nRounds = 0; ❶
     mutable done = false;
     repeat {                                                   ❷
         set nRounds = nRounds + 1;
         set done = (NextRandomBit() == Zero);                  ❸
     }
     until (done)                                               ❹
     fixup {}
  
     Message($"It took Lancelot {nRounds} turns to get home."); ❺
 }
  

❶ All Q# variables are immutable by default — we can use the mutable keyword to declare a variable which we can change later with the set keyword. Here, we start by initializing a mutable variable indicating how many rounds have already passed, and a mutable variable we’ll use to exit the loop.

❷ Q# allows operations to use a kind of loop called a “repeat-until-success” (RUS) loop. Unlike a while-loop, RUS loops allow us to specify a “fixup” that runs if the condition to exit the loop isn’t met. Note that the fixup block is required, even if it’s empty.

❸ Inside our loop, we call the QRNG that we wrote above as the NextRandomBit operation. We check to see if the result is a Zero (if Lancelot wins and can leave), and if true, set done to be true.

❹ If we got a Zero, then we can stop the loop.

❺ Finally, we use Message again to print the number of rounds to the screen. To do this, we use $"" strings which, similar to $"" strings in C# and f"" strings in Python, and include variables in the diagnostic message by using {} placeholders inside the string.

We can run this new operation with the %simulate command in a similar fashion as the ClassicalHello example. When we do this, we can see how long Lancelot has to stay:

  
 In []: %simulate PlayMorganasGame
 It took Lancelot 1 turns to get home.
 Out[]: ()
  

Looks like Lancelot got lucky that time! Or perhaps unlucky, if he was bored of hanging ’round the table in Camelot.

Passing Operations as Arguments

Let’s suppose that in Morgana’s game, we’re interested in sampling random bits with nonuniform probability. After all, Morgana didn’t tell Lancelot how she prepared the qubit that they are measuring; she can keep him playing longer if she makes a biased coin with their qubit instead of a fair coin.

The easiest way to modify Morgana’s game is to, instead of calling H directly, take as an input an operation representing what Morgana does to prepare for their game. To take an operation as input, we need to write down the type of the input, as can write down qubit : Qubit to declare an input qubit of type Qubit. Operation types are indicated by thick arrows (=>) from their input type to their output type. For instance, H has type Qubit => Unit because H takes a single qubit as input and returns an empty tuple as its output.

  
 operation PrepareFairCoin(qubit : Qubit) : Unit {   
     H(qubit);
 }
  
 operation NextRandomBit(       
         statePreparation : (Qubit => Unit)                 ❶
 ) : Result {
     using (qubit = Qubit()) {
         statePreparation(qubit);                  ❷       
         return result = MResetZ(qubit);                 ❸
     }
 }
  

❶ This time, we’ve added a new input called statePreparation to NextRandomBit that represents the operation we want to use to prepare the state we use as a coin. In this case, Qubit => Unit is the type of any operation which takes a single qubit and returns the empty tuple type Unit.

❷ Within NextRandomBit, the operation passed as statePreparation can be called in the same way as any other operation.

❸ The Q# standard libraries provide MResetZ as a convenience for measuring and resetting a qubit in one step. This is equivalent to the set result = M(qubit); Reset(qubit); statements we saw in the previous example, but requires one less measurement to perform.

In this example, we see that NextRandomBit treats its input statePreparation as a “black box.” The only way to learn anything about Morgana’s preparation strategy is to run it.

Put differently, we don’t want to do anything with statePreparation that implies we know what it does or what it is. The only way that NextRandomBit can interact with statePreparation is by calling it, passing it a Qubit to act on.

This allows us to reuse the logic in NextRandomBit for many different kinds of state preparation procedures which Morgana might use to cause Lancelot a bit of trouble. For example, suppose she wants a biased coin that returns a One ¾ of the time and a Zero ¼ of the time. Then, we might run something like the following to predict this new strategy:

  
 open Microsoft.Quantum.Math;          ❶
  
 operation PrepareQuarterCoin(qubit : Qubit) : Unit {    
     Ry(2.0 * PI() / 3.0, qubit);                 ❷
 }
  

❶ Classical math functions such as Sin, Cos, Sqrt, and ArcCos, as well as constants like PI() are provided by the Microsoft.Quantum.Math namespace, and we open it as well as the intrinsics.

❷ The Ry operation implements the Y -axis rotation that we saw in Chapter 2. Q# uses radians rather than degrees to express rotations, so this is a rotation of 120° about the Y -axis. Thus, if qubit starts in |0〉, this prepares qubit in the state Ry(-120◦)|0〉 = √3/4 |0〉 + √1/4 |1〉, such that the probability of observing 1 when we measure is √3/42 = 3/4.

We can make this example even more general, allowing Morgana to specify an arbitrary bias for her coin (which is implemented by their shared qubit):

  
 operation PrepareBiasedCoin(morganaWinProbability : Double, qubit : Qubit) : Unit {
     let rotationAngle = -2.0 * ArcCos(Sqrt(morganaWinProbability));          ❶
     Ry(rotationAngle, qubit);
 }
  
 operation PrepareMorganasCoin(qubit : Qubit) : Unit {                  ❷    
     PrepareBiasedCoin(0.62, qubit);
 }
  

❶ We need to find out what angle we rotate the input qubit by in order to get the right probability of seeing a Zero as our result. This takes a little bit of trigonometry, see the sidebar below for the details.

❷ This operation has the right type signature (Qubit => Unit) and we can see that the probability Morgana wins each round is 62%.

---

Figure 5. How Morgana can choose θ to control how her game plays out

---

This is somewhat unsatisfying, though, in that the operation PrepareMorganasCoin introduces a lot of boilerplate to lock down the value of 0.62 for the input argument headsProbability to PrepareBiasedCoin. If Morgana changes her strategy to have a different bias, then using this approach means we’ll need another new boilerplate operation to represent it. Taking a step back, let’s look at what PrepareMorganasCoin does. It starts with an operation PrepareBiasedCoin : (Double, Qubit) => Unit, and wraps it into an operation of type Qubit => Unit by locking down the Double argument to 0.62. It removes one of the arguments to PrepareBiasedCoin by fixing the value of that input to 0.62.

Thankfully, Q# provides a convenient shorthand for making new functions and operations by locking down some (but not all!) of the inputs. Using this shorthand, known as partial application, we can rewrite the above in a more readable form:

  
 let flip = NextRandomBit(PrepareBiasedCoin(0.62, _));
  

The _ here indicates that a part of the input to PrepareBiasedCoin is missing. We say that PrepareBiasedCoin has been partially applied. Whereas PrepareBiasedCoin had type (Double, Qubit) => Unit, because we filled in the Double part of the input, PrepareBiasedCoin(0.62, _) has type Qubit => Unit, making it compatible with our modifications to NextRandomBit. Partial application in Q# is similar to functools.partial in Python and the _ keyword in Scala.

Another way to think of partial application is as a way to make new functions and operations by specializing existing functions and operations:

  
 function BiasedPreparation(headsProbability : Double) : (Qubit => Unit) { ❶    
     return PrepareBiasedCoin(headsProbability, _);                        ❷
 }
  

❶ Here, the output type of BiasedPreparation is an operation that takes a Qubit and returns the empty tuple. BiasedPreparation is a function that makes new operations!

❷ We make the new operation by passing along headsProbability, but leaving a blank

(_) for the target qubit. This gives us an operation that takes a single Qubit and substitutes in the blank.

It may seem a bit confusing that BiasedPreparation returns an operation from a function, but this is completely consistent with the split between functions and operations described above, because BiasedPreparation is still predictable. In particular, BiasedPreparation(p) always returns the same operation for a given p, no matter how many times you call the function. We can assure ourselves that this is the case by noticing that BiasedPreparation only partially applies operations, but never calls them.

That’s all for this article.

If you want to learn more about the book, check it out on our browser-based liveBook reader here and see this slide deck.