cirq.protocols.SupportsConsistentApplyUnitary

An object that can be efficiently left-multiplied into tensors.

cirq.protocols.SupportsConsistentApplyUnitary(
    *args, **kwargs
)

Methods

_apply_unitary_

View source

_apply_unitary_(
    args: cirq.protocols.ApplyUnitaryArgs
) -> Union[np.ndarray, None, NotImplementedType]

Left-multiplies a unitary effect onto a tensor with good performance.

This method is given both the target tensor and workspace of the same shape and dtype. The method then either performs inline modifications of the target tensor and returns it, or writes its output into the workspace tensor and returns that. This signature makes it possible to write specialized simulation methods that run without performing large allocations, significantly increasing simulation performance.

The target may represent a wave function, a unitary matrix, or some other tensor. Implementations will work in all of these cases as long as they correctly focus on only operating on the given axes.

Args
args A cirq.ApplyUnitaryArgs object with the args.target_tensor to operate on, an args.available_workspace buffer to use as temporary workspace, and the args.axes of the tensor to target with the unitary operation. Note that this method is permitted (and in fact expected) to mutate args.target_tensor and args.available_workspace.

Returns
If the receiving object is not able to apply its unitary effect, None or NotImplemented should be returned.

If the receiving object is able to work inline, it should directly mutate args.target_tensor and then return args.target_tensor. The caller will understand this to mean that the result is in args.target_tensor.

If the receiving object is unable to work inline, it can write its output over args.available_buffer and then return args.available_buffer. The caller will understand this to mean that the result is in args.available_buffer (and so what was args.available_buffer will become args.target_tensor in the next call, and vice versa).

The receiving object is also permitted to allocate a new numpy.ndarray and return that as its result.