feat!: Support generic comptime functions by mark-koch · Pull Request #1630 · Quantinuum/guppylang

mark-koch · 2026-04-02T14:13:09Z

Closes #896

BREAKING CHANGE: TracedFunctionDef is no longer a CompilableDef, but now a CheckableGenericDef that returns a monomorphic TracedMonoFunctionDef after checking
BREAKING CHANGE: trace_function now requires the generic instantiation as an extra argument

github-actions · 2026-04-02T14:17:47Z

Bencher Report

Branch	mk/generic-comptime
Testbed	Linux

Click to view all benchmark results

Benchmark	Latency	Benchmark Result microseconds (µs) (Result Δ%)	Upper Boundary microseconds (µs) (Limit %)
tests/benchmarks/test_big_array.py::test_big_array_check	📈 view plot 🚷 view threshold	498,346.28 µs (-38.39%) Baseline: 808,929.89 µs	849,376.38 µs (58.67%)
tests/benchmarks/test_big_array.py::test_big_array_compile	📈 view plot 🚷 view threshold	1,357,856.57 µs (-13.27%) Baseline: 1,565,544.88 µs	1,643,822.13 µs (82.60%)
tests/benchmarks/test_big_array.py::test_big_array_executable	📈 view plot 🚷 view threshold	6,267,170.48 µs (-10.07%) Baseline: 6,969,038.29 µs	7,317,490.20 µs (85.65%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_check	📈 view plot 🚷 view threshold	76,847.48 µs (-22.15%) Baseline: 98,714.66 µs	103,650.39 µs (74.14%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_compile	📈 view plot 🚷 view threshold	142,670.06 µs (-22.44%) Baseline: 183,939.09 µs	193,136.05 µs (73.87%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_executable	📈 view plot 🚷 view threshold	723,402.41 µs (-33.61%) Baseline: 1,089,615.34 µs	1,144,096.11 µs (63.23%)
tests/benchmarks/test_prelude.py::test_import_guppy	📈 view plot 🚷 view threshold	34.76 µs (-17.11%) Baseline: 41.94 µs	44.03 µs (78.95%)

🐰 View full continuous benchmarking report in Bencher

hugrbot · 2026-04-02T14:26:59Z

This PR contains breaking changes to the public Python API.

Breaking changes summary

guppylang-internals/src/guppylang_internals/tracing/function.py:71: trace_function(node):
Positional parameter was moved
Details: position: from 4 to 5 (+1)

guppylang-internals/src/guppylang_internals/tracing/function.py:71: trace_function(func_def):
Positional parameter was moved
Details: position: from 5 to 6 (+1)

guppylang-internals/src/guppylang_internals/tracing/function.py:71: trace_function(generic_args):
Parameter was added as required

guppylang-internals/src/guppylang_internals/definition/traced.py:0: TracedFunctionDef.compile_outer:
Public object was removed

guppylang-internals/src/guppylang_internals/definition/traced.py:0: CompiledTracedFunctionDef.__init__(func_def):
Positional parameter was moved
Details: position: from 6 to 7 (+1)

guppylang-internals/src/guppylang_internals/definition/traced.py:0: CompiledTracedFunctionDef.__init__(generic_args):
Parameter was added as required

codecov-commenter · 2026-04-02T14:28:30Z

Codecov Report

❌ Patch coverage is 83.01887% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.82%. Comparing base (85e42d1) to head (a31c69e).

Files with missing lines	Patch %	Lines
...ernals/src/guppylang_internals/tracing/function.py	76.92%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1630      +/-   ##
==========================================
- Coverage   92.87%   92.82%   -0.05%     
==========================================
  Files         136      136              
  Lines       13167    13206      +39     
==========================================
+ Hits        12229    12259      +30     
- Misses        938      947       +9

☔ View full report in Codecov by Harness.
📢 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.

github-actions · 2026-04-02T14:44:47Z

Bencher Report

Branch	mk/generic-comptime
Testbed	Linux

Click to view all benchmark results

Benchmark	hugr_bytes	Benchmark Result bytes x 1e3 (Result Δ%)	Upper Boundary bytes x 1e3 (Limit %)	hugr_nodes	Benchmark Result nodes (Result Δ%)	Upper Boundary nodes (Limit %)
tests/benchmarks/test_big_array.py::test_big_array_compile	📈 view plot 🚷 view threshold	158.77 x 1e3 (0.00%) Baseline: 158.77 x 1e3	160.36 x 1e3 (99.01%)	📈 view plot 🚷 view threshold	6,641.00 (0.00%) Baseline: 6,641.00	6,707.41 (99.01%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_compile	📈 view plot 🚷 view threshold	27.54 x 1e3 (0.00%) Baseline: 27.54 x 1e3	27.81 x 1e3 (99.01%)	📈 view plot 🚷 view threshold	1,074.00 (0.00%) Baseline: 1,074.00	1,084.74 (99.01%)
tests/benchmarks/test_queue_push_pop.py::test_queue_push_benchmark_compile	📈 view plot 🚷 view threshold	10.91 x 1e3 (0.00%) Baseline: 10.91 x 1e3	11.02 x 1e3 (99.01%)	📈 view plot 🚷 view threshold	308.00 (0.00%) Baseline: 308.00	311.08 (99.01%)
tests/benchmarks/test_queue_push_pop.py::test_queue_push_pop_benchmark_compile	📈 view plot 🚷 view threshold	14.84 x 1e3 (0.00%) Baseline: 14.84 x 1e3	14.99 x 1e3 (99.01%)	📈 view plot 🚷 view threshold	435.00 (0.00%) Baseline: 435.00	439.35 (99.01%)

🐰 View full continuous benchmarking report in Bencher

codspeed-hq · 2026-06-08T11:19:05Z

Merging this PR will not alter performance

✅ 9 untouched benchmarks

_{Comparing mk/generic-comptime (a31c69e) with main (85e42d1)}

acl-cqc

Looks great, Mark, lots of nice examples in tests :). Comments relate only to comments/docs in the code really although I am nervous about the __closure__, __code__ and co_freevars bit....is there any alternative there?

acl-cqc · 2026-06-08T11:52:31Z

+    T = guppy.type_var("T", copyable=True, droppable=True)
+
+    @guppy.comptime
+    def foo(x: T @ comptime) -> T:


I admit I'm a bit confused here as to whether the @ comptime applied to the T here or the x or indeed whether it's necessary at all?

It applies to the x. It says that foo takes an input x of type T whose value must be known at compile-time. This in turn is syntactic sugar for a generic function

@guppy.comptime def foo[T: (Copy, Drop), x: T]() -> T: ...

acl-cqc · 2026-06-08T11:54:50Z

+
+        @guppy.comptime
+        def foo(self) -> int:
+            assert isinstance(n, int)


Presumably this is not in any sense "required" but we are just checking that it works? (Which is good to check - i.e. that we are able to access n during comptime execution)

acl-cqc · 2026-06-08T11:57:44Z

+        assert isinstance(n, int)
+        assert isinstance(m, int)
+        assert isinstance(k, int)
+        return n + m + k


Suggested change

return n + m + k

return xs[k] + ys[k]

acl-cqc · 2026-06-08T12:09:09Z

+        generic_values = {
+            x: const_argument_to_python_value(arg)
+            for x, arg in generic_args.items()
+            # TODO: We don't have a comptime representation of types yet, so we can only


This "representation of types" that we need is not a Hugr representation, right, just a python representation to provide at comptime?

In which case, we do have one: the same representation as in the rest of the compiler, namely guppylang_internals.tys...... So we could expose that. I'm not saying we should**, but maybe clarify the comment ("public representation" perhaps, or say something about not wanting to expose guppylang-internals stuff)

** I mean, how much guppylang-internals to expose, is a subjective question, but I'm not going to push you one way or the other. We do in a few places I think but not many.

acl-cqc · 2026-06-08T12:10:30Z

+        return self.ty.params
+
+    def check(self, type_args: Inst, globals: Globals) -> "TracedMonoFunctionDef":
+        """Type checks the body of the function."""


Suggested change

"""Type checks the body of the function."""

"""Type checks (and thus traces/executes) the body of the function."""

Actually I'm not sure it does trace/execute?? That only happens in compile? In which case are we really doing "check the body" at all?

acl-cqc · 2026-06-08T12:14:02Z

-            call = dfg.builder.call(
-                self.func_def, *args, instantiation=func_ty, type_args=hugr_type_args
-            )
+            call = dfg.builder.call(self.func_def, *args)


So...just checking...the ht.FunctionType has been compiled into self.func_def, right?

acl-cqc · 2026-06-08T12:16:56Z

+                val = generic_values.pop(inp.name)
+            else:
                # Function inputs are only allowed to be mutable if they are borrowed.
                # For owned arguments, mutation wouldn't be observable by the caller,


(driveby?) Not sure I follow this. The mutation wouldn't be observable by the caller but only because the caller has lost/handed over the object that was mutated, so that respects python semantics (in that we have statically disallowed programs in which they'd be able to see the mutations!)

acl-cqc · 2026-06-08T12:20:50Z

+            if x in generic_values:
+                f.__closure__[i].cell_contents = generic_values.pop(x)
+
+    # If all values have been assigned, we can stop here


nit: I think all the code below is fine (does nothing) if generic_values are empty... is it worth this? (It's nice to have only one yield)

acl-cqc · 2026-06-08T12:23:43Z

+
+
+@contextmanager
+def insert_generic_args(


how about add_generic_args_to_globals or ...to_function_globals? That'd make the callsite a lot clearer (I was thinking it was gonna prepend them to an existing list of generic args or something)

acl-cqc · 2026-06-08T12:24:56Z

+    instantiation of generic parameters."""
+    # The values of Python 3.12+ style generics are generated using an annotation scope
+    # (see https://docs.python.org/3/reference/compound_stmts.html#generic-functions).
+    # Thus, their values will be bound in the `__closure__` table of the function and


Argh. This is by far the nastiest bit. I note there is no python version check, either, which might make me feel slightly happier. I didn't see this from the link you give just above, is that the best reference?

feat: Support generic comptime functions

df9ca44

mark-koch requested a review from a team as a code owner April 2, 2026 14:13

mark-koch requested a review from acl-cqc April 2, 2026 14:13

CalMacCQ mentioned this pull request Apr 2, 2026

Update docs once generic comptime functions are available Quantinuum/guppy-docs#94

Open

maximilianruesch mentioned this pull request Apr 17, 2026

[Bug]: Guarded array indexing fails bounds check after monomorphization #1669

Open

mark-koch added 4 commits June 8, 2026 12:00

Merge remote-tracking branch 'origin/main' into mk/generic-comptime

48fbbd4

Simplify CompiledTracedFunctionDef.compile_call

cbbbe3e

Update docstring

85d0c2d

Ruff

a31c69e

mark-koch changed the title ~~feat: Support generic comptime functions~~ feat!: Support generic comptime functions Jun 8, 2026

acl-cqc approved these changes Jun 8, 2026

View reviewed changes

	"""Type checks the body of the function."""
	"""Type checks (and thus traces/executes) the body of the function."""

Conversation

mark-koch commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hugrbot commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codspeed-hq Bot commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Uh oh!

acl-cqc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mark-koch Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mark-koch commented Apr 2, 2026 •

edited

Loading

github-actions Bot commented Apr 2, 2026 •

edited

Loading

hugrbot commented Apr 2, 2026 •

edited

Loading

codecov-commenter commented Apr 2, 2026 •

edited

Loading

github-actions Bot commented Apr 2, 2026 •

edited

Loading

codspeed-hq Bot commented Jun 8, 2026 •

edited

Loading

mark-koch Jun 8, 2026 •

edited

Loading