Microsoft Quantum Development Kit Release Notes

Version 0.4.1901

Release date: January 30, 2019

This release contains the following:

  • adds support for a new primitive type, BigInt, which represents a signed integer of arbitrary size. Learn more about BigInt type.
  • adds new Toffoli simulator, a special purpose fast simulator that can simulate X, CNOT and multi-controlled X quantum operations with very large numbers of qubits. Learn more about Toffoli simulator.
  • adds a simple resource estimator that estimates the resources required to run a given instancee of a Q# operation on a quantum computer. Learn more about the Resource Estimator.

Version 0.3.1811.2802

Release date: November 28, 2018

Even though our VS Code extension was not using it, it was flagged and removed from the marketplace during the extensions purge related to the event-stream NPM package. This version removes all runtime dependencies that could make the extension trigger any red flags.

If you had previously installed the extension you will need to install it again by visiting the Microsoft Quantum Development Kit for Visual Studio Code extension on the Visual Studio Marketplace and press Install. We are sorry about the inconvenience.

Version 0.3.1811.1511

Release date: November 20, 2018

This release fixes a bug that prevented some users to successfully load the Visual Studio extension.

If you are upgrading from a 0.2 version of the Quantum Development Kit, learn more about Q# language changes and migrating your Q# program.

Version 0.3.1811.203

Release date: November 2, 2018

This release includes a few bug fixes, including:

  • Invoking DumpMachine could change the state of the simulator under certain situations.
  • Removed compilation warnings when building projects using a version of .NET Core previous to 2.1.403.
  • Clean up of documentation, specially the tooltips shown during mouse hover in VS Code or Visual Studio.

If you are upgrading from a 0.2 version of the Quantum Development Kit, learn more about Q# language changes and migrating your Q# program.

Version 0.3.1810.2508

Release date: October 29, 2018

This release includes new language features and an improved developer experience:

  • This release includes a language server for Q#, as well as the client integrations for Visual Studio and Visual Studio Code. This enables a new set of IntelliSense features along with live feedback on typing in form of squiggly underlinings of errors and warnings.
  • This update greatly improves diagnostic messages in general, with easy navigation to and precise ranges for diagnostics and additional details in the displayed hover information.
  • The Q# language has been extended in ways that unifies the ways developers can do common operations and new enhancements to the language features to powerfully express quantum computation. There are a handful of breaking changes to the Q# language with this release.

Learn more about Q# language changes and migrating your Q# program.

This release also includes a new quantum chemistry library:

  • The chemistry library contains new Hamiltonian simulation features, including:
    • Trotter–Suzuki integrators of arbitrary even order for improved simulation accuracy.
    • Qubitization simulation technique with chemistry-specific optimizations for reducing $T$-gate complexity.
  • A new open source schema, called Broombridge Schema (in reference to a landmark celebrated as a birthplace of Hamiltonians), is introduced for importing representations of molecules and simulating them.
  • Multiple chemical representations defined using the Broombridge Schema are provided. These models were generated by NWChem, an open source high-performance computational chemistry tool.
  • Tutorials and Samples describe how to use the chemistry library and the Broombridge data models to:
    • Construct simple Hamiltonians using the chemistry library
    • Visualize ground and excited energies of Lithium Hydride using phase estimation.
    • Perform resource estimates of quantum chemistry simulation.
    • Estimate energy levels of molecules represented by the Broombridge schema.
  • Documentation describes how to use NWChem to generate additional chemical models for quantum simulation with Q#.

Learn more about the Quantum Development Kit chemistry library.

With the new chemistry library, we are separating out the libraries into a new GitHub repo, Microsoft/QuantumLibraries. The samples remain in the repo Microsoft/Quantum. We welcome contributions to both!

This release includes bug fixes and features for issues reported by the community:

  • Intellisense for Q#? (UserVoice).
  • .qs files (UserVoice).
  • Improve error message when curly braces are abbreviated in if statement (UserVoice).
  • Support tuple deconstruction at mutable (re-)binding (UserVoice).
  • Error Running Provided BitFlipCode (UserVoice).
  • H2SimulationGUI displays big peaks sometimes (UserVoice).

Community Contributions

Thank you! to the following contributors to our open code base at These contributions add significantly to the rich samples of Q# code:

  • Rolf Huisman (@RolfHuisman): Improved the experience for QASM/Q# developers by creating a QASM to Q# translator. PR #58.

  • Andrew Helwer (@ahelwer): Contributed a sample implementing the CHSH Game, a quantum game related to non-locality. PR #84.

