cuquantum.densitymat.MultidiagonalOperator

class cuquantum.densitymat.MultidiagonalOperator(data, offsets, callback=None, copy=True)

Multidiagonal single-mode operator from data buffer, offsets and optional callback.

Parameters

• data – Data buffer for diagonal elements, of shape (mode_dimension, num_diagonals) and an optional batch dimension at the end.

• offsets – The diagonal offsets of length num_diagonals.

• callback – An inplace or out-of-place callback function that modifies CPU or GPU buffer.

Note

• data should be of shape (mode_dimension, num_diagonals) or (mode_dimension, num_diagonals, batch_size).

• The data layout is different from scipy.sparse.dia_matrix and cupyx.scipy.sparse.dia_matrix. In this class, the elements of the offsets[i]-th diagonal corresponds to the i-th column of the input data buffer read from the top of the column.

• If copy=True, a copy will be created on the data buffer and can be accessed through the data attribute. Note that if a np.ndarray is passed, it will be copied to GPU at a later stage.

• If copy=False, the provided data buffer is required to be a cp.ndarray and Fortran-contiguous.

• The current underlying data buffer is accessible via the data attribute. Modification of the underlying data buffer by the user will lead to undefined behaviour.

• If an out-of-place callback is provided, it needs to return an array needs that is consistent with the provided data buffer in terms of shape and data type.

• If an inplace callback is provided, it needs perform an inplace modification on an array that is provided as its third positional argument.

• The data buffer will be updated when this instance is involved in a compute method of an Operator or OperatorAction if a callback is passed.

Examples

>>> import numpy as np
>>> from cuquantum.densitymat import MultidiagonalOperator

Suppose we want to construct a creation operator on a Hilbert space of dimension 3 as a MultidiagonalOperator. It can be constructed from the data buffer and diagonal offsets as

>>> data = np.array([[1], [np.sqrt(2)], [0]]) # the last element doesn't matter
>>> offsets = [-1]
>>> dia_op = MultidiagonalOperator(data, offsets)

If we already have the elementary operator in scipy.sparse.dia_matrix format, e.g,

>>> dia_matrix = scipy.sparse.dia_matrix(...) # put your data here

We can create a MultidiagonalOperator with the following:

>>> offsets = list(dia_matrix.offsets)
>>> data = np.zeros((dia_matrix.shape[0], len(offsets)), dtype=dia_matrix.dtype)
>>> for i, offset in enumerate(offsets):
>>>    end = None if offset == 0 else -abs(offset)
>>>    data[:end, i] = dia_matrix.diagonal(offset)
>>> dia_op = MultidiagonalOperator(data, offsets)

Methods

__add__(other: Union[DenseOperator, MultidiagonalOperator]) → Union[DenseOperator, MultidiagonalOperator]

Add an elementary operator to this instance and return a new elementary operator of the same type as other.

__init__(data: Union[numpy.ndarray, cupy.ndarray], offsets: Sequence[int], callback: Callback | None = None, copy: bool = True) → None

Initialize a multidiagonal single-mode operator from data buffer, offsets and optional callback.

__matmul__(other: Union[DenseOperator, MultidiagonalOperator]) → Union[DenseOperator, MultidiagonalOperator]

Perform matrix multiplication between this instance and another elementary operator and return a new elementary operator of the same type as other.

__mul__(scalar: Union[numbers.Number, numpy.ndarray, cupy.ndarray]) → MultidiagonalOperator

Multiply this instance with a scalar on the left.

__rmul__(scalar: numbers.Number) → MultidiagonalOperator

Multiply this instance with a scalar on the right.

__sub__(other: Union[DenseOperator, MultidiagonalOperator]) → Union[DenseOperator, MultidiagonalOperator]

Subtract an elementary operator from this instance and return a new elementary operator of the same type as other.

dag() → MultidiagonalOperator

Return the conjugate complex transpose of this instance.

to_array(t: float | None = None, args: Optional[Union[numpy.ndarray, cupy.ndarray]] = None, device: str | int | None = None) → Union[numpy.ndarray, cupy.ndarray]

Return the array form of the multidiagonal elementary operator on the specified device.

If the device is not specified, an ElementaryOperator without callback will return a reference to its current underlying data, else the return location will be the return location of the Callback instance passed. This call is blocking if it involves device-to-host or device-to-device transfer, otherwise it is stream-ordered on the current stream.

Note

This function returns the dense array form of the multidiagonal elementary operator. If the original data buffer containing the diagonal elements is needed, use the data attribute if no callback was passed or invoke callback with arguments t and Beyond sys.argv.

to_dense() → DenseOperator

Return the DenseOperator form of the multidiagonal elementary operator.

Attributes

data

Data buffer of the elementary operator.

device_id

Return device ID if stored on GPU and None if stored on CPU.

has_gradient