cirq.ApplyUnitaryArgs

Arguments for performing an efficient left-multiplication by a unitary.

cirq.ApplyUnitaryArgs(
    target_tensor: np.ndarray,
    available_buffer: np.ndarray,
    axes: Iterable[int],
    subspaces: Optional[Sequence[Tuple[int, ...]]] = None
)

The receiving object is expected to mutate target_tensor so that it contains the state after multiplication, and then return target_tensor. Alternatively, if workspace is required, the receiving object can overwrite available_buffer with the results and return available_buffer. Or, if the receiving object is attempting to be simple instead of fast, it can create an entirely new array and return that.

target_tensor The input tensor that needs to be left-multiplied by the unitary effect of the receiving object. The tensor will have the shape (2, 2, 2, ..., 2). It usually corresponds to a multi-qubit superposition, but it could also be a multi-qubit unitary transformation or some other concept.
available_buffer Pre-allocated workspace with the same shape and dtype as the target tensor.
axes Which axes the unitary effect is being applied to (e.g. the qubits that the gate is operating on).
subspaces Which subspace (in the computational basis) the unitary effect is being applied to, on each axis. By default it applies to subspace 0..d-1 on each axis, where d is the dimension of the unitary effect on that axis. Subspaces on each axis must be representable as a slice, so the dimensions specified here need to have a consistent step size.

ValueError If the subspace count does not equal the axis count, if any subspace has zero dimensions, or if any subspace has dimensions specified without a consistent step size.

target_tensor The input tensor that needs to be left-multiplied by the unitary effect of the receiving object. The tensor will have the shape (2, 2, 2, ..., 2). It usually corresponds to a multi-qubit superposition, but it could also be a multi-qubit unitary transformation or some other concept.
available_buffer Pre-allocated workspace with the same shape and dtype as the target tensor.
axes Which axes the unitary effect is being applied to (e.g. the qubits that the gate is operating on).
subspaces Which subspace (in the computational basis) the unitary effect is being applied to, on each axis. By default it applies to subspace 0..d-1 on each axis, where d is the dimension of the unitary effect on that axis. Subspaces on each axis must be representable as a slice, so the dimensions specified here need to have a consistent step size.

Methods

default

View source

@staticmethod
default(
    num_qubits: Optional[int] = None,
    *,
    qid_shape: Optional[Tuple[int, ...]] = None
) -> 'ApplyUnitaryArgs'

A default instance starting in state |0⟩.

Specify exactly one argument.

Args
num_qubits The number of qubits to make space for in the state.
qid_shape The shape of the state, specifying the dimension of each qid.

Raises
TypeError If exactly neither num_qubits or qid_shape is provided or both are provided.

for_unitary

View source

@classmethod
for_unitary(
    num_qubits: Optional[int] = None,
    *,
    qid_shape: Optional[Tuple[int, ...]] = None
) -> 'ApplyUnitaryArgs'

A default instance corresponding to an identity matrix.

Specify exactly one argument.

Args
num_qubits The number of qubits to make space for in the state.
qid_shape A tuple representing the number of quantum levels of each qubit the identity matrix applies to. qid_shape is (2, 2, 2) for a three-qubit identity operation tensor.

Raises
TypeError If exactly neither num_qubits or qid_shape is provided or both are provided.

subspace_index

View source

subspace_index(
    little_endian_bits_int: int = 0, *, big_endian_bits_int: int = 0
) -> Tuple[Union[slice, int, 'ellipsis'], ...]

An index for the subspace where the target axes equal a value.

Args
little_endian_bits_int The desired value of the qubits at the targeted axes, packed into an integer. The least significant bit of the integer is the desired bit for the first axis, and so forth in increasing order. Can't be specified at the same time as big_endian_bits_int.
big_endian_bits_int The desired value of the qubits at the targeted axes, packed into an integer. The most significant bit of the integer is the desired bit for the first axis, and so forth in decreasing order. Can't be specified at the same time as little_endian_bits_int.

Returns
A value that can be used to index into target_tensor and available_buffer, and manipulate only the part of Hilbert space corresponding to a given bit assignment.

Example
If target_tensor is a 4 qubit tensor and axes is [1, 3] and then this method will return the following when given little_endian_bits=0b01:

`(slice(None), 0, slice(None), 1, Ellipsis)`

Therefore the following two lines would be equivalent:

args.target_tensor[args.subspace_index(0b01)] += 1

args.target_tensor[:, 0, :, 1] += 1

with_axes_transposed_to_start

View source

with_axes_transposed_to_start() -> 'ApplyUnitaryArgs'

Returns a transposed view of the same arguments.

Returns
A view over the same target tensor and available workspace, but with the numpy arrays transposed such that the axes field is guaranteed to equal range(len(result.axes)). This allows one to say e.g. result.target_tensor[0, 1, 0, ...] instead of result.target_tensor[result.subspace_index(0b010)].