Getting Started With Q# Programming

Last month, Microsoft announced a new quantum computing language named Q#, pronounced as “q-sharp”. With the language, Microsoft also announced a quantum development kit (QDK) for developers with all the necessary tools, a compiler, simulators, and the resources to build Q# programs using Visual Studio 2017 and C#.

In this tutorial, you’ll learn how to build your first simple “Hello World” Q# app. Just follow these following steps.

If you’re new to quantum computing, start with A Beginner’s Guide to Quantum Computing.

Step 1. Install Visual Studio 2017

To build quantum computing applications, you will need the latest version of Visual Studio 2017 (15.6 or later).

Download Visual Studio 2017 Community edition from here:

Step 2. Install Microsoft Quantum Development Kit

Visit Microsoft’s Quantum Computing home page here:

Click on "Download Now" button.

On the next page, fill out the details and click on "Download Now".

Figure 1.

This action will send you to the Visual Studio Marketplace and download the Quantum Development Kit page:

Download Quantum Development Kit and installed it. Once the installation is completed, you should see the following Figure 2.

Figure 2.

Installation of the Quantum Development Kit adds Q# Visual Studio project templates to the VS templates list.

Step 3. Create Q# Project

Now, let’s create our first Q# application.

Open Visual Studio 2017 Community and go to File > New Project > Visual C#. We see three Q# project templates – Q# Application, Q# Library, and Q# Test Project.

Select Q# Application project template, type your project name and click OK. See Figure 3.

Figure 3.

The default solution looks like Figure 4.

Figure 4.

Each Q# application has two default files – the C# driver (Driver.cs) and quantum code (Operation.qs). C# driver code listed in Driver.cs file is the entry point of the application. This code will look familiar to C# developers. See Listing 1.

  1. using Microsoft.Quantum.Simulation.Core;  
  2. using Microsoft.Quantum.Simulation.Simulators;  
  4. namespace Quantum.HelloQ  
  5. {  
  7.   class Driver  
  8.   {  
  10.     static void Main(string[] args)  
  11.     {  
  12.     }  
  13.   }  
  14. }   

Listing 1.

The quantum code is in Operation.qs. See Listing 2.

  1. namespace Quantum.HelloQ    
  2. {    
  3.   open Microsoft.Quantum.Primitive;    
  4.   open Microsoft.Quantum.Canon;    

  5.   operation Operation () : ()    
  6.   {    
  7.     body    
  8.     {  
  10.     }    
  11.   }    
  12. }  

Listing 2.

Step 4. Write a Q# Operation

Let’s write some Q# code that will do something. For the simplicity sake, I’ll create a simple operation in Q# that adds two integers and returns the total of the two.

Open Operation.qs and replace the code with Listing 3.

  1. namespace Quantum.HelloQ  
  2. {  
  3.     // Import Quantum.Primitive  
  4.     open Microsoft.Quantum.Primitive;  
  6.     // Create an operation that adds two int and returns a total int  
  7.     operation Add (a : Int, b : Int): (Int)  
  8.     {  
  9.         body  
  10.         {  
  11.             return (a + b);  
  12.         }         
  13.     }  
  14. }  

Listing 3.

In Listing 3, first of all, we import the Microsoft.Quantum.Primitive namespace.

open Microsoft.Quantum.Primitive;

Next, we write an operation. The basic unit of quantum execution is an operation. It is equivalent to a C/C++ function or a static method in C# or Java. The code snippet in Listing 4 is an operation.

  1. // Create an operation that adds two int and returns a total int    
  2. operation Add (a : Int, b : Int): (Int)    
  3. {    
  4.     body    
  5.     {    
  6.         return (a + b);    
  7.     }           
  8. }    

Listing 4.

An operation starts with the keyword “operation”. An operation can be with or without arguments and can return nothing or a value. The arguments are a form of a tuple. If you’re not familiar with tuples, check out Tuples in C#. The type of an argument is defined using a colon. The return value is also separated from the arguments using a colon.

The operation Add declared in Listing 4 takes two arguments of int type and returns the sum of the two values. Each operation has a body section that contains the implementation of the operation.

Step 5. Execute a Q# Operation

The Main method of the Driver class is the gateway to the program that executes Q# code. Since there is no real quantum computer on my laptop, the way to execute a Q# program is using a quantum simulator. The quantum simulator is installed as a part of the QDK.

The QuantumSimulator class defined in the Microsoft.Quantum.Simulation.Simulators

namespace represents a simulator. The following code snippet creates a quantum simulator.

using (var sim = new QuantumSimulator())

An operation is executed by using a call operation.Run(simulator, arguments). The following code snippet executes the Add operation.

var res = Add.Run(sim, 20, 10).Result;

The complete code of Driver class is listed in Listing 4. The code calls the Add operation by passing a simulator, two arguments of integer type, and the results are returned in a var.

  1. using System;  
  3. using Microsoft.Quantum.Simulation.Core;  
  4. using Microsoft.Quantum.Simulation.Simulators;  
  6. namespace Quantum.HelloQ  
  7. {  
  8.     class Driver  
  9.     {  
  10.         static void Main(string[] args)  
  11.         {  
  12.             using (var sim = new QuantumSimulator())  
  13.             {  
  14.                 var res = Add.Run(sim, 20, 10).Result;  
  15.                 Console.WriteLine(res);  
  16.             }  
  17.             Console.WriteLine("Press any key to continue...");  
  18.             Console.ReadKey();  
  19.         }  
  20.     }  
  21. }  

Listing 5.

Step 6. Build and Run

If you build the project, you will get a bunch of errors. To fix that, you need to target a specific framework and platform.

Right click on project name in Solution Explorer and click on Properties. On Application settings, change Target framework to 4.6.1 and on Build settings, change Platform target from Any CPU to x64. See Figure 5.

Figure 5.

Now Build and Run the application and you should see result 30 printed on the console i.e. total of the two values passed to the Q# operation.


Q# is the newest programming language introduced by Microsoft to write a quantum computing based application. In this article, you learned how to install Quantum Development Kit, setup up Visual Studio 2017 for a Q# project, write our first Q# code, and build and execute it.

If you’re new to quantum computing, I recommend reading A Beginner’s Guide to Quantum Computing. Learn more Q# Programming here >