feat!: runtime entrypoint arguments via generic tket.argreader op by ss2165 · Pull Request #1731 · Quantinuum/tket2

ss2165 · 2026-06-19T16:11:00Z

Runtime entrypoint arguments (`tket.argreader`)

Based on #1682 (originally by @jake-arkinstall).

What this does

Lets a compiled user program read runtime arguments at the entrypoint, so a program can be compiled once and run many times with different parameters (the motivating use case is variational workloads like QAOA, where today every parameter update forces a recompile).

Dependant guppy PR: Quantinuum/guppylang#1890

The argreader extensionexposes one generic read_arg<Tag, T> op that is parametrised by string tag (like result) and the type it outputs.
tket-qsystem: argreader extension definition (extension/argreader.rs) and LLVM lowering (llvm/argreader.rs, llvm/prelude.rs). Roughly mirrors result codegen. However, this new op can create new arrays so needs allocation in ArrayLowering.
tket-exts: ships the tket.argreader extension JSON + Python bindings.
qis-compiler: wires the argreader plugin into codegen; regenerated test HUGRs and LLVM/selene snapshots (the large diff is almost entirely regenerated snapshot fixtures).

BREAKING CHANGE: ArrayLowering trait has new required method alloc_array for allocating a fresh array.

codecov · 2026-06-19T16:14:32Z

Codecov Report

❌ Patch coverage is 90.53254% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.35%. Comparing base (1281928) to head (3c06d0c).

Files with missing lines	Patch %	Lines
tket-qsystem/src/extension/argreader.rs	81.60%	14 Missing and 2 partials ⚠️
tket-qsystem/src/llvm/argreader.rs	93.98%	7 Missing and 6 partials ⚠️
tket-qsystem/src/extension.rs	0.00%	2 Missing ⚠️
tket-qsystem/src/llvm/array_utils.rs	88.88%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1731      +/-   ##
==========================================
+ Coverage   85.29%   85.35%   +0.06%     
==========================================
  Files         191      194       +3     
  Lines       30355    30692     +337     
  Branches    28986    29299     +313     
==========================================
+ Hits        25890    26196     +306     
- Misses       3240     3262      +22     
- Partials     1225     1234       +9

Flag	Coverage Δ
python	`91.92% <100.00%> (+0.15%)`	⬆️
qis-compiler	`92.59% <ø> (ø)`
rust	`85.03% <89.80%> (+0.05%)`	⬆️

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

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

from PR #1682 Initial concept of entrypoint arg lowering using selene's argreader utility Restore debug path stripping, but just strip the paths to keep the IR valid cargo fmt Anyhow is now not behind a feature flag Add simple documentation to satisfy clippy (will likely need elaboration)

