feat(qsystem): add Random number generation module (#822)

Closes: #769

Depends on:
- CQCL/tket2#786
  - CQCL/tket2#790
- #810

Some changes from the issue:
- Introduces `RNG` guppy type, instead of the `RNGContext` guppy struct.
- We have `def __new__(seed: int) -> "RNG":` instead of `__init__(seed:
int) -> "RNGContext"`
- We have `maybe_rng` instead of `init_safe(seed: int) ->
Option["RNGContext"]`

Other thoughts:

Unsure if this interface is the best we can do:
```py
def test() -> tuple[int, nat, float, int]:
    rng = RNG(42)
    rint = rng.random_int()
    rnat = rng.random_nat()
    rfloat = rng.random_float()
    rint_bnd = rng.random_int_bounded(100)
    rng.discard()
    return rint, rnat, rfloat, rint_bnd
```
It might be nice to provide a context manager interface such as:
```py
def test() -> tuple[int, nat, float, int]:
    with RNG(42) as rng:
        rint = rng.random_int()
        rnat = rng.random_nat()
        rfloat = rng.random_float()
        rint_bnd = rng.random_int_bounded(100)
    return rint, rnat, rfloat, rint_bnd
```
which would enforce the linear discipline on `RNG`. Mark confirms it's
currently not possible within guppy.

---

Release-As: 0.16.1

Author: qartik

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-added-large-files
       - id: check-case-conflict
@@ -38,7 +38,7 @@ repos:
       - id: debug-statements
 
   - repo: https://github.com/crate-ci/typos
-    rev: v1.21.0
+    rev: typos-dict-v0.12.6
     hooks:
       - id: typos
         args: []

.typos.toml

@@ -5,3 +5,4 @@ inot = "inot"
 inout = "inout"
 inouts = "inouts"
 anc = "anc"
+setable = "setable"

guppylang/compiler/expr_compiler.py

@@ -174,7 +174,7 @@ def _if_else(
         only_true_inputs: list[PlaceNode] | None = None,
         only_false_inputs: list[PlaceNode] | None = None,
     ) -> tuple[AbstractContextManager[None], AbstractContextManager[None]]:
-        """Builds a `Conditional`, returing context managers to build the `True` and
+        """Builds a `Conditional`, returning context managers to build the `True` and
         `False` branch.
         """
         conditional = self.builder.add_conditional(

guppylang/std/_internal/compiler/arithmetic.py

@@ -7,6 +7,7 @@
 from hugr import tys as ht
 from hugr.std.int import int_t
 
+from guppylang.std._internal.compiler.prelude import error_type
 from guppylang.tys.ty import NumericType
 
 INT_T = int_t(NumericType.INT_WIDTH)
@@ -55,6 +56,26 @@ def iwiden_s(from_width: int, to_width: int) -> ops.ExtOp:
     )
 
 
+def inarrow_u(from_width: int, to_width: int) -> ops.ExtOp:
+    """Returns an unsigned `std.arithmetic.int.narrow_u` operation."""
+    return _instantiate_int_op(
+        "inarrow_u",
+        [from_width, to_width],
+        [int_t(from_width)],
+        [ht.Either([error_type()], [int_t(to_width)])],
+    )
+
+
+def inarrow_s(from_width: int, to_width: int) -> ops.ExtOp:
+    """Returns a signed `std.arithmetic.int.narrow_s` operation."""
+    return _instantiate_int_op(
+        "inarrow_s",
+        [from_width, to_width],
+        [int_t(from_width)],
+        [ht.Either([error_type()], [int_t(to_width)])],
+    )
+
+
 # ------------------------------------------------------
 # --------- std.arithmetic.conversions ops -------------
 # ------------------------------------------------------

guppylang/std/_internal/compiler/qsystem.py

@@ -0,0 +1,44 @@
+from hugr import Wire
+from hugr import tys as ht
+from hugr.std.int import int_t
+
+from guppylang.definition.custom import CustomInoutCallCompiler
+from guppylang.definition.value import CallReturnWires
+from guppylang.std._internal.compiler.arithmetic import inarrow_s, iwiden_s
+from guppylang.std._internal.compiler.prelude import build_unwrap_right
+from guppylang.std._internal.compiler.quantum import (
+    QSYSTEM_RANDOM_EXTENSION,
+    RNGCONTEXT_T,
+)
+from guppylang.std._internal.util import external_op
+
+
+class RandomIntCompiler(CustomInoutCallCompiler):
+    def compile_with_inouts(self, args: list[Wire]) -> CallReturnWires:
+        [ctx] = args
+        [rnd, ctx] = self.builder.add_op(
+            external_op("RandomInt", [], ext=QSYSTEM_RANDOM_EXTENSION)(
+                ht.FunctionType([RNGCONTEXT_T], [int_t(5), RNGCONTEXT_T]), []
+            ),
+            ctx,
+        )
+        [rnd] = self.builder.add_op(iwiden_s(5, 6), rnd)
+        return CallReturnWires(regular_returns=[rnd], inout_returns=[ctx])
+
+
+class RandomIntBoundedCompiler(CustomInoutCallCompiler):
+    def compile_with_inouts(self, args: list[Wire]) -> CallReturnWires:
+        [ctx, bound] = args
+        bound_sum = self.builder.add_op(inarrow_s(6, 5), bound)
+        bound = build_unwrap_right(
+            self.builder, bound_sum, "bound must be a 32-bit integer"
+        )
+        [rnd, ctx] = self.builder.add_op(
+            external_op("RandomIntBounded", [], ext=QSYSTEM_RANDOM_EXTENSION)(
+                ht.FunctionType([RNGCONTEXT_T, int_t(5)], [int_t(5), RNGCONTEXT_T]), []
+            ),
+            ctx,
+            bound,
+        )
+        [rnd] = self.builder.add_op(iwiden_s(5, 6), rnd)
+        return CallReturnWires(regular_returns=[rnd], inout_returns=[ctx])

guppylang/std/_internal/compiler/quantum.py

@@ -8,7 +8,15 @@
 from hugr import ext as he
 from hugr import tys as ht
 from hugr.std.float import FLOAT_T
-from tket2_exts import futures, qsystem, qsystem_utils, quantum, result, rotation
+from tket2_exts import (
+    futures,
+    qsystem,
+    qsystem_random,
+    qsystem_utils,
+    quantum,
+    result,
+    rotation,
+)
 
 from guppylang.definition.custom import CustomInoutCallCompiler
 from guppylang.definition.value import CallReturnWires
@@ -19,17 +27,22 @@
 
 FUTURES_EXTENSION = futures()
 QSYSTEM_EXTENSION = qsystem()
+QSYSTEM_RANDOM_EXTENSION = qsystem_random()
 QSYSTEM_UTILS_EXTENSION = qsystem_utils()
 QUANTUM_EXTENSION = quantum()
 RESULT_EXTENSION = result()
 ROTATION_EXTENSION = rotation()
 
+RNGCONTEXT_T_DEF = QSYSTEM_RANDOM_EXTENSION.get_type("context")
+RNGCONTEXT_T = ht.ExtType(RNGCONTEXT_T_DEF)
+
 ROTATION_T_DEF = ROTATION_EXTENSION.get_type("rotation")
 ROTATION_T = ht.ExtType(ROTATION_T_DEF)
 
 TKET2_EXTENSIONS = [
     FUTURES_EXTENSION,
     QSYSTEM_EXTENSION,
+    QSYSTEM_RANDOM_EXTENSION,
     QSYSTEM_UTILS_EXTENSION,
     QUANTUM_EXTENSION,
     RESULT_EXTENSION,

guppylang/std/qsystem/random.py

@@ -0,0 +1,70 @@
+from typing import no_type_check
+
+from guppylang.decorator import guppy
+from guppylang.module import GuppyModule
+from guppylang.std._internal.compiler.qsystem import (
+    RandomIntBoundedCompiler,
+    RandomIntCompiler,
+)
+from guppylang.std._internal.compiler.quantum import (
+    QSYSTEM_RANDOM_EXTENSION,
+    RNGCONTEXT_T,
+)
+from guppylang.std._internal.util import external_op
+from guppylang.std.builtins import nat, owned
+from guppylang.std.option import Option
+
+qsystem_random = GuppyModule("qsystem.random")
+
+
+@guppy.hugr_op(
+    external_op("NewRNGContext", [], ext=QSYSTEM_RANDOM_EXTENSION),
+    module=qsystem_random,
+)
+@no_type_check
+def _new_rng_context(seed: int) -> Option["RNG"]: ...
+
+
+@guppy(qsystem_random)
+def maybe_rng(seed: int) -> Option["RNG"]:  # type: ignore[type-arg] # "Option" expects no type arguments, but 1 given
+    """Safely create a new random number generator using a seed.
+
+    Returns `nothing` if RNG is already initialized."""
+    return _new_rng_context(seed)  # type: ignore[no-any-return] # Returning Any from function declared to return "Option"
+
+
+@guppy.type(RNGCONTEXT_T, copyable=False, droppable=False, module=qsystem_random)
+class RNG:
+    """Random number generator."""
+
+    @guppy(qsystem_random)  # type: ignore[misc] # Unsupported decorated constructor type; Self argument missing for a non-static method (or an invalid type for self)
+    def __new__(seed: int) -> "RNG":
+        """Create a new random number generator using a seed."""
+        return _new_rng_context(seed).unwrap()  # type: ignore[no-any-return] # Returning Any from function declared to return "RNGContext"
+
+    @guppy.hugr_op(
+        external_op("DeleteRNGContext", [], ext=QSYSTEM_RANDOM_EXTENSION),
+        module=qsystem_random,
+    )
+    @no_type_check
+    def discard(self: "RNG" @ owned) -> None: ...
+
+    @guppy.custom(RandomIntCompiler(), module=qsystem_random)
+    @no_type_check
+    def random_int(self: "RNG") -> int: ...
+
+    @guppy(qsystem_random)
+    def random_nat(self: "RNG") -> nat:
+        """Generate a random 32-bit natural number."""
+        return nat(self.random_int())  # type: ignore[call-arg] # Too many arguments for "nat"
+
+    @guppy.hugr_op(
+        external_op("RandomFloat", [], ext=QSYSTEM_RANDOM_EXTENSION),
+        module=qsystem_random,
+    )
+    @no_type_check
+    def random_float(self: "RNG") -> float: ...
+
+    @guppy.custom(RandomIntBoundedCompiler(), module=qsystem_random)
+    @no_type_check
+    def random_int_bounded(self: "RNG", bound: int) -> int: ...

pyproject.toml

@@ -39,7 +39,7 @@ dependencies = [
     "pydantic >=2.7.0b1,<3",
     "typing-extensions >=4.9.0,<5",
     "hugr >=0.10.3,<0.11",
-    "tket2-exts>=0.4.0,<0.5",
+    "tket2-exts>=0.5.0,<0.6",
 ]
 
 [project.optional-dependencies]
@@ -65,7 +65,7 @@ test = [
     "pytest-notebook >=0.10.0,<0.11",
     "pytest-snapshot >=0.9.0,<1",
     "ipykernel >=6.29.5,<7",
-    "tket2>=0.6.1",
+    "tket2>=0.7.0",
     "pytest-benchmark>=5.1.0",
 ]
 execution = [
@@ -76,7 +76,7 @@ execution = [
     "maturin >=1.7.7,<2",
     "pip >=24",
 ]
-pytket_integration = [{ include-group = "test" }, "pytket >=1.34.0,<2"]
+pytket_integration = [{ include-group = "test" }, "pytket >=1.34.0"]
 
 [tool.uv.workspace]
 members = ["execute_llvm"]
@@ -86,7 +86,7 @@ execute-llvm = { workspace = true }
 
 # Uncomment these to test the latest dependency version during development
 #  hugr = { git = "https://github.com/CQCL/hugr", subdirectory = "hugr-py", rev = "e40b6c7" }
-# tket2-exts = { git = "https://github.com/CQCL/tket2", subdirectory = "tket2-exts", rev = "175a02d"}
+# tket2-exts = { git = "https://github.com/CQCL/tket2", subdirectory = "tket2-exts", rev = "633ebd7"}
 # tket2 = { git = "https://github.com/CQCL/tket2", subdirectory = "tket2-py", rev = "259cf88"}
 
 

tests/integration/test_qsystem.py

@@ -4,7 +4,8 @@
 from guppylang.module import GuppyModule
 from guppylang.std.angles import angle
 
-from guppylang.std.builtins import owned
+from guppylang.std.builtins import nat, owned
+from guppylang.std.qsystem.random import RNG, maybe_rng
 from guppylang.std.qsystem.utils import get_current_shot
 from guppylang.std.quantum import qubit
 from guppylang.std.qsystem.functional import (
@@ -13,6 +14,7 @@
     qsystem_functional,
     measure_and_reset,
     zz_max,
+    reset,
     rz,
     measure,
     qfree,
@@ -30,7 +32,7 @@ def compile_qsystem_guppy(fn) -> ModulePointer:  # type: ignore[no-untyped-def]
     ), "`@compile_qsystem_guppy` does not support extra arguments."
 
     module = GuppyModule("module")
-    module.load(angle, qubit, get_current_shot)  # type: ignore[arg-type]
+    module.load(angle, qubit, get_current_shot, RNG, maybe_rng)  # type: ignore[arg-type]
     module.load_all(qsystem_functional)
     guppylang.decorator.guppy(module)(fn)
     return module.compile()
@@ -53,3 +55,21 @@ def test(q1: qubit @ owned, q2: qubit @ owned, a1: angle) -> bool:
         return b
 
     validate(test)
+
+
+def test_qsystem_random(validate):  # type: ignore[no-untyped-def]
+    """Compile various operations from the qsystem random extension."""
+
+    @compile_qsystem_guppy
+    def test() -> tuple[int, nat, float, int]:
+        rng = RNG(42)
+        rng2 = maybe_rng(84)
+        rng2.unwrap_nothing()
+        rint = rng.random_int()
+        rnat = rng.random_nat()
+        rfloat = rng.random_float()
+        rint_bnd = rng.random_int_bounded(100)
+        rng.discard()
+        return rint, rnat, rfloat, rint_bnd
+
+    validate(test)