ionq_core.gates

  1# SPDX-FileCopyrightText: 2026 IonQ, Inc.
  2# SPDX-License-Identifier: Apache-2.0
  3
  4"""Pure-Python unitary matrices for IonQ native trapped-ion gates.
  5
  6All functions return nested tuples of complex numbers (no NumPy dependency).
  7
  8**Parameter conventions:**
  9
 10- Phase parameters (``phi``, ``phi0``, ``phi1``) are in **turns** -
 11  fractions of 2*pi. So ``phi=0.25`` means pi/2 radians.
 12- Interaction parameters (``angle``) are in **units of pi**. So
 13  ``angle=0.25`` means pi/4 radians.
 14
 15**Type aliases:**
 16
 17- `Matrix2x2` - ``tuple[tuple[complex, complex], tuple[complex, complex]]``
 18- `Matrix4x4` - 4x4 nested tuple of complex numbers
 19
 20Example:
 21    ```python
 22    from ionq_core import gpi_matrix, gpi2_matrix, ms_matrix, zz_matrix
 23
 24    gpi_matrix(0)  # Pauli X gate
 25    gpi2_matrix(0.25)  # pi/2 rotation about Y axis
 26    ms_matrix(0, 0)  # maximally-entangling MS gate
 27    zz_matrix(0.1)  # ZZ interaction
 28    ```
 29"""
 30
 31__all__ = ["gpi2_matrix", "gpi_matrix", "ms_matrix", "zz_matrix"]
 32
 33import cmath
 34import math
 35
 36Matrix2x2 = tuple[tuple[complex, complex], tuple[complex, complex]]
 37"""Type alias for a 2x2 unitary matrix (single-qubit gate)."""
 38
 39Matrix4x4 = tuple[
 40    tuple[complex, complex, complex, complex],
 41    tuple[complex, complex, complex, complex],
 42    tuple[complex, complex, complex, complex],
 43    tuple[complex, complex, complex, complex],
 44]
 45"""Type alias for a 4x4 unitary matrix (two-qubit gate)."""
 46
 47_2PI = 2 * math.pi
 48
 49
 50def gpi_matrix(phi: float) -> Matrix2x2:
 51    r"""Single-qubit GPI gate.
 52
 53    Matrix form: ``[[0, e^{-i*2*pi*phi}], [e^{i*2*pi*phi}, 0]]``
 54
 55    At ``phi=0`` this is the Pauli X gate.
 56
 57    Args:
 58        phi: Phase angle in turns (fractions of 2*pi).
 59
 60    Returns:
 61        A `Matrix2x2` unitary matrix.
 62
 63    Examples:
 64        ```python
 65        >>> gpi_matrix(0)       # Pauli X
 66        ((0, (1+0j)), ((1+0j), 0))
 67        ```
 68    """
 69    e = cmath.exp(1j * _2PI * phi)
 70    return ((0, 1 / e), (e, 0))
 71
 72
 73def gpi2_matrix(phi: float) -> Matrix2x2:
 74    """Single-qubit GPI2 gate (pi/2 rotation about an axis in the XY plane).
 75
 76    Args:
 77        phi: Phase angle in turns (fractions of 2*pi) defining the
 78            rotation axis in the XY plane.
 79
 80    Returns:
 81        A `Matrix2x2` unitary matrix.
 82    """
 83    e = cmath.exp(1j * _2PI * phi)
 84    s = 1 / math.sqrt(2)
 85    return ((s, -1j * s / e), (-1j * s * e, s))
 86
 87
 88def ms_matrix(phi0: float, phi1: float, angle: float = 0.25) -> Matrix4x4:
 89    """Two-qubit Molmer-Sorensen (MS) gate.
 90
 91    The default ``angle=0.25`` produces a maximally-entangling gate.
 92
 93    Args:
 94        phi0: Frame rotation phase for qubit 0 in turns.
 95        phi1: Frame rotation phase for qubit 1 in turns.
 96        angle: Interaction angle in units of pi. Defaults to 0.25
 97            (i.e. pi/4 radians).
 98
 99    Returns:
100        A `Matrix4x4` unitary matrix.
101
102    Examples:
103        ```python
104        >>> ms_matrix(0, 0)         # maximally-entangling MS gate
105        >>> ms_matrix(0, 0, 0.125)  # partial entanglement
106        ```
107    """
108    a = math.pi * angle
109    ca, sa = math.cos(a), math.sin(a)
110    ep = cmath.exp(1j * _2PI * (phi0 + phi1))
111    em = cmath.exp(1j * _2PI * (phi0 - phi1))
112    return (
113        (ca, 0, 0, -1j * sa / ep),
114        (0, ca, -1j * sa / em, 0),
115        (0, -1j * sa * em, ca, 0),
116        (-1j * sa * ep, 0, 0, ca),
117    )
118
119
120def zz_matrix(angle: float) -> Matrix4x4:
121    """Two-qubit ZZ interaction gate.
122
123    Diagonal matrix: ``diag(e^{-i*pi*a}, e^{i*pi*a}, e^{i*pi*a}, e^{-i*pi*a})``
124
125    At ``angle=0`` this is the identity gate.
126
127    Args:
128        angle: Interaction angle in units of pi.
129
130    Returns:
131        A `Matrix4x4` unitary matrix.
132    """
133    em = cmath.exp(-1j * math.pi * angle)
134    ep = cmath.exp(1j * math.pi * angle)
135    return (
136        (em, 0, 0, 0),
137        (0, ep, 0, 0),
138        (0, 0, ep, 0),
139        (0, 0, 0, em),
140    )