- Remove ArgumentReadOpDef (8 variants) and replace with ReadArgOpDef { ReadArg } - Replace ArgumentReadOp/SimpleArgs/ReadArgs with ReadArgOp { tag, output_type } - Delete map_type and wrap_entrypoint_with_arguments (surgery will live in guppy) - Add ArgKind enum + classify_arg_type() for type-driven LLVM dispatch - Add ReadArgBuilder trait for ergonomic graph construction - Rewrite LLVM lowering with type-driven dispatch and emit_array_read helper - Add 13 extension unit tests and 7 LLVM lowering snapshot tests - Add Default derive to QISPreludeCodegen for test setup - Remove 'entry_args' from Python test parametrize (no guppy changes yet) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add argreader::EXTENSION to qsystem_extensions() so it is serialized - Regenerate tket-exts/src/tket_exts/data/tket/argreader.json - Add ArgReaderExtension Python wrapper with read_arg() helper - Register argreader in tket_exts __init__ and tket_registry() - Add validation test fixture for the argreader extension Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…sting Move ArgKind, classify_arg_type and the scalar/array classification helpers out of the HUGR extension definition and into the LLVM lowering module, since classification is purely a codegen concern. - Identify types via full Type comparison against the canonical tables (INT_TYPES, bool_t, float64_type) and the borrow_array TypeDef, instead of flakily matching on bare extension ids. - Reject integer widths other than i64 (log-width 6) at codegen time, where the get_i64 selene extern is the only integer reader; the extension layer stays permissive about width. - Revert anyhow back to an optional dependency in tket-qsystem, gated by the cli + llvm features, now that the only non-llvm anyhow user has moved. - qis-compiler: enable module.verify() after codegen and validate that the entrypoint has no leftover input parameters (all args must flow through read_arg ops). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Mirror the result/debug codegen by making argreader operate on the standard `array` type through the existing `ArrayLowering` abstraction, instead of being hard-wired to `borrow_array`. - Add `alloc_array` to the `ArrayLowering` trait (argreader produces arrays, whereas result only consumes them) and implement it for `HeapArrayLowering` via `array::build_array_alloc`. - Make `ArgReaderCodegenExtension` generic over `AL: ArrayLowering`; allocate + wrap the extern-filled buffer with `alloc_array` + `array_from_ptr`. - Classify the standard `array` typedef (`as_borrow_array` -> `as_std_array`). - Wire argreader with `SeleneHeapArrayCodegen::LOWERING` in qis-compiler, the same lowering result/debug use; the bespoke borrow-array path is gone. - Tests + snapshots updated to standard arrays; classification and narrow-int rejection unchanged. The asymmetry that motivated this is a guppy compilation choice: guppy bridges borrow_array -> standard array before `result`, so the matching bridge will be added before `read_arg` in the guppy entrypoint wrapper. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

hugrbot · 2026-06-22T11:21:34Z

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.20.0 (current)
     Built [  46.422s] (current)
   Parsing tket v0.20.0 (current)
    Parsed [   0.127s] (current)
  Building tket v0.20.0 (baseline)
     Built [  45.098s] (baseline)
   Parsing tket v0.20.0 (baseline)
    Parsed [   0.119s] (baseline)
  Checking tket v0.20.0 -> v0.20.0 (assume minor change)
   Checked [   0.132s] 196 checks: 196 pass, 57 skip
   Summary no semver update required
  Finished [  93.457s] tket
  Building tket-qsystem v0.26.0 (current)
     Built [  46.921s] (current)
   Parsing tket-qsystem v0.26.0 (current)
    Parsed [   0.037s] (current)
  Building tket-qsystem v0.26.0 (baseline)
     Built [  46.039s] (baseline)
   Parsing tket-qsystem v0.26.0 (baseline)
    Parsed [   0.034s] (baseline)
  Checking tket-qsystem v0.26.0 -> v0.26.0 (assume minor change)
   Checked [   0.066s] 196 checks: 195 pass, 1 fail, 0 warn, 57 skip

--- failure trait_method_added: pub trait method added ---

Description:
A non-sealed public trait added a new method without a default implementation, which breaks downstream implementations of the trait
      ref: https://doc.rust-lang.org/cargo/reference/semver.html#trait-new-item-no-default
     impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.48.0/src/lints/trait_method_added.ron

Failed in:
trait method tket_qsystem::llvm::array_utils::ArrayLowering::alloc_array in file /home/runner/work/tket2/tket2/PR_BRANCH/tket-qsystem/src/llvm/array_utils.rs:53

   Summary semver requires new major version: 1 major and 0 minor checks failed
  Finished [  94.942s] tket-qsystem

Copilot

Pull request overview

Adds a new tket.argreader HUGR extension and LLVM lowering to enable reading runtime-provided entrypoint arguments (scalars and fixed-size arrays), wiring it through tket-qsystem, tket-exts, and qis-compiler, with updated snapshot fixtures.

Changes:

