The Q# User Guide

Welcome to the Q# User Guide!

In the different topics of this guide, we detail the core concepts of the Q# language and all the information you need to write quantum programs.

User Guide Contents

  • Q# Basics: An introductory overview of the purpose and functionality of the Q# programming language.

  • Ways to run a Q# program: describes how a Q# program is run, and provides an overview of the various ways you can call the program: from the command line, in Q# Jupyter Notebooks, or from a classical host program written in Python or a .NET language.

Q# Language

  • Types in Q#: Lays out the Q# type model and describes the syntax for specifying and working with types.

  • Type Expressions: Details how to specify, reference, combine, and operate on values of each type in Q#.

Using Q#

  • Q# File Structure: Describes the structure and syntax of a *.qs Q# file.

  • Operations and Functions: Details the two callable types of the Q# language: operations, which include action on qubit registers, and functions, which strictly work with classical information. Here you see how to define and call them, including the adjoint and controlled versions of quantum operations.

  • Variables: Describes the role of variables within Q# programs and how to leverage them effectively. For example, you can find information about binding scopes, as well as the difference between immutable and mutable variables and how to assign or re-assign them.

  • Working with qubits: Describes the features of Q# used to address individual qubits and systems of qubits, specifically, allocating them, performing operations on them, and measuring them.

  • Control Flow: Details the programming control flow patterns available in Q#, which includes many standard techniques (such as conditional processing, for loops, while loops) as well as the quantum-specific Repeat-Until-Success pattern.

  • Testing and debugging: Details some techniques for making sure your code is doing what it is supposed to do. Due to the general opacity of quantum information, debugging a quantum program can require specialized techniques. Fortunately, Q# supports many of the classical debugging techniques programmers are familiar with, as well as those that are quantum-specific. These include creating and running unit tests in Q#, embedding assertions on values and probabilities in your code, and the Dump functions which output the states of target machines. The latter can be used alongside our full-state simulator to debug certain parts of computations by skirting some quantum limitations, for example, the no-cloning theorem.

Quantum Simulators and Resource Estimators

  • Quantum simulators and host applications: An overview of the different simulators available, as well of how host programs and target machines work together to run Q# programs.

  • Full state simulator: The target machine which simulates the full quantum state. Useful for fully running or debugging smaller-scale programs (less than a few dozen qubits)

  • Resources estimator: Estimates the resources required to run a given instance of a Q# operation on a quantum computer.

  • Trace simulator: Runs a quantum program without actually simulating the state of a quantum computer, and therefore can run quantum programs that use thousands of qubits. Useful for debugging classical code within a quantum program, as well as estimating resources required.

  • Toffoli simulator: A special-purpose quantum simulator that can be used with millions of qubits, but only for programs with a restricted set of quantum operations - X, CNOT, and multi-controlled X.

Quick Reference Pages

  • IQ# Magic Commands: Quick reference page for IQ# magic commands within Q# Jupyter Notebooks.