cirq.apply_unitary(unitary_value: Any, args: cirq.protocols.apply_unitary.ApplyUnitaryArgs, default: TDefault = array([], dtype=float64)) → Union[numpy.ndarray, TDefault][source]

High performance left-multiplication of a unitary effect onto a tensor.

If unitary_value defines an _apply_unitary_ method, that method will be
used to apply unitary_value’s unitary effect to the target tensor.
Otherwise, if unitary_value defines a _unitary_ method, its unitary
matrix will be retrieved and applied using a generic method. Otherwise the
application fails, and either an exception is raised or the specified
default value is returned.
  • unitary_value – The value with a unitary effect to apply to the target.
  • args – A mutable cirq.ApplyUnitaryArgs object describing the target tensor, available workspace, and axes to operate on. The attributes of this object will be mutated as part of computing the result.
  • default – What should be returned if unitary_value doesn’t have a unitary effect. If not specified, a TypeError is raised instead of returning a default value.

If the receiving object is not able to apply its unitary effect, the specified default value is returned (or a TypeError is raised). If this occurs, then target_tensor should not have been mutated.

If the receiving object was able to work inline, directly mutating target_tensor it will return target_tensor. The caller is responsible for checking if the result is target_tensor.

If the receiving object wrote its output over available_buffer, the result will be available_buffer. The caller is responsible for checking if the result is available_buffer (and e.g. swapping the buffer for the target tensor before the next call).

The receiving object may also write its output over a new buffer that it created, in which case that new array is returned.


TypeErrorunitary_value doesn’t have a unitary effect and default wasn’t specified.