We are modernizing the quantum katas experience. Please visit https://quantum.microsoft.com/experience/quantum-katas to try the new online Azure Quantum katas experience, with integrated assistance from Copilot in Azure Quantum.
For the Modern QDK repository, please visit Microsoft/qsharp.
For more information about the Modern QDK and Azure Quantum, visit https://aka.ms/AQ/Documentation.
The Quantum Katas are a collection of self-paced tutorials and programming exercises to help you learn quantum computing and Q# programming.
Each kata is a separate set of exercises that includes:
The Quantum Katas also include tutorials that introduce the learner to the basic concepts and algorithms used in quantum computing, starting with the necessary math (complex numbers and linear algebra). They follow the same pattern of supplementing the theory with Q# demos and hands-on programming exercises.
Here is the learning path we suggest you to follow if you are starting to learn quantum computing and quantum programming. Once you're comfortable with the basics, you're welcome to jump ahead to the topics that pique your interest!
For a Q# programming language quick reference sheet, see Q# Language Quick Reference.
The Quantum Katas are now available as Jupyter Notebooks online! See index.ipynb for the list of all katas and tutorials, and instructions for running them online.
Note that mybinder.org is running with reduced capacity, so getting a virtual machine and launching the notebooks on it might take several attempts. While running the Katas online is the easiest option to get started, if you want to save your progress and enjoy better performance, we recommend you to choose the local setup option.
To use the Quantum Katas locally, you'll need the Quantum Development Kit, available for Windows 10, macOS, and Linux. If you don't already have the Quantum Development Kit installed, see the install guide for the Quantum Development Kit.
If you want to run the katas and tutorials locally as Jupyter Notebooks:
pytest
package.matplotlib
package.matplotlib
and numpy
packages.
Refer to Updating IQ# kernel for updating IQ# kernel to a new version with monthly QDK releases.
If you want to run the katas and tutorials locally as Q# projects:
Follow the steps in the QDK install guide for Visual Studio, Visual Studio Code or other editors.
Running the Q# projects of the Katas locally requires downloading and installing the .NET 6.0 SDK. You can do this even if you have another .NET version installed, since multiple versions are supported side-by-side.
Since Visual Studio 2019 does not support .NET 6.0 projects, you will need to upgrade to Visual Studio 2022 and install the corresponding Microsoft Quantum Development Kit extension.
If you have Git installed, clone the Microsoft/QuantumKatas repository:
$ git clone https://github.com/Microsoft/QuantumKatas.git
TIP
Both Visual Studio 2022 and Visual Studio Code make it easy to clone repositories from within your development environment. For details, see the Visual Studio and Visual Studio Code documentation.
If you don't have Git installed, download the katas from https://github.com/Microsoft/QuantumKatas/archive/main.zip.
The best way to run the katas as Jupyter Notebooks is to navigate to the root folder of the repository and to open index.ipynb
using Jupyter:
$ cd QuantumKatas/
$ jupyter notebook index.ipynb
This will open the notebook that contains a list of all katas and tutorials, and you will be able to navigate to the one you want using links.
NOTE: This will start Jupyter Notebooks server in the same command line window you used to run the command. If you want to keep using that window for navigation, you can launch Jupyter Notebooks server in a new window using the following commands:
For Windows:
$ cd QuantumKatas/ $ start jupyter notebook index.ipynb
For Ubuntu:
$ cd QuantumKatas/ $ gnome-terminal -- start jupyter notebook index.ipynb
You can also open an individual notebook directly, but this might render internal links invalid:
$ cd QuantumKatas/tutorials/ComplexArithmetic
$ jupyter notebook ComplexArithmetic.ipynb
Each kata is in its own directory as a self-contained Q# project, solution and Jupyter Notebook triplet. For instance, the BasicGates directory structure is:
QuantumKatas/
BasicGates/
README.md # Instructions specific to this kata.
.vscode/ # Metadata used by Visual Studio Code.
BasicGates.sln # Visual Studio solution file.
BasicGates.csproj # Project file used to build both classical and quantum code.
BasicGates.ipynb # Jupyter Notebook front-end for this kata.
Workbook_BasicGates.ipynb # Jupyter Notebook workbook for this kata.
Tasks.qs # Q# source code that you will fill as you solve each task.
Tests.qs # Q# tests that verify your solutions.
ReferenceImplementation.qs # Q# source code containing solutions to the tasks.
To open the BasicGates kata in Visual Studio 2022, open the QuantumKatas/BasicGates/BasicGates.sln solution file.
To open the BasicGates kata in Visual Studio Code, open the QuantumKatas/BasicGates/ folder. Press Ctrl + Shift + P (or ⌘ + Shift + P on macOS) to open the Command Palette. Type Open Folder on Windows 10 or Linux or Open on macOS.
TIP
Almost all commands available in Visual Studio Code are in the Command Palette. If you get stuck, press Ctrl + Shift + P (or ⌘ + Shift + P on macOS) and start typing to search through all available commands.You can also launch Visual Studio Code from the command line:
$ code QuantumKatas/BasicGates/
Once you have a kata open, it's time to run the tests using the following instructions. Initially all tests will fail. Don't panic! Open Tasks.qs and start filling in the code to complete the tasks. Each task is covered by a unit test. Once you fill in the correct code for a task, rebuild the project and re-run the tests, and the corresponding unit test will pass.
cd
command.dotnet test
in the integrated terminal.
This should build the kata project and run all of the unit tests. All of the unit tests should fail.dotnet test
again.For convenience, a tasks.json configuration file exists for each kata. It allows Visual Studio Code to run the build and test steps from the Command Palette. Press Ctrl + Shift + P (or ⌘ + Shift + P on macOS) to open the Palette and type Run Build Task or Run Test Task and press Enter.
You can use the included Dockerfile to create a docker image with all the necessary tools to run the katas from the command line or Jupyter.
katas
:docker build -t katas .
katas-container
with interactive command-line and redirect container port 8888
to local port 8888
(needed to run Jupyter):docker run -it --name katas-container -p 8888:8888 katas /bin/bash
cd ~/BasicGates/
dotnet test
cd ~/BasicGates/ && jupyter notebook --ip=0.0.0.0 --no-browser
http://localhost:8888/notebooks/BasicGates.ipynb
To exit a docker container without killing it (daemon mode), press Ctrl+P, Ctrl+Q
To re-enter the existing katas-container
(in daemon mode):
docker attach katas-container
Once you're done, remove the katas-container
:
docker rm --force katas-container
This project welcomes contributions and suggestions. See How Can I Contribute? for details.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.