Matrices#

This module provides a collection of core functions for constructing matrices in quantum mechanics.

from qhronology.mechanics.matrices import vector_basis, ket, bra, quantum_state, encode, decode_slow, decode, decode_fast, decode_multiple

Functions#

vector_basis( dim: int, ) → list[MutableDenseMatrix][source]#

Creates an ordered list of column vectors that form an orthonormal basis for a dim-dimensional Hilbert space.

Parameters:: dim (int) – The dimensionality of the vector basis. Must be a non-negative integer.
Returns:: list[int] – An ordered list of basis vectors.

Examples

>>> vector_basis(2)
[Matrix([
 [1],
 [0]]),
 Matrix([
 [0],
 [1]])]

>>> vector_basis(3)
[Matrix([
 [1],
 [0],
 [0]]),
 Matrix([
 [0],
 [1],
 [0]]),
 Matrix([
 [0],
 [0],
 [1]])]

ket( spec: int | list[int], dim: int | None = None, ) → MutableDenseMatrix[source]#

Creates a normalized ket (column) basis vector corresponding to the (multipartite) computational-basis value(s) of spec in a dim-dimensional Hilbert space.

In mathematical notation, spec describes the value of the ket vector, e.g., a spec of [i,j,k] corresponds to the ket vector \(\ket{i,j,k}\) (for some non-negative integers i, j, and k).

Parameters:

spec (int | list[int]) – A non-negative integer or a list of such types.
dim (int) – The dimensionality of the vector. Must be a non-negative integer. Defaults to 2.

Returns:

mat – A normalized column vector.

Examples

>>> ket(0)
Matrix([
[1],
[0]])

>>> ket(1)
Matrix([
[0],
[1]])

>>> ket([2, 1], dim=3)
Matrix([
[0],
[0],
[0],
[0],
[0],
[0],
[0],
[1],
[0]])

bra( spec: int | list[int], dim: int | None = None, ) → MutableDenseMatrix[source]#

Creates a normalized bra (row) basis vector corresponding to the (multipartite) computational-basis value(s) of spec in a dim-dimensional dual Hilbert space.

In mathematical notation, spec describes the value of the bra vector, e.g., a spec of [i,j,k] corresponds to the bra vector \(\bra{i,j,k}\) (for some non-negative integers i, j, and k).

Parameters:

spec (int | list[int]) – A non-negative integer or a list of such types.
dim (int) – The dimensionality of the vector. Must be a non-negative integer. Defaults to 2.

Returns:

mat – A normalized row vector.

Examples

>>> bra(0)
Matrix([[1, 0]])

>>> bra(1)
Matrix([[0, 1]])

>>> bra([0, 2], dim=3)
Matrix([[0, 0, 1, 0, 0, 0, 0, 0, 0]])

Constructs a dim-dimensional matrix or vector representation of a quantum state from a given specification spec.

Parameters:

spec –
The specification of the quantum state. Provides a complete description of the state’s values in a standard dim-dimensional basis. Can be one of:
- a SymPy matrix (mat)
- a NumPy array (arr)
- a list of lists of numerical, symbolic, or string expressions that collectively specify a vector or (square) matrix (list[list[num | sym | str]])
- a list of 2-tuples of numerical, symbolic, or string coefficients paired their respective number-basis specification (list[tuple[num | sym | str, int | list[int]]])
form (str) – A string specifying the form for the quantum state to take. Can be either of "vector" or "matrix". Defaults to "matrix".
kind (str) – A string specifying the kind for the quantum state to take. Can be either of "mixed" or "pure". Defaults to "mixed".
dim (int) – The dimensionality of the quantum state’s Hilbert space. Must be a non-negative integer. Defaults to 2.

Returns:

mat – The matrix or vector representation of the quantum state.

Examples

>>> quantum_state([("a", [0]), ("b", [1])], form="vector", kind="pure", dim=2)
Matrix([
[a],
[b]])

>>> quantum_state([("a", [0]), ("b", [1])], form="matrix", kind="pure", dim=2)
Matrix([
[a*conjugate(a), a*conjugate(b)],
[b*conjugate(a), b*conjugate(b)]])

>>> quantum_state([("a", [0]), ("b", [1])], form="matrix", kind="mixed", dim=2)
Matrix([
[a, 0],
[0, b]])

>>> quantum_state(
...     spec=[("a", [0]), ("b", [1]), ("c", [2])],
...     form="vector",
...     kind="pure",
...     dim=3,
... )
Matrix([
[a],
[b],
[c]])

>>> quantum_state(
...     spec=[("a", [0, 0]), ("b", [1, 1])],
...     form="vector",
...     kind="pure",
...     dim=2,
... )
Matrix([
[a],
[0],
[0],
[b]])

>>> quantum_state([["a", "b"], ["c", "d"]], form="matrix", kind="mixed", dim=2)
Matrix([
[a, b],
[c, d]])

>>> matrix = sp.Matrix([["a", "b"], ["c", "d"]])
>>> quantum_state(matrix, form="matrix", kind="mixed", dim=2)
Matrix([
[a, b],
[c, d]])

encode( integer: int, num_systems: int | None = None, dim: int | None = None, reverse: bool | None = None, output_list: bool | None = None, ) → MutableDenseMatrix[source]#

