qilisdk.core.qtensor

Attributes

Complex

Classes

QTensor

Lightweight wrapper around sparse matrices representing quantum states or operators.

Functions

`basis_state`(→ QTensor)	Generate the n'th basis vector representation, on a N-size Hilbert space (N=2**num_qubits).
`ket`(→ QTensor)	Generate a ket state for a multi-qubit system.
`bra`(→ QTensor)	Generate a bra state for a multi-qubit system.
`tensor_prod`(→ QTensor)	Calculate the tensor product of a list of QTensors.
`expect_val`(→ Complex)	Calculate the expectation value of an operator with respect to a quantum state.

Module Contents

Complex[fuente]

class QTensor(data: numpy.ndarray | scipy.sparse.sparray | scipy.sparse.spmatrix)[fuente]

Lightweight wrapper around sparse matrices representing quantum states or operators.

The QTensor class is a wrapper around sparse matrices (or NumPy arrays, which are converted to sparse matrices) that represent quantum states (kets, bras, or density matrices) or operators. It provides utility methods for common quantum operations such as taking the adjoint (dagger), computing tensor products, partial traces, and norms.

The internal data is stored as a SciPy CSR (Compressed Sparse Row) matrix for efficient arithmetic and manipulation. The expected shapes for the data are: - (2**N, 2**N) for operators or density matrices (or scalars), - (2**N, 1) for ket states, - (1, 2**N) for bra states.

Converts a NumPy array to a CSR matrix if needed and validates the shape of the input. The input must represent a valid quantum state or operator with appropriate dimensions.

Ejemplo

import numpy as np
from qilisdk.core import QTensor

ket = QTensor(np.array([[1.0], [0.0]]))
density = ket * ket.adjoint()

Parámetros:: data (np.ndarray | sparray | spmatrix) – Dense or sparse matrix defining the quantum object. Expected shapes are (2**N, 2**N) for operators, (2**N, 1) for kets, (1, 2**N) for bras, or (1, 1) for scalars.
Muestra:: ValueError – If data is not 2-D or does not correspond to valid qubit dimensions.

property data: scipy.sparse.csr_matrix[fuente]

Get the internal sparse matrix representation of the QTensor.

Devuelve:: The internal representation as a CSR matrix.
Tipo del valor devuelto:: csc_matrix

property nqubits: int[fuente]

Compute the number of qubits represented by the QTensor.

Devuelve:: The number of qubits if determinable; otherwise, -1.
Tipo del valor devuelto:: int

property shape: tuple[int, int][fuente]

Get the shape of the QTensor’s internal matrix.

Devuelve:: The shape of the internal matrix.
Tipo del valor devuelto:: tuple[int, …]

dense() → numpy.ndarray[fuente]

Get the dense (NumPy array) representation of the QTensor.

Devuelve:: The dense array representation.
Tipo del valor devuelto:: np.ndarray

is_ket() → bool[fuente]

is_bra() → bool[fuente]

is_scalar() → bool[fuente]

is_operator() → bool[fuente]

adjoint() → QTensor[fuente]

Compute the adjoint (conjugate transpose) of the QTensor.

Devuelve:: A new QTensor that is the adjoint of this object.
Tipo del valor devuelto:: QTensor

trace() → complex[fuente]

ptrace(keep: list[int], dims: list[int] | None = None) → QTensor[fuente]

Compute the partial trace over subsystems not in “keep”.

This method calculates the reduced density matrix by tracing out the subsystems that are not specified in the “keep” parameter. The input “dims” represents the dimensions of each subsystem (optional), and “keep” indicates the indices of those subsystems to be retained.

If the QTensor is a ket or bra, it will first be converted to a density matrix.

Parámetros:

keep (list[int]) – A list of indices corresponding to the subsystems to retain. The order of the indices in “keep” is not important, since dimensions will be returned in the tensor original order, but the indices must be unique.
dims (list[int], optional) – A list specifying the dimensions of each subsystem. If not specified, a density matrix of qubit states is assumed, and the dimensions are inferred accordingly (i.e. we split the state in dim 2 states).

Muestra:

ValueError – If the product of the dimensions in dims does not match the shape of the QTensor’s dense representation or if any dimension is non-positive.
ValueError – If the indices in “keep” are not unique or are out of range.
ValueError – If the QTensor is not a valid density matrix or state vector.
ValueError – If the number of subsystems exceeds the available ASCII letters.

Devuelve:

A new QTensor representing the reduced density matrix: for the subsystems specified in “keep”.

Tipo del valor devuelto:

QTensor

norm(order: int | Literal['fro', 'tr'] = 1) → float[fuente]

Compute the norm of the QTensor.

For density matrices, the norm order can be specified. For state vectors, the norm is computed accordingly.

Parámetros:: order (int or {"fro", "tr"}, optional) – The order of the norm. Only applies if the QTensor represents a density matrix. Other than all the orders accepted by scipy, it also accepts “tr” for the trace norm. Defaults to 1.
Muestra:: ValueError – If the QTensor is not a valid density matrix or state vector,
Devuelve:: The computed norm of the QTensor.
Tipo del valor devuelto:: float

