querystates

Query possible states

Since R2023a

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

Syntax

[states,probabilities] = querystates(s)

[states,probabilities] = querystates(s,qubits)

[states,probabilities] = querystates(___,Name=Value)

Description

[states,probabilities] = querystates(s) returns the possible states and the probability of measuring each state from the specified quantum state or measurement. The input s must be a QuantumState or QuantumMeasurement object.

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

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

[states,probabilities] = querystates(s,qubits) specifies a set of qubits for which to find possible states and the probabilities of those states.

[states,probabilities] = querystates(___,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 output.

Examples

Query Possible States 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>"

Query each possible state and its probability distribution.

[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

Plot the histogram of the final state that shows each possible state and its probability distribution.

histogram(s)

You can also specify a subset of qubits when querying the possible states. The querystates function returns 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, query the possible states of qubits 1 and 3. The output shows that the two qubits can be in the "00", "01", "10", and "11" states, where their corresponding probabilities are 0.1250, 0.7286, 0.0214, and 0.1250.

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

states = 

  4×1 string array

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


probabilities =

    0.1250
    0.7286
    0.0214
    0.1250

Query States of Measurement Result

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" 

Query each measured state and its estimated probability.

[states,probabilities] = querystates(m)

states = 

  7×1 string array

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


probabilities =

    0.0600
    0.3300
    0.0500
    0.4000
    0.0500
    0.0300
    0.0800

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

histogram(m)

You can also specify a subset of qubits when querying the measured states. The querystates function returns the measured 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, query the measured states of qubit 1. The output shows the "0" and "1" states, where their corresponding probabilities are 0.84 and 0.16.

[states,probabilities] = querystates(m,1)

states = 

  2×1 string array

    "0"
    "1"


probabilities =

    0.8400
    0.1600

Specify Basis and Threshold to Query States

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

Query the possible states of this quantum state in the default Z basis.

[states,probabilities] = querystates(s)

states = 

  2×1 string array

    "0"
    "1"


probabilities =

    0.5775
    0.4225

Query the state in the X basis by specifying the Basis name-value argument as "X".

[states,probabilities] = querystates(s,Basis="X")

states = 

  2×1 string array

    "+"
    "-"


probabilities =

    0.9940
    0.0060

Query the state including only states with a probability greater than 0.01. Specify the probability threshold as 0.01 by using the Threshold name-value argument.

[states,probabilities] = querystates(s,Basis="X",Threshold=0.01)

states = 

    "+"


probabilities =

    0.9940

Input Arguments

s — Quantum state or measurement

QuantumState object | QuantumMeasurement object

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

• If s is a QuantumState object, then the probability of measuring a state is the magnitude squared of the amplitude of that state.

• If s is a QuantumMeasurement object, then the estimated probabilities depend on the measurement result provided by the remote device (in some cases, the estimated probabilities can be negative). When the number of counts of each measured state are provided, the estimated probabilities are these counts divided by their sum.

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 querystates queries the possible states 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: querystates(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) — Return the output states in the Z basis (the "0" and "1" states).

• "X" — Return the output states in the X basis (the "+" and "-" states).

• String containing "Z" and "X" — Return the output states 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 querystates returns the output states 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.

Setting the threshold to "none" returns all possible states of the requested qubits.

Output Arguments

states — Possible states

string vector

Possible states, returned as a string vector.

probabilities — Probabilities of possible states

vector of real numbers

Probabilities of possible states, returned as a vector of real numbers.

Tips

• To plot a histogram of possible states and their probabilities, you can use histogram. The histogram function (with no output argument) has the same syntaxes as querystates.

Version History

Introduced in R2023a