Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


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


A quantum circuit simulator based on Features:

  • A simple programming language for quantum circuits in the Clifford+T gate set
  • An algorithm for sampling from the output distribution of a circuit
  • An algorithm for calculating the probability of a particular output for a circuit

This application is written in python, a cross-platform programming language. A C implementation also is available for the slow part of both algorithms. The C implementation is used by default, but a python-only version is also available.

See the documentation for a complete description, once it is available.


  1. Install python

Python 3 is recommended, although the code should still work in python 2. Download from or use your favorite package manager.

  1. Install numpy

Download numpy from use pip. Scipy is not required.

  1. (Optional) Install matplotlib

The circuits/ test script generates a plot similar to the one in using matplotlib. You can disable this but setting plot = False on line 30, or you can download and install matplotlib from

  1. Download the code

Press the clone or download button above and press "Download ZIP" or open up a terminal and type

$ git clone
  1. Compile the code C implementation

On Mac OS X and Linux simply:

  1. Open a terminal
  2. Change into the root directory: $ cd CircuitSimulator
  3. Call make: $ make

On Windows, a precompiled executable is available at libcirc/sample.exe. Tell the executable to use it by passing cpath=libcirc/sample.exe as an option. If that does not work, try the -py option to use the python back-end.


There are two ways to use CircuitSimulator:

  1. Use the handle to compile a circuit and run an algorithm.


python circuits/toffoli.circ MMM
python circuits/HTstack.circ 0

A full usage statement is available:

python -h

Or just read the documentation.

  1. Import the libcirc/ file and use the probability() and sampleQubits() functions.

This is useful for automatically generated circuits that need to be evaluated. The circuits/ file does exactly this: it randomly generates a circuit implementing the hidden shift algorithm and evaluates it immediately. Read circuits/ for guidance when writing your own code and/or consult the documentation.