simulate

Simulate quantum circuit

Since R2023a

Syntax

s = simulate(c)

s = simulate(c,inputState)

Description

Add-On Required: This feature requires the MATLAB Support Package for Quantum Computing add-on.

s = simulate(c) simulates the quantum circuit c and returns the final state s after running the circuit. By default, each qubit in the circuit is initially in the $$|0\rangle$$ state.

s = simulate(c,inputState) additionally specifies the initial quantum state of the circuit.

The default value of inputState is "0...0" with as many "0" characters as there are qubits in c, where each qubit is in the $$|0\rangle$$ state. You can specify inputState as a string containing "0", "1", "+", or "-" with as many characters as there are qubits in c, a numeric vector, or a QuantumState object.

Examples

Simulate Quantum Circuit

Create a quantum circuit that consists of a Hadamard gate and a controlled X gate to entangle two qubits.

gates = [hGate(1); cxGate(1,2)];
c = quantumCircuit(gates);

Simulate the circuit using the default initial state where each qubit is in the $$|0\rangle$$ state.

s = simulate(c)

s = 

  QuantumState with properties:

    BasisStates: [4×1 string]
     Amplitudes: [4×1 double]
      NumQubits: 2

Show the final state of the circuit.

formula(s)

ans = 

    "0.70711 * |00> +
     0.70711 * |11>"

Plot the histogram of probabilities to measure possible states from the final state of the circuit.

histogram(s)

Simulate Quantum Circuit with Different Initial States

Create a quantum circuit that consists of a controlled X gate.

c = quantumCircuit(cxGate(1,2));

Simulate the circuit using initial states of "00", "01", "10", and "11". Show the final state of the circuit for each initial state after running the circuit.

for ket=["00", "01", "10", "11"]
    s = simulate(c,ket);
    disp("|" + ket + "> -> " + formula(s));
end

|00> -> 1 * |00>
|01> -> 1 * |01>
|10> -> 1 * |11>
|11> -> 1 * |10>

Input Arguments

c — Quantum circuit

quantumCircuit object | vector of quantumCircuit objects

Quantum circuit, specified as a quantumCircuit object or a vector of quantumCircuit objects.

inputState — Initial state of quantum circuit

string scalar | numeric vector | QuantumState object

Initial state of the quantum circuit, specified as one of these values:

• String scalar containing "0", "1", "+", or "-" with as many characters as there are qubits in c. For example, to specify four qubits that are in the initial state $$|0+1-\rangle$$, use "0+1-".

• Numeric vector containing amplitudes of the initial states. The simulate function normalizes the amplitudes as inputState/norm(inputState). For example, you can construct the initial state $$|11\rangle$$ using [0 0 0 1]. (since R2023b)

• QuantumState object, which accepts string scalar and numeric vector input to create a quantum state. For example, you can construct the initial state $$|11\rangle$$ using inputState = quantum.gate.QuantumState("11") or inputState = quantum.gate.QuantumState([0 0 0 1]). You can also specify a QuantumState object that is returned by running simulate on another quantum circuit (with the same number of qubits).

By default, the inputState is "0...0" with as many characters "0" as there are qubits in c.

Output Arguments

s — Final state after running the circuit

QuantumState object | vector of QuantumState objects

Final state after running the circuit, returned as a QuantumState object or a vector of QuantumState objects. Each object contains the normalized amplitudes of all possible $$2^n$$ basis states of n qubits that form the quantum state. The quantum state can include a global phase or relative phases among the amplitudes of the basis states that do not affect the probabilities of measuring these states.

Limitations

• Because the number of possible basis states of a quantum state scales as $$2^n$$ as the number of qubits n grows, using simulate is practical for finding the final state s of a circuit only when n is less than about 15.

References

[1] Beeumen, Roel Van, Daan Camps, and Neil Mehta. “QCLAB++: Simulating Quantum Circuits on GPUs.” Preprint, submitted February 28, 2023. https://doi.org/10.48550/arXiv.2303.00123.

Version History

Introduced in R2023a

R2025b: Specify quantum circuits as a vector (November 2025, Version 25.2.1)

This function now supports implicit expansion. You can simulate multiple quantum circuits at a time by specifying an input vector of quantumCircuit objects.

R2023b: Specify initial state as numeric vector

In addition to specifying the initial state of the quantum circuit as a string scalar or QuantumState object, you can now specify a numeric vector. See inputState for more information.