Introduces tket.argreader extension (Rust + JSON + Python bindings) with a generic read_arg<tag, T>() -> T op.
Implements LLVM codegen for read_arg, including array allocation support via a new ArrayLowering::alloc_array method.
Integrates the argreader codegen into qis-compiler and updates LLVM snapshot fixtures accordingly.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tket-qsystem/src/llvm/argreader.rs	New LLVM lowering for `tket.argreader` ops, including scalar/array variants and tests.
tket-qsystem/src/llvm/array_utils.rs	Extends `ArrayLowering` with `alloc_array` and implements it for heap lowering.
tket-qsystem/src/llvm/prelude.rs	Makes `QISPreludeCodegen` `Default` (and still `Clone`).
tket-qsystem/src/llvm.rs	Exposes the new `llvm::argreader` module.
tket-qsystem/src/extension/argreader.rs	Defines the `tket.argreader` extension and `ReadArgOp` plumbing + tests.
tket-qsystem/src/extension.rs	Registers the new extension in the qsystem extension list/registry.
tket-qsystem/src/llvm/snapshots/tket_qsystem__llvm__argreader__test__emit_argreader_codegen@pre-mem2reg@llvm21_1.snap	New snapshot fixture for argreader scalar bool (pre-mem2reg).
tket-qsystem/src/llvm/snapshots/tket_qsystem__llvm__argreader__test__emit_argreader_codegen@pre-mem2reg@llvm21_2.snap	New snapshot fixture for argreader scalar int (pre-mem2reg).
tket-qsystem/src/llvm/snapshots/tket_qsystem__llvm__argreader__test__emit_argreader_codegen@pre-mem2reg@llvm21_3.snap	New snapshot fixture for argreader scalar f64 (pre-mem2reg).
tket-qsystem/src/llvm/snapshots/tket_qsystem__llvm__argreader__test__emit_argreader_codegen@pre-mem2reg@llvm21_4.snap	New snapshot fixture for argreader bool array (pre-mem2reg).
tket-qsystem/src/llvm/snapshots/tket_qsystem__llvm__argreader__test__emit_argreader_codegen@pre-mem2reg@llvm21_5.snap	New snapshot fixture for argreader i64 array (pre-mem2reg).
tket-qsystem/src/llvm/snapshots/tket_qsystem__llvm__argreader__test__emit_argreader_codegen@pre-mem2reg@llvm21_6.snap	New snapshot fixture for argreader f64 array (pre-mem2reg).
tket-qsystem/src/llvm/snapshots/tket_qsystem__llvm__argreader__test__emit_argreader_codegen@llvm21_1.snap	New snapshot fixture for argreader scalar bool (post-opt).
tket-qsystem/src/llvm/snapshots/tket_qsystem__llvm__argreader__test__emit_argreader_codegen@llvm21_2.snap	New snapshot fixture for argreader scalar int (post-opt).
tket-qsystem/src/llvm/snapshots/tket_qsystem__llvm__argreader__test__emit_argreader_codegen@llvm21_3.snap	New snapshot fixture for argreader scalar f64 (post-opt).
tket-qsystem/src/llvm/snapshots/tket_qsystem__llvm__argreader__test__emit_argreader_codegen@llvm21_4.snap	New snapshot fixture for argreader bool array (post-opt).
tket-qsystem/src/llvm/snapshots/tket_qsystem__llvm__argreader__test__emit_argreader_codegen@llvm21_5.snap	New snapshot fixture for argreader i64 array (post-opt).
tket-qsystem/src/llvm/snapshots/tket_qsystem__llvm__argreader__test__emit_argreader_codegen@llvm21_6.snap	New snapshot fixture for argreader f64 array (post-opt).
tket-exts/src/tket_exts/data/tket/argreader.json	Ships the extension definition JSON for `tket.argreader`.
tket-exts/src/tket_exts/tket/argreader.py	Adds Python API surface for `read_arg`.
tket-exts/src/tket_exts/tket/init.py	Exports `argreader` submodule.
tket-exts/src/tket_exts/init.py	Registers/exports `ArgReaderExtension` in the public extension registry.
tket-exts/tests/test_validate_exts.py	Adds validation coverage for the new extension export + op instantiation.
qis-compiler/rust/lib.rs	Wires `ArgReaderCodegenExtension` into codegen extension set.
qis-compiler/python/tests/snapshots/test_basic_generation/test_llvm/sol-x86_64-windows-msvc-entry_args/entry_args_x86_64-windows-msvc_sol	Updated LLVM snapshot for entry-args on sol (windows x86_64).
qis-compiler/python/tests/snapshots/test_basic_generation/test_llvm/sol-x86_64-unknown-linux-gnu-entry_args/entry_args_x86_64-unknown-linux-gnu_sol	Updated LLVM snapshot for entry-args on sol (linux x86_64).
qis-compiler/python/tests/snapshots/test_basic_generation/test_llvm/sol-x86_64-apple-darwin-entry_args/entry_args_x86_64-apple-darwin_sol	Updated LLVM snapshot for entry-args on sol (macOS x86_64).
qis-compiler/python/tests/snapshots/test_basic_generation/test_llvm/sol-aarch64-apple-darwin-entry_args/entry_args_aarch64-apple-darwin_sol	Updated LLVM snapshot for entry-args on sol (macOS aarch64).
qis-compiler/python/tests/snapshots/test_basic_generation/test_llvm/helios-x86_64-windows-msvc-entry_args/entry_args_x86_64-windows-msvc_helios	Updated LLVM snapshot for entry-args on helios (windows x86_64).
qis-compiler/python/tests/snapshots/test_basic_generation/test_llvm/helios-aarch64-apple-darwin-entry_args/entry_args_aarch64-apple-darwin_helios	Updated LLVM snapshot for entry-args on helios (macOS aarch64).
qis-compiler/pyproject.toml	Expands uv cache keys to include upstream Rust sources so rebuilds invalidate correctly.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ss2165 mentioned this pull request Jun 19, 2026

