GraphBuilder->Graph with separate Workflow type by acl-cqc · Pull Request #381 · Quantinuum/tierkreis

acl-cqc · 2026-03-04T08:52:34Z

Add parametrized Workflow holding a GraphData and outputs_type.
GraphBuilder renamed to Graph, and .outputs renamed to .finish_with_outputs which returns a Workflow
- TODO: Rename finish_with_outputs to build??
Change methods that take Graph(Builders) (e.g. loop, eval) to take Workflow's, removing check in embed that the Output node is present (this is now guaranteed if your python code is well-typed - I was surprised not to find more such checks in map/loop/eval/const/etc.)
Add a ModelConvertible protocol like DictConvertible/etc. but that works for parametrized types. (This was a bit of a can of worms, there are some slightly suspect bits in types.py.) Workflow implements this, and serializes as a GraphData. (Type erasure: Workflow is a build-time-only construct).
- This was in commit 6ccf080, previously I included Workflow in the union of PType's which was a bit hacky (special-case, awkward circular import, etc.) but a lot shorter/easier (and DictConvertible makes me worry about robustness and parametrization). Thoughts?
Update stub generator to support TNamedModel's as well as PModel Structs (by adding an is_ptype field to GenericType - this is not super-neat, suggestions of better ways to do this welcome, but my previous attempt was even (much) worse]: 454c18f)
- It'd be good to remove @runtime_checkable from the RestrictedNamedTuple subclasses/instantiations, but leaving that for Another PR
Update test functions, docs/notebooks, etc., and test worker (including tests from tests: more fun with workers making graphs #392) to take/return parametrized Workflow rather than GraphData. This was a bit tedious, and the bulk of changed files in the PR... I have tried to update the text of the docs a little but there is a lot of use of the word "graph" to mean either an unfinished one or a finished one, and trying to distinguish which of those should be workflows is...tricky. This may suggest calling the two classes GraphBuilder and Graph rather than Graph and Workflow???

The end result is that you need fewer TypedGraphRefs (but still some), and when you do need one, pyright should catch cases of providing the wrong outputs_type (because this is now just a runtime reification of a type that pyright knows statically).

Other possible TODOs (maybe too much for one PR??)

Remove output type from Graph (and provide when you set the outputs)? This would mean splitting the class hierarchy i.e. we'd need a parent _BaseGraph[Inputs] with all methods except finish_with_outputs and graph_ref, then class Graph[Inputs](_BaseGraph[Inputs]): ...fn finish_with_outputs[Outputs](self, outputs_type: type[Outputs], outputs: Outputs) and separately class RecursiveGraph[Inputs,Outputs](_BaseGraph[Inputs]): ...fn finish_with_outputs(self, outputs: Outputs) plus fn graph_ref(self). Not sure whether this is worth it so I think leave for another PR?
We have quite a few tests that build GraphData's directly (not using the builder)....if we want the builder to be the only supported way of building graphs, we'll need to update these too.
- If we do that, then this would allow hiding GraphData (i.e. making private, this is python) where it is used in the builder, so GraphData is really part of the graph runtime, not part of the user-facing graph-building API.

…puts_type before outputs_type (#391) Also remove some overloads that seem pointless (??), and tidy some imports Removing generics_in_ptype as a preliminary to #381 because it's hard to handle parametrized FinishedGraph. `TypedGraphRef[Inputs, Outputs]` was constructed via `TypedGraphRef(outputs_type, inputs_type)`, so reorder the latter. (Although the `inputs_type` field is unused it helps `pyright` figure out the `Inputs` type parameter when in strict mode or with `reportUnknownVariableType` so keep it for now.)

…isualizer??

…ke & stubs import FinGraph, regen stubs+import FinishedGraph...tests pass but pyright fails

…out Struct

acl-cqc · 2026-03-09T14:14:59Z

-        graph: GraphBuilder[A, B],
+        graph: FinishedGraph[A, B],
    ) -> TypedGraphRef[A, B]:
        # TODO @philipp-seitz: Turn this into a public method?


I'd +1 this, shall I do it in this PR?

Go for it if it's a simple change

Was gonna leave this until we could unify TKR[Workflow...] and TypedGraphRef but now I realise that we can't - the former is a handle to a Workflow that will have outputs_type when it appears, whereas TypedGraphRef gives us that outputs_type right now.

So, yes, done, removing a #noqa

rossduncan · 2026-03-09T22:45:55Z

Why do we need both FinishedGraph and GraphData ?

acl-cqc · 2026-03-10T09:18:31Z

Why do we need both FinishedGraph and GraphData ?

As per last paragraph in the description (TODOs/future work):

We have quite a few tests that build GraphData's directly (not using the builder)....if we want the builder to be the only supported way of building graphs, we'll need to update these too.

If we do that, then this would allow hiding GraphData (i.e. making private, this is python) where it is used in the builder, so GraphData is really part of the graph runtime, not part of the user-facing graph-building API.

I.e. I think we need GraphData as an internal struct, for (a) serialization, and (b) passing from GraphBuilder into FinishedGraph, but we could hide it from the user with more updates to tests etc. Except this may restrict partial in the future, we should do a bit of investigation.

…es from types.py (still defined at bottom)

johnchildren

I have some small comments but I think we can likely proceed with merging with or/without them

johnchildren · 2026-03-26T10:23:17Z

 from typing import NamedTuple

-from tierkreis.builder import GraphBuilder
+from tierkreis.builder import Graph


Entirely a vanity thing but do we want to change the module where we import this from as well? I don't think it matters too much though. Possibly we should at least re-export Graph from the root module.

johnchildren · 2026-03-26T10:32:51Z

    outs_str = "\n    ".join(outs)

-    bases = ["NamedTuple"] if is_portmapping else ["Struct", "Protocol"]
+    def is_tmodel() -> bool:


Is it worth moving this out into a top level function? As far as I can tell it only captures model from the outer scope.

Or a method on tierkreis.idl.models.Model ?

Yes that could make sense as we know we have a Model at this point, I don't have a preference.

Moved to a function on Model, admittedly it is a little bit dubious because GenericType.is_ptype itself is a bit dubious (i.e. we only really know if we build the GenericType from a type)

johnchildren · 2026-03-26T10:51:45Z

-        graph: GraphBuilder[A, B],
+        graph: FinishedGraph[A, B],
    ) -> TypedGraphRef[A, B]:
        # TODO @philipp-seitz: Turn this into a public method?


