quairkit.core.state.backend.simulator¶

Source file for base class that simulates quantum states.

class quairkit.core.state.backend.simulator.StateSimulator(data, sys_dim, system_seq, probability)¶

The abstract base class for simulating quantum states in QuAIRKit.

Parameters:¶

data : Tensor¶: tensor array for quantum state(s).
sys_dim : List[int]¶: a list of dimensions for each system.
system_seq : List[int] | None¶: the system order of this state. Defaults to be from 0 to n - 1.
probability : List[Tensor] | None¶: list of state probability distributions. Defaults to be 1.

Note

This class is designed to be inherited by specific state simulator classes. Such class should simulate quantum computing with batch, qudit and probabilities.

abstract prob_select(outcome_idx, prob_idx=-1)¶

Indexing probability outcome from the State batch along the given dimension.

Parameters:¶

outcome_idx : Tensor¶: the 1-D tensor containing the outcomes to index
prob_idx : int¶: the int that indexing which probability distribution. Defaults to be the last distribution.

Returns:¶

States that are selected by the specific probability outcomes.

Return type:¶

StateSimulator

abstract add_probability(prob)¶

Add one probability distribution to the state.

Parameters:¶

prob : Tensor¶: the probability distribution to be added, which should be a 1-D tensor.

abstract expand_as(other)¶

Expand this tensor to the same size as other.

Parameters:¶

other : StateSimulator¶: the state to be expanded to.

Note

See torch.Tensor.expand_as() for more information about expand logic.

abstract kron(other)¶

Take the tensor product with other state.

abstract static check(data, sys_dim, eps=0.0001)¶

Assert whether the input data is valid for the specific State class.

Parameters:¶

data : Tensor¶: tensor array for quantum state(s).
sys_dim : int | List[int]¶: (list of) dimension(s) of the systems, can be a list of integers or an integer.
eps : float | None¶: the tolerance for the numerical check. Can be None means the check is overridden.

Returns:¶

the number of systems.

Return type:¶

int

abstract property probability : Tensor¶: The probability distribution(s) of these states’ occurrences

abstract property batch_dim : list[int]¶: The batch dimension of this state

numel()¶

The number of elements in this data

abstract property shape : Size¶: The recognize shape of this state

abstract property ket : Tensor¶: The ket form of this state

Note

If the state is pure, the ket form is the statevector representation. If the state is mixed, the ket form is the vectorization of its density matrix representation.

property bra : Tensor¶: Dagger of the ket form.

abstract property density_matrix : Tensor¶: The density matrix representation of this state.

property vec : Tensor¶

\(\textrm{vec}(|i \rangle\langle j|)=|j, i \rangle\)

Type:¶: Vectorization of the state

abstract property rank : list[int]¶: The rank of the state.

abstract normalize()¶

Normalize this state to the correct format

abstract numpy()¶

Get the data in numpy.

Returns:¶: The numpy array of the data for the quantum state.
Return type:¶: ndarray

abstract clone()¶

Return a copy of the quantum state.

abstract to(dtype=None, device=None)¶

Change the property of the data tensor, and return a copy of this State

Parameters:¶

dtype : str¶: the new data type of the state.
device : str¶: the new device of the state.

index_select(new_indices)¶

Select the entries stored in this state.

Parameters:¶

new_indices : Iterable[int]¶: the new indices of the entries to be selected.

Returns:¶

a new state with selected indices.

Return type:¶

StateSimulator

abstract permute(target_seq)¶

Permute the systems order of the state.

Parameters:¶

target_seq : List[int]¶: the target systems order.

evolve(unitary, sys_idx=None)¶

Evolve this state with unitary operators.

Parameters:¶

unitary : Tensor¶: the unitary operator.
sys_idx : int | List[int] | None¶: the system indices to be acted on. Defaults to all systems.

Returns:¶

the evolved state.

Return type:¶

StateSimulator

Note

Evolve support the broadcast rule.

transform(op, sys_idx=None, repr_type='kraus')¶

Apply a general linear operator to the state.

Parameters:¶

op : Tensor¶: the input operator.
sys_idx : int | List[int] | None¶: the qubit indices to be applied. Defaults to all systems.
repr_type : str¶: the representation type of input operator. Defaults to ‘kraus’.

Returns:¶

the transformed state.

Return type:¶

StateSimulator

product_trace(trace_state, trace_idx)¶

Partial trace over this state, when this state is a product state

Parameters:¶

trace_state : StateSimulator¶: the state for the subsystem to be traced out.
trace_idx : List[int]¶: the subsystem indices to be traced out.

Note

This function only works when the state is a product state represented by PureState

expec_val(hamiltonian, shots=None, decompose=False)¶

The expectation value of the observable with respect to the quantum state.

Parameters:¶

hamiltonian : Hamiltonian¶: Input observable.
shots : int | None¶: The number of shots to measure the observable. Should not be used in simulation mode.
decompose : bool¶: If decompose is True, it will return the expectation value of each term.

Returns:¶

The expectation value (per term) of the input observable for the quantum state.

Return type:¶

Tensor

Note

currently only run in qubit case.

Raises:¶

NotImplementedError – If shots is specified, since simulators do not support shot-based computations.
NotImplementedError – If the state is not a qubit state.
AssertionError – If the number of qubits in the Hamiltonian is greater than the number of state qubits.

expec_state(prob_idx=None)¶

The expectation with respect to the specific probability distribution(s) of states

Parameters:¶

prob_idx : int | List[int] | None¶: indices of probability distributions. Defaults to all distributions.

Returns:¶

The expected State obtained from the taken probability distributions.

Return type:¶

StateSimulator

measure(system_idx=None, shots=None, measure_op=None, is_povm=False, keep_state=False)¶

Measure the quantum state

Parameters:¶

system_idx : int | List[int] | None¶: the system indices to be measured. Defaults to all systems.
shots : int | None¶: the number of shots to measure. Should not be used in simulation mode.
measure_op : Tensor | None¶: measurement operator. Defaults to the computational basis.
is_povm : bool¶: whether the measurement is a POVM.
keep_state : bool¶: whether to keep the state after measurement.

Returns:¶

The probability of each measurement result. The corresponding collapsed state will also be returned if is_povm is False or keep_state is True.

Raises:¶

NotImplementedError – If shots is specified, since simulators do not support shot-based computations.
UserWarning – is_povm and keep_state cannot be both True,
since a general POVM does not distinguish states. –

Return type:¶

Tensor | Tuple[Tensor, StateSimulator]

abstract sqrt()¶

Matrix square root of the state.

abstract log()¶

Matrix logarithm of the state.

trace(trace_idx=None)¶

(Partial) trace of the state

Parameters:¶

trace_idx : int | List[int] | None¶: the subsystem indices to be traced out. Defaults to all systems.

Returns:¶

the trace of the state as a Tensor, or a new state if sys_idx is not None.

Return type:¶

Tensor | StateSimulator

reset(reset_idx, replace_state)¶

Reset the state to a new state.

Parameters:¶

reset_idx : List[int] | int¶: the subsystem indices to be reset.
replace_state : StateSimulator¶: the state to replace the quantum state.

Returns:¶

the new state after resetting.

Return type:¶

StateSimulator

transpose(transpose_idx=None)¶

(Partial) transpose of the state

Parameters:¶

transpose_idx : int | List[int] | None¶: the subsystem indices to be transposed. Defaults to all systems.

Returns:¶

the transpose of the state as a Tensor, or a new state if sys_idx is not None.

Return type:¶

StateSimulator