feat(qsystem): add Random number generation module

[qartik]

Closes: #769

Depends on:

• fix!: remove type argument from RNGContext type, swap returns tket2#786
  • chore(py): release tket2-exts 0.5.0 tket2#790
• Can't discard None of an optional qubit #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:

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:

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.

---

This comment override removes the release-as flag in the original commit:

BEGIN_COMMIT_OVERRIDE
feat(qsystem): add Random number generation module
END_COMMIT_OVERRIDE

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 94.02985% with 4 lines in your changes missing coverage. Please review.

Project coverage is 93.11%. Comparing base (d9b085f) to head (358e85c).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
guppylang/std/qsystem/random.py	91.42%	3 Missing ⚠️
guppylang/std/_internal/compiler/arithmetic.py	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #822      +/-   ##
==========================================
+ Coverage   93.06%   93.11%   +0.05%     
==========================================
  Files          72       74       +2     
  Lines        8564     8633      +69     
==========================================
+ Hits         7970     8039      +69     
  Misses        594      594              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mark-koch]

Nice, thank you!

[ss2165]

It's unclear whether init_safe(seed: int) -> Option["RNGContext"] can be written without maintaining any state and whether it's actually useful given the explicit linear typing currently required to use RNG

I don't follow why this is sorry - the __new__ method is unwrapping the option, __init_safe__ would presumably just return it as-is?

[qartik]

I don't follow why this is sorry - the __new__ method is unwrapping the option, __init_safe__ would presumably just return it as-is?

__new__ is a special dunder that's called for memory allocation even before __init__. It returns a new object and hence doesn't require passing in self as its first argument unlike __init__. So apart from __new__, I can't write another method that doesn't require self.

I also tried using @staticmethod decorator for __init_safe__, but then I get:

tests/integration/test_qsystem.py:8: in <module>
    from guppylang.std.qsystem.random import RNG
guppylang/std/qsystem/random.py:26: in <module>
    class RNG:
guppylang/std/qsystem/random.py:34: in RNG
    @guppy(qsystem_random)
guppylang/decorator.py:141: in <lambda>
    return lambda s: dec(s, arg)
guppylang/decorator.py:118: in dec
    return module.register_func_def(f)
guppylang/module.py:229: in register_func_def
    defn = RawFunctionDef(DefId.fresh(self), f.__name__, None, f, get_py_scope(f))
guppylang/module.py:404: in get_py_scope
    code = f.__code__
E   AttributeError: 'staticmethod' object has no attribute '__code__'. Did you mean: '__call__'?

which perhaps suggests that static methods are not yet supported in Guppy?

[ss2165]

ah that's fine (indeed static methods are not supported) - just have it available as a standalone function (new_rng_checked or something like that). I think this just means making your _new_rng_context function public effectively with a docstring and and a less ambiguous name.

[qartik]

Sounds good. Blocked by #810 Also I will need to write a wrapper maybe_rng instead of directly using _new_rng_context as docstrings don't yet work on placeholder functions, to be fixed in #826

[ss2165]

#810 has been closed: abb1aa1

[qartik]

@ss2165 is it accurate that we need CQCL/hugr#1946 and another PR for truncation to be able to finish this PR work on the eldarion PR?

Or am I missing how to perform type conversions between 32-bit and 64-bit ints?

• Learned I can use https://github.com/CQCL/hugr/blob/34c8f380e3d0921b4586f04c50575f40cdc698a9/hugr-core/src/std_extensions/arithmetic/int_ops.rs#L119

[ss2165]

I think that's right - I didn't realise they weren't being emitted apologies

[mark-koch]

Nice, looks good!

[qartik]

I have a patch to take this to merge, but it might require #846

diff --git a/pyproject.toml b/pyproject.toml
index b5b31b2..5a826c0 100644
--- a/pyproject.toml
+++ b/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 = [
@@ -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 = "633ebd7"}
+# 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"}

[qartik]

ah that's fine (indeed static methods are not supported) - just have it available as a standalone function (new_rng_checked or something like that). I think this just means making your _new_rng_context function public effectively with a docstring and and a less ambiguous name.

Hi @ss2165, I think maybe_rng or init_safe are useless, given there is no failure at runtime on seeding the RNG twice. I am removing them in #873

I recall anticipating this issue in #822 (comment) but we hadn't tested full stack then.

[ss2165]

@qartik The issue is not seeding the rng twice, it is a lack of guarantee that you have a unique handle to rng state, so reproducibility isn't guaranteed because rng calls could be reordered. The failure at runtime should be from calling initialisation twice without discarding first.

[qartik]

@qartik The issue is not seeding the rng twice, it is a lack of guarantee that you have a unique handle to rng state, so reproducibility isn't guaranteed because rng calls could be reordered. The failure at runtime should be from calling initialisation twice without discarding first.

I am unsure which runtime we are referring to. If the platform call doesn't fail, how can we detect this ordering violation?

Since RNG state is a linear type, it's tracked statically by the guppy type checker. The other way I was thinking of implementing maybe_rng was storing some state in RNG type itself, but that also will not be a runtime failure.