quairkit.loss.measure¶

The source file of the class for the measurement.

class quairkit.loss.measure.Measure(measure_op=None)¶

Compute the probability of the specified measurement result.

Parameters:¶

measure_op : str | Tensor | None¶

Specify the basis of the measurement. Defaults to 'computational'.

Note

the allowable input for measure_op are: - None, i.e., a ‘computational’ basis - a string composed of ‘i’, ‘x’, ‘y’, and ‘z’ - a projection-valued measurement (PVM) in torch.Tensor

from quairkit.database import random_state, std_basis

# Define measurement basis using a string (e.g., 'xy' denotes eigen-basis of X ⊗ Y)
op = Measure("xy")
# Define a custom measurement basis using a user-specified PVM tensor
pvm_tensor = std_basis(2).density_matrix
op = Measure(pvm_tensor)
# Use default computational basis
op = Measure()

state = random_state(num_qubits=2)

# Full measurement: probability distribution over all measurement outcomes.
result = op(state)
print("Probabilities for measuring all qubits:", result)

# Measurement on a targeted subsystem (e.g., the first qubit)
result = op(state, system_idx=0)
print("Probabilities for measuring the first qubit:", result)

# Compute probability for a specific full-system outcome ('10')
result = op(state, desired_result='10')
print("Probability for measuring all qubits with outcome 10:", result)

# Compute probabilities for selected outcomes (e.g., outcomes corresponding to indices 0 and 3)
result = op(state, desired_result=[0, 3])
print("Probabilities for measuring all qubits with outcomes 00 and 11:", result)

# Retrieve both the probability and the post-measurement state.
prob, post_state = op(state, keep_state=True)
print("Post-measurement state:", post_state)

# Batched measurement on multiple states.
state_batch = random_state(num_systems=2, size=2)
result = op(state_batch)
print(f"Probabilities for measuring two states:\n{result}")

Probabilities for measuring all qubits: tensor([0.1273, 0.0956, 0.3312, 0.4459])
Probabilities for measuring the first qubit: tensor([0.2229, 0.7771])
Probability for measuring all qubits with outcome 10: tensor([0.3312])
Probabilities for measuring all qubits with outcomes 00 and 11: tensor([0.1273, 0.4459])
Post-measurement state:
-----------------------------------------------------
Backend: state_vector
System dimension: [2, 2]
System sequence: [0, 1]
Batch size: [4]

# 0:
[1.+0.j 0.+0.j 0.+0.j 0.+0.j]
# 1:
[0.+0.j 1.+0.j 0.+0.j 0.+0.j]
# 2:
[0.+0.j 0.+0.j 1.+0.j 0.+0.j]
# 3:
[0.+0.j 0.+0.j 0.+0.j 1.+0.j]
-----------------------------------------------------

Probabilities for measuring two states:
tensor([[0.2846, 0.1826, 0.2665, 0.2663],
        [0.1513, 0.4921, 0.1676, 0.1891]])

forward(state, system_idx='full', shots=None, desired_result=None, keep_state=False)¶

Compute the probability of measurement to the input state.

Parameters:¶

state : StateSimulator | StateOperator¶

The quantum state to be measured.

system_idx : Iterable[int] | int | str | None¶

The index of the systems to be measured. Defaults to 'full' which means measure all the qubits.

shots : int | None¶

The number of shots for the measurement. Defaults to None which means the default behavior.

desired_result : List[int | str] | int | str | None¶

Specify the results of the measurement to return. Defaults to None which means return the probability of all the results.

keep_state : bool¶

Whether return the measured state. Defaults to False.

Returns:¶

The probability of the measurement.

Return type:¶

Tensor | Tuple[Tensor, StateSimulator | StateOperator] | Tuple[Dict, StateSimulator | StateOperator]

class quairkit.loss.measure.ExpecVal(hamiltonian)¶

The class of the loss function to compute the expectation value for an observable.

This interface allows you to use the expectation value of an observable as a loss function for training quantum circuits. The expectation value is defined as \(\langle H \rangle = \text{tr}(\rho H)\).

Parameters:¶

hamiltonian : Hamiltonian¶

The input observable (Hamiltonian) to compute the expectation value for.

Note

This class supports batch operations. When input states have batch dimensions, the expectation value is computed element-wise along the batch dimension.

Examples

from quairkit.database import random_hamiltonian_generator, random_state
from quairkit.loss import ExpecVal

# Create observable and compute expectation value
observable = random_hamiltonian_generator(1)
print(f'The input observable is:\n{observable}')
expec_val = ExpecVal(observable)

input_state = random_state(num_systems=1, rank=2)
result = expec_val(input_state, decompose=True)
print('The expectation value of the observable:', result)

The input observable is:
-0.28233465254251144 Z0
0.12440505341821817 X0
-0.2854054036807161 Y0
The expectation value of the observable: tensor([-0.1162,  0.0768, -0.0081])

# Batch expectation value example
input_state_batch = random_state(num_systems=1, size=2)
batch_result = expec_val(input_state_batch, decompose=False)
print('The expectation value of the observable:', batch_result)

The expectation value of the observable: tensor([0.1748, 0.0198])

forward(state, shots=None, decompose=False)¶

Compute the expectation value of the observable with respect to the input state.

The value computed by this function can be used as a loss function to optimize quantum circuits.

Parameters:¶

state : StateSimulator | StateOperator¶

The input quantum state which will be used to compute the expectation value. Can be a single state or a batch of states.

shots : int | None¶

The number of shots to measure the observable. Defaults to None, which means exact computation.

decompose : bool | None¶

If True, returns the expectation value of each term in the observable separately. Defaults to False, which returns the total expectation value.

Returns:¶

The expectation value of the observable. If decompose=True, returns a tensor with one value per term. If decompose=False, returns a scalar for single states or a tensor for batched states.

Raises:¶

NotImplementedError – If the backend is wrong or not supported.

Return type:¶

Tensor