install-jupyter-qkd.md

author	description	ms.author	ms.date	ms.service	ms.subservice	ms.topic	no-loc	title	uid
bradben	This article shows you how to install the Quantum Developer Kit (QDK) and develop your own Q# notebooks.	v-benbra	02/01/2021	azure-quantum	qdk	quickstart	Q# $$v	Develop with Q# Jupyter notebooks	microsoft.quantum.install-qdk.overview.jupyter

Develop with Q# Jupyter Notebooks

This article shows you how to install the Quantum Developer Kit (QDK) for developing Q# operations on Q# Jupyter Notebooks. Then, learn how to start developing your own Q# notebooks.

Jupyter Notebooks allow running code in-place alongside instructions, notes, and other content. This environment is ideal for writing Q# code with embedded explanations or quantum computing interactive tutorials.

Install the IQ# Jupyter kernel

IQ# (pronounced i-q-sharp) is an extension primarily used by Jupyter and Python to the .NET Core SDK that provides the core functionality for compiling and simulating Q# operations.

Install using conda (recommended)

1. Install Miniconda or Anaconda. Note: 64-bit installation required.

2. Open an Anaconda Prompt.

   • Or, if you prefer to use PowerShell or pwsh: open a shell, run conda init powershell, then close and re-open the shell.

3. Create and activate a new conda environment named qsharp-env with the required packages (including Jupyter Notebook and IQ#) by running the following commands:

   conda create -n qsharp-env -c quantum-engineering qsharp notebook
   
   conda activate qsharp-env
   

4. Run python -c "import qsharp" from the same terminal to verify your installation and populate your local package cache with all required QDK components.

Install using .NET CLI (advanced)

1. Prerequisites:

   • Python 3.6 or later
   • Jupyter Notebook
   • .NET Core SDK 3.1

2. Install the Microsoft.Quantum.IQSharp package.

   dotnet tool install -g Microsoft.Quantum.IQSharp
   dotnet iqsharp install
   

Note

If you get an error during the dotnet iqsharp install step, open a new terminal window and try again. If this still doesn't work, try locating the installed dotnet-iqsharp tool (on Windows, dotnet-iqsharp.exe) and running:

/path/to/dotnet-iqsharp install --user --path-to-tool="/path/to/dotnet-iqsharp"

where /path/to/dotnet-iqsharp should be replaced by the absolute path to the dotnet-iqsharp tool in your file system. Typically this will be under .dotnet/tools in your user profile folder.

---

That's it! You now have the IQ# kernel for Jupyter, which provides the core functionality for compiling and running Q# operations from Q# Jupyter Notebooks.

Create your first Q# notebook

Now you are ready to verify your Q# Jupyter Notebook installation by writing and running a simple Q# operation.

1. From the environment you created during installation (that is, either the conda environment you created, or the Python environment where you installed Jupyter), run the following command to start the Jupyter Notebook server:

   jupyter notebook
   

   • If the Jupyter Notebook doesn't open automatically in your browser, copy and paste the URL provided by the command line into your browser.

2. Choose New → Q# to create a Jupyter Notebook with a Q# kernel, and add the following code to the first notebook cell:

   open Microsoft.Quantum.Intrinsic;
   
   operation SampleQuantumRandomNumberGenerator() : Result {
       use q = Qubit(); // Allocate a qubit.
       H(q);            // Put the qubit to superposition. It now has a 50% chance of being 0 or 1.
       let r = M(q);    // Measure the qubit value.
       Reset(q);
       return r;
   }

3. Run this cell of the notebook:

   

   You should see SampleQuantumRandomNumberGenerator in the output of the cell. When running in Jupyter Notebook, the Q# code is compiled, and the cell outputs the name of any operations that it finds.

4. In a new cell, run the operation you just created (in a simulator) by using the %simulate command:

   

   You should see the result of the operation you invoked. In this case, because your operation generates a random result, you will see either Zero or One printed on the screen. If you run the cell repeatedly, you should see each result approximately half the time.

Note

In a Jupyter Notebook, Q# code is automatically wrapped in a namespace for you. Since Q# does not feature nested namespaces, you should make sure not to declare any additional namespaces inside of code cells.

Next steps

Now that you have installed the QDK for Q# Jupyter Notebooks, you can write and run your first quantum program by writing Q# code directly within the Jupyter Notebook environment.

For more examples of what you can do with Q# Jupyter Notebooks, please take a look at:

• Intro to Q# and Jupyter Notebook. There you will find a Q# Jupyter Notebook that provides more details on how to use Q# in the Jupyter environment.
• Quantum Katas, an open-source collection of self-paced tutorials and sets of programming exercises in the form of Q# Jupyter Notebooks. The Quantum Katas tutorial notebooks are a good starting point. The Quantum Katas are aimed at teaching you elements of quantum computing and Q# programming at the same time. They're an excellent example of what kind of content you can create with Q# Jupyter Notebooks.