unit(order: int | Literal['fro', 'tr'] = 'tr') → QTensor[fuente]

Normalize the QTensor.

Scales the QTensor so that its norm becomes 1, according to the specified norm order.

Parámetros:: order (int or {"fro", "tr"}, optional) – The order of the norm to use for normalization. Only applies if the QTensor represents a density matrix. Other than all the orders accepted by scipy, it also accepts “tr” for the trace norm. Defaults to «tr».
Muestra:: ValueError – If the norm of the QTensor is 0, making normalization impossible.
Devuelve:: A new QTensor that is the normalized version of this object.
Tipo del valor devuelto:: QTensor

expm() → QTensor[fuente]

Compute the matrix exponential of the QTensor.

Devuelve:: A new QTensor representing the matrix exponential.
Tipo del valor devuelto:: QTensor

to_density_matrix() → QTensor[fuente]

Convert the QTensor to a density matrix.

If the QTensor represents a state vector (ket or bra), this method calculates the corresponding density matrix by taking the outer product. If the QTensor is already a density matrix, it is returned unchanged. The resulting density matrix is normalized.

Muestra:

ValueError – If the QTensor is a scalar, as a density matrix cannot be derived.
ValueError – If the QTensor is an operator that is not a density matrix.

Devuelve:

A new QTensor representing the density matrix.

Tipo del valor devuelto:

QTensor

is_density_matrix(tol: float | None = None) → bool[fuente]

Determine if the QTensor is a valid density matrix.

A valid density matrix must be square, Hermitian, positive semi-definite, and have a trace equal to 1.

Parámetros:: tol (float, optional) – The numerical tolerance for verifying Hermiticity, eigenvalue non-negativity, and trace. Defaults to the global setting for zero tolerance.
Devuelve:: True if the QTensor is a valid density matrix, False otherwise.
Tipo del valor devuelto:: bool

is_hermitian(tol: float | None = None) → bool[fuente]

Check if the QTensor is Hermitian.

Parámetros:: tol (float, optional) – The numerical tolerance for verifying Hermiticity. Defaults to the global setting for zero tolerance.
Devuelve:: True if the QTensor is Hermitian, False otherwise.
Tipo del valor devuelto:: bool

basis_state(n: int, N: int) → QTensor[fuente]

Generate the n’th basis vector representation, on a N-size Hilbert space (N=2**num_qubits).

This function creates a column vector (ket) representing the Fock state |n⟩ in a Hilbert space of dimension N.

Parámetros:

n (int) – The desired number state (from 0 to N-1).
N (int) – The dimension of the Hilbert space, has a value 2**num_qubits.

Muestra:

ValueError – If n >= N.

Devuelve:

A QTensor representing the |n⟩”th basis state on a N-size Hilbert space (N=2**num_qubits).

Tipo del valor devuelto:

QTensor

ket(*state: int) → QTensor[fuente]

Generate a ket state for a multi-qubit system.

This function creates a tensor product of individual qubit states (kets) based on the input values. Each input must be either 0 or 1. For example, ket(0, 1) creates a two-qubit ket state |0⟩ ⊗ |1⟩.

Parámetros:: *state (int) – A sequence of integers representing the state of each qubit (0 or 1).
Muestra:: ValueError – If any of the provided qubit states is not 0 or 1.
Devuelve:: A QTensor representing the multi-qubit ket state.
Tipo del valor devuelto:: QTensor

bra(*state: int) → QTensor[fuente]

Generate a bra state for a multi-qubit system.

This function creates a tensor product of individual qubit states (bras) based on the input values. Each input must be either 0 or 1. For example, bra(0, 1) creates a two-qubit bra state ⟨0| ⊗ ⟨1|.

Parámetros:: *state (int) – A sequence of integers representing the state of each qubit (0 or 1).
Devuelve:: A QTensor representing the multi-qubit bra state.
Tipo del valor devuelto:: QTensor

tensor_prod(operators: list[QTensor]) → QTensor[fuente]

Calculate the tensor product of a list of QTensors.

This function computes the tensor (Kronecker) product of all input QTensors, resulting in a composite QTensor that represents the combined state or operator.

Parámetros:: operators (list[QTensor]) – A list of QTensors to be combined via tensor product.
Devuelve:: A new QTensor representing the tensor product of the inputs.
Tipo del valor devuelto:: QTensor
Muestra:: ValueError – If operators list is empty.

expect_val(operator: QTensor, state: QTensor) → Complex[fuente]

Calculate the expectation value of an operator with respect to a quantum state.

Computes the expectation value ⟨state| operator |state⟩. The function handles both pure state vectors and density matrices appropriately.

Parámetros:

operator (QTensor) – The quantum operator represented as a QTensor.
state (QTensor) – The quantum state or density matrix represented as a QTensor.

Muestra:

ValueError – If the operator is not a square matrix.
ValueError – If the state provided is not a valid quantum state.

Devuelve:

The expectation value. The result is guaranteed to be real if the operator is Hermitian, and may be complex otherwise.

Tipo del valor devuelto:

Complex