Microsoft Q# — Quantum Programming with Azure Quantum

In this tutorial, you'll learn about Microsoft Q#. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

Microsoft Q# (Q-sharp) is a domain-specific programming language for quantum algorithms, integrated with Azure Quantum and the Quantum Development Kit for simulation and execution.

What You'll Learn

By the end of this tutorial, you will understand Q# syntax, write quantum programs, use the Quantum Development Kit (QDK), run simulations, and implement quantum algorithms like teleportation and Grover search.

Why It Matters

Q# is Microsoft's entry in the Quantum Computing ecosystem, deeply integrated with Azure Quantum for cloud access to diverse hardware (IonQ, Quantinuum, Rigetti). Q# provides a high-level programming model with type safety, resource estimation, and seamless classical-quantum integration.

Real-World Use

Azure Quantum customers use Q# for quantum chemistry simulations in drug discovery (with Johnson & Johnson), financial portfolio optimization (with Goldman Sachs), and Quantum Machine Learning research. Microsoft's resource estimator helps plan for fault-tolerant quantum execution.

Learning Path

flowchart LR
  A[Google Cirq] --> B[Microsoft Q#]
  B --> C[Quantum Hardware]
  B --> D{You Are Heaven}
  style D fill:#f90,color:#fff

Setting Up the QDK

# Install the Quantum Development Kit
dotnet tool install -g Microsoft.Quantum.IQSharp
dotnet iqsharp install

# Or install the QDK for Python
pip install qsharp

# Verify installation
python -c "import qsharp; print(qsharp.__version__)"
# Expected: 1.x.x

Your First Q# Program

Q# files have a .qs extension and define operations and functions.

// BellState.qs
namespace Quantum.BellState {
    open Microsoft.Quantum.Intrinsic;
    open Microsoft.Quantum.Measurement;
    open Microsoft.Quantum.Canon;

    @EntryPoint()
    operation CreateBellState() : (Result, Result) {
        // Allocate two qubits
        using ((q0, q1) = (Qubit(), Qubit())) {
            // Initialize to |0⟩
            Reset(q0);
            Reset(q1);

            // Create Bell state
            H(q0);           // Superposition
            CNOT(q0, q1);    // Entangle

            // Measure both qubits
            let result0 = MResetZ(q0);
            let result1 = MResetZ(q1);

            return (result0, result1);
        }
    }
}

Running from Python

# run_bell_state.py
import qsharp
from Quantum.BellState import CreateBellState

# Run the Q# operation
print("=== Bell State with Q# ===")

# Run multiple times and collect statistics
results = {"(Zero, Zero)": 0, "(One, One)": 0, "(Zero, One)": 0, "(One, Zero)": 0}
for _ in range(4096):
    result = CreateBellState.simulate()
    key = f"({result[0]}, {result[1]})"
    results[key] += 1

print(f"Results: {results}")

Expected output:

=== Bell State with Q# ===
Results: {'(Zero, Zero)': 2048, '(One, One)': 2048, '(Zero, One)': 0, '(One, Zero)': 0}

Q# Language Features

Qubit Types and Operations

// qubit_types.qs
namespace Quantum.QubitTypes {
    open Microsoft.Quantum.Intrinsic;
    open Microsoft.Quantum.Measurement;

    operation UseQubitTypes() : Unit {
        // Single qubit
        using (q = Qubit()) {
            H(q);
            let result = MResetZ(q);
            Message($"Measured: {result}");
        }

        // Array of qubits
        using (qubits = Qubit[3]) {
            ApplyToEach(H, qubits);
            let results = MultiM(qubits);
            Message($"Results: {results}");
        }
    }
}

Controlled Operations and Adjoints

// controlled_adjoint.qs
namespace Quantum.ControlledAdjoint {
    open Microsoft.Quantum.Intrinsic;
    open Microsoft.Quantum.Canon;

    operation ApplyControlledH(control : Qubit, target : Qubit) : Unit is Adj + Ctl {
        // Controlled-Hadamard using decomposition
        H(target);
        CNOT(control, target);
        H(target);
        T(target);
        CNOT(control, target);
        T(target);
        H(target);
    }

    operation DemonstrateAdjoint() : Unit {
        using ((q0, q1) = (Qubit(), Qubit())) {
            // Apply operation
            ApplyControlledH(q0, q1);

            // Apply adjoint (inverse) — automatically generated
            Adjoint ApplyControlledH(q0, q1);
        }
    }
}

Quantum Teleportation in Q#

// QuantumTeleportation.qs
namespace Quantum.Teleportation {
    open Microsoft.Quantum.Intrinsic;
    open Microsoft.Quantum.Measurement;
    open Microsoft.Quantum.Canon;

    operation TeleportMessage() : Unit {
        using ((message, alice, bob) = (Qubit(), Qubit(), Qubit())) {
            // Prepare message state: |+⟩ = (|0⟩ + |1⟩)/√2
            H(message);

            // Create Bell pair between Alice and Bob
            H(alice);
            CNOT(alice, bob);

            // Alice: CNOT with message and her qubit
            CNOT(message, alice);

            // Alice: Hadamard on message qubit
            H(message);

            // Alice measures her two qubits
            let msg_result = MResetZ(message);
            let alice_result = MResetZ(alice);

            // Bob applies corrections based on classical bits
            if (alice_result == One) {
                X(bob);
            }
            if (msg_result == One) {
                Z(bob);
            }

            // Verify teleportation by measuring Bob's qubit in X basis
            H(bob);
            let bob_result = MResetZ(bob);
            Message($"Bob's result: {bob_result}");
        }
    }
}

Running Teleportation

# run_teleport.py
import qsharp
from Quantum.Teleportation import TeleportMessage

print("=== Quantum Teleportation in Q# ===")
for _ in range(10):
    TeleportMessage.simulate()

Expected output:

=== Quantum Teleportation in Q# ===
Bob's result: Zero
Bob's result: Zero
Bob's result: One
Bob's result: Zero
...

Resource Estimation

One of Q#'s most powerful features is resource estimation (counting qubits, gates, and T-depth without running the full circuit).

// resource_estimate.qs
namespace Quantum.ResourceEstimate {
    open Microsoft.Quantum.Intrinsic;
    open Microsoft.Quantum.Canon;
    open Microsoft.Quantum.Arrays;

    operation ShorResourceEstimate(nBits : Int) : Unit {
        // Resource estimate for Shor period finding
        let nQubits = 2 * nBits + 3;

        using (qubits = Qubit[nQubits]) {
            // Hadamard on counting qubits
            ApplyToEach(H, qubits[0..nBits-1]);

            // Modular exponentiation (conceptual)
            // In practice, use Microsoft.Quantum.ResourceEstimation

            // QFT on counting qubits
            // QFT(qubits[0..nBits-1]);

            Message($"Qubits needed: {nQubits}");
            Message($"Requires fault-tolerant implementation");
        }
    }
}

Python Resource Estimation

# estimate_resources.py
import qsharp
from Quantum.ResourceEstimate import ShorResourceEstimate

print("=== Resource Estimation ===")

# The ResourceEstimator estimates qubit counts and gate depths
# This is a key feature for planning fault-tolerant execution

try:
    # Use the resource estimator instead of simulator
    result = ShorResourceEstimate.estimate_resources(nBits=4)
    print(f"Qubit count: {result['qubitCount']}")
    print(f"T gates: {result['tCount']}")
    print(f"CNOT gates: {result['cnotCount']}")
    print(f"Depth: {result['depth']}")
except Exception as e:
    print(f"Resource estimation requires Azure Quantum SDK: {e}")
    print("Note: Install Microsoft.Quantum.ResourceEstimation package")

Grover Search in Q#

// GroverSearch.qs
namespace Quantum.GroverSearch {
    open Microsoft.Quantum.Intrinsic;
    open Microsoft.Quantum.Measurement;
    open Microsoft.Quantum.Canon;
    open Microsoft.Quantum.Math;

    operation Oracle(qubits : Qubit[], target : Int) : Unit {
        // Mark target by flipping its phase
        let nQubits = Length(qubits);

        // Convert target to binary
        for i in 0..nQubits-1 {
            let bit = (target >>> i) &&& 1;
            if bit == 0 {
                X(qubits[i]);
            }
        }

        // Multi-controlled Z
        Controlled Z(qubits[0..nQubits-2], qubits[nQubits-1]);

        // Undo X gates
        for i in 0..nQubits-1 {
            let bit = (target >>> i) &&& 1;
            if bit == 0 {
                X(qubits[i]);
            }
        }
    }

    operation Diffusion(qubits : Qubit[]) : Unit {
        let nQubits = Length(qubits);
        ApplyToEach(H, qubits);
        ApplyToEach(X, qubits);

        // Multi-controlled Z
        Controlled Z(qubits[0..nQubits-2], qubits[nQubits-1]);

        ApplyToEach(X, qubits);
        ApplyToEach(H, qubits);
    }

    @EntryPoint()
    operation RunGroverSearch() : Int {
        let nQubits = 3;
        let target = 5;  // Search for |101⟩
        let nIterations = Round(PI() / 4.0 * Sqrt(IntAsDouble(2^nQubits)));

        mutable result = 0;

        using (qubits = Qubit[nQubits]) {
            // Initialize to |0...0⟩
            ResetAll(qubits);

            // Initial superposition
            ApplyToEach(H, qubits);

            // Grover iterations
            for _ in 1..nIterations {
                Oracle(qubits, target);
                Diffusion(qubits);
            }

            // Measure
            let measurements = MultiM(qubits);
            set result = ResultArrayAsInt(measurements);
            ResetAll(qubits);
        }

        Message($"Found: {result}");
        return result;
    }
}

Running Grover

# run_grover.py
import qsharp
from Quantum.GroverSearch import RunGroverSearch

print("=== Grover Search in Q# ===")

results = {}
for _ in range(1000):
    result = RunGroverSearch.simulate()
    results[result] = results.get(result, 0) + 1

print(f"Results (1000 runs):")
for key, count in sorted(results.items()):
    bitstring = format(key, '03b')
    print(f"  |{bitstring}⟩: {count} ({count/10:.1f}%)")

Expected output:

=== Grover Search in Q# ===
Results (1000 runs):
  |000⟩: 12 (1.2%)
  |001⟩: 8 (0.8%)
  |010⟩: 10 (1.0%)
  |011⟩: 15 (1.5%)
  |100⟩: 9 (0.9%)
  |101⟩: 945 (94.5%)
  |110⟩: 6 (0.6%)
  |111⟩: 10 (1.0%)

Q# with Python Host

Q# integrates seamlessly with Python for classical orchestration.

# qsharp_host.py
import qsharp
import numpy as np

# Define a Q# operation inline
qsharp.eval("""
    operation PrepareSuperposition(angle : Double) : (Result, Result) {
        using ((q0, q1) = (Qubit(), Qubit())) {
            Ry(angle, q0);
            CNOT(q0, q1);
            let r0 = MResetZ(q0);
            let r1 = MResetZ(q1);
            return (r0, r1);
        }
    }
""")

# Run with different parameters
print("=== Parameterized Q# from Python ===")
for angle in [0.0, np.pi/4, np.pi/2, np.pi]:
    results = {"(Zero, Zero)": 0, "(One, One)": 0, "(Zero, One)": 0, "(One, Zero)": 0}
    for _ in range(1024):
        r0, r1 = qsharp.eval(f"PrepareSuperposition({angle})")
        key = f"({r0}, {r1})"
        results[key] += 1
    print(f"angle={angle:.2f}: {results}")

Expected output:

=== Parameterized Q# from Python ===
angle=0.00: {'(Zero, Zero)': 1024, '(One, One)': 0, ...}
angle=0.79: {'(Zero, Zero)': 854, '(One, One)': 170, ...}
angle=1.57: {'(Zero, Zero)': 512, '(One, One)': 512, ...}
angle=3.14: {'(Zero, Zero)': 0, '(One, One)': 1024, ...}

Common Mistakes

1. Forgetting Qubit Reset

Qubits must be returned to |0⟩ state before release. Using MResetZ instead of M ensures automatic reset. Forgetting this causes runtime errors.

2. Confusing Q# Types

Unlike Python, Q# is strongly typed. Int vs Double vs Result matter. Use type conversions (IntAsDouble, ResultArrayAsInt) explicitly.

3. Missing the EntryPoint

A Q# program needs an @EntryPoint() attribute on the entry operation, or you must specify which operation to call from Python.

4. Using M instead of MResetZ

M measures without resetting. In simulators this works, but on real hardware, qubits must be reset. MResetZ is the safer choice.

5. Ignoring Resource Costs

Q# compiles to quantum instruction sets. Large circuits may exceed resource limits. Use the Resource Estimator before running on hardware.

Practice Questions

1. What is Q# and how is it different from Qiskit?

Q# is a Domain-Specific Language for Quantum Computing, while Qiskit is a Python SDK. Q# has built-in support for adjoints, controlled operations, and resource estimation.

2. How does Q# handle qubit allocation?

Qubits are allocated using using blocks. They start in |0⟩ state and must be reset before release. MResetZ combines measurement and reset.

3. What is the Quantum Development Kit?

The QDK is Microsoft's toolchain for Q#: compiler, simulator, resource estimator, and Azure Quantum integration. It supports VS Code, Jupyter, and Python hosts.

4. How does Azure Quantum work with Q#?

Azure Quantum provides cloud access to IonQ, Quantinuum, and Rigetti hardware. Q# programs are submitted as jobs and executed on the selected target.

5. What is resource estimation in Q#?

Resource estimation counts qubits, T-gates, and circuit depth without full simulation. This helps determine fault-tolerant resource requirements for algorithms.

Challenge: Implement Shor's Algorithm in Q#

Using Q#'s built-in number theory and QFT libraries, implement Shor's algorithm:

namespace Quantum.Shor {
    open Microsoft.Quantum.Intrinsic;
    open Microsoft.Quantum.Arithmetic;
    open Microsoft.Quantum.Characterization;

    operation FactorNumber(N : Int) : (Int, Int) {
        // Implement Shor's factoring algorithm
        // Use integer arithmetic and QFT
        return (0, 0);
    }
}

Hints: Use Microsoft.Quantum.Arithmetic for modular exponentiation and Microsoft.Quantum.Characterization.QFT for the quantum Fourier transform.

Real-World Task: Quantum Chemistry with Q#

Use Q#'s quantum chemistry libraries to compute the ground state energy of molecular hydrogen:

import qsharp
from Microsoft.Quantum.Chemistry import *

Set up the Hamiltonian for H₂, create a variational ansatz, and run VQE to find the minimum energy. Compare to the known ground state energy of H₂ (-1.137 Ha at equilibrium bond length). This workflow is used by quantum chemists at Microsoft and partner organizations.

FAQ

Try It Yourself

Install the QDK and run the Bell state program. Experiment with different gates and measurements. Try the resource estimator to understand qubit and gate counts for your circuits.

What's Next

You now understand Microsoft Q# and Azure Quantum. Next, you will learn about the physical hardware platforms that implement quantum computers.

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro. Last updated: 2026-06-21.