Repository files navigation

Welcome to the Azure Quantum Development Kit!

This repository contains tooling for the Q# language, specifically:

• compiler: core compiler logic and command-line tooling
• fuzz: fuzz testing infrastructure
• jupyterlab: JupyterLab extension
• language_service: Q# language service and editor features
• library: Q# standard library
• npm: Q# npm package
• pip: Q# Python pip package
• playground: simple website for interacting with Q#
• resource_estimator: Implementation for the Azure Quantum Resource Estimator
• vscode: Visual Studio Code extension
• wasm: The bindings and logic for the WebAssembly module
• widgets: The Q# Jupyter widgets Python package

There are also the tutorials and samples in the./katas and./samples directories, respectively.

Code from this repository powers the Q# development experience onhttps://quantum.microsoft.com.

To build this repository there are dependencies that need to be installed. These are:

• Python (https://python.org)
• Rust (https://www.rust-lang.org/tools/install)
  • On all platforms, thewasm32-unknown-unknown must be installed to build the WASM based components

    rustup target add wasm32-unknown-unknown

  • On MacOS, ensure that bothaarch64 andx86_64 targets are installed or you will encounter linking errors.

    rustup target add x86_64-apple-darwinrustup target add aarch64-apple-darwin

• Node.js (https://nodejs.org/)
• AC compiler
• wasm-bindgen (seehttps://github.com/rustwasm/wasm-bindgen)
• wasm-opt (seehttps://github.com/WebAssembly/binaryen)

The last two can be installed into your HOME directory by runningpython ./prereqs.py --install

The build script will check these dependencies and their versions and fail if not met. (Or runpython ./prereqs.py directly to check if the minimum required versions are installed).

To build, in the root directory runpython ./build.py. By default this will run a releasebuild of each project, including running tests and checks such as linting. Run with the--help option for detailed usage.

Theplayground is a small website that loads the Q# editor, compiler, samples, katas, and documentation for the standard library. It's a way to manually validate any changes you make to these components.

To see instructions for building the playground, refer toBuilding the Playground Locally.

When building the Python packages (pip andjupyterlab), if the build script does not detecta current Python virtual environment, it will automatically create one undersource/pip/.venv orsource/jupyterlab/.venv. When developing locally, you can use these virtual environments to run thetests by runningsource .venv/bin/activate (Linux/MacOS) or.venv/Scripts/activate.bat (Windows).

The easiest way to develop in this repo is to use VS Code. When you open the project root, bydefault VS Code will recommend you install the extensions listed in.vscode/extensions.json.These extensions provide language services for editing, as well as linters and formatters toensure the code meets the requirements (which are checked by thebuild.py script and CI).

Some settings are recommended (but not enforced) to make development easier. These are in the.vscode/*.shared.json files. If theWorkspace Config+extension is installed, this will automatically apply these settings, as well as overrides fromyour own corresponding.vscode/*.local.json settings. If you don't install this extension, you canuse these as a reference for editing your own.vscode/*.json settings files. (See the extensionhome page for more details).

Debugging the VS Code extension is best done inside VS Code by launching with F5(orRun / Start Debugging from the VS Code menu). Thelaunch.shared.jsonfile will be applied if using theWorkspace Config+ extension outlined above,and this includes a command-line flag to launch the development instance with aprofile nameddev. (If not familiar with VS Code profiles seehttps://code.visualstudio.com/docs/configure/profiles).

This allows you to develop in the main VS Code instance with all your regularextensions enabled (including the QDK), but use adev profile that onlyincludes the minimal extensions for testing (e.g. GitHub Copilot, Python,Jupyter). This avoids the issue where launching with all extensions disabledstops you from testing Copilot, Python, etc., but launching with your defaultextensions enabled will cause conflicts with the installed QDK and the one beingdebugged.

By default the debugger will launch a VS Code instance with the./samplesdirectory open in the workspace. The directorysamples/scratch is excludedfrom the repo via.gitignore, so you can work on temporary files in thisdirectory without them cluttering yourgit diff or accidentally checking themin.

If you use Q#, Azure Quantum Development Kit, or Azure Quantum Resource Estimator, please cite as follows:

• Azure Quantum Development Kit:

@software{Microsoft_Azure_Quantum_Development,author ={{Microsoft}},license ={MIT},title ={{Azure Quantum Development Kit}},url ={https://github.com/microsoft/qsharp} }

• Q# programming language:

@inproceedings{Svore_2018,series={RWDSL2018},title={{Q\#: Enabling Scalable Quantum Computing and Development with a High-level DSL}},url={http://dx.doi.org/10.1145/3183895.3183901},DOI={10.1145/3183895.3183901},booktitle={Proceedings of the Real World Domain Specific Languages Workshop 2018},publisher={ACM},author={Svore, Krysta and Geller, Alan and Troyer, Matthias and Azariah, John and Granade, Christopher and Heim, Bettina and Kliuchnikov, Vadym and Mykhailova, Mariia and Paz, Andres and Roetteler, Martin},year={2018},month=feb,collection={RWDSL2018} }

• Azure Quantum Resource Estimator:

@inproceedings{Azure_Quantum_Resource_Estimator,author ={van Dam, Wim and Mykhailova, Mariia and Soeken, Mathias},title ={{Using Azure Quantum Resource Estimator for Assessing Performance of Fault Tolerant Quantum Computation}},year ={2023},isbn ={9798400707858},publisher ={Association for Computing Machinery},address ={New York, NY, USA},url ={https://doi.org/10.1145/3624062.3624211},doi ={10.1145/3624062.3624211},booktitle ={Proceedings of the SC '23 Workshops of The International Conference on High Performance Computing, Network, Storage, and Analysis},pages ={1414–1419},numpages ={6},series ={SC-W '23} }

If you have feedback about the content in this repository, please let us know by filing anew issue!

Security issues and bugs should be reported privately following oursecurity issue documentation.

This project welcomes contributions and suggestions. Most contributions require you to agree to aContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant usthe rights to use your contribution. For details, visithttps://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to providea CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructionsprovided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted theMicrosoft Open Source Code of Conduct.For more information see theCode of Conduct FAQ orcontactopencode@microsoft.com with any additional questions or comments.

For more details, please seeCONTRIBUTING.md.

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsofttrademarks or logos is subject to and must followMicrosoft's Trademark & Brand Guidelines.Use of Microsoft trademarks or logos in modified versions of this project must not cause confusionor imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to thosethird-party's policies.