Quantum States API

Quantum States

class graphcalc.quantum.states.QuantumState(rho: Sequence[Sequence[complex]] | ndarray, *, dims: Sequence[int], validate: bool = True, tol: float = 1e-09)

Bases: object

Finite-dimensional multipartite quantum state represented by a density operator.

The state is stored as a pair (rho, dims) where rho is a square complex matrix of size d x d with d = prod(dims), and dims records the subsystem dimensions.

Conventions

• states are finite-dimensional

• density operators are Hermitian, positive semidefinite, and trace one

• pure states may be constructed from ket vectors but are stored internally as density operators

• subsystem structure is explicit through dims

param rho:

Density matrix representation of the state.

type rho:

array-like

param dims:

Dimensions of the subsystems.

type dims:

tuple of int

param validate:

Whether to validate the input as a density operator.

type validate:

bool, default=True

param tol:

Numerical tolerance used in validation.

type tol:

float, default=1e-9

Notes

The internal density matrix is stored privately as _rho. Public access is provided through a read-only property that returns a copy.

classmethod basis_state(index: int, *, dim: int = 2, tol: float = 1e-09) → QuantumState

Construct a computational basis state |index><index| in dimension dim.

copy() → QuantumState

Return a copy of the quantum state.

property dimension: int

Return the total Hilbert-space dimension.

property dims: Tuple[int, ...]

Return the subsystem dimensions.

eigenvalues() → ndarray

Return the eigenvalues of the density operator.

classmethod from_density(rho: Sequence[Sequence[complex]] | ndarray, *, dims: Sequence[int], validate: bool = True, tol: float = 1e-09) → QuantumState

Construct a quantum state from a density matrix.

classmethod from_ket(ket: Sequence[complex] | ndarray, *, dims: Sequence[int], normalize: bool = True, tol: float = 1e-09) → QuantumState

Construct a quantum state from a ket vector.

Parameters:

• ket (array-like) – State vector.

• dims (tuple of int) – Dimensions of the subsystems.

• normalize (bool, default=True) – Whether to normalize the ket before constructing the density matrix.

• tol (float, default=1e-9) – Numerical tolerance used in validation.

property is_mixed: bool

Return True iff the state is mixed.

property is_pure: bool

Return True iff the state is pure.

property num_subsystems: int

Return the number of subsystems.

partial_trace(subsystems: Iterable[int]) → QuantumState

Trace out the given subsystems.

Parameters:

subsystems (iterable of int) – Indices of subsystems to trace out.

Returns:

The reduced state on the remaining subsystems.

Return type:

QuantumState

partial_transpose(subsystems: Iterable[int]) → QuantumState

Return the partial transpose with respect to the given subsystems.

Parameters:

subsystems (iterable of int) – Indices of subsystems on which to apply matrix transposition.

Notes

The partial transpose of a valid quantum state need not be positive semidefinite, so the returned operator is constructed with validate=False.

purity() → float

Return Tr(rho^2).

property rank: int

Return the matrix rank of the density operator.

reduced_state(subsystems: Iterable[int]) → QuantumState

Return the reduced state on the given subsystems.

Parameters:

subsystems (iterable of int) – Indices of subsystems to keep.

property rho: ndarray

Return a copy of the density matrix.

subsystem_dimensions(subsystems)

Return the dimensions of the specified subsystems.

tensor(other: QuantumState) → QuantumState

Return the tensor product of this state with another state.

property trace: complex

Return the trace of the density matrix.

validate() → None

Validate that the stored matrix is a density operator.