[open-systems] More classical data types (#1717)

Some ideas on how to handle the fact that for a given _encoding_ we
usually want both a quantum data type and classical data type. For
example, QInt and CInt both encode mathematical integers into bits or
qubits in the same way but in a circuit we want to distinguish between a
quantum integer and a classical integer.

 - Introduce `BitEncoding` abstract base class
 - Each data type "has a" `BitEncoding`
 - Shimming for backwards compatibility
 - Pretty easy to make data types based purely on composition

I think it's important to have distinct objects for common quantum and
classical data types e.g. QBit CBit QInt CInt. Maybe it's annoying to
always have to define two classes for each BitEncoding (the quantum and
classical one). You could use something like the `ClassicalVersion`
meta-data-type in this PR. I'm worried that: right now data type
compatibility is `dt1 == dt2` but if we have `ClassicalVersion(QInt)`
representing the same thing as `CInt` it gets complicated. Generally,
I'd prioritize making the end user (quantum programmer)'s life easier
with top-level quantum and classical versions of everything at the
expense of the "developer" (introducer of new quantum data types) having
to do some boilerplate.

Author: mpharrigan

qualtran/DataTypes.ipynb

@@ -283,49 +283,105 @@
    "source": [
     "## `QDType`, `CDType`, and `QCDType`\n",
     "\n",
-    "Quantum variables are essential when authoring quantum programs, but we live in a classical world. Measuring a qubit yields a classical bit, and a program can do classical branching (choosing which quantum operations to execute based on a classical bit). Each data type we've seen so far is a quantum data type and inherits from `QDType`. "
+    "Quantum variables are essential when authoring quantum programs, but we live in a classical world. Measuring a qubit yields a classical bit, and a program can do classical branching (choosing which quantum operations to execute based on a classical bit). Each data type we've seen so far is a quantum data type and inherits from `QDType`. There is a more general base class: `QCDType` that includes both quantum and classical data types. Classical data types inherit from `CDType`"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "06c5c158-555b-48cd-b612-e00d03b82f70",
+   "id": "25191c43-18d1-49fd-9a76-363cc3b7548c",
    "metadata": {},
    "outputs": [],
    "source": [
-    "from qualtran import QDType\n",
-    "\n",
-    "print(\"QBit()   is QDType:\", isinstance(QBit(), QDType),   \"; num_qubits =\", QBit().num_qubits)\n",
-    "print(\"QUInt(4) is QDType:\", isinstance(QUInt(4), QDType), \"; num_qubits =\", QUInt(4).num_qubits)"
+    "# Make a list of all the built-in data types\n",
+    "import qualtran.dtype as qdt\n",
+    "\n",
+    "dtypes = [\n",
+    "    qdt.QBit(), qdt.CBit(),\n",
+    "    qdt.QAny(8),\n",
+    "    qdt.QInt(8), qdt.CInt(8),\n",
+    "    qdt.QIntOnesComp(8), qdt.CIntOnesComp(8),\n",
+    "    qdt.QUInt(8), qdt.CUInt(8),\n",
+    "    qdt.BQUInt(8, 230), qdt.BCUInt(8, 230),\n",
+    "    qdt.QFxp(8, 2), qdt.CFxp(8, 2),\n",
+    "    qdt.QMontgomeryUInt(8, 227), qdt.CMontgomeryUInt(8, 227),\n",
+    "    qdt.QGF(3, 4), qdt.CGF(3, 4),\n",
+    "    qdt.QGFPoly(4, qdt.QGF(2,2)), qdt.CGFPoly(4, qdt.CGF(2,2)),\n",
+    "]"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "c434a68e-b691-4a35-bc81-49b7159728f8",
+   "id": "701ebb85-8e44-4456-95da-ef2ead979c5f",
    "metadata": {},
    "source": [
-    "There is a more general base class: `QCDType` that includes both quantum and classical data types. Classical data types inherit from `CDType`"
+    "### Table of data type properties"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "c983e4cb-ac84-497b-883f-3a71abf6878f",
+   "id": "7c38eb9b-60d5-4d0c-b282-19f2638bc483",
    "metadata": {},
    "outputs": [],
    "source": [
-    "from qualtran import QCDType, QDType, CDType, CBit\n",
-    "\n",
-    "dtypes = [QBit(), QUInt(4), CBit()]\n",
-    "\n",
-    "print(f\"{'dtype':10} {'QCDType?':9s} {'QDType?':9s} {'CDType?':9s}\"\n",
-    "      f\"{'bits':>6s} {'qubits':>6s} {'cbits':>6s}\"\n",
-    "     )\n",
+    "print(f\"{'dtype':23} {'QCDType?':9s} \"\n",
+    "      f\"{'QDType?':9s} {'CDType?':9s} \"\n",
+    "      f\"{'bits':>6s} {'qubits':>6s} {'cbits':>6s}\")\n",
+    "print(\"-\"*80)\n",
+    "for dtype in dtypes:\n",
+    "    print(f\"{dtype!s:23} {isinstance(dtype, qdt.QCDType)!s:9} \"\n",
+    "          f\"{isinstance(dtype, qdt.QDType)!s:9} {isinstance(dtype, qdt.CDType)!s:9}\"\n",
+    "          f\"{dtype.num_bits:6d} {dtype.num_qubits:6d} {dtype.num_cbits:6d}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c2089b62-36ce-4c90-b794-4e5e8338de47",
+   "metadata": {},
+   "source": [
+    "### Table of data type encoding examples"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dd0c1fd9-94d3-45fd-8766-c18615fc5123",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(f\"{'dtype':23} {'val':>6s}  \"\n",
+    "      f\"{'encoding':s}\")\n",
     "print(\"-\"*60)\n",
     "for dtype in dtypes:\n",
-    "    print(f\"{dtype!s:10} {isinstance(dtype, QCDType)!s:9} {isinstance(dtype, QDType)!s:9} {isinstance(dtype, CDType)!s:9}\"\n",
-    "          f\"{dtype.num_bits:6d} {dtype.num_qubits:6d} {dtype.num_cbits:6d}\"\n",
-    "         )"
+    "    if isinstance(dtype, QAny):\n",
+    "        print(f\"{dtype!s:23} {'':6s}  [opaque encoding]\")\n",
+    "        continue\n",
+    "    vals = list(dtype.get_classical_domain())\n",
+    "\n",
+    "    val = vals[0] # take the minimum\n",
+    "    val_bits = dtype.to_bits(val)\n",
+    "    val_bits_str = ','.join(str(bit) for bit in val_bits)\n",
+    "    print(f\"{dtype!s:23} {val!s:>6}  {val_bits_str}\")\n",
+    "\n",
+    "    val = vals[-1] # take the maximum\n",
+    "    val_bits = dtype.to_bits(val)\n",
+    "    val_bits_str = ','.join(str(bit) for bit in val_bits)\n",
+    "    print(f\"{'':23} {val!s:>6}  {val_bits_str}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a40933a4-1656-4a5a-b352-a09daf626518",
+   "metadata": {},
+   "source": [
+    "## Adding a new type\n",
+    "\n",
+    "You can add custom types by implementing the `_BitEncoding` interface and defining a light-weight `QDType` and/or `CDType`.\n",
+    "\n",
+    " 1. Define a class that implements the `BitEncoding[T]` abstract interface. the generic `T` should be the type of the analogous Python classical type. For example, `_Int` inherits from `BitEncoding[int]` and defines methods `to_bits`, `from_bits`, etc.\n",
+    " 2. Define a _quantum_ data type class that inherits from the `QDType[T]` base class.  Override the abstract property `_bit_encoding` to return an instance of the bit encoding class you defined before. For example, `QInt` inherits from `QDType[int]` and its `_bit_encoding` property returns `_Int(self.bitsize)`. \n",
+    " 3. Perform an analogous step to deinfe a _classical_ data type class that inherits from `CDType[T]` (but returns the same `BitEncoding` implementation). For example, `CInt` inherits from `CDType[int]` and its `_bit_encoding` property returns `_Int(self.bitsize)`. "
    ]
   }
  ],
@@ -345,7 +401,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.8"
+   "version": "3.13.9"
   }
  },
  "nbformat": 4,

qualtran/__init__.py

@@ -58,13 +58,21 @@
     QBit,
     CBit,
     QInt,
+    CInt,
     QIntOnesComp,
+    CIntOnesComp,
     QUInt,
+    CUInt,
     BQUInt,
+    BCUInt,
     QFxp,
+    CFxp,
     QMontgomeryUInt,
+    CMontgomeryUInt,
     QGF,
+    CGF,
     QGFPoly,
+    CGFPoly,
     QDTypeCheckingSeverity,
     check_dtypes_consistent,
 )