cirq_superstaq.ops.qudit_gates
==============================

.. py:module:: cirq_superstaq.ops.qudit_gates


Attributes
----------

.. autoapisummary::

   cirq_superstaq.ops.qudit_gates.BSWAP
   cirq_superstaq.ops.qudit_gates.BSWAP_INV
   cirq_superstaq.ops.qudit_gates.CZ3
   cirq_superstaq.ops.qudit_gates.CZ3_INV
   cirq_superstaq.ops.qudit_gates.QutritZ0
   cirq_superstaq.ops.qudit_gates.QutritZ1
   cirq_superstaq.ops.qudit_gates.QutritZ2
   cirq_superstaq.ops.qudit_gates.SWAP3


Classes
-------

.. autoapisummary::

   cirq_superstaq.ops.qudit_gates.BSwapPowGate
   cirq_superstaq.ops.qudit_gates.QubitSubspaceGate
   cirq_superstaq.ops.qudit_gates.QuditSwapGate
   cirq_superstaq.ops.qudit_gates.QutritCZPowGate
   cirq_superstaq.ops.qudit_gates.QutritZ0PowGate
   cirq_superstaq.ops.qudit_gates.QutritZ1PowGate
   cirq_superstaq.ops.qudit_gates.QutritZ2PowGate
   cirq_superstaq.ops.qudit_gates.VirtualZPowGate


Functions
---------

.. autoapisummary::

   cirq_superstaq.ops.qudit_gates.custom_resolver
   cirq_superstaq.ops.qudit_gates.qubit_subspace_op
   cirq_superstaq.ops.qudit_gates.qudit_swap_op


Module Contents
---------------

.. py:class:: BSwapPowGate(*, exponent: cirq.value.TParamVal = 1.0, global_shift: float = 0.0)

   Bases: :py:obj:`cirq.EigenGate`, :py:obj:`cirq.InterchangeableQubitsGate`


   iSWAP-like qutrit entangling gate swapping the "11" and "22" states of two qutrits.


   .. py:property:: dimension
      :type: int


      Indicates that this gate acts on qutrits.

      :returns: The integer `3`, representing the qudit dimension for qutrits.


.. py:class:: QubitSubspaceGate(sub_gate: cirq.Gate, qid_shape: collections.abc.Sequence[int], subspaces: collections.abc.Sequence[tuple[int, int]] | None = None)

   Bases: :py:obj:`cirq.Gate`


   Embeds an n-qubit (i.e. SU(2^n)) gate into a given subspace of a higher-dimensional gate.


   .. py:property:: qid_shape
      :type: tuple[int, Ellipsis]


      Specifies the qudit dimension for each of the inputs.

      :returns: The dimensions for the input qudits.


   .. py:property:: sub_gate
      :type: cirq.Gate


      The gate that is applied to the specified subspace.

      :returns: The underlying gate used.


   .. py:property:: subspaces
      :type: list[tuple[int, int]]


      A list of subspace indices acted upon.

      For instance, a CX on the 0-1 qubit subspace of two qudits would have subspaces of
      [(0, 1), (0, 1)]. The same gate acting on the 1-2 subspaces of both qudits would correspond
      to [(1, 2), (1, 2)].

      :returns: A list of dimensions tuples, specified for each subspace.


.. py:class:: QuditSwapGate(dimension: int)

   Bases: :py:obj:`cirq.Gate`, :py:obj:`cirq.InterchangeableQubitsGate`


   A (non-parametrized) SWAP gate on two qudits of arbitrary dimension.


   .. py:property:: dimension
      :type: int


      The qudit dimension on which this SWAP gate will act.

      :returns: The qudit dimension.


