Skip to content

docs: Add section on parallel execution semantics#149

Draft
acl-cqc wants to merge 4 commits into
mainfrom
acl/parallel_semantics
Draft

docs: Add section on parallel execution semantics#149
acl-cqc wants to merge 4 commits into
mainfrom
acl/parallel_semantics

Conversation

@acl-cqc

@acl-cqc acl-cqc commented Jun 30, 2026

Copy link
Copy Markdown

closes #143

Note very much DRAFT, and particularly bits in [square brackets] that might be left out (or else formatted normally).

Added as a section of python_differences.md but might want to be a separate document. Can read here: https://github.com/Quantinuum/guppy-docs/blob/acl/parallel_semantics/sphinx/language_guide/python_differences.md#parallel-execution-semantics

Expectations of future releases

I'm assuming that we'll consider a change to the spec (i.e. allowing more reordering) as breaking, but have included a documentation of the v1.0 release with the intention that we can change that behaviour (within the bounds of the parent section) without considering it breaking. Unsure if this is the right approach...

...e.g. a "rolling breakage" model like that proposed for the standard library might be better, although deprecation here is not really practical (we can't tell when people are relying on particular semantics).

Content

I've stated panics can be reordered. I have not said anything specifically about qalloc; by implication, this means

  • we could reorder qalloc vs, say, an array indexing op, and get an "unexpected" change to panic message
  • we could reorder qalloc vs each other. My justification here is that currently the following program fails on an emulator with only one qubit: qalloc(); qalloc() - and it fails with a message guppylang.emulator.exceptions.EmulatorError: Panic (#1001): No more qubits available to allocate. - that is, we're (predictably) panicking, and the message does not specify which qalloc failed, so there is no possibility of surprise even there.

But, I have not said qallocs can be reordered vs. qfree - should I explicitly clarify that this cannot happen? (Similarly, reordering of panic/output is not documented. I think we need that to be fixed for v1.0 where output is used as debug print. Since there is no replacement debug-print yet, I don't think we can really "deprecate" that...)

Re. documented behaviour of 1.0 release, I've investigated the hugrs for a few examples and think this is correct but please shout out if you think otherwise.

```
seeing the message "Index was...." does not necessarily mean that the array access succeeded and thus that i==0; it could also occur for out-of-range i<0.

<!-- on copyable-element arrays, `take` compiles to `get`,

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is just a note, doesn't need to go in

@acl-cqc acl-cqc added this to the guppy-docs V1 milestone milestone Jul 7, 2026
@acl-cqc acl-cqc changed the title Add section on parallel execution semantics docs: Add section on parallel execution semantics Jul 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Docs]: Execution Semantics

1 participant