Encodes a non-negative integer as a single quantum state vector (ket).

This is a kind of unsigned integer encoding. It creates a base-dim numeral system representation of integer as an (ordered) list of encoded digits. Returns this list if output_list is True, otherwise returns the corresponding ket vector (i.e., a ket vector with a spec of these digits).

Parameters:

integer (int) – The non-negative integer to be encoded.
num_systems (int) – The number of systems (e.g., qubits) necessary to represent the integer in the encoding. Must be a non-negative integer. If None, it automatically increases to the smallest possible number of systems with which the given integer can be encoded.
dim (int) – The dimensionality (or base) of the encoding. Must be a non-negative integer. Defaults to 2.
reverse (str) –
Whether to reverse the ordering of the resulting encoded state.
- If reverse is False, the significance of the digits decreases along the list (i.e., the least-significant digit is last).
- If reverse is True, the significance of the digits increases along the list (i.e., the least-significant digit is first).
Defaults to False.
output_list (bool) – Whether to output a list of encoded digits instead of an encoded state. Defaults to False.

Returns:

mat – A normalized column vector (if output_list is False).
list[int] – An ordered list of the encoded digits (if output_list is True).

Examples

>>> encode(3, num_systems=2)
Matrix([
[0],
[0],
[0],
[1]])

>>> encode(7, num_systems=2, dim=3)
Matrix([
[0],
[0],
[0],
[0],
[0],
[0],
[0],
[1],
[0]])

>>> encode(264, num_systems=3, dim=10, output_list=True)
[2, 6, 4]

>>> encode(115, num_systems=8, output_list=True)
[0, 1, 1, 1, 0, 0, 1, 1]

>>> encode(115, num_systems=8, output_list=True, reverse=True)
[1, 1, 0, 0, 1, 1, 1, 0]

decode_slow( matrix: mat | QuantumObject, dim: int | None = None, reverse: bool | None = None, ) → int[source]#

Decodes a quantum matrix or vector state to an unsigned integer.

Note

The current method by which this particular implementation operates is accurate but slow. For a faster algorithm, use the decode_fast() function.

Note

This function can also be called using the alias decode().

Parameters:

matrix (mat | QuantumObject) – The quantum (matrix or vector) state to be decoded.
dim (int) – The dimensionality (or base) of the encoding. Must be a non-negative integer. Defaults to 2.
reverse (str) –
Whether to reverse the digit ordering of the encoded state prior to decoding.
- If reverse is False, the significance of the digits should decrease along the list (i.e., the least-significant digit is last).
- If reverse is True, the significance of the digits should increase along the list (i.e., the least-significant digit is first).
Defaults to False.

Returns:

int – The decoded (unsigned) integer.

Examples

>>> decode_slow(encode(64))
64

>>> matrix = sp.Matrix([0, 0, 0, 0, 1, 0, 0, 0])
>>> decode_slow(matrix)
4

decode( matrix: mat | QuantumObject, dim: int | None = None, reverse: bool | None = None, ) → int#: An alias for the decode_slow() function.

decode_fast( matrix: mat | QuantumObject, dim: int | None = None, ) → int[source]#

Decodes a quantum matrix or vector state to an unsigned integer.

Note

The current method by which this particular implementation operates is fast but may be inaccurate (due to some computational shortcuts that may not work in all cases). For a slower but accurate algorithm, use the decode_slow() function.

Note

The output cannot be reversed like in decode_slow().

Parameters:

matrix (mat | QuantumObject) – The quantum (matrix or vector) state to be decoded.
dim (int) – The dimensionality (or base) of the encoding. Must be a non-negative integer. Defaults to 2.

Returns:

int – The decoded (unsigned) integer.

Examples

>>> decode_fast(encode(2048))
2048

>>> matrix = sp.Matrix([0, 0, 1, 0, 0, 0, 0])
>>> decode_fast(matrix, dim=3)
2

decode_multiple( matrix: mat | QuantumObject, dim: int | None = None, reverse: bool | None = None, ) → list[tuple[int, num | sym]][source]#

Decodes a quantum matrix or vector state to one or more unsigned integers with their respective probabilities.

Parameters:

matrix (mat | QuantumObject) – The quantum (matrix or vector) state to be decoded.
dim (int) – The dimensionality (or base) of the encoding. Must be a non-negative integer. Defaults to 2.
reverse (str) –
Whether to reverse the digit ordering of the encoded state prior to decoding.
- If reverse is False, the significance of the digits should decrease along the list (i.e., the least-significant digit is last).
- If reverse is True, the significance of the digits should increase along the list (i.e., the least-significant digit is first).
Defaults to False.

Returns:

list[tuple[int, num | sym]] – The list of tuples of pairs of decoded (unsigned) integers and their corresponding probabilities.

Examples

>>> a, b = sp.symbols("a, b")
>>> matrix = a * encode(0) + b * encode(1)
>>> decode_multiple(matrix)
[(0, a*conjugate(a)), (1, b*conjugate(b))]

>>> matrix = sp.Matrix(["x", 0, 0, "y"])
>>> decode_multiple(matrix)
[(0, x*conjugate(x)), (3, y*conjugate(y))]