feat: runtime entrypoint arguments for the emulator Quantinuum/guppylang#1890

Draft

ss2165 force-pushed the ss/argreader branch 4 times, most recently from 8781aed to 46fdd23 Compare June 22, 2026 10:10

ss2165 changed the base branch from main to ss/regen June 22, 2026 10:10

Base automatically changed from ss/regen to main June 22, 2026 10:37

jake-arkinstall and others added 6 commits June 22, 2026 12:16

minor cleanups

974a615

ss2165 force-pushed the ss/argreader branch from 9a6e5ad to 3c06d0c Compare June 22, 2026 11:16

ss2165 changed the title ~~feat: runtime entrypoint arguments via generic tket.argreader op~~ feat!: runtime entrypoint arguments via generic tket.argreader op Jun 22, 2026

ss2165 requested a review from Copilot June 22, 2026 12:40

ss2165 marked this pull request as ready for review June 22, 2026 12:40

ss2165 requested a review from a team as a code owner June 22, 2026 12:40

ss2165 requested a review from maximilianruesch June 22, 2026 12:40

Copilot started reviewing on behalf of ss2165 June 22, 2026 12:41 View session

Copilot AI reviewed Jun 22, 2026

View reviewed changes

Comment thread tket-qsystem/src/llvm/argreader.rs

Comment thread tket-qsystem/src/llvm/argreader.rs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat!: runtime entrypoint arguments via generic tket.argreader op#1731

feat!: runtime entrypoint arguments via generic tket.argreader op#1731
ss2165 wants to merge 6 commits into
mainfrom
ss/argreader

ss2165 commented Jun 19, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Jun 19, 2026 •

edited

Loading

Uh oh!

hugrbot commented Jun 22, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

ss2165 commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Runtime entrypoint arguments (tket.argreader)

What this does

Uh oh!

codecov Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

hugrbot commented Jun 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ss2165 commented Jun 19, 2026 •

edited

Loading

Runtime entrypoint arguments (`tket.argreader`)

codecov Bot commented Jun 19, 2026 •

edited

Loading