Get started with Q# programs and Visual Studio Code

Article
03/18/2024

In this article you will find the steps to use VC Code to create and submit Q#, Jupyter Notebook, or Python quantum computing jobs to Azure Quantum using VS Code.

Submitting Q# jobs to Azure Quantum

Learn how to use VS Code to run, debug, and submit a Q# program to Azure Quantum.

Prerequisites

For installation details, see Installing the Modern QDK on VS Code.

An Azure Quantum workspace in your Azure subscription. To create a workspace, see Create an Azure Quantum workspace.
The latest version of Visual Studio Code or open VS Code on the Web.
The latest version of the Azure Quantum Development Kit extension.

Load a Q# sample program

In VS Code, select File > New Text File and save the file as RandomNum.qs.
Open RandomNum.qs and type sample, then select Random Bit sample from the list of options and save the file.

Note

You can also open your own Q# file. If you run an older Q# program and run into errors, see Testing and debugging or Migrating your programs to the Modern QDK.

Run a Q# program

To test run your program locally on the built-in simulator, click on Run from the list of commands below @EntryPoint(), or press Ctrl+F5. Your output will appear in the debug console.
To debug your program before submitting it to Azure Quantum, click on Debug from the list of commands below @EntryPoint(), or press F5. Use the debugging controls at the top to step over, into, and out of the code. For more information about debugging Q# programs, see Testing and debugging.

Visualize the frequency histogram

The frequency histogram represents the distribution of results obtained from running a quantum program multiple times, or "shots". Each bar in the histogram corresponds to a possible outcome, and its height represents the number of times that outcome is observed. The frequency histogram helps visualize the probability distribution of these outcomes.

Select View -> Command Palette and type “histogram” which should bring up the Q#: Run file and show histogram option. You can also click on Histogram from the list of commands below @EntryPoint(). Select this option to open the Q# histogram window.
Enter a number of shots to execute the program, for example, 100 shots, and press Enter. The histogram will display in the Q# histogram window.
Click the top-left settings icon to display options.
Click on a bar to display the percentage of that outcome. In this case there are two possible outcomes, 0 and 1, and the percentage of each outcome is close to 50%.

Tip

You can zoom the histogram using the mouse scroll wheel or a trackpad gesture. When zoomed in, you can pan the chart by pressing 'Alt' while scrolling.

Visualize the quantum circuit

Quantum circuit diagrams are a visual representation of quantum operations. They show the flow of qubits through the quantum program, including the gates and measurements applied to them. For more information, see Quantum circuit diagrams in Visual Studio Code.

Select View -> Command Palette and type “circuit” which should bring up the Q#: Show circuit option. You can also click on Circuit from the list of commands below @EntryPoint().
The circuit is displayed in the Q# circuit window. The circuit diagram shows one qubit register which it's initialized to the |0⟩ state. Then, a Hadamard gate, H, is applied to the qubit, followed by a measurement operation, which is represented by a meter symbol. For more information, see Quantum circuits conventions.

Connect to Azure Quantum and submit your job

You can connect and submit jobs directly from VS Code. For this example, you'll submit a job to the Rigetti simulator.

Select View -> Command Palette and type Q#: Connect to an Azure Quantum workspace. Press Enter.
Select Azure account, and follow the prompts to connect to your preferred directory, subscription, and workspace.

Note

If you have a connection string, you can select Connection string and paste the connection string corresponding to your Azure Quantum workspace. For more information, see Connect to a Quantum workspace using a connection string.
Once you are connected, in the Explorer pane, expand Quantum Workspaces.
Expand your workspace and expand the Rigetti provider.

Note

If there is an issue connecting to Azure Quantum, a warning icon displays next to the workspace name. Hover over the workspace name to display error information.
Select rigetti.sim.qvm as your target.
Select the play icon to the right of the target name to start submitting the current Q# program. If you get a popup, select Change the QIR target profile and continue.
Add a name to identify the job.
Add the number of shots, or number of times that the program is run.
Press Enter to submit the job. The job status will display at the bottom of the screen.
Expand Jobs and hover over your job, which displays the times and status of your job.
To view the results, select the cloud icon next to the job name to download the results from your workspace storage and display it in VS Code.

Submitting Jupyter Notebooks jobs to Azure Quantum

Learn how to use VS Code to run, debug, and submit a Q# Jupyter Notebook to Azure Quantum. The steps in this article also apply to Jupyter Notebooks on your local Jupyter server or notebooks in the Azure Quantum portal.

Prerequisites

For installation details, see Installing the Modern QDK on VS Code.

