histogram

Histogram plot of possible states

Since R2023a

Installation Required: This functionality requires MATLAB Support Package for Quantum Computing.

Syntax

histogram(s)

histogram(s,qubits)

histogram(___,Name=Value)

h = histogram(___)

Description

histogram(s) plots a histogram of each possible state and its probability from the specified quantum state or measurement. The input s must be a QuantumState or QuantumMeasurement object.

• If s is a QuantumState object, then histogram plots each possible state and the probability of measuring that state.

• If s is a QuantumMeasurement object, then histogram plots each measured state and the estimated probability of that state.

histogram(s,qubits) specifies which qubits to include in the histogram plot. By default, the histogram shows the possible states for all qubits in the input quantum state or measurement.

histogram(___,Name=Value) specifies options using one or more name-value arguments in addition to any of the input argument combinations in previous syntaxes. For example, you can choose the basis in which each qubit is represented or a probability threshold to include states in the histogram.

h = histogram(___) also returns a Histogram object. Use this object to inspect and adjust the properties of the histogram. For a list of properties, see Histogram Properties.

Examples

Plot Histogram of Simulated Quantum State

Create a quantum circuit that consists of three x-axis rotation gates. The first gate acts on qubit 1 with rotation angle pi/4, the second gate acts on qubit 2 with rotation angle pi/2, and the third gate acts on qubit 3 with rotation angle 3*pi/4.

g = rxGate(1:3,pi/4*(1:3));
c = quantumCircuit(g);

Simulate this circuit using the default initial state, where all qubits are in the $$|0\rangle$$ state.

s = simulate(c)

s = 

  QuantumState with properties:

    BasisStates: [8×1 string]
     Amplitudes: [8×1 double]
      NumQubits: 3

Show the final state after simulating this circuit.

str = formula(s)

str = 

    "(0.25+0i)     * |000> +
     (0-0.60355i)  * |001> +
     (0-0.25i)     * |010> +
     (-0.60355+0i) * |011> +
     (0-0.10355i)  * |100> +
     (-0.25+0i)    * |101> +
     (-0.10355+0i) * |110> +
     (0+0.25i)     * |111>"

Plot the histogram of the final state to show each possible state and its probability distribution.

histogram(s)

You can also specify which qubits to plot in the histogram. The histogram shows the possible states of the specified qubits (where the other qubits can be in any state) and their corresponding probability distributions (where the probabilities of the other qubits being in any state are combined).

For example, specify qubits 1 and 3 to plot in the histogram. This histogram shows the possible states $$|00\rangle$$, $$|01\rangle$$, $$|10\rangle$$, and $$|11\rangle$$, where their corresponding probabilities are 0.125, 0.7286, 0.0214, and 0.125.

histogram(s,[1 3])

To query each possible state of all qubits and its probability distribution, use the querystates function.

[states,probabilities] = querystates(s)

states = 

  8×1 string array

    "000"
    "001"
    "010"
    "011"
    "100"
    "101"
    "110"
    "111"


probabilities =

    0.0625
    0.3643
    0.0625
    0.3643
    0.0107
    0.0625
    0.0107
    0.0625

You can also specify which qubits to query when using querystates.

[states,probabilities] = querystates(s,[1 3])

states = 

  4×1 string array

    "00"
    "01"
    "10"
    "11"


probabilities =

    0.1250
    0.7286
    0.0214
    0.1250

Plot Histogram of Measured States

Create a quantum circuit that consists of three x-axis rotation gates. The first gate acts on qubit 1 with rotation angle pi/4, the second gate acts on qubit 2 with rotation angle pi/2, and the third gate acts on qubit 3 with rotation angle 3*pi/4.

g = rxGate(1:3,pi/4*(1:3));
c = quantumCircuit(g);

Simulate this circuit using the default initial state, where all qubits are in the $$|0\rangle$$ state. After running the circuit, randomly sample the quantum state with 100 shots and return the resulting simulated measurement.

