feat!: Explicit effects system, prevent calls from annotated funcs to those with fewer effects by acl-cqc · Pull Request #1723 · Quantinuum/guppylang

acl-cqc · 2026-05-07T18:13:18Z

closes #1745.

However, note this is pure typechecking, and does not add any new order edges (ideally we would use the effect-system information to replace EXTENSION_OPS_WITH_SIDE_EFFECTS but leaving that to the PR that solves #1746.

The annotation takes a list of Effect; I've added both internal and frontend enums but these might be combined. At present the only known effect is ANY.
Unannotated functions are assumed to have [Effect.ANY]
Callable types can be given effects via an @effects modifier; without which, you get [ANY] by default.
- Callables are invariant. We could perhaps be more flexible, while we are using Order edges not tokens, but that would be introducing subtyping; moreover this is consistent, and will be improved in Shorthand syntax for Effect Variables #1760 (as this does cause some degradations).
Nested functions are assumed to have the same effects as their containing function (for now; this could cause issues if you want to return one as a Callable return value)
Changes made to stdlib, and compiler changes to support them by making conversion-to-bool, enum and struct constructors all "pure", are all gathered together in 4523d81 (you can see without the PR without these: https://github.com/Quantinuum/guppylang/pull/1723/changes/BASE..51745bfdb8c55a24c57d783a0a5d1b91c3613781

Do I want more tests of the quantum stdlib? Any ideas what?

BREAKING CHANGE: Functions taking Callable will be able to accept either only Callables with effects (the default) or (if annotated) those without, rather than both; those returning Callables will need an explicit annotation if the returnee is pure.

…edGuppyKwargs

…...should this be in `Context`?

…n Context and check_bb/cfg/etc.

…e_call

…ed notes

hugrbot · 2026-05-07T18:14:26Z

This PR contains breaking changes to the public Python API.

Breaking changes summary

guppylang-internals/src/guppylang_internals/definition/overloaded.py:0: OverloadNoMatchError.__init__(max_effects_from):
Parameter was added as required

guppylang-internals/src/guppylang_internals/checker/cfg_checker.py:73: check_cfg(first_modifier_node):
Positional parameter was moved
Details: position: from 6 to 7 (+1)

guppylang-internals/src/guppylang_internals/checker/cfg_checker.py:73: check_cfg(max_effects_from):
Parameter was added as required

guppylang-internals/src/guppylang_internals/checker/cfg_checker.py:228: check_bb(max_effects_from):
Parameter was added as required

guppylang-internals/src/guppylang_internals/checker/modifier_checker.py:22: check_modified_block(max_effects_from):
Parameter was added as required

github-actions · 2026-05-07T18:14:48Z

Bencher Report

Branch	acl/max_effects
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.53 x 1e3 (-0.01%) Baseline: 27.54 x 1e3	27.81 x 1e3 (99.00%)	📈 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

codecov-commenter · 2026-05-07T18:16:21Z

Codecov Report

❌ Patch coverage is 97.70992% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.91%. Comparing base (82b9c77) to head (74d1453).
⚠️ Report is 25 commits behind head on main.

Files with missing lines	Patch %	Lines
guppylang/src/guppylang/decorator.py	88.23%	2 Missing ⚠️
guppylang/src/guppylang/std/effects.py	77.77%	2 Missing ⚠️
...ls/src/guppylang_internals/checker/func_checker.py	96.15%	1 Missing ⚠️
...uppylang-internals/src/guppylang_internals/span.py	85.71%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1723      +/-   ##
==========================================
- Coverage   92.98%   92.91%   -0.08%     
==========================================
  Files         135      138       +3     
  Lines       13056    13303     +247     
==========================================
+ Hits        12140    12360     +220     
- Misses        916      943      +27

☔ 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.

codspeed-hq · 2026-05-07T18:31:16Z

Merging this PR will not alter performance

✅ 9 untouched benchmarks

_{Comparing acl/max_effects (74d1453) with main (db54090)}

…inting

This reverts commit 41b68c68f112276a24747ccc0e76fd78aa147ae4.

mark-koch

Nice! The implementation looks good to me, just some questions and suggestions for the interface and error messages

mark-koch · 2026-06-02T15:03:58Z

                    raise GuppyError(LinearComptimeError(node.right, ty))
+            case ast.Call(func=ast.Name(id="effects")) as fx:
+                if not isinstance(ty, FunctionType):
+                    raise GuppyError(InvalidFlagError(node.right))


Could you add tests for each before merging?

mark-koch · 2026-06-02T15:07:15Z

+                    # We might want to support ast.Attribute with LHS "Effects"
+                    # and look at RHS


I think users shouldn't think of effects as an enum. In particular, libraries may declare their own effects so they can come from different namespaces

At the moment we only have ANY so this isn't an issue, but imo not worth spending a lot of time on this until we figure out how new effects should be declared

mark-koch · 2026-06-02T15:09:16Z

+        arrow = (
+            "->"
+            if ty.declared_effects is None
+            else f"-{Effect.format_list(ty.declared_effects)}->"


Mhmm I think this makes the error message so much worse that we shouldn't release it to users as is.

Maybe for now we could do an inversion of defaults: Regular arrow means ANY effects and have a special thing for empty effects?

mark-koch · 2026-06-02T15:11:27Z

        for inp in sig.inputs
    )
    s += ", ..." if has_var_args else ""
+    # TODO Not clear how to display effects in a Python-like syntax? (skip for now)


Maybe def foo(x : int) -> int @ effects(...)?

But again, we should only print it if the effects are not the default

mark-koch · 2026-06-02T15:42:36Z

+# Pending https://github.com/Quantinuum/guppylang/issues/1752 we need to explicitly
+# declare the effects of `f`


I don't see the connection to #1752. Isn't this just because of invariance?

Sorry, I meant #1760, which follows on from that

mark-koch · 2026-06-02T15:48:15Z

+    # When we have effect variables, we should use an existential
+    # variable upper-bounded by those allowed in the context.
+    exp_sig = exp_sig.with_effects([])


Have you annotated all __bool__ functions in the standard library?

mark-koch · 2026-06-02T15:51:57Z

+        if (
+            isinstance(d, ast.Call)
+            and isinstance(d.func, ast.Name)
+            and d.func.id == "guppy"


This sort of string matching will break for e.g. guppy-ft where they define their own decorators that internally call guppy

Don't know what the best solution is, but this seems too fragile. Especially if you're throwing an InternalGuppyError when the decorator is not found

Ok yes good point about custom decorators. Tricky to see what to do though.

It seems hard to identify a custom-decorator (that calls guppy) from the AST, there's so little to go on (we haven't even identified the custom-decorator definition/implementation that the ast.Call points to!).

When the decorator executes, it calls guppy. So the latter could be an opportunity to put something into the e.g. GuppyFunctionDefinition. However at this point it's hard to identify which bit of AST lead to the call to guppy.

Best hack I can see might be for guppy to see the source file of the decorated function, look up the call stack (for callers to guppy) until it finds one in that source file (?!) and note that somehow. Doesn't work well as if the definition of the custom decorator is in the same source file as it's use...could we look up the call stack (calling guppy) until we find something that's listed as a decorator of the AST node for the function that guppy is running on? That seems hard, and possibly fragile, but I can have a go...[maybe in another PR?]

Alternatively we make to make custom decorators do some work themselves (some will have to add an effects= parameter too but custom decorators might be pure-only or some such)...even this I'm not quite clear on though; we could add an extra effects_declared_at parameter to @guppy and get them to fill that in, but even finding the AST node to pass to that parameter could be quite hard for them.

Would @guppy @ effects(...) help? (Would it even work? Perhaps if that was not using __rmatmul__ but if @effects was its own decorator....then we could spot it independently of the @guppy / @custom, although it wouldn't work well if the custom-decorator specified the effects itself)

Least improvement is to fall back to the def line or the whole declaration if we can't find a decorator, rather than InternalError - I'll certainly do that.

If we can't find the decorator, then the span of the FunctionDef includes the function body but not the decorator list, which isn't much good - so even just this fallback was more awkward than expected. But done. (We can make an issue for providing some way for custom decorators to override that and do better but for another PR?)

mark-koch · 2026-06-02T15:57:16Z

+    # For now we assume the nested function has the same effects as that enclosing.
+    # We could do better by allowing a separate annotation (rather than a parameter
+    # to @guppy), but we will wait for callgraph analysis to compute precisely:
+    # nested functions are not part of any public API, so changes are not breaking.


Does this guarantee that programs that compile with this version will still compile once we do callgraph analysis?

Not if they do things with Callable, e.g.

@guppy(effects=[ANY]) def outer() -> Callable[[int], int, ANY]: result(...) # Just to justify the ANY on the outer function, not otherwise relevant def inner(x: int) -> int: return x + 1 return inner

callgraph analysis figures out that inner is pure, but Callable is invariant.

However with #1760 and existentials for the effects of the returned Callable then you could make it work if you declared def outer() -> Callable[[int],int]

mark-koch · 2026-06-02T15:58:44Z

    from collections.abc import Callable, Sequence
    from types import FrameType

+    from guppylang import Effect


Yeah this seems wrong. At the very least we should guard behind if TYPE_CHECKING

…body :(

…ith effects only if hidden

acl-cqc added 15 commits May 4, 2026 10:56

Decorator add max_effects as list[str]

66a397e

Make annotation be list[Effect] with empty Enum

d5815fc

Add field to Raw(Traced)FunctionDef,Decl, store string values in Pars…

b28cdbd

…edGuppyKwargs

Add field and copy through into Parsed/Checked/Compile variants

96b9346

Add max_effects parameter to many funcs, with default for StmtChecker…

9a71a83

…...should this be in `Context`?

Remove from StmtChecker, add to Context

d8632ba

driveby common-up FunctionType constructions in decorator.py

2afa232

Remove from Parsed def/decl (only Raw), add to FunctionType - still i…

4d256e5

…n Context and check_bb/cfg/etc.

check_nested_func_def gets max_effects from Context

706f062

Add TooManyEffectsError, check+raise in toplevel check_call+synthesiz…

1067f5c

…e_call

First success/failure tests; no binary ops yet, and error messages ne…

10b682c

…ed notes

Add test of calling result...aaiieeeee

6f92edb

Add max_effects to @hugr_op and RawCustomFunctionDef

595e0bb

Use int+ in tests, breaking

c1b6439

Declare int+ as having no effects...fixes tests

dd1245d

acl-cqc added 11 commits May 11, 2026 11:33

test cleanups (don't import array), inc driveby bracket-removal

28454b4

Add error test: Callable has unknown effects

be231e0

refactor: Common up effects check

6ee59a3

improve error location when possible

dbc5fcb

Parse Callable[[inp,...],out,max_effects]

87959e6

pure_calls_impure_def: remove comment about result, we've done that now

8782e3e

test no contravariance of argument type

6224053

no, test no covariance of return type, simpler right

4284ee9

Enforce invariance of Callable max-effects when assignment, +test +pr…

8965c2e

…inting

pretty-print as -[]->

5cf12c7

list[str](|None) -> list[tys.Effect](|None)

ba705c8

acl-cqc added 2 commits May 26, 2026 19:37

missed from move of @effects

4689bd4

missing import in fun_ty_mismatch_4

af1f2e5

acl-cqc requested review from mark-koch and maximilianruesch May 26, 2026 19:01

acl-cqc marked this pull request as ready for review May 26, 2026 19:07

acl-cqc requested a review from a team as a code owner May 26, 2026 19:07

acl-cqc added 2 commits May 26, 2026 21:17

undo stdlib changes, enum+struct constructors, bool conversion

51745bf

Redo stdlib changes, enum+struct constructors, bool conversion

4523d81

This reverts commit 41b68c68f112276a24747ccc0e76fd78aa147ae4.

maximilianruesch requested a review from tatiana-s May 27, 2026 09:18

mark-koch reviewed Jun 2, 2026

View reviewed changes

acl-cqc added 19 commits June 5, 2026 11:22

Add test w/custom decorator -> InternalError, oops

78f12ed

refactor: max_effects_from stores Span

db75029

Give whole FunctionDef as context if can't find decorator...includes …

7b26c25

…body :(

Include decorators, exclude body

63a5b4e

Better errors when parsing @ effects

8659f75

make decorator more flexible

31b3a69

correct issue link

e532548

use set when checking invariance

458de9a

Skip the explicit list of allowed effects when its in the decorator

dac0e57

change tuple[list[Effect], Span | expr] -> EffectLimitDecl, add s

33948ec

Add decl_name to EffectLimitDecl and MaxFromDecl

fa3ab4e

TooManyEffectsError: display target name with effects, or just type w…

1f5ff09

…ith effects only if hidden

drop pipeline comment

74d1453

Remove external decorator enum Effect, just re-export

3810760

Internals decorator use internals.tys.Effect not re-export

975bb02

Tests of comptime (some failing)

4e64ea8

Add comptime error tests (messages wrong atm)

d5b45af

Refactor EffectLimitDecl.for_def

281501f

Implement for tracing, update error messages

d7665a2

acl-cqc mentioned this pull request Jun 8, 2026

Build callgraph of guppy functions, use to calculate effects of unannotated funcs #1748

Open

		# We might want to support ast.Attribute with LHS "Effects"
		# and look at RHS

		# Pending https://github.com/Quantinuum/guppylang/issues/1752 we need to explicitly
		# declare the effects of `f`

Conversation

acl-cqc commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

codspeed-hq Bot commented May 7, 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!

mark-koch left a comment

Choose a reason for hiding this comment

Uh oh!

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!

mark-koch Jun 2, 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!

mark-koch Jun 2, 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

acl-cqc commented May 7, 2026 •

edited

Loading

hugrbot commented May 7, 2026 •

edited

Loading

github-actions Bot commented May 7, 2026 •

edited

Loading

codecov-commenter commented May 7, 2026 •

edited

Loading

codspeed-hq Bot commented May 7, 2026 •

edited

Loading

mark-koch Jun 2, 2026 •

edited

Loading

mark-koch Jun 2, 2026 •

edited

Loading