An Azure Quantum workspace in your Azure subscription. To create a workspace, see Create an Azure Quantum workspace.
A Python environment with Python and Pip installed.
VS Code with the Azure Quantum Development Kit, Python, and Jupyter extensions installed.
The Azure Quantum qsharp, qsharp-widgets, and azure-quantum packages, and the ipykernel package.
```
python -m pip install --upgrade qsharp qsharp-widgets azure-quantum ipykernel
```

Run and test your program in the local simulator

In VS Code, select View > Command palette and select Create: New Jupyter Notebook.
In the top-right, VS Code will detect and display the version of Python and the virtual Python environment that was selected for the notebook. If you have multiple Python environments, you may need to select a kernel using the kernel picker in the top right. If no environment was detected, see Jupyter Notebooks in VS Code for setup information.
In the first cell of the notebook, run the following Python code to import the necessary modules:
```
import qsharp
import azure.quantum
```
- The qsharp module activates the %%qsharp magic command that lets you enter Q# code directly into a cell.
- The azure-quantum module provides connectivity to your Azure Quantum workspace.
Note

If the Jupyter Python kernel ipykernel is not detected, VS Code will prompt you to install it.

Add another cell and enter this Q# code that returns a user-specified number of random bits:

Note

Notice that as soon as you type in the magic command %%qsharp, the notebook cell changes type from Python to Q#.

%%qsharp

operation Random() : Result {
    use q = Qubit();
    H(q);
    let result = M(q);
    Reset(q);
    return result
}

operation RandomNBits(N: Int): Result[] {
    mutable results = [];
    for i in 0 .. N - 1 {
        let r = Random();
        set results += [r];
    }
    return results
}

To test your operation, you can use the eval method, which can call any Q# operation previously defined in the notebook:
```
qsharp.eval("RandomNBits(4)")
```
```
[Zero, One, One, Zero]
```

To run your program to the local simulator, use the run method. Specify the shots, or number of times to run the program, and the simulator returns the results as a Python list.

qsharp.run("RandomNBits(4)", shots=10)

[[One, One, One, One],
[Zero, Zero, One, Zero],
[One, Zero, Zero, One],
[Zero, One, Zero, Zero],
[One, Zero, One, One],
[One, Zero, One, Zero],
[One, One, One, Zero],
[One, One, One, One],
[Zero, Zero, Zero, One],
[One, Zero, Zero, One]]

Visualize the quantum circuit

You can visualize quantum circuits using the qsharp-widgets package. This package provides a widget that renders a quantum circuit diagram as an SVG image. For more information, see Quantum circuit diagrams with Jupyter Notebooks.

Add the following code to a new cell to visualize the circuit:

from qsharp_widgets import Circuit

Circuit(qsharp.circuit("RandomNBits(4)"))

Screenshot of Jupyter Notebook showing how to visualize the circuit for a Q# operation.

For more information, see Quantum circuits conventions.

Compile your job using the Base profile

When you run programs on the local quantum simulator, you can submit any type of Q# program. However, Azure Quantum hardware targets do not yet support the full capabilities required to run all Q# programs. In order to compile and submit Q# programs to Azure Quantum, you need to set your target profile to tell Q# which capabilities your target hardware supports. Currently, that is the Base profile. For more information, see Profile types in Azure Quantum.

To reinitialize the Q# interpreter and compile your program with the base profile:

Use the init method to set the profile:

qsharp.init(target_profile=qsharp.TargetProfile.Base)

Since you reinitialized the interpreter, you need to run your code again with the new profile:

%%qsharp

operation Random() : Result {
    use q = Qubit();
    H(q);
    let result = M(q);
    Reset(q);
    return result
}

operation RandomNBits(N: Int): Result[] {
    mutable results = [];
    for i in 0 .. N - 1 {
        let r = Random();
        set results += [r];
    }
    return results
}

Next, use the compile method to specify the operation or function that is the entry point to your program. This compiles your code into QIR format, which can then be submitted to any quantum hardware:
```
MyProgram = qsharp.compile("RandomNBits(4)")
```

Connect to Azure Quantum and submit your job

Now that you have your program compiled into the correct format, create an azure.quantum.Workspace object to connect to Azure Quantum. You'll use the Resource ID of your Azure Quantum workspace in order to connect. The Resource ID and location can be copied from your workspace overview page in the Azure portal.

In a new cell, fill in your resource ID and location from your Azure Quantum workspace:

MyWorkspace = azure.quantum.Workspace(
    resource_id = "MyResourceID",
    location = "MyLocation"
)

Use the get_targets method to see the available hardware targets in your workspace:

MyTargets = MyWorkspace.get_targets()
print("This workspace's targets:")
MyTargets

Select the rigetti.sim.qvm target:

