Qubit Toaster

The Qubit Toaster is a high performance quantum circuit simulator designed for speed. It is based on our original algorithms for circuit optimization and efficient execution. Can be used stand-alone or as a replacement in popular quantum programming frameworks.

Designed for speed

More benchmarks comming soon. You can help by contributing code to Quantum Simulator Benchmark repository. More simulators and more algorithms are welcome.

Install

Qubit Toaster is shipped as a precompiled binary for Linux, MacOS and Windows, and can be installed in two ways:

• Install directly on your local machine

• Fetch and run pre-configured Docker container

Install on "bare metal"

Linux and MacOS

To install on your local machine, open your terminal and execute following command:

curl https://quantastica.com/toaster/install | /bin/sh

The script will download and extract binaries into ~/.qubit-toaster/ directory. Sript will then try to make symlink in /usr/local/bin/. Creating symlink requires sudo permissions, so if you are installing as non-privileged user, you will be asked to enter your sudo password. This is not mandatory - if you skip creating symlink then qubit-toaster will not be globally accessible from terminal, but you will be able to run it by providing full path to the executable. You can also create symlink manually after the installation.

Windows

Please download and run windows installer: Qubit-Toaster-Installer.exe

Install and run pre-configured Docker container

If you are uncomfortable with running pre-compiled binary directly on your system, you can run Qubit Toaster in a Docker container.

Fetch docker image

docker pull quantastica/qubit-toaster:latest

Run container

docker run -d -p 127.0.0.1:8001:8001 --restart=always --name qubit-toaster quantastica/qubit-toaster:latest

Inside container, qubit toaster is running as a server and is listening for http requests on port 8001.

Usage

Qubit Toaster can run in two modes:

• Server mode

• Command line tool

When running in server mode, it can be used as a replacement simulator in Qiskit and other popular quantum programming frameworks (backends for pyQuil and Cirq coming soon).

Running in server mode

If are running a pre-configured Docker container then Qubit Toaster is already started in server mode inside container and is listening on (default) port 8001.

If you installed the toaster on a "bare metal", then simply run following command:

qubit-toaster -S

Running as a command line tool

When executed as a command line tool, it expects quantum circuit in json format (from file or directly from stdin) and after execution it prints simulation results to stdout.

Input file can be generated automatically from IBM's QASM or from Rigetti's QUIL code by using qconvert command line utility, or Web based online converter.

Example usage:

qubit-toaster -s 1024 -r counts bell_state.json

Output will be:

{
   "qtoaster_version": "0.9.10",
   "error_code": 0,
   "message": "",
   "counts": { "00": 518, "11": 506},
   "time_taken": "0.000159"
}

If you wish to get state vector then use -r state option:

qubit-toaster -s 1024 -r counts -r state bell_state.json

Output:

{
   "qtoaster_version": "0.9.10",
   "error_code": 0,
   "message": "",
   "counts": { "00": 515, "11": 509 },
   "statevector": [ [0.707106781186545, 0], [0, 0], [0, 0], [0.707106781186545, 0] ],
   "time_taken": "0.000248"
}

Qubit toaster is QASM 2.0 compatible, so it supports classical registers and classicaly controlled quantum gates.

For more options type:

qubit-toaster --help

Using with Qiskit

In order to use the Qubit Toaster instead of Aer simulators in your Qiskit experiments, make sure that toaster is running in server mode and do following:

Install ToasterBackend for Qiskit

pip install quantastica-qiskit-toaster

Import ToasterBackend into your Qiskit code

from quantastica.qiskit_toaster import ToasterBackend

And then instead:

backend = Aer.get_backend("qasm_simulator")

Use:

backend = ToasterBackend.get_backend("qasm_simulator")

Toaster can be used instead Aer's statevector simulator as well:

backend = ToasterBackend.get_backend("statevector_simulator")

Simple as that.

Backend options

For more details, please see quantastica-qiskit-toaster package's README.

Using with QPS

Quantum Programming Studio can run simulations directly on your locally installed Qubit Toaster. Please see QPS Client Docs for more information.

HTTP API

POST /submit

Submits json payload to qubit-toaster for execution, parameters are passed via HTTP headers.

Required HTTP headers:

• Content-Type : must be application/json

• Content-Length : size of payload

Optional HTTP headers:

• x-qtc-seed (integer) Number (uint32) used for overriding default random number generator seed value

• x-qtc-shots (integer) Number of repetitions

• x-qtc-optimization (integer) Optimization level (0 - automatic, 1 - off, 2.. - use given optimization level)

• x-qtc-return (string) What to return? Can be one or more of the following:

  • counts (default)

  • measure_all

  • probabilities

  • registers

  • state

• x-qtc-no-wait (0 or 1) If this parameter is set to 1 the server will close HTTP request right after it is completely read, to get results client needs to use GET /getresult or GET /pollresult endpoints

• x-qtc-jobid (string) jobid that will be used for querying result of this simulation (not needed if you are sure that this request will not timeout)

GET /getresult/{jobid}

Returns (immediately) result (as application/json) or one of following HTTP status codes:

• 202 - given job is not processed yet

• 404 - job with that id is not found

GET /pollresult/{jobid}

If given job is processed returns immediately, otherwise waits until it is processed. If job with give jobid is not found API returns 404 HTTP status code

GET /info

Returns info in json format containing following values:

• version - toaster's version

• queue_size - queue size

• available - number available slots in queue

• unread - number of jobs that are processed but their result is not read yet

Possible HTTP status codes

• 201 Queued

• 202 Not Processed Yet

• 400 Bad Request

• 404 Not Found

• 409 Jobid Conflict

• 413 Payload Too Large

• 415 Unsupported Media Type

• 422 Unprocessable Entity

• 429 Too Many Requests

• 431 Request Header Fields Too Large

• 499 Generic Error

CURL Examples

Notes

• -H "Expect:" is used in following examples to prevent curl from sending Expect:100 Continue request first.

• qubit-toaster should be listening on default port (8001), to see debug info you can pass debug level like following:

  qubit-toaster -S -l info

Simple submit of adder.json

curl -H "Expect:"   --header "Content-Type: application/json" --data-binary @examples/adder.json http://localhost:8001/submit

Executing bell.json with custom params

curl -H "Expect:"   --header "Content-Type: application/json" --data-binary @examples/bell.json -H "x-qtc-seed: 2" -H "x-qtc-shots:16" -H "x-qtc-optimization:7" -H "x-qtc-return:measure_all"  http://localhost:8001/submit

Executing qft25.json, getting info and querying results later

Please note that if you execute following requests multiple times on same instance of toaster the submit request (first one) will fail with 409 Jobid Conflict status

curl -v -H "Expect:"   --header "Content-Type: application/json" --data-binary @examples/qft25.json -H "x-qtc-seed: 2" -H "x-qtc-shots:16" -H "x-qtc-optimization:7" -H "x-qtc-return:measure_all" -H "x-qtc-jobid:1234567" -H "x-qtc-no-wait:1" http://localhost:8001/submit

curl http://localhost:8001/info
curl -v http://localhost:8001/getresult/1234567
curl -v http://localhost:8001/pollresult/1234567