feat: InlineHint metadata

[aborgna-q]

Follow up to Quantinuum/hugr#1524. Defines a metadata value for hinting the compiler on which functions to inline.

Part of #1804.

Note that this definition is rust-only. We still need to add exports for all tket metadata definitions on the python bindings.

Guppy issue/PR (they'll need to be updated):

• feat: (WIP) add metadata and guppy kwarg for inline="always" guppylang#1513
• Inlining annotations guppylang#1054

[codecov]

Codecov Report

❌ Patch coverage is 86.36364% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.24%. Comparing base (1bfef9a) to head (dcdc717).
⚠️ Report is 6 commits behind head on main.

Files with missing lines	Patch %	Lines
tket-py/tket/metadata.py	80.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1532      +/-   ##
==========================================
+ Coverage   84.05%   84.24%   +0.19%     
==========================================
  Files         189      189              
  Lines       29358    29778     +420     
  Branches    28174    28581     +407     
==========================================
+ Hits        24677    25087     +410     
- Misses       3501     3502       +1     
- Partials     1180     1189       +9     

Flag	Coverage Δ
python	90.60% <80.00%> (-0.16%)	⬇️
qis-compiler	91.66% <ø> (ø)
rust	83.97% <100.00%> (+0.20%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

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

[acl-cqc]

Ok let's combine functionality (not necessarily PRs) here with #1449.
I've updated that to use a similar metadata (there without the Never, with #[non_exhaustive], and I called it InlineAnnotation rather than hint, but at least it's in the same place ;-)).
Noting that #1524 uses inline_acyclic which will mean any function on a cycle will not be inlined at all (cycles are removed from graph rather than merely broken), I think #1449 handles the "Always" bit better, so that can be run first as a separate pass.

Thus, either (a) put this in first, but without the Always option (to be added in 1449); or (b) let's get #1449 in first and then this can add the Never option. I don't really mind which way around, and I think #1449 can be marked ready now (probably for a random reviewer? But you might want to check over the annotation).

WRT this PR:

• I am also unsure about "follow_hints=False" still respecting the "Never" hint; are we sure it shouldn't follow that too? (Otherwise, follow_hints will do nothing when Always is removed. One could say "Always is not a hint" but an annotation, iow it's correct for "follow_hints" to have no effect until we add some InlineAnnotation::XYZHint).
• Would be nice to add to the heuristic here that (non-preserved?) functions with only one call "are always small enough" ;)
• I haven't checked what you're doing here, but I note it's quite tricksy doing inlining respecting PassScope::EntrypointXXX :(

[acl-cqc]

If we'd rather put this in with the algorithm as here, which I think is ok....

• Do we want to combine metadata for this pass and chore: devenv update hugr#1449?
  • If so, I think it should be "InlineAnnotation" and the variants that are hints should be called XyzHint, or something like that. (Does it live in tket.hint.... ?) e.g. your "always" is a hint, not a command.
  • Otherwise, we could have both InlineAnnotation and InlineHint....
• "Always" would be better as "BestEffort" or "Best" or "Max" or something like that, with actually "always" handled by chore: devenv update hugr#1449. (Really "Always" here means "Trust me I am small enough")
• "follow"ing hints (default true) would be better as "ignore hints" (default false).
  • Should probably apply uniformly to both never and (pseudo-)always?

[aborgna-q]

• Renamed metadata::InlineHint to metadata::InlineAnnotation. It's now #[non_exhaustive].
• Renamed the metadata key from tket.hint.inline to just tket.inline.
• Removed InlineAnnotation::Always and added a BestEffort (encoded as best_effort).
• Removed the follow_inline_hints flag from the inline funcs pass. It's less confusing now.

I think that should combine well with your PR now?

[hugrbot]

This PR contains breaking changes to the public Rust API.
Please deprecate the old API instead (if possible), or mark the PR with a ! to indicate a breaking change.

cargo-semver-checks summary

    Building tket v0.18.0 (current)
     Built [  44.904s] (current)
   Parsing tket v0.18.0 (current)
    Parsed [   0.122s] (current)
  Building tket v0.18.0 (baseline)
     Built [  43.016s] (baseline)
   Parsing tket v0.18.0 (baseline)
    Parsed [   0.103s] (baseline)
  Checking tket v0.18.0 -> v0.18.0 (assume minor change)
   Checked [   0.149s] 196 checks: 195 pass, 1 fail, 0 warn, 56 skip

--- failure inherent_method_missing: pub method removed or renamed ---

Description:
A publicly-visible method or associated fn is no longer available under its prior name. It may have been renamed or removed entirely.
      ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
     impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.47.0/src/lints/inherent_method_missing.ron

Failed in:
InlineFunctionsPass::follow_inline_hints, previously in file /home/runner/work/tket2/tket2/BASELINE_BRANCH/tket/src/passes/inline_funcs.rs:84
InlineFunctionsPass::follow_inline_hints, previously in file /home/runner/work/tket2/tket2/BASELINE_BRANCH/tket/src/passes/inline_funcs.rs:84

   Summary semver requires new major version: 1 major and 0 minor checks failed
  Finished [  90.364s] tket
  Building tket-qec v0.1.0 (current)
     Built [  37.566s] (current)
   Parsing tket-qec v0.1.0 (current)
    Parsed [   0.006s] (current)
  Building tket-qec v0.1.0 (baseline)
     Built [  37.678s] (baseline)
   Parsing tket-qec v0.1.0 (baseline)
    Parsed [   0.006s] (baseline)
  Checking tket-qec v0.1.0 -> v0.1.0 (assume minor change)
   Checked [   0.015s] 196 checks: 196 pass, 56 skip
   Summary no semver update required
  Finished [  76.898s] tket-qec
  Building tket-qsystem v0.24.0 (current)
     Built [  44.416s] (current)
   Parsing tket-qsystem v0.24.0 (current)
    Parsed [   0.026s] (current)
  Building tket-qsystem v0.24.0 (baseline)
     Built [  44.180s] (baseline)
   Parsing tket-qsystem v0.24.0 (baseline)
    Parsed [   0.026s] (baseline)
  Checking tket-qsystem v0.24.0 -> v0.24.0 (assume minor change)
   Checked [   0.059s] 196 checks: 196 pass, 56 skip
   Summary no semver update required
  Finished [  90.285s] tket-qsystem

[acl-cqc]

Thanks Agustin, looks good to me

[acl-cqc]

Suggested change

	Inline the function if we know it won't produce an invalid Hugr.
	Inline the function if possible

or "as much as the compiler is able."

I don't know that infinitely big Hugrs are invalid. I mean, we can't validate them, but if we had infinite memory and address space, validation won't throw an error... ;)

[acl-cqc]

Suggested change

	This is a best effort option; the compiler may choose not to inline
	Whilst this is no guarantees (the compiler may choose not to inline
	functions with this annotation), the compiler should aim to inline whenever possible, ignoring any restrictions due to finite quantities

Or "ignoring quantitative restrictions" or something like that

[aborgna-q]

I'd be cautious of promising what the compiler will do here.
We don't want to be limited by the metadata restrictions when updating the compiler inlining pass.

[acl-cqc]

Just wondering if it's possible to use a Literal["never","best_effort"] instead of this Enum? That might be much simpler?

[aborgna-q]

Yeah, for a public API it may be simpler to do strings. Updated.