# 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

example

````[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. ```

example

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

example

````[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

collapse all

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〉$ 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```

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〉$ 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```

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

collapse all

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.

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 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.

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

collapse all

Possible states, returned as a string vector.

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