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

.. py:module:: cirq_superstaq.ops


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/cirq_superstaq/ops/qubit_gates/index
   /autoapi/cirq_superstaq/ops/qudit_gates/index


Attributes
----------

.. autoapisummary::

   cirq_superstaq.ops.AQTICCX
   cirq_superstaq.ops.AQTITOFFOLI
   cirq_superstaq.ops.AceCRMinusPlus
   cirq_superstaq.ops.AceCRPlusMinus
   cirq_superstaq.ops.BSWAP
   cirq_superstaq.ops.BSWAP_INV
   cirq_superstaq.ops.CR
   cirq_superstaq.ops.CZ3
   cirq_superstaq.ops.CZ3_INV
   cirq_superstaq.ops.DD
   cirq_superstaq.ops.QutritZ0
   cirq_superstaq.ops.QutritZ1
   cirq_superstaq.ops.QutritZ2
   cirq_superstaq.ops.SWAP3
   cirq_superstaq.ops.ZX


Classes
-------

.. autoapisummary::

   cirq_superstaq.ops.AceCR
   cirq_superstaq.ops.BSwapPowGate
   cirq_superstaq.ops.Barrier
   cirq_superstaq.ops.DDPowGate
   cirq_superstaq.ops.ParallelGates
   cirq_superstaq.ops.ParallelRGate
   cirq_superstaq.ops.QubitSubspaceGate
   cirq_superstaq.ops.QuditSwapGate
   cirq_superstaq.ops.QutritCZPowGate
   cirq_superstaq.ops.QutritZ0PowGate
   cirq_superstaq.ops.QutritZ1PowGate
   cirq_superstaq.ops.QutritZ2PowGate
   cirq_superstaq.ops.RGate
   cirq_superstaq.ops.StrippedCZGate
   cirq_superstaq.ops.VirtualZPowGate
   cirq_superstaq.ops.ZXPowGate
   cirq_superstaq.ops.ZZSwapGate


Functions
---------

.. autoapisummary::

   cirq_superstaq.ops.approx_eq_mod
   cirq_superstaq.ops.barrier
   cirq_superstaq.ops.parallel_gates_operation
   cirq_superstaq.ops.qubit_subspace_op
   cirq_superstaq.ops.qudit_swap_op


Package Contents
----------------

.. py:class:: AceCR(rads: str | cirq.TParamVal = np.pi / 2, sandwich_rx_rads: cirq.TParamVal = 0)

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


   Active Cancellation Echoed Cross Resonance (AceCR) gate, parametrized (e.g., supporting
   polarity switches) and supporting sandwiches.

   The typical AceCR in literature is a positive half-CR, then X on "Z side", then negative
   half-CR ("Z side" and "X side" refer to the two sides of the underlying ZX interactions).


   .. py:attribute:: rads


   .. py:attribute:: sandwich_rx_rads
      :value: 0



.. 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:: Barrier(num_qubits: Optional[int] = None, qid_shape: Optional[Tuple[int, Ellipsis]] = None)

   Bases: :py:obj:`cirq.ops.IdentityGate`, :py:obj:`cirq.InterchangeableQubitsGate`


   A temporal boundary restricting circuit compilation and pulse scheduling.

   Otherwise equivalent to the identity gate.


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

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


   The Dipole-Dipole gate for EeroQ hardware.


.. py:class:: ParallelGates(*component_gates: cirq.Gate)

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


   A single gate combining a collection of concurrent gate(s) acting on different qubits.


   .. py:method:: qubit_index_to_equivalence_group_key(index: int) -> int

      Returns a key that differs between qubits.

      Does it by different component gates and non-interchangeable qubits in the same component
      gate.

      :param index: The qubit index.

      :returns: Equivalence group key.



   .. py:method:: qubit_index_to_gate_and_index(index: int) -> tuple[cirq.Gate, int]

      Gets gate (and index) for the corresponding index.

      :param index: The index into a particular member of the `ParallelGates` operation.

      :returns: A tuple of the gate at the given index and the index itself.

      :raises ValueError: If index is outside bounds of gate index range.



   .. py:attribute:: component_gates
      :type:  tuple[cirq.Gate, Ellipsis]
      :value: ()



.. py:class:: ParallelRGate(theta: cirq.TParamVal, phi: cirq.TParamVal, num_copies: int)

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


   Wrapper class to define a ParallelGate of identical RGate gates.


   .. py:property:: exponent
      :type: cirq.TParamVal


      The `exponent` property of `ParallelRGate`.

      :returns: The sub gate exponent.


   .. py:property:: phase_exponent
      :type: cirq.TParamVal


      The `phase_exponent` property of each `RGate`.

      :returns: The phase exponent.


   .. py:property:: phi
      :type: cirq.TParamVal


      The `phi` property of `ParallelRGate`, defining orientation (i.e., axis of rotation).

      :returns: The rotation-axis angle phi.


   .. py:property:: sub_gate
      :type: RGate


      The gate that is applied to the specified subspace.

      :returns: The underlying gate used.


   .. py:property:: theta
      :type: cirq.TParamVal


      The `theta` property of `ParallelRGate`, angle to rotate about the phi-determined axis.

      :returns: The rotation angle theta.