Go for it if it's a simple change

johnchildren · 2026-03-26T10:59:16Z

        :rtype: TypedGraphRef[Inputs, Outputs]
        """
-        return TypedGraphRef((-1, "body"), self.inputs_type, self.outputs_type)
+        return TypedGraphRef(TKR(-1, "body"), self.outputs_type)


I think this might be the first time we are constructing TKR directly rather than using ValueRef. I don't really object to this but we might want to clarify what the distinction between the two is meant to be later.

Not the first time - existing cases in ifelse, eifelse, and _map_fn_single_in in this file. I am not really sure what the difference is - is it just that TKR is parametrized (TKR[T: PModel]) whereas ValueRef is not? (in which case we might want to combine them?? one can always use x: TKR without specifying the type argument)

fwiw, TKR has a method for returning a ValueRef.

Yeah possibly TKR carries type information while ValueRef doesn't then? Worth reviewing again at a later date.

…references from types.py (still defined at bottom)" This reverts commit 6ccf080.

johnchildren · 2026-03-30T13:58:20Z


+    if issubclass(origin, Workflow):
+        _inputs, outputs = get_args(annotation)
+        return annotation(coerce_from_annotation(ser, GraphData), outputs)  # type: ignore


annotation(output_type=outputs, **ser)

Could work if we want to do something minimal that allows type erasure.

This reverts commit c5bb444.

acl-cqc · 2026-03-30T15:31:28Z

Reverted to listing Workflow in the big union of possible PTypes after pydantic BaseModel didn't like a field of type[Outputs] when Outputs = TKR[int]...boo :-(

acl-cqc mentioned this pull request Mar 4, 2026

refactor: remove unused generics_in_ptype/model, put TypedGraphRef.inputs_type before outputs_type #391

Merged

acl-cqc force-pushed the acl/finished-graph branch from e8d272b to 7e92fcb Compare March 4, 2026 21:41

acl-cqc changed the base branch from main to acl/tidy_types March 4, 2026 21:54

acl-cqc force-pushed the acl/finished-graph branch 4 times, most recently from dc8ba1f to e8ce026 Compare March 4, 2026 22:08

acl-cqc force-pushed the acl/tidy_types branch from 485d82f to db22a10 Compare March 4, 2026 22:08

acl-cqc changed the title ~~Split FinishedGraph off from GraphBuilder~~ Split FinishedGraph off from GraphBuilder, return from worker Mar 4, 2026

acl-cqc commented Mar 4, 2026

View reviewed changes

Comment thread tierkreis_visualization/tierkreis_visualization/visualize_graph.py Outdated

acl-cqc added 2 commits March 5, 2026 10:32

add some interesting functions to worker (and, update justfile)

c2391c4

tests

9f1bf66

acl-cqc mentioned this pull request Mar 5, 2026

tests: more fun with workers making graphs #392

Merged

Base automatically changed from acl/tidy_types to main March 5, 2026 17:49

acl-cqc added 11 commits March 5, 2026 17:52

Merge remote-tracking branch 'origin/main' into acl/test_worker_graphs

4307b17

Hide ApplyTwiceInput

75e2a38

Test that GraphData is a PType

de7aca6

Define FinishedGraph, return instead of GraphBuilder via GB.outputs(...)

692b563

GraphBuilder: declare inputs_type

05a29f3

FinishedGraph: frozen=True, remove get_data()

1f8a6a7

Rename GraphBuilder.(=>finish_with_)outputs

4a7bd52

Move FinishedGraph into types.py (but keep imports via builder for now)

d0fbe1d

types.py: include FinishedGraph in PType

aed05b0

Remove GraphBuilder.get_data(), test worker returns FinishedGraph - v…

3f47680

…isualizer??

Test roundtrip of a FinishedGraph, given annotation; fix

6600e54

acl-cqc force-pushed the acl/finished-graph branch from e8ce026 to 969cd0f Compare March 5, 2026 22:31

acl-cqc commented Mar 5, 2026

View reviewed changes

Comment thread tierkreis/tests/workers/graph/stubs.py Outdated

acl-cqc added 2 commits March 5, 2026 22:45

TypedGraphRef = TKR[FinishedGraph...]+reified inputs, worker funcs ta…

5794e3f

…ke & stubs import FinGraph, regen stubs+import FinishedGraph...tests pass but pyright fails

fix pyright by Manually copying ApplyTwiceInput from main to stubs w/…

acfdfa5

…out Struct

Update ipynb's + md's, bleurgh

419c026

acl-cqc commented Mar 9, 2026

View reviewed changes

Comment thread tierkreis/tierkreis/builder.py Outdated

acl-cqc commented Mar 9, 2026

View reviewed changes

Default GenericType to represent ptype in order to fix parsed types

138f028

acl-cqc requested a review from johnchildren March 9, 2026 14:37

acl-cqc added 2 commits March 15, 2026 21:23

Rename FinishedGraph -> Workflow

1543bfa

GraphBuilder -> Graph

deabc7a

acl-cqc changed the title ~~Split FinishedGraph off from GraphBuilder, return from worker~~ GraphBuilder->Graph with separate Workflow type Mar 16, 2026

acl-cqc added 2 commits March 16, 2026 12:03

Revert/reduce change to test_types.py

e30c5bb

Add ModelConvertible, allowing parametrized; Remove Workflow referenc…

6ccf080

…es from types.py (still defined at bottom)

acl-cqc force-pushed the acl/finished-graph branch from 07f9b93 to 6ccf080 Compare March 16, 2026 12:03

acl-cqc added 2 commits March 16, 2026 12:14

Visualizer: restore use of Graph

4910e5d

doc improvements

76f8160

johnchildren reviewed Mar 26, 2026

View reviewed changes

Revert "Add ModelConvertible, allowing parametrized; Remove Workflow …

6470fcc

…references from types.py (still defined at bottom)" This reverts commit 6ccf080.

johnchildren reviewed Mar 30, 2026

View reviewed changes

acl-cqc added 7 commits March 30, 2026 15:20

Move Workflow back into Models by inheriting BaseModel

c5bb444

Revert "Move Workflow back into Models by inheriting BaseModel"

9224cfb

This reverts commit c5bb444.

Merge remote-tracking branch 'origin/main' into acl/finished-graph

f759fa1

Reinstate sphinx docs on types

fe8b0ce

Move is_tmodel to models.py::is_pmodel

cd50b21

doc GenericType.is_ptype

ce5daee

_graph_const -> graph_const

0ce3a34

acl-cqc requested a review from johnchildren March 30, 2026 15:30

johnchildren approved these changes Mar 30, 2026

View reviewed changes

johnchildren merged commit a82f490 into main Mar 30, 2026
13 checks passed

johnchildren deleted the acl/finished-graph branch March 30, 2026 15:47

Conversation

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

Uh oh!

Uh oh!

Uh oh!

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!

rossduncan commented Mar 9, 2026

Uh oh!

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

Uh oh!

Uh oh!

johnchildren left a comment

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!

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!

acl-cqc commented Mar 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

acl-cqc commented Mar 4, 2026 •

edited

Loading

acl-cqc commented Mar 10, 2026 •

edited

Loading