MyTarget = MyWorkspace.get_targets("rigetti.sim.qvm")

Lastly, use the submit method to submit your program with its parameters and display the results:

job = MyTarget.submit(MyProgram, "MyQuantumJob", shots=100)
job.get_results()

{'Histogram': ['[0, 0, 0, 0]',
  0.3,
  '[1, 0, 0, 0]',
  0.1,
  '[1, 1, 1, 1]',
  0.3,
  '[0, 1, 1, 1]',
  0.3]}

All the properties of the job are accessible in job.details, for example:

print(job.details)
print("\nJob name:", job.details.name)
print("Job status:", job.details.status)
print("Job ID:", job.details.id)

{'additional_properties': {'isCancelling': False}, 'id': '0150202e-9638-11ee-be2f-b16153380354', 'name': 'MyQuantumJob', 'provider_id': 'rigetti'...}
Job name: MyQuantumJob
Job status: Succeeded
Job ID: 0150202e-9638-11ee-be2f-b16153380354

Submitting Python with Q# jobs to Azure Quantum

Learn how to use VS Code to write a Python program that calls Q# operations, connect to Azure using the Python commands or Azure CLI, and submit your job.

Prerequisites

For installation details, see Installing the Modern QDK on VS Code.

An Azure Quantum workspace in your Azure subscription. To create a workspace, see Create an Azure Quantum workspace.
A Python environment with Python and Pip installed.
VS Code with the Azure Quantum Development Kit and Python extension installed.
The Azure Quantum qsharp and azure-quantum packages.
Azure CLI with the latest Azure Quantum extension installed.

Create and import your Q# operations

With the qsharp package, you can store your functions and operations in Q# files and create Q# projects that let you call into any of them from your Python code. This especially helpful when you need to launch a program that takes input parameters.

Follow the steps to create a Q# project.
Open a new text file, add the following Q# code that returns a user-specified number of random bits, and save the file to the /src directory in your project as source.qs.

Note

Note that this Q# code doesn't have an @EntryPoint function like a Q# program (see Submitting Q# jobs to Azure Quantum), but it does require a namespace, unlike a Jupyter Notebook (see Submitting Jupyter Notebook jobs to Azure Quantum).
```
namespace Sample {

  operation Random() : Result {
        use q = Qubit();
        H(q);
        let result = M(q);
        Reset(q);
        return result
  }

  operation RandomNBits(N: Int): Result[] {
        mutable results = [];
        for i in 0 .. N - 1 {
           let r = Random();
           set results += [r];
        }
        return results
  }
}
```
In the project root folder (with the qsharp.json file), open another file and save it as randomNum.py.
Add the following code to import the qsharp and azure.quantum modules.
```
import qsharp
import azure.quantum
```
Next, add code to define the Q# project root folder and test run the target operation on the local simulator. The operation is called by <namespace>.<operation_name( )>, and in this case, you are passing in the number of random bits to return.
```
qsharp.init(project_root = '../MyProjectRootFolder')
print(qsharp.eval("Sample.RandomNBits(4)"))
```
```
[Zero, One, One, Zero]
```

You can also test the operation with the run method, which passes an additional shots parameter, and returns the results in a Python list. In randomNum.py, replace the previous print statement with the following:

result = qsharp.run("Sample.RandomNBits(4)", shots=10)
for x in result:
    print(x)

[[One, One, One, One],
[Zero, Zero, One, Zero],
[One, Zero, Zero, One],
[Zero, One, Zero, Zero],
[One, Zero, One, One],
[One, Zero, One, Zero],
[One, One, One, Zero],
[One, One, One, One],
[Zero, Zero, Zero, One],
[One, Zero, Zero, One]]

Compile your job using the Base profile

When you run programs on the local quantum simulator, you can submit any type of Q# program. However, Azure Quantum hardware targets do not yet support the full capabilities required to run all Q# programs. In order to compile and submit Q# programs to Azure Quantum, you need to set your target profile to tell Q# which capabilities that your target hardware supports. Currently, that is the Base profile. For more information, see Profile types in Azure Quantum.

Note

For Q# only programs in VS Code, VS Code sets the Base profile automatically.

Use the init method to set the profile:

qsharp.init(target_profile=qsharp.TargetProfile.Base)

Then use the compile method to specify the operation or function that is the entry point to your program. The compiled program can then be submitted to any quantum hardware:
```
MyProgram = qsharp.compile("Sample.RandomNBits(4)")
```

Connect to Azure Quantum and submit your job

You can connect to Azure Quantum and submit your job using a Python-created Workspace object, or connect and submit your job using Azure CLI. Using Azure CLI requires that you save the compiled program as a text file and submit that file using a CLI command.