.. 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`


   Generalized CZ gate for pairs of equal-dimension qudits.

   It is defined by the following 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:: RGate(theta: cirq.TParamVal, phi: cirq.TParamVal)

   Bases: :py:obj:`cirq.PhasedXPowGate`


   A single-qubit gate that rotates about an axis in the `X`-`Y` plane.


   .. py:property:: phi
      :type: cirq.TParamVal


      Angle (in radians) defining the axis of rotation in the `X`-`Y` plane.

      :returns: The phi rotation angle.


   .. py:property:: theta
      :type: cirq.TParamVal


      Angle (in radians) by which to rotate about the axis given by `self.phi`.

      :returns: The theta rotation angle.


.. py:class:: StrippedCZGate(rz_rads: cirq.TParamVal = 0)

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


   The Stripped CZ gate is a regular CZ gate when the rz angle = 0.

   It is the gate that is actually being performed by Sqale, and it is corrected
   into a CZ gate by RZ gates afterwards if the rz angle is nonzero.


   .. py:property:: rz_rads
      :type: cirq.TParamVal


      The RZ-rotation angle in radians for the gate.

      :returns: The angle for the RZ rotation.


.. 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:class:: ZXPowGate(*, exponent: cirq.value.TParamVal = 1.0, global_shift: float = 0.0)

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


   The ZX-parity gate, possibly raised to a power.

   Per arxiv.org/pdf/1904.06560v3 eq. 135, the ZX**t gate implements the following unitary:

   .. math::

       e^{-\frac{i\pi}{2} t Z \otimes X} = \begin{bmatrix}
                                       c & -s & . & . \\
                                       -s & c & . & . \\
                                       . & . & c & s \\
                                       . & . & s & c \\
                                       \end{bmatrix}

   where '.' means '0' and :math:`c = \cos(\frac{\pi t}{2})`
   and :math:`s = i \sin(\frac{\pi t}{2})`.



.. py:class:: ZZSwapGate(theta: cirq.TParamVal)

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


   The ZZ-SWAP gate, which performs the ZZ-interaction followed by a SWAP.

   ZZ-SWAPs are useful for applications like QAOA or Hamiltonian Simulation,
   particularly on linear- or low- connectivity devices. See https://arxiv.org/pdf/2004.14970.pdf
   for an application of ZZ SWAP networks.

   The unitary for a ZZ-SWAP gate parametrized by ZZ-interaction angle :math:`\theta` is:

    .. math::

       \begin{bmatrix}
       1 & . & . & . \\
       . & . & e^{i \theta} & . \\
       . & e^{i \theta} & . & . \\
       . & . & . & 1 \\
       \end{bmatrix}

   where '.' means '0'.
   For :math:`\theta = 0`, the ZZ-SWAP gate is just an ordinary SWAP.


   .. py:attribute:: theta


.. py:function:: approx_eq_mod(a: cirq.TParamVal, b: cirq.TParamVal, period: float, atol: float = 1e-08) -> bool

   Check if a ~= b (mod period). If either input is an unresolved parameter, returns a == b.

   :param a: A Cirq parameter value.
   :param b: A Cirq parameter value.
   :param period: The parameter period (i.e., cycle time).
   :param atol: The absolute tolerance for equality checking.

   :returns: A boolean indicating whether input parameters are approximately equal.


.. py:function:: barrier(*qubits: cirq.Qid) -> cirq.Operation

   Equivalent to https://qiskit.org/documentation/stubs/qiskit.circuit.library.Barrier.html.

   :param qubits: The qubits that the barrier will cover.

   :returns: A barrier `cirq.Operation` on the provided qubits.


.. py:function:: parallel_gates_operation(*ops: cirq.Operation) -> cirq.Operation

   Constructs a parallel gates operation.

   Given operations acting on disjoint qubits, constructs a single `cirq_superstaq.ParallelGates` instance
   and applies it such that each operation's `.gate` is applied to its `.qubits`.

   :param ops: Operations to pack into a single `ParallelGates` operation.

   :returns: `ParallelGates(op.gate, op2.gate, ...).on(*op.qubits, *op2.qubits, ...)`

   :raises ValueError: If the operation has no `.gate` attribute.
   :raises ValueError: If the operation has tags.


.. 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:: AQTICCX

.. py:data:: AQTITOFFOLI

.. py:data:: AceCRMinusPlus

.. py:data:: AceCRPlusMinus

.. py:data:: BSWAP

.. py:data:: BSWAP_INV

.. py:data:: CR

.. py:data:: CZ3

.. py:data:: CZ3_INV

.. py:data:: DD

.. py:data:: QutritZ0

.. py:data:: QutritZ1

.. py:data:: QutritZ2

.. py:data:: SWAP3

.. py:data:: ZX