.. py:class:: QutritCZPowGate(*, exponent: cirq.value.TParamVal = 1.0, global_shift: float = 0.0)

   Bases: :py:obj:`cirq.EigenGate`, :py:obj:`cirq.InterchangeableQubitsGate`


   For pairs of equal-dimension qudits, the generalized CZ gate is defined by the unitary:

       U = Σ_(i<d,j<d) ω**ij.|i⟩⟨i|.|j⟩⟨j|,

   where d is the dimension of the qudits and ω = exp(2πi/d).

   Currently written for qutrits (d = 3), but its implementation should work for any dimension.


   .. py:property:: dimension
      :type: int


      Indicates that this gate acts on qutrits.

      :returns: The integer `3`, representing the qudit dimension for qutrits.


.. py:class:: QutritZ0PowGate(*, exponent: cirq.value.TParamVal = 1.0, global_shift: float = 0.0)

   Bases: :py:obj:`_QutritZPowGate`


   Phase rotation on the ground state of a qutrit.


.. py:class:: QutritZ1PowGate(*, exponent: cirq.value.TParamVal = 1.0, global_shift: float = 0.0)

   Bases: :py:obj:`_QutritZPowGate`


   Phase rotation on the first excited state of a qutrit.


.. py:class:: QutritZ2PowGate(*, exponent: cirq.value.TParamVal = 1.0, global_shift: float = 0.0)

   Bases: :py:obj:`_QutritZPowGate`


   Phase rotation on the second excited state of a qutrit.


.. py:class:: VirtualZPowGate(dimension: int = 2, level: int = 1, exponent: cirq.TParamVal = 1.0, global_shift: float = 0.0)

   Bases: :py:obj:`cirq.EigenGate`


   Applies a phase rotation between two successive energy levels of a qudit.


   .. py:property:: dimension
      :type: int


      The qudit dimension on which this gate acts.

      :returns: The gate's dimension.


   .. py:property:: level
      :type: int


      The lowest energy level onto which this gate applies a phase; for example if `level=2`
      a phase of `(-1)**exponent` will be applied to energy levels `[2, ..., dimension - 1]`. This
      is equivalent to phase shifting all subsequent single-qudit gates acting in the `(1, 2)`
      subspace (assuming all other gates commute with this one).

      :returns: The lowest energy level onto which this gate applies a phase.


.. py:function:: custom_resolver(cirq_type: str) -> type[cirq.Gate] | None

   Tells `cirq.json` how to deserialize cirq_superstaq's custom gates.

   Changes to gate names in this file should be reflected in this resolver.
   See quantumai.google/cirq/dev/serialization for more information about (de)serialization.

   :param cirq_type: The string of the gate type for the serializer to resolve.

   :returns: The resolved Cirq Gate matching the input, or None if no match.


.. py:function:: qubit_subspace_op(sub_op: cirq.Operation, qid_shape: collections.abc.Sequence[int], subspaces: collections.abc.Sequence[tuple[int, int]] | None = None) -> cirq.Operation

   Embeds a qubit Operation into a given subspace of a higher-dimensional Operation.

   Uses `QubitSubspaceGate`.

   :param sub_op: The `cirq.Operation` to embed.
   :param qid_shape: The dimensions of the subspace.
   :param subspaces: The list of all subspaces.

   :returns: A `cirq.Operation` embedding a low-dimensional operation.

   :raises ValueError: If there is no gate specified for the subspace operation.


.. py:function:: qudit_swap_op(qudit0: cirq.Qid, qudit1: cirq.Qid) -> cirq.Operation

   Construct a SWAP gate and apply it to the provided qudits.

   If both qudits have dimension 2, uses `cirq.SWAP`; otherwise uses `QuditSwapGate`.

   :param qudit0: The first qudit to swap.
   :param qudit1: The second qudit to swap.

   :returns: A SWAP gate acting on the provided qudits.

   :raises ValueError: If the input qudits don't have the same dimension.


.. py:data:: BSWAP

.. py:data:: BSWAP_INV

.. py:data:: CZ3

.. py:data:: CZ3_INV

.. py:data:: QutritZ0

.. py:data:: QutritZ1

.. py:data:: QutritZ2

.. py:data:: SWAP3