# Crate qdk_sim

Expand description

## Quantum Development Kit Preview Simulators

### 📝 NOTE

This crate is in preview, and may undergo breaking API changes with no notice.

As a preview feature, this crate may be buggy or incomplete. Please check the tracking issue at microsoft/qsharp-runtime#714 for more information.

### ⓘ TIP

This crate provides low-level APIs for interacting with experimental simulators. If you’re interested in using the experimental simulators to run your Q# programs, please see the installation instructions at https://github.com/microsoft/qsharp-runtime/blob/main/documentation/preview-simulators.md.

This crate implements simulation functionality for the Quantum Development Kit, including:

• Open systems simulation
• Stabilizer simulation

The c_api module allows for using the simulation functionality in this crate from C, or from other languages with a C FFI (e.g.: C++ or C#), while Rust callers can take advantage of the structs and methods in this crate directly.

Similarly, the [python] module allows exposing data structures in this crate to Python programs.

### Cargo Features

• python: Enables Python bindings for this crate.
• wasm: Ensures that the crate is compatible with usage from WebAssembly.

### Representing quantum systems

This crate provides several different data structures for representing quantum systems in a variety of different conventions:

### Noise model serialization

Noise models can be serialized to JSON for interoperability across languages. In particular, each noise model is represented by a JSON object with properties for each operation, for the initial state, and for the instrument used to implement $Z$-basis measurement.

For example:

{
"initial_state": {
"n_qubits": 1,
"data": {
"Mixed": {
"v": 1, "dim":[2 ,2],
"data": [[1.0, 0.0], [0.0, 0.0], [0.0, 0.0], [0.0, 0.0]]
}
}
},
"i": {
"n_qubits": 1,
"data": {
"Unitary": {
"v": 1,"dim": [2, 2],
"data": [[1.0, 0.0], [0.0, 0.0], [0.0, 0.0], [1.0, 0.0]]
}
}
},
...
"z_meas": {
"Effects": [
{
"n_qubits": 1,
"data": {
"KrausDecomposition": {
"v":1, "dim": [1, 2, 2],
"data": [[1.0, 0.0], [0.0, 0.0], [0.0, 0.0], [0.0, 0.0]]
}
}
},
{
"n_qubits": 1,
"data": {
"KrausDecomposition": {
"v": 1,"dim": [1, 2, 2],
"data":[[0.0, 0.0], [0.0, 0.0], [0.0, 0.0], [1.0, 0.0]]
}
}
}
]
}
}

The value of the initial_state property is a serialized State, the value of each operation property (i.e.: i, x, y, z, h, s, s_adj, t, t_adj, and cnot) is a serialized Process, and the value of z_meas is a serialized Instrument.

#### Representing arrays of complex numbers

Throughout noise model serialization, JSON objects representing $n$-dimensional arrays of complex numbers are used to store various vectors, matrices, and tensors. Such arrays are serialized as JSON objects with three properties:

• v: The version number of the JSON schema; must be "1".
• dims: A list of the dimensions of the array being represented.
• data: A list of the elements of the flattened array, each of which is represented as a list with two entries representing the real and complex parts of each element.

For example, consider the serialization of the ideal y operation:

"y": {
"n_qubits": 1,
"data": {
"Unitary": {
"v": 1, "dim": [2, 2],
"data": [[0.0, 0.0], [0.0, 1.0], [0.0, -1.0], [0.0, 0.0]]
}
}
}

#### Representing states and processes

Each state and process is represented in JSON by an object with two properties, n_qubits and data. The value of data is itself a JSON object with one property indicating which variant of the StateData or ProcessData enum is used to represent that state or process, respectively.

For example, the following JSON object represents the mixed state $\ket{0}\bra{0}$:

{
"n_qubits": 1,
"data": {
"Mixed": {
"v": 1, "dim":[2 ,2],
"data": [[1.0, 0.0], [0.0, 0.0], [0.0, 0.0], [0.0, 0.0]]
}
}
}

TODO

### Known issues

• Performance of open systems simulation still needs additional work for larger registers.
• Some gaps in different conversion functions and methods.
• Stabilizer states cannot yet be measured through Instrument struct, only through underlying Tableau.
• Many parts of the crate do not yet have Python bindings.
• Stabilizer simulation not yet exposed via C API.
• Test and microbenchmark coverage still incomplete.
• Too many APIs panic! or unwrap, and need replaced with Result returns instead.

## Modules

Using Experimental Simulators from C

Definitions for commonly used vectors and matrices, such as the Pauli matrices, common Clifford operators, and elementary matrices.

Provides common linear algebra functions and traits.

## Structs

A description of the noise that applies to the state of a quantum system as the result of applying operations.

Represents that a given type has a size that can be measured in terms of a number of qubits (e.g.: State).

Represents a stabilizer group with logical dimension 1; that is, a single stabilizer state expressed in terms of the generators of its stabilizer group, and those generators of the Pauli group that anticommute with each stabilizer generator (colloquially, the destabilizers of the represented state).

## Enums

Represents a quantum instrument; that is, a process that accepts a quantum state and returns the new state of a system and classical data extracted from that system.

An element of the single-qubit Pauli group.

Data used to represent a given process.

Data used to represent a given state.

## Constants

The imaginary unit $i$, represented as a complex number with two 64-bit floating point fields.

The real unit 1, represented as a complex number with two 64-bit floating point fields.

The number zero, represented as a complex number with two 64-bit floating point fields.

## Traits

Types that can be converted to unitary matrices.

A type that can be converted into a mixture of Pauli operators.

## Functions

Returns a copy of an amplitude damping channel of a given strength (that is, a channel representing relaxation to the $\ket{0}$ state in a characteristic time given by $1 / \gamma$).

Returns a copy of a depolarizing channel of a given strength (that is, a channel representing relaxation to the maximally mixed state).

Prints a message as an error.

Prints a message as an error, and returns it as a Result.

Returns the phase introduced by the binary symplectic product of two rows.

Given a two-dimensional array, updates a row of that matrix to be the row-sum of that row and the given row of another matrix, taking into account the phase product introduced by the binary symplectic product.

Given a one-dimensional array, updates it to be the row-sum of that vector and the given row of a matrix, taking into account the phase product introduced by the binary symplectic product.

Given a row of a binary symplectic matrix augmented with phase information, returns its $X$, $Z$, and phase parts.

Given two columns in a two-dimensional array, swaps them in-place.

## Type Definitions

A complex number with two 64-bit floating point fields. That is, the analogy of f64 to complex values.

A linear function from quantum states to quantum states.

The state of a quantum system.