qasmsim

A QASM interpreter and quantum simulator in Rust.

Prerequisites

Make sure you have cargo installed. For compiling the WASM version, make sure you have wasm-pack also installed.

What is missing?

Looking for what's new? See RELEASE_NOTES.

Very few is missing, but the most important things are allowing the inclusion of external libraries throught the include directive, and improve the reporting of errors. Nevertheless, including qelib1.inc is possible since it comes with the interpreter.

Planned for future versions is:

• Allow including external source.
  • In the native lib.
  • In the WASM version.
• Add a semantic checker for checking the correctness of the program before runtime.
• Handling opaque gates. Right now they are ignored and calling an opaque gate results in Error, like trying to call an undefined gate.

A sample QASM program can be found here:

OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
h q[0];
cx q[0], q[1];

The complete specification can be found under the QASM repository.

qasmsim CLI

Install qasmsim with:

$ cargo install --git https://github.com/delapuente/qasmsim

And simulate a QASM program with:

$ qasmsim source.qasm

See more options with:

$ qasmsim --help
qasmsim 1.2.0
A QASM interpreter and quantum simulator in Rust.

USAGE:
    qasmsim [FLAGS] [OPTIONS] [source]

FLAGS:
    -b, --binary           Prints the binary representation of the values
    -h, --help             Prints help information
    -x, --hexadecimal      Prints the hexadecimal representation of the values
    -i, --integer          Prints the interger representation of the values. Default option
        --probabilities    Prints the probabilities vector of the simulation. Ignored if shots is set
        --statevector      Prints the state vector of the simulation. Ignored if shots is set
    -t, --times            Prints times measured for parsing and simulating
    -V, --version          Prints version information
    -v                     Verbosity of the output

OPTIONS:
        --info <info>      Show gate-related information
        --out <out>        Output files prefix, print in the stdout if not present. The output format of each file is
                           CSV. At most, three files are created with the names out.memory.csv, out.state.csv and
                           out.times.csv
        --shots <shots>    Specify the number of simulations

ARGS:
    <source>    QASM program file, read from stdin if not present

qasmsim library

qasmsim is also a library including a QASM parser which generates a QASM AST, an interpreter, and a quantum state-vector simulator. The command-line tool is just one of the multiple consumers the library can have. If you want to install the library functionality only, remove the default features when installing:

$ cargo install --no-default-features

Testing the project

You can refer to unit tests (in the files under the src folder) and integration tests (under the tests folder) to figure out what is implemented. For passing the tests of the project you can do:

$ cargo test

WASM version

qasmsim can be used in the web if you compile it for Web Assembly. Doing it is easy, simply download the sources, ensure you have wasm-pack installed and run:

$ wasm-pack build -- --features="serde"

It will compile your project and pack it inside the pkg folder. Now enter the www directory, install the dependencies with (you only need run this once):

$ npm install

And start the web server with:

$ npm start

Browse the URL provided by the second command and you'll see a blank page. Go to the developer tools of your browser and try running a small test:

var result = qasmsim.run(`
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
h q[0];
cx q[0], q[1];
`);

The module is exported by default as the qasmsim object in window and implements the following interface:

interface qasmsim {
  run: (input: string, shots?: number) => Execution,
  simulate: (program: OpenQasmProgram, shots?: number) => Computation,
  parseAndLink: (source: string) => OpenQasmProgram,
  parseProgram: (source: string) => OpenQasmProgram,
  parseLibrary: (source: string) => OpenQasmLibrary,
  parseExpression: (source: string) => Expression,
  parseProgramBody: (source: string) => Statement[],
  parseStatement: (source: string) => Statement
  getGateInfo: (source: string, gateName: string) => GateInfo
}

interface Computation {
  histogram?: Histogram,
  probabilities: Float64Array,
  statevector: { bases: Float64Array, qubitWidth: number },
  memory: Memory
}

interface Execution extends Computation {
  times: ExecutionTimes
}

type Memory = { [key: string]: Array[number] }
type Histogram = { [key: string]: Array[[number, number]] }
type ExecutionTimes = {
  parsing: number,
  simulation: number,
  serialization: number
}
type GateInfo = {
  docstring: string,
  name: string,
  realParameters: Array[string],
  quantumParameters: Array[string]
}

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.