s = simulate(c);
m = randsample(s,100)

m = 

  QuantumMeasurement with properties:

    MeasuredStates: [7×1 string]
            Counts: [7×1 double]
     Probabilities: [7×1 double]
         NumQubits: 3

Show the counts and estimated probabilities of the measured states.

table(m.Counts,m.Probabilities,m.MeasuredStates, ...
    VariableNames=["Counts","Probabilities","States"])

ans =

  7×3 table

    Counts    Probabilities    States
    ______    _____________    ______

       6          0.06         "000" 
      33          0.33         "001" 
       5          0.05         "010" 
      40           0.4         "011" 
       5          0.05         "101" 
       3          0.03         "110" 
       8          0.08         "111" 

Plot the histogram of the measurement result to show each measured state and its estimated probability.

histogram(m)

To show all possible states in the histogram, even if these states have 0 measurement probability, specify a threshold value of "none" when using histogram.

histogram(m,Threshold="none")

To query each possible state and its estimated probability, use the querystates function and specify the threshold as "none".

[states,probabilities] = querystates(m,Threshold="none")

states = 

  8×1 string array

    "000"
    "001"
    "010"
    "011"
    "100"
    "101"
    "110"
    "111"


probabilities =

    0.0600
    0.3300
    0.0500
    0.4000
         0
    0.0500
    0.0300
    0.0800

Specify Basis and Threshold for Histogram

Create a quantum state for a single qubit.

s = quantum.gate.QuantumState([0.76 0.65])

s = 

  QuantumState with properties:

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

Plot the histogram of this state in the default Z basis.

histogram(s)

Plot the histogram in the X basis by specifying the Basis name-value argument as "X".

histogram(s,Basis="X")

Plot the histogram including only states with a probability greater than 0.05. Specify the probability threshold as 0.05 by using the Threshold name-value argument.

histogram(s,Basis="X",Threshold=0.05)

Input Arguments

s — Quantum state or measurement

QuantumState object | QuantumMeasurement object

Quantum state or measurement, specified as a QuantumState object or a QuantumMeasurement object.

qubits — Qubit indices

vector of positive integers

Qubit indices, specified as a vector of positive integers. By default, this vector is 1:s.NumQubits, where histogram plots the possible states (with nonzero probabilities) of all qubits in s.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: histogram(quantum.gate.QuantumState("1+-"),Threshold=0.1,Basis="X")

Basis — Basis in which to represent each qubit

"Z" (default) | "X" | string containing "Z" and "X"

Basis in which to represent each qubit, specified as one of these values:

• "Z" (default) — Plot the histogram in the Z basis (the "0" and "1" states).

• "X" — Plot the histogram in the X basis (the "+" and "-" states).

• String containing "Z" and "X" — Plot the histogram in the Z or X basis specified for each qubit in the input quantum state. The length of the string must equal the number of qubits in s.

This name-value argument is available only if the input s is a QuantumState object. If s is a QuantumMeasurement object, then histogram plots in the Z basis.

Threshold — Probability threshold to include states

real number | "none"

Probability threshold to include states, specified as a real number or "none". The default threshold is:

• s.NumQubits*eps("like",s.Amplitudes) if s is a QuantumState object.

• s.NumQubits*eps if s is a QuantumMeasurement object.

If s is a QuantumState object, then setting the threshold to "none" shows all possible states of the requested qubits in the histogram.

If s is a QuantumMeasurement object, then setting the threshold to "none" shows all states with nonnegative estimated probabilities in the histogram. The histogram plot ignores the states with negative estimated probabilities. To plot the states with negative probabilities, you can use querystates on s with the threshold set to "none" instead, and pass the outputs to the bar function.

Tips

• To return the possible states and their probabilities, you can use querystates. The querystates function (with two output arguments) has the same syntaxes as histogram.

Version History

Introduced in R2023a