Using Python
Using the Azure CLI

Add the following code to randomNum.py, filling in your resource ID and location from your Azure Quantum workspace:
```
workspace = azure.quantum.Workspace(
    resource_id = "MyResourceID",
    location = "MyLocation"
)
```

Use the get_targets method to display the available hardware targets in your workspace:

MyTargets = workspace.get_targets()
print("This workspace's targets:")
for x in MyTargets:
    print(x)

Select the rigetti.sim.qvm target:

MyTarget = workspace.get_targets("rigetti.sim.qvm")

Lastly, use the submit method to submit your program with its parameters. The job results are returned as a Python dictionary.
```
job = MyTarget.submit(MyProgram, "MyPythonJob", shots=100)
results = job.get_results()
print("\nResults: ", results)
```

To extract just the values and display them:

resultList = results.get("Histogram")
for x in resultList:
    print(x)

[0, 0, 0, 0]
0.3
[1, 0, 0, 0]
0.1
[1, 1, 1, 1]
0.3
[0, 1, 1, 1]
0.3

All the properties of the job are accessible in job.details, for example:

print(job.details)
print("\nJob name:", job.details.name)
print("Job status:", job.details.status)
print("Job ID:", job.details.id)

{'additional_properties': {'isCancelling': False}, 'id': '0fc396d2-97dd-11ee-9958-6ca1004ff31f', 'name': 'MyPythonJob', 'provider_id': 'rigetti'...}
Job name: MyPythonJob
Job status: Succeeded
Job ID: fc396d2-97dd-11ee-9958-6ca1004ff31f

To submit a job to Azure Quantum with the Azure CLI, you need to submit a physical file of the program that you just compiled.

Add to following code to your randomNum.py file. This opens a text file and writes your compiled program to the proper format.
```
file = open("compiled_output.txt", "w")
file.write(MyProgram._ll_str)
file.close()
```
To submit the job to Azure Quantum, login with the Azure CLI:
```
az login
```
Ensure you are running the latest version of the Azure CLI quantum extension:
```
az extension add --upgrade --name quantum
```
Specify the subscription you want to use from those associated with your Azure account. You can also find your subscription ID in the overview of your workspace in Azure portal.
```
az account set -s <MySubscriptionID>
```
View your available workspaces with:
```
az quantum workspace list
```

You can use quantum workspace set to select a default workspace that you want to use to list and submit jobs.

az quantum workspace set \
   -g <MyResourceGroup> \
   -w <MyWorkspace> \
   -l <MyLocation> \
   -o table

Display the available targets in your workspace with:
```
az quantum target list -o table
```
Submit your job using the job submit command.
- --target-id can be any target. For this example, use the rigetti.sim.qvm target.
- --job-name can be any string.
- --job-input-format is always qir.v1.
- --job-input-file is the name of the text file you created in step 1.
- --entry-point is always ENTRYPOINT__main
```
az quantum job submit \
    --target-id rigetti.sim.qvm \
    --job-name MyQuantumJob \
    --job-input-format qir.v1 \
    --job-input-file compiled_output.txt \
    --entry-point ENTRYPOINT__main
```

To check the status of the job, copy the id from the output of the last step and use the job show command:

az quantum job show --job-id b0012975-744a-4405-970e-3d8dc4afb2c0 -o table

Name      Id                                    Status     Target           Submission time                   Completion time                  
--------  ------------------------------------  ---------  ---------------  --------------------------------  -------------------------------- 
MyQuantumJob  b2f07cc4-b49b-40b0-b63b-9a4885e5fef5  Succeeded  rigetti.sim.qvm  2023-12-11T05:33:23.187773+00:00  2023-12-11T05:33:29.252742+00:00

To view the output of the job, use the job output command:

az quantum job output --job-id b0012975-744a-4405-970e-3d8dc4afb2c0 -o table

Result        Frequency
------------  -----------  ----------------------
[0, 1, 1, 1]  1.00000000   |████████████████████|

Share via

Get started with Q# programs and Visual Studio Code

Submitting Q# jobs to Azure Quantum

Prerequisites

Load a Q# sample program

Run a Q# program

Visualize the frequency histogram

Visualize the quantum circuit

Connect to Azure Quantum and submit your job

Submitting Jupyter Notebooks jobs to Azure Quantum

Prerequisites

Run and test your program in the local simulator

Visualize the quantum circuit

Compile your job using the Base profile

Connect to Azure Quantum and submit your job

Submitting Python with Q# jobs to Azure Quantum

Prerequisites

Create and import your Q# operations

Compile your job using the Base profile

Connect to Azure Quantum and submit your job

Next steps

Feedback

Feedback

Additional resources