feat: InlineFunctionsPass supports "Always" annotation that errors if unsatisfiable

tket-py/test/test_pass.py

@@ -4,9 +4,11 @@
 from typing import Callable, Any
 import subprocess
 from tket._ops import TketOp
+from tket.metadata import InlineAnnotation
 from tket.passes import (
     _badger_optimise,
     _greedy_depth_reduce,
+    InlineFunctionsError,
     InlineFunctions,
     inline_funcs,
     NormalizeGuppy,
@@ -23,6 +25,7 @@
 
 from tket.passes import PytketHugrPass, QSystemPass
 from hugr.build.base import Hugr
+import hugr.tys as tys
 
 import numpy as np
 import pytest
@@ -334,6 +337,50 @@ def test_modifier_execution() -> None:
             np.testing.assert_allclose(computed_statevector, expected_statevector)
 
 
+@pytest.mark.parametrize("annotate", [True, False])
+def test_inline_always(annotate: bool) -> None:
+    import hugr.ops as ops
+    from hugr.build.dfg import Dfg
+
+    d = Dfg(tys.Tuple(tys.Qubit, tys.Qubit))
+
+    f_id = d.module_root_builder().define_function(
+        "id",
+        [tys.Qubit],
+    )
+    f_id.set_outputs(f_id.input_node[0])
+
+    if annotate:
+        f_id.metadata[InlineAnnotation] = "always"
+
+    (tup,) = d.inputs()
+    (q1, q2) = d.add(ops.UnpackTuple()(tup))
+    call1 = d.call(f_id, q1)
+    call2 = d.call(f_id, q2)
+    (tup,) = d.add(ops.MakeTuple()(call1, call2))
+
+    d.set_outputs(tup)
+
+    InlineFunctions(heuristic=inline_funcs.MaxSize(0))(d.hugr)
+    CompilationState.from_python(d.hugr).validate()
+    assert _count_ops(d.hugr, "Call") == 0 if annotate else 2
+
+
+def test_inline_always_cycle() -> None:
+    from hugr.build.function import Module
+
+    mod = Module()
+
+    f_recursive = mod.define_function("recurse", [tys.Qubit])
+    f_recursive.declare_outputs([tys.Qubit])
+    call = f_recursive.call(f_recursive, f_recursive.input_node[0])
+    f_recursive.set_outputs(call)
+
+    f_recursive.metadata[InlineAnnotation] = "always"
+    with pytest.raises(InlineFunctionsError):
+        InlineFunctions(heuristic=inline_funcs.MaxSize(0))(mod.hugr)
+
+
 def test_inline_functions() -> None:
     hugr = _hugr_from_path("test_files/guppy_examples/fn_calls.hugr")
 

tket-py/tket/_tket/passes.pyi

@@ -18,6 +18,9 @@ class CircuitChunks:
 class PullForwardError(Exception):
     """Error from a `PullForward` operation."""
 
+class InlineFunctionsError(Exception):
+    """Errors from the function inlining pass."""
+
 def normalize_guppy(
     circ: CompilationState,
     *,

tket-py/tket/metadata.py

@@ -74,16 +74,19 @@ class MaxQubitsHint(Metadata[int]):
     KEY = _metadata.MAX_QUBITS_HINT
 
 
-InlineAnnotationValue: TypeAlias = Literal["never"] | Literal["best_effort"]
+InlineAnnotationValue: TypeAlias = Literal["never", "best_effort", "always"]
 
 
 class InlineAnnotation(Metadata[InlineAnnotationValue]):
     """Metadata hinting the compiler that a function declaration should be inlined at its call sites.
 
+    For functions annotated with "always", an error will be raised if the function is on a cycle.
+
     When a function is not annotated, we use a heuristic to determine whether to inline.
 
     Values:
     - "never": Never inline this function.
+    - "always": Always inline this function; raise an error if this is not possible.
     - "best_effort":
         Inline the function if possible.
         This is not guaranteed, the compiler may choose not to inline functions with this annotation.
@@ -98,10 +101,10 @@ def to_json(cls, value: InlineAnnotationValue) -> JsonType:
     @classmethod
     def from_json(cls, value: JsonType) -> InlineAnnotationValue:
         match value:
-            case "never" | "best_effort":
+            case "never" | "best_effort" | "always":
                 return value
             case _:
-                msg = f"Expected {cls.KEY} metadata to be 'never' or 'best_effort', but got {value!r}"
+                msg = f"Expected {cls.KEY} metadata to be 'never', 'best_effort', or 'always', but got {value!r}"
                 raise TypeError(msg)
 
 

tket-py/tket/passes/__init__.py

@@ -13,7 +13,7 @@
 from .._pattern import Rule, RuleMatcher
 from .._state.build import OneQbGate, from_coms
 from .._tket import passes as _passes, optimiser as _optimiser
-
+from .._tket.passes import InlineFunctionsError
 from hugr.passes.composable import (
     ComposablePass,
     ComposedPass,
@@ -29,6 +29,7 @@
 __all__ = [
     "PytketHugrPass",
     "PassResult",
+    "InlineFunctionsError",
     "InlineFuncsHeuristic",
     "InlineFunctions",
     "NormalizeGuppy",
@@ -235,6 +236,8 @@ class InlineFunctions(ComposablePass):
     Parameters:
     - heuristic: Heuristic used to choose which non-recursive functions to
       inline. Defaults to `MaxSize(64)`.
+
+    Calls to functions annotated with `inline="always"` are processed first.
     """
 
     heuristic: inline_funcs.InlineFuncsHeuristic = inline_funcs.MaxSize(64)

tket/src/metadata.rs

@@ -49,6 +49,10 @@ impl Metadata for MaxQubitsHint {
 #[serde(rename_all = "snake_case")]
 #[non_exhaustive]
 pub enum InlineAnnotation {
+    /// Always inline calls to this function.
+    ///
+    /// If this cannot be done, an error will be raised.
+    Always,
     /// Inline the function if we know it won't produce an invalid Hugr.
     ///
     /// This is a best effort option; the compiler may choose not to inline