Thank you also to Rohit Gupta (@guptarohit,PR #90), Tanaka Takayoshi (@tanaka-takayoshi,PR #289), and Lee James O'Riordan (@mlxd,PR #96) for their work improving the content for all of us through documentation, spelling and typo corrections!

Version 0.2.1809.701

Release date: September 10, 2018

This release includes bug fixes for issues reported by the community. Including:

  • Unable to use shift operator (GitHub).
  • DumpMachine / DumpRegister fails on QCTraceSimulator when printing to console (UserVoice).
  • Allow allocating 0 qubits (UserVoice).
  • AssertQubitState requires explicit Complex() call (UserVoice).
  • Measure operation always returns One on macOS (UserVoice).


Version 0.2.1806.3001

Release date: June 30, 2018

This releases is just a quick fix for issue #48 reported on GitHub (Q# compilation fails if user name contains a blank space). Follow same update instructions as 0.2.1806.1503 with the corresponding new version (0.2.1806.3001-preview).

Version 0.2.1806.1503

Release date: June 22, 2018

This release includes several community contributions as well as an improved debugging experience and improved performance. Specifically:

  • Performance improvements on both small and large simulations for the QuantumSimulator target machine.
  • Improved debugging functionality.
  • Community contributions in bug fixes, new helper functions, operations and new samples.

Performance improvements

This update includes significant performance improvements for simulation of large and small numbers of qubits for all the target machines. This improvement is easily visible with the H2 simulation that is a standard sample in the Quantum Development Kit.

Improved debugging functionality

This update adds new debugging functionality:

  • Added two new operations, DumpMachine and DumpRegister that output wave function information about the target quantum machine at a point in time.
  • In Visual Studio, the probability of measuring a $\ket{1}$ on a single qubit is now automatically shown in the debugging window for the QuantumSimulator target machine.
  • In Visual Studio, improved the display of variable properties in the Autos and Locals debug windows.

Learn more about Testing and Debugging.

Community Contributions

The Q# coder community is growing and we are thrilled to see the first user contributed libraries and samples that were submitted to our open code base at A big Thank you! to the following contributors:

  • Mathias Soeken (@msoeken): contributed a sample defining a transformation based logic synthesis method that constructs Toffoli networks to implement a given permutation. The code is written entirely in Q# functions and operations. PR #41.
  • RolfHuisman (@RolfHuisman): Microsoft MVP Rolf Huisman contributed a sample that generates flat QASM code from Q# code for a restricted class of programs that do not have classical control flow and restricted quantum operations. PR #59
  • Sarah Kasier (@crazy4pi314): helped to improve our code base by submitting a library function for controlled operations. PR #53
  • Jessica Lemieux (@Lemj3111): fixed QuantumPhaseEstimation and created new unit tests. PR #54
  • Tama McGlinn (@TamaHobbit): cleaned the Teleportation sample by making sure the QuantumSimulator instance is disposed. PR #20

Additionally, a big Thank You! to these Microsoft Software Engineers from the Commercial Engineering Services team contributors who made valuable changes to our documentation during their Hackathon. Their changes vastly improved the clarity and onboarding experience for all of us:

  • Sascha Corti
  • Mihaela Curmei
  • John Donnelly
  • Kirill Logachev
  • Jan Pospisil
  • Anita Ramanan
  • Frances Tibble
  • Alessandro Vozza

Update existing projects

This release is fully backwards compatible. Just update the nuget pakages in your projects to version 0.2.1806.1503-preview and do a full rebuild to make sure all intermediate files are regenerated.

From Visual Studio, follow the normal instructions on how to update a package.

To update project templates for the command line, run the following command:

dotnet new -i "Microsoft.Quantum.ProjectTemplates::0.2.1806.1503-preview"

After running this command, any new projects created using dotnet new <project-type> -lang Q# will automatically use this version of the Quantum Development Kit.

To update an existing project to use the newest version, run the following command from within the directory for each project:

dotnet add package Microsoft.Quantum.Development.Kit -v "0.2.1806.1503-preview"
dotnet add package Microsoft.Quantum.Canon -v "0.2.1806.1503-preview"

If an existing project also uses XUnit integration for unit testing, then a similar command can be used to update that package as well:

dotnet add package Microsoft.Quantum.Xunit -v "0.2.1806.1503-preview"

Depending on the version of XUnit that your test project uses, you may also need to update XUnit to 2.3.1:

dotnet add package xunit -v "2.3.1" 

After the update, make sure you remove all temporary files generated by the previous version by doing:

dotnet clean 

Known Issues

No aditional known issues to report.

Version 0.2.1802.2202

Release date: February 26, 2018

This release brings support for development on more platforms, language interoperability, and performance enhancements. Specifically:

  • Support for macOS- and Linux-based development.
  • .NET Core compatibility, including support for Visual Studio Code across platforms.
  • A full Open Source license for the Quantum Development Kit Libraries.
  • Improved simulator performance on projects requiring 20 or more qubits.
  • Interoperability with the Python language (preview release available on Windows).

.NET Editions

The .NET platform is available through two different editions, the .NET Framework that is provided with Windows, and the open-source .NET Core that is available on Windows, macOS and Linux. With this release, most parts of the Quantum Development Kit are provided as libraries for .NET Standard, the set of classes common to both Framework and Core. These libraries are therefore compatible with recent versions of either .NET Framework or .NET Core.

Thus, to help ensure that projects written using the Quantum Development Kit are as portable as possible, we recommend that library projects written using the Quantum Development Kit target .NET Standard, while console applications target .NET Core. Since previous releases of the Quantum Development Kit only supported .NET Framework, you may need to migrate your existing projects; see below for details on how to do this.

Project Migration

Projects created using previous versions of Quantum Development Kit will still work, as long as you don't update the NuGet packages used in them. To migrate existing code to the new version, perform the following steps:

  1. Create a new .NET Core project using the right type of Q# project template (Application, Library or Test Project).
  2. Copy existing .qs and .cs/.fs files from the old project to the new project (using Add > Existing Item). Do not copy the AssemblyInfo.cs file.
  3. Build and run the new project.

Please note that the operation RandomWalkPhaseEstimation from the namespace Microsoft.Quantum.Canon was moved into the namespace Microsoft.Research.Quantum.RandomWalkPhaseEstimation in the Microsoft/Quantum-NC repository.

Known Issues

  • The --filter option to dotnet test does not work correctly for tests written in Q#. As a result, individual unit tests cannot be run in Visual Studio Code; we recommend using dotnet test at the command line to re-run all tests.

Version 0.1.1801.1707

Release date: January 18, 2018

This release fixes some issues reported by the community. Namely:

  • The simulator now works with early non-AVX-enabled CPUs.
  • Regional decimal settings will not cause the Q# parser to fail.
  • SignD primitive operation now returns Int rather than Double.

Version 0.1.1712.901

Release date: December 11, 2017

Known Issues

Hardware and Software Requirements

  • The simulator included with the Quantum Development Kit requires a 64-bit installation of Microsoft Windows to run.
  • Microsoft's quantum simulator, installed with the Quantum Development Kit, utilizes Advance Vector Extensions (AVX), and requires an AVX-enabled CPU. Intel processors shipped in Q1 2011 (Sandy Bridge) or later support AVX. We are evaluating support for earlier CPUs and may announce details at a later time.

Project Creation

  • When creating a solution (.sln) that will use Q#, the solution must be one directory higher than each project (.csproj) in the solution. When creating a new solution, this can be accomplished by making sure that the "Create directory for solution" checkbox on the "New Project" dialog box is checked. If this is not done, the Quantum Development Kit NuGet packages will need to be installed manually.


  • Intellisense does not display proper errors for Q# code. Make sure that you are displaying Build errors in the Visual Studio Error List to see correct Q# errors. Also note that Q# errors will not show up until after you've done a build.
  • Using a mutable array in a partial application may lead to unexpected behavior.
  • Binding an immutable array to a mutable array (let a = b, where b is a mutable array) may lead to unexpected behavior.
  • Profiling, code coverage and other VS plugins may not always count Q# lines and blocks accurately.
  • The Q# compiler does not validate interpolated strings. It is possible to create C# compilation errors by misspelling variable names or using expressions in Q# interpolated strings.


  • The Quantum Simulator uses OpenMP to parallelize the linear algebra required. By default OpenMP uses all available hardware threads, which means that programs with small numbers of qubits will often run slowly because the coordination required will dwarf the actual work. This can be fixed by setting the environment variable OMP_NUM_THREADS to a small number. As a very rough rule of thumb, 1 thread is good for up to about 4 qubits, and then an additional thread per qubit is good, although this is highly dependent on your algorithm.


  • F11 (step in) doesn't work in Q# code.
  • Code highlighting in Q# code at a breakpoint or single-step pause is sometimes inaccurate. The correct line will be highlighted, but sometimes the highlight will start and end at incorrect columns on the line.


  • Tests must be executed in 64-bit mode. If your tests are failing with a BadImageFormatException, go to the Test menu and select Test Settings > Default Processor Architecture > X64.
  • Some tests take a long time (possibly as much as 5 minutes depending on your computer) to run. This is normal, as some use over twenty qubits; our largest test currently runs on 23 qubits.


  • On some machines, some small samples may run slowly unless the environment variable OMP_NUM_THREADS is set to "1". See also the release note under "Simulation".


  • There is an implicit assumption that the qubits passed to an operation in different arguments are all distinct. For instance, all of the library operations (and all of the simulators) assume that the two qubits passed to a controlled NOT are different qubits. Violating this assumption may lead to unpredictable unexpected. It is possible to test for this using the quantum computer tracer simulator.
  • The Microsoft.Quantum.Bind function may not act as expected in all cases.
  • In the Microsoft.Quantum.Extensions.Math namespace, the SignD function returns a Double rather than an Int, although the underlying System.Math.Sign function always returns an integer. It is safe to compare the result against 1.0, -1.0, and 0.0, since these doubles all have exact binary representations.