Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

CHP simulator for Q#

All Contributors

This library implements a new classical simulator for Q# that utilizes the CHP stabilizer classical sub-theory. Based on the Python implementation by @Strilanc here:


tl;dr If we impose some constraints on quantum systems they can become way easier to simulate classically.

This simulator uses one such set of constraints to simulate thousands of qubits easily which allows us to learn more about quantum algorithms we don't yet have the hardware to run or simulate in full generality.

Simulating quantum systems on a classical computer is hard to do in full generalization, as the resources needed scale exponentially with the number of qubits you want to simulate (up to about ~30 qubits on a typical machine). If you impose some constraints on the operations you can do in your programs, you can use a different kind of simulator that allows you to simulate hundreds of qubits by using what is called a classical sub-theory of quantum physics. There are a variety of sub-theories that each have a different set of constraints you have to work with to leverage it. This repo implements a simulator for the CHP (CNOT, Hadamard, and Phase) classical sub-theory which helpfully has the constraint baked into the name. In this simulator, all operations it supports have to be comprised of (or decomposable to) only the operations CNOT, Hadamard, and Phase. If you run a program with this simulator as the target, and you ask for an operation that is not supported, the simulator will throw and exception.

Build status

Build NuGet QSharpCommunity.Simulators.Chp on

Code style

q# code style q# APIcode style c# APIcode style CoC


Jupyter screenshot

Tech/framework used

Built with:


Anywhere you can use Q#, you can use this simulator!

  • Python host program
  • Jupyter Notebooks
  • Stand-alone command line application
  • C#/F# host program

Code Example

TODO: Add more! Fix syntax highlighting


To use this simulator, there is no reqired installation (unless you want to develop the simulator locally). See the section below on how to use the simulator to see how to add it to your projects.

More generally, for complete and up-to-date ways to install the Quantum Development Kit (including Q# tooling) see the official Q# docs.

Python installation the scratch pad notebooks (Python packages only, no Q#/Chp simulator)

  1. Start with your favorite Anaconda or Miniconda install
  2. Use the included environment-qutip.yml or environment-quaec.yml to create a conda envionment.
    $ conda env create -f <NAME OF FILE.yml>
  3. Activate the environment and then start the Jupyter Notebook. The <ENV NAME> will be at the top of the yml file you used to create the environment.
    $ conda activate <ENV NAME>
    $ jupyter notebook
    Then you should have Jupyter Notebook launch and you can use the corresponding notebook at the environment root for scratch work/testing your understanding of stabilizers.

API Reference

TODO: Complete once compiler extension is finalized for scraping API docs


The tests for this library all live in the tests directory. To run the tests, navigate to that directory and run dotnet test and the .NET project will find and run all the tests in this directory. If you are adding new features or functionality, make sure to add some tests to either the existing files, or make a new one. For more info on writing tests for Q#, check out the official Q# docs.

How to use?

You want to use a published version of the simulator:

Just add a PackageReference to you project file with the following line:

<PackageReference Include="QSharpCommunity.Simulators.Chp" Version="X.X.X" />

or this console command:

$ dotnet add package QSharpCommunity.Simulators.Chp -v X.X.X

In both cases you can omit the version information to use the latest available Chp simulator on

You want to develop the simulator (locally build and use simulator):

The basic idea in this case is build locally a version of the nuget package for the simulator and then put it in a folder that is a known source to nuget.

  1. Remove any previous copies of the package from your local nuget feed (you likely picked this location), and global nuget cache (default path on Windows 10 for the cache is below):
> rm C:\Users\skais\nuget-packages\QSharpCommunity.Simulators.Chp.X.X.X.nupkg
> rm C:\Users\skais\.nuget\packages\QSharpCommunity.Simulators.Chp\
  1. Build the package for the Chp Simulator:
> cd src
> dotnet pack
  1. Copy the package to your local nuget source (a location you selected, an example one is below). The X in the name are the place holder for the version number you are building (should be generated by the previous step).
> cp .\bin\Debug\QSharpCommunity.Simulators.Chp.X.X.X.nupkg 'C:\Users\skais\nuget-packages\'


Please see our contributing guidelines and our code of conduct before working on a contribution, thanks!


  • Primary developers: @crazy4pi314 @RolfHuisman
  • Contributors: @cgranade


If you need to check your intuition/understanding of the stabilizer formalism, you should check out these Python packages:


MIT © Sarah Kaiser


Thanks goes to these wonderful people (emoji key):

Rolf Huisman

🚇 ⚠️ 💻

This project follows the all-contributors specification. Contributions of any kind welcome!