Guppy execution module (guppy.exec?) that binds Selene interface.

[CalMacCQ]

Now that Selene is open source it gives us an oppurtunity to include Selene as an optional extra when installing Guppy. We can also bind Selene and have a nice interface for Selene as part of Guppy.

Benefits

1. Users only have to install a single package to write/execute Guppy.
2. We can have whatever interface that we like built on top of Selene (no more build needed) -> https://github.com/quantinuum-dev/selene/issues/149

Selene as an optional extra for Guppy

pip install guppylang[exec]

Alternatives pip install guppylang[selene], pip install guppy[emulator]

Initial syntax ideas

from guppylang import guppy
from guppylang.exec import Quest
from hugr.qsystem.result import QsysResult

selene_exec = guppy.build_executable(compiled_hugr) # compiles HUGR -> selene executable

result: QsysResult = guppy.run(selene_exec, Quest(random_seed=5), n_qubits=6, n_shots=1000)

guppy.build_executable would build an object file from a hugr (just like build in selene.

Its probably also worth having a method that builds an object file from guppy source (skipping the hugr step).

We could have guppy.compile_executable or something for this? Although thats possibly confusing if we already have build_executable as well for hugr -> selene executable.

Open to better syntax ideas. These are just initial suggestions.

[jake-arkinstall]

A possible concern with guppy.build_executable is that it isn't clear that the executable is one to be invoked for the purposes of emulation or for a real device. I also wonder if what is being built is an executable is relevant to the user.

guppy.build_emulator could be a nice alternative

[CalMacCQ]

guppy.build_emulator sounds fine to me.

[CalMacCQ]

An alternative would be to pass an arg to guppy.build-executable to indicate whether you're building for an emulator or a real device.

[jake-arkinstall]

guppy.run(selene_exec, Quest(random_seed=5), n_qubits=6, n_shots=1000)

Something I'd really like to know is what a more usable interface to this might be. It seems equivalent to run_shots in selene, and it's an interface I do not like. It is kept around because we already have a lot of code that uses it, but I would definitely like to abstract over it.

Here is the full list of params:

 def run_shots(
        self,
        simulator: Simulator,
        n_qubits: int,
        n_shots: int = 1,
        error_model: ErrorModel = IdealErrorModel(),
        runtime: Runtime = SimpleRuntime(),
        event_hook: EventHook = NoEventHook(),
        verbose: bool = False,
        timeout: datetime.timedelta | None = None,
        results_logfile: Path | None = None,
        random_seed: int | None = None,
        shot_offset: int = 0,
        shot_increment: int = 1,
        n_processes: int = 1,
    ) -> Iterator[Iterator[TaggedResult]]:

There's even one more argument to be added, and already available in 0.1 (internal), that determines whether event hooks are processed via selene or simply kept in the result stream. Put simply - it's a flexible interface but insufficiently structured, and is starting to remind me of another python function that is so highly configurable that it trips me up every time I use it.

---

One thing I have been considering is abstracting it with emulation usecases, e.g.

def coinflip(...)
def classical_replay(...)
# ...

where the simulator args and some other things are pre-baked in (e.g. classical replay should have no error model).

Perhaps from the guppy side of things you have some solid usecases in mind and a top-down approach could be beneficial - forget the selene interface and consider what the perfect interface to those usecases might be, then find a way to connect that to selene.

Then, over time, we can look at the structure that has emerged and see if Selene itself would benefit from adopting it (I hope this to be the case). Stick with a run_shots-like interface and it might make implementation of abstractions in selene a bit more sticky.

[ss2165]

Perhaps from the guppy side of things you have some solid usecases in mind and a top-down approach could be beneficial - forget the selene interface and consider what the perfect interface to those usecases might be, then find a way to connect that to selene.

This is exactly my intent - the current flexibility of run_shots makes this easy to do (hopefully)

[CalMacCQ]

The most obviviously useful args to me as a user are the following

self,
simulator: Simulator,
n_qubits: int,
n_shots: int = 1,
error_model: ErrorModel = IdealErrorModel(),
random_seed: int | None = None

I don't know so much about what the other args do.

[jake-arkinstall]

I'll explain here just in case it plays into the design.

The runtime arg allows a user to provide different optimisation/transport behaviours - e.g. Simple is as eager as it can be (and does RZs), SoftRZ is lazier and doesn't apply RZs, and there are other ones that users need for reliable emulation of on-device behaviour.

event_hook adds additional things into the result stream, like metrics and event logs (for circuit extraction, runtime batch logs, etc).

timeout lets users cap simulation response times. This is more of a diagnostic feature.

shot_offset and shot_increment allows users to only run specific shots. It is similar to python [shot_offset:-1:shot_increment] behaviour, which is useful if you want to reproduce a pattern of shots, spawn off to multiple machines, etc.

n_processes runs sims in parallel on a user-defined number of processes.

results_logfile lets you store a dump of the result stream to a specific file, which you can then use for diagnostics or forwarding to an alternate result stream handler (this gives you an apples-to-apples comparison between hardware and emulation).

[jake-arkinstall]

Ultimately these options came from various user requirements.

Another aspect that is useful for some things and not for others is that the return type of run_shots is not a list of results, but an iterator.

The shot result is yielded one by one as the result stream comes in. This is needed if you want to output per-shot information, interrupt the simulation without waiting for everything to finish, add a tqdm progress bar, etc.

It would be a sensible default for guppy's runner to return a list but, internally, wrap the run_shots call into tqdm. I also think it would be useful to detect panics and still offer the intermediate results (gathered through the run_shots iterator), as naively wrapping run_shots into a list will lose all of the information gathered about shots that were successfully simulated before the shot with the panic.

[CalMacCQ]

Thanks for the explanation :)

With the exception of n_processes and shot_offset It seems like these extra args you described are more suited to debugging/logging use cases. Maybe there could be a different interface for that somehow?