state

Interfaces for classical or quantum states.

This module contains the interfaces State, BasisState, QuantumState, BasisStateProbabilities, and BasisStateCounts. Specific implementations of the interfaces in the Pauli bases can be found in the module parityos.states.pauli_state.

class parityos.states.state.State

Bases: HasFrozenQubits[QubitT_co], ABC

Interface for all types of states defined on a set of qubits.

abstractmethod flip_qubits(qubits: QubitT_co | Iterable[QubitT_co] | None = None) → Self

Flip the state on every qubit in qubits.

For each qubit in qubits the state on this qubit is flipped (0 <-> 1). Qubits in qubits that are not in this state are ignored.

Note

If qubits is None (default), all qubits are flipped.

Parameters:

qubits – Qubits to flip. If None, all qubits are flipped. Defaults to None.

Returns:

Copy of self with state on all qubits in qubits flipped

class parityos.states.state.StateT_contra

A contravariant TypeVar representing a State.

alias of TypeVar(‘StateT_contra’, bound=State, contravariant=True)

class parityos.states.state.BasisState

Bases: State[QubitT_co], HasFrozenQubits[QubitT_co], ABC

Interface for basis states of quantum states.

Basis states are assumed to be product states with an associated mapping qubit_to_value from each qubit to its boolean bit value representing the qubits state.

property qubit_to_value: MappingProxyType

A mapping from each qubit to its boolean value.

Example

A product state \(|0101\rangle\) on qubits q_0, q_1, q_2, q_3 would return a mapping equivalent to {q_0: False, q_1: True, q_2: False, q_3: True}.

Returns:

A mapping from each qubit to its boolean value, indicating the product state.

get_bit_value(qubit: QubitT_co) → bool

Get boolean bit assignment for qubit of this BasisState.

Parameters:

qubit – Qubit for which to get its assigned boolean bit value.

Returns:

Boolean bit value of qubit in this basis state.

Raises:

ParityOSException – If qubit is not contained in this basis state.

class parityos.states.state.BasisStateProbabilities

Bases: State[QubitT_co], Generic[QubitT_co, BasisStateT_co], ABC

Interface for states with probabilities assigned to BasisState instances.

BasisStateProbabilities are defined by a mapping from product states (BasisState instances) to the probability of observing this BasisState.

property state_to_probability: MappingProxyType

A mapping from BasisState instances to their probabilities.

Example

A state with probability 1/2 of measuring the basis states \(|01\rangle\) and \(|10\rangle\) would return a mapping equivalent to \(\{|01\rangle: 0.5, |10\rangle: 0.5\}\).

class parityos.states.state.QuantumState

Bases: BasisStateProbabilities[QubitT_co, BasisStateT_co], ABC

Interface for quantum states.

Quantum states are defined by a mapping from product states (BasisState instances) to their corresponding amplitudes. Amplitudes can be complex numbers or Symbolic coefficients.

property state_to_amplitude: MappingProxyType

A mapping from BasisState instances to their amplitudes.

Amplitudes can be complex numbers or Symbolic coefficients.

Example

The Bell state \(1/\sqrt{2}\left(|00\rangle + |11\rangle\right)\) would return a mapping equivalent to \(\{|00\rangle: 1/\sqrt{2}, |11\rangle: 1/\sqrt{2}\}\).

abstractmethod to_normalized() → Self

Rescale all amplitudes such that their squared absolute values sum to 1, i.e. the quantum state is properly normalized.

Returns:

A normalized copy of this state.

property norm_squared: Symbolic | float

Squared norm of the quantum state \(\langle\Psi|\Psi\rangle\).

property norm: Symbolic | float

Norm of the quantum state \(\lVert|\Psi\rangle\rVert = \sqrt{\langle\Psi|\Psi\rangle}\).

property state_to_probability: MappingProxyType

A mapping from BasisState instances to their probabilities.

Example

A state with probability 1/2 of measuring the basis states \(|01\rangle\) and \(|10\rangle\) would return a mapping equivalent to \(\{|01\rangle: 0.5, |10\rangle: 0.5\}\).

class parityos.states.state.BasisStateCounts

Bases: BasisStateProbabilities[QubitT_co, BasisStateT_co], ABC

Interface for an ensemble of measured basis states with corresponding measurement counts.

BasisStateCounts are defined by a mapping from product states (BasisState instances) to their corresponding measurement counts (integer). They are typically obtained from measurements on QPUs where measurement counts of basis states are recorded, i.e. how often they have been observed.

property total_count: int

Sum of all measurement counts.

This corresponds to the total number of measurements performed, and is useful for normalization and obtaining empirical probabilities of measuring individual basis states.

Returns:

The total sum of all measurement counts.

property state_to_count: MappingProxyType

A mapping from BasisState instances to their measurement counts.

property state_to_probability: MappingProxyType

A mapping from BasisState instances to their probabilities.

Example

A state with probability 1/2 of measuring the basis states \(|01\rangle\) and \(|10\rangle\) would return a mapping equivalent to \(\{|01\rangle: 0.5, |10\rangle: 0.5\}\).