Add stim.GateData.{inverse,generalized_inverse} (#674)

quantumlib · Nov 30, 2023 · 1985a2e · 1985a2e
1 parent 97a9cd6
commit 1985a2e
Show file tree

Hide file tree

Showing 5 changed files with 390 additions and 0 deletions.
diff --git a/doc/python_api_reference_vDev.md b/doc/python_api_reference_vDev.md
@@ -194,6 +194,8 @@ API references for stable versions are kept on the [stim github wiki](https://gi
     - [`stim.GateData.__repr__`](#stim.GateData.__repr__)
     - [`stim.GateData.__str__`](#stim.GateData.__str__)
     - [`stim.GateData.aliases`](#stim.GateData.aliases)
+    - [`stim.GateData.generalized_inverse`](#stim.GateData.generalized_inverse)
+    - [`stim.GateData.inverse`](#stim.GateData.inverse)
     - [`stim.GateData.is_noisy_gate`](#stim.GateData.is_noisy_gate)
     - [`stim.GateData.is_reset`](#stim.GateData.is_reset)
     - [`stim.GateData.is_single_qubit_gate`](#stim.GateData.is_single_qubit_gate)
@@ -6798,6 +6800,105 @@ def aliases(
     """
 ```
 
+<a name="stim.GateData.generalized_inverse"></a>
+```python
+# stim.GateData.generalized_inverse
+
+# (in class stim.GateData)
+@property
+def generalized_inverse(
+    self,
+) -> stim.GateData:
+    """The closest-thing-to-an-inverse for the gate, if forced to pick something.
+
+    The generalized inverse of a unitary gate U is its actual inverse U^-1.
+
+    The generalized inverse of a reset or measurement gate U is a gate V such that,
+    for every stabilizer flow that U has, V has the time reverse of that flow (up
+    to Pauli feedback, with potentially more flows). For example, the time-reverse
+    of R is MR because R has the single flow 1 -> Z and MR has the time reversed
+    flow Z -> rec[-1].
+
+    The generalized inverse of noise like X_ERROR is just the same noise.
+
+    The generalized inverse of an annotation like TICK is just the same annotation.
+
+    Examples:
+        >>> import stim
+
+        >>> stim.gate_data('H').generalized_inverse
+        stim.gate_data('H')
+
+        >>> stim.gate_data('CXSWAP').generalized_inverse
+        stim.gate_data('SWAPCX')
+
+        >>> stim.gate_data('X_ERROR').generalized_inverse
+        stim.gate_data('X_ERROR')
+
+        >>> stim.gate_data('MX').generalized_inverse
+        stim.gate_data('MX')
+
+        >>> stim.gate_data('MRY').generalized_inverse
+        stim.gate_data('MRY')
+
+        >>> stim.gate_data('R').generalized_inverse
+        stim.gate_data('MR')
+
+        >>> stim.gate_data('DETECTOR').generalized_inverse
+        stim.gate_data('DETECTOR')
+
+        >>> stim.gate_data('TICK').generalized_inverse
+        stim.gate_data('TICK')
+    """
+```
+
+<a name="stim.GateData.inverse"></a>
+```python
+# stim.GateData.inverse
+
+# (in class stim.GateData)
+@property
+def inverse(
+    self,
+) -> Optional[stim.GateData]:
+    """The inverse of the gate, or None if it has no inverse.
+
+    The inverse V of a gate U must have the property that V undoes the effects of U
+    and that U undoes the effects of V. In particular, the circuit
+
+        U 0 1
+        V 0 1
+
+    should be equivalent to doing nothing at all.
+
+    Examples:
+        >>> import stim
+
+        >>> stim.gate_data('H').inverse
+        stim.gate_data('H')
+
+        >>> stim.gate_data('CX').inverse
+        stim.gate_data('CX')
+
+        >>> stim.gate_data('S').inverse
+        stim.gate_data('S_DAG')
+
+        >>> stim.gate_data('CXSWAP').inverse
+        stim.gate_data('SWAPCX')
+
+        >>> stim.gate_data('X_ERROR').inverse is None
+        True
+        >>> stim.gate_data('M').inverse is None
+        True
+        >>> stim.gate_data('R').inverse is None
+        True
+        >>> stim.gate_data('DETECTOR').inverse is None
+        True
+        >>> stim.gate_data('TICK').inverse is None
+        True
+    """
+```
+
 <a name="stim.GateData.is_noisy_gate"></a>
 ```python
 # stim.GateData.is_noisy_gate

diff --git a/doc/stim.pyi b/doc/stim.pyi
@@ -5212,6 +5212,91 @@ class GateData:
             ['CNOT', 'CX', 'ZCX']
         """
     @property
+    def generalized_inverse(
+        self,
+    ) -> stim.GateData:
+        """The closest-thing-to-an-inverse for the gate, if forced to pick something.
+
+        The generalized inverse of a unitary gate U is its actual inverse U^-1.
+
+        The generalized inverse of a reset or measurement gate U is a gate V such that,
+        for every stabilizer flow that U has, V has the time reverse of that flow (up
+        to Pauli feedback, with potentially more flows). For example, the time-reverse
+        of R is MR because R has the single flow 1 -> Z and MR has the time reversed
+        flow Z -> rec[-1].
+
+        The generalized inverse of noise like X_ERROR is just the same noise.
+
+        The generalized inverse of an annotation like TICK is just the same annotation.
+
+        Examples:
+            >>> import stim
+
+            >>> stim.gate_data('H').generalized_inverse
+            stim.gate_data('H')
+
+            >>> stim.gate_data('CXSWAP').generalized_inverse
+            stim.gate_data('SWAPCX')
+
+            >>> stim.gate_data('X_ERROR').generalized_inverse
+            stim.gate_data('X_ERROR')
+
+            >>> stim.gate_data('MX').generalized_inverse
+            stim.gate_data('MX')
+
+            >>> stim.gate_data('MRY').generalized_inverse
+            stim.gate_data('MRY')
+
+            >>> stim.gate_data('R').generalized_inverse
+            stim.gate_data('MR')
+
+            >>> stim.gate_data('DETECTOR').generalized_inverse
+            stim.gate_data('DETECTOR')
+
+            >>> stim.gate_data('TICK').generalized_inverse
+            stim.gate_data('TICK')
+        """
+    @property
+    def inverse(
+        self,
+    ) -> Optional[stim.GateData]:
+        """The inverse of the gate, or None if it has no inverse.
+
+        The inverse V of a gate U must have the property that V undoes the effects of U
+        and that U undoes the effects of V. In particular, the circuit
+
+            U 0 1
+            V 0 1
+
+        should be equivalent to doing nothing at all.
+
+        Examples:
+            >>> import stim
+
+            >>> stim.gate_data('H').inverse
+            stim.gate_data('H')
+
+            >>> stim.gate_data('CX').inverse
+            stim.gate_data('CX')
+
+            >>> stim.gate_data('S').inverse
+            stim.gate_data('S_DAG')
+
+            >>> stim.gate_data('CXSWAP').inverse
+            stim.gate_data('SWAPCX')
+
+            >>> stim.gate_data('X_ERROR').inverse is None
+            True
+            >>> stim.gate_data('M').inverse is None
+            True
+            >>> stim.gate_data('R').inverse is None
+            True
+            >>> stim.gate_data('DETECTOR').inverse is None
+            True
+            >>> stim.gate_data('TICK').inverse is None
+            True
+        """
+    @property
     def is_noisy_gate(
         self,
     ) -> bool:

diff --git a/glue/python/src/stim/__init__.pyi b/glue/python/src/stim/__init__.pyi
@@ -5212,6 +5212,91 @@ class GateData:
             ['CNOT', 'CX', 'ZCX']
         """
     @property
+    def generalized_inverse(
+        self,
+    ) -> stim.GateData:
+        """The closest-thing-to-an-inverse for the gate, if forced to pick something.
+
+        The generalized inverse of a unitary gate U is its actual inverse U^-1.
+
+        The generalized inverse of a reset or measurement gate U is a gate V such that,
+        for every stabilizer flow that U has, V has the time reverse of that flow (up
+        to Pauli feedback, with potentially more flows). For example, the time-reverse
+        of R is MR because R has the single flow 1 -> Z and MR has the time reversed
+        flow Z -> rec[-1].
+
+        The generalized inverse of noise like X_ERROR is just the same noise.
+
+        The generalized inverse of an annotation like TICK is just the same annotation.
+
+        Examples:
+            >>> import stim
+
+            >>> stim.gate_data('H').generalized_inverse
+            stim.gate_data('H')
+
+            >>> stim.gate_data('CXSWAP').generalized_inverse
+            stim.gate_data('SWAPCX')
+
+            >>> stim.gate_data('X_ERROR').generalized_inverse
+            stim.gate_data('X_ERROR')
+
+            >>> stim.gate_data('MX').generalized_inverse
+            stim.gate_data('MX')
+
+            >>> stim.gate_data('MRY').generalized_inverse
+            stim.gate_data('MRY')
+
+            >>> stim.gate_data('R').generalized_inverse
+            stim.gate_data('MR')
+
+            >>> stim.gate_data('DETECTOR').generalized_inverse
+            stim.gate_data('DETECTOR')
+
+            >>> stim.gate_data('TICK').generalized_inverse
+            stim.gate_data('TICK')
+        """
+    @property
+    def inverse(
+        self,
+    ) -> Optional[stim.GateData]:
+        """The inverse of the gate, or None if it has no inverse.
+
+        The inverse V of a gate U must have the property that V undoes the effects of U
+        and that U undoes the effects of V. In particular, the circuit
+
+            U 0 1
+            V 0 1
+
+        should be equivalent to doing nothing at all.
+
+        Examples:
+            >>> import stim
+
+            >>> stim.gate_data('H').inverse
+            stim.gate_data('H')
+
+            >>> stim.gate_data('CX').inverse
+            stim.gate_data('CX')
+
+            >>> stim.gate_data('S').inverse
+            stim.gate_data('S_DAG')
+
+            >>> stim.gate_data('CXSWAP').inverse
+            stim.gate_data('SWAPCX')
+
+            >>> stim.gate_data('X_ERROR').inverse is None
+            True
+            >>> stim.gate_data('M').inverse is None
+            True
+            >>> stim.gate_data('R').inverse is None
+            True
+            >>> stim.gate_data('DETECTOR').inverse is None
+            True
+            >>> stim.gate_data('TICK').inverse is None
+            True
+        """
+    @property
     def is_noisy_gate(
         self,
     ) -> bool: