Skip to content

dq.QArray

Dynamiqs custom array to represent quantum objects.

A qarray is a wrapper around the data structure representing a quantum object (a ket, a density matrix, an operator, a superoperator, etc.) that offers convenience methods.

The underlying data can be in two formats:

  • Dense: wrapper around JAX arrays, dense representation of the array.
  • SparseDIA: Dynamiqs sparse diagonal format, storing only the non-zero diagonals.
Constructing a new qarray from an other array type

Use the function dq.asqarray() to create a qarray from a qarray-like. Objects that can be converted to a QArray are of type dq.QArrayLike. This includes all numeric types (bool, int, float, complex), a NumPy or JAX array, a Dynamiqs qarray, a QuTiP qobj, or any nested sequence of these types. See also dq.isqarraylike().

Attributes:

  • dtype (numpy.dtype) –

    Data type.

  • shape (tuple of ints) –

    Shape.

  • ndim (int) –

    Number of dimensions in the shape.

  • layout (Layout) –

    Data layout, either dq.dense or dq.dia.

  • dims (tuple of ints) –

    Hilbert space dimension of each subsystem.

  • mT (qarray) –

    Returns the qarray transposed over its last two dimensions.

  • vectorized (bool) –

    Whether the underlying object is non-vectorized (ket, bra or operator) or vectorized (operator in vector form or superoperator in matrix form).

Arithmetic operation support

Qarrays support basic arithmetic operations -, +, *, /, @ with other qarray-likes.

Shortcuts methods to use quantum utilities

Many functions of the library can be called directly on a qarray rather than through the functional API. For example, you can use x.dag() instead of dq.dag(x).

Here is the list of qarray methods:

Method Description
x.conj() Returns the element-wise complex conjugate of the qarray.
x.dag() Alias of dq.dag(x).
x.powm() Alias of dq.powm(x).
x.expm() Alias of dq.expm(x).
x.cosm() Alias of dq.cosm(x).
x.sinm() Alias of dq.sinm(x).
x.signm() Alias of dq.signm(x).
x.trace() Alias of dq.trace(x).
x.ptrace(keep) Alias of dq.ptrace(x, keep, dims=x.dims).
x.norm() Alias of dq.norm(x).
x.unit() Alias of dq.unit(x).
x.isket() Alias of dq.isket(x).
x.isbra() Alias of dq.isbra(x).
x.isdm() Alias of dq.isdm(x).
x.isop() Alias of dq.isop(x).
x.isherm() Alias of dq.isherm(x).
x.toket() Alias of dq.toket(x).
x.tobra() Alias of dq.tobra(x).
x.todm() Alias of dq.todm(x).
x.proj() Alias of dq.proj(x).
x.reshape(*shape) Returns a reshaped copy of a qarray.
x.broadcast_to(*shape) Broadcasts a qarray to a new shape.
x.swapaxes(axis1, axis2) Interchanges two axes of a qarray.
x.moveaxis(source, destination) Moves axes of a qarray to new positions.
x.expand_dims(axis) Expands the shape of a qarray by inserting new axes.
x.where(condition, y) Alias of dq.where(condition, x, y).
x.addscalar(y) Adds a scalar.
x.elmul(y) Computes the element-wise multiplication.
x.elpow(power) Computes the element-wise power.

There are also several conversion methods available:

Method Description
x.to_qutip() Alias of dq.to_qutip(x, dims=x.dims).
x.to_jax() Alias of dq.to_jax(x).
x.to_numpy() Alias of dq.to_numpy(x).
x.asdense() Converts to a dense layout.
x.assparsedia() Converts to a sparse diagonal layout.

ndiags 

ndiags: int

Number of stored diagonals (only for sparse diagonal layout).

QArray.conj 

conj() -> QArray

Returns the element-wise complex conjugate of the qarray.

Returns:

  • New qarray with element-wise complex conjuguated values.

QArray.reshape 

reshape(*shape: int) -> QArray

Returns a reshaped copy of a qarray.

Parameters:

  • *shape –

    New shape, which must match the original size.

Returns:

  • New qarray with the given shape.

QArray.broadcast_to 

broadcast_to(*shape: int) -> QArray

Broadcasts a qarray to a new shape.

Parameters:

  • *shape –

    New shape, which must be compatible with the original shape.

Returns:

  • New qarray with the given shape.

QArray.swapaxes 

swapaxes(axis1: int, axis2: int) -> QArray

Interchange two axes of a qarray.

Parameters:

  • axis1 –

    First axis.

  • axis2 –

    Second axis.

Returns:

  • Qarray with axes axis1 and axis2 interchanged.

QArray.moveaxis 

moveaxis(source: int | Sequence[int], destination: int | Sequence[int]) -> QArray

Move axes of a qarray to new positions.

Parameters:

  • source –

    Original positions of the axes to move.

  • destination –

    Destination positions for each moved axis.

Returns:

  • Qarray with moved axes.

QArray.expand_dims 

expand_dims(axis: int | Sequence[int]) -> QArray

Expand the shape of a qarray by inserting new axes.

Parameters:

  • axis –

    Axis or axes where new dimensions are inserted.

Returns:

  • Qarray with additional dimensions.

QArray.where 

where(condition: ArrayLike, y: QArrayLike) -> QArray

Select values from this qarray or another operand depending on a condition.

Parameters:

  • condition –

    Boolean array-like condition.

  • y –

    Values selected when condition is false.

Returns:

  • Qarray with values chosen from self and y.

QArray.asdense 

asdense() -> QArray

Converts to a dense layout.

Returns:

  • A qarray with dense data layout.

QArray.assparsedia 

assparsedia(offsets: tuple[int, ...] | None = None) -> QArray

Converts to a sparse diagonal layout.

Parameters:

  • offsets –

    Offsets of the stored diagonals. If None, offsets are determined automatically from the matrix structure. This argument can also be explicitly specified to ensure compatibility with JAX transformations, which require static offset values.

Returns:

  • A qarray with sparse diagonal data layout.

QArray.addscalar 

addscalar(y: ArrayLike) -> QArray

Adds a scalar.

Parameters:

  • y –

    Scalar to add, whose shape should be broadcastable with the qarray.

Returns:

  • New qarray resulting from the addition with the scalar.

QArray.elmul 

elmul(y: QArrayLike) -> QArray

Computes the element-wise multiplication.

Parameters:

  • y –

    Qarray-like to multiply with element-wise.

Returns:

  • New qarray resulting from the element-wise multiplication.

QArray.elpow 

elpow(power: int) -> QArray

Computes the element-wise power.

Parameters:

  • power –

    Power to raise to.

Returns:

  • New qarray with elements raised to the specified power.

QArray.__getitem__ 

__getitem__(key: IndexType) -> QArray | Array

Get item from the qarray.

Note

If the indexing operation modifies the last two dimensions of the qarray, an array is returned instead of a qarray.

Parameters:

  • key –

    Indexing key, which can be an int, slice, array-like, ellipsis, None, or a tuple of these.

Returns:

  • New qarray or array resulting from the indexing operation.