A Runtime for the Compile-time (bqskit.runtime)

This package provides an execution environment for compiler passes, enabling them to parallelize and distribute their workload efficiently.

Launching a Server

To parallelize BQSKit compilations, you can launch a BQSKit Runtime server in either attached or detached mode, and submit a CompilationTask through a connected Compiler.

By default, a compiler will automatically start and connect to an attached runtime server during initialization. In this mode, the compiler starts up and shuts down the server automatically and transparently to the end user. See AttachedServer for more info.

A server running in attached mode is limited to a single machine. If you would like to parallelize BQSKit across multiple nodes over a network, you can launch a server independently in detached mode. Here, you first start Manager processes on all machines. Then link them all together by running a DetachedServer process, which Compilers’ can connect to by passing the appropriate address in their constructor.

Upon installing BQSKit, two shell scripts are added to your environment that can spawn managers and detached servers:



bqskit-server <address_of_bqskit_managers>

Typically, you start managers first on all nodes in the desired cluster. Then you can start the server with a comma-separated list of all managers ip address and optionally ports. Once a server is started and has connected to the requested managers, no more managers can be added. You can see the -h option of each command or the start_server() and start_manager() entry points for more information.

For more information on how to manage jobs submitted to a runtime server, see the compiler documentation.

AttachedServer([num_workers, port, worker_port])

BQSKit Runtime Server in attached mode.

DetachedServer(ipports[, port])

BQSKit Runtime Server in detached mode.

Manager([port, num_workers, ipports, ...])

BQSKit Runtime Manager.


Entry point for a detached runtime server process.


Entry point for runtime manager processes.


Entry point for spawning a rank of runtime worker processes.

Parallelize Pass Computation

When developing a BQSKit compiler pass, you can hook into the active runtime server through the get_runtime() function. This returns a RuntimeHandle, which you can use to submit, map, wait on, and cancel tasks in the execution environment.

For more information on how to design a custom pass, see this (TODO, sorry, you can look at the source code of existing passes for a good example for the time being).


Return a handle on the active runtime.

RuntimeHandle(*args, **kwargs)

A structural type capturing BQSKit Runtime capabilities.


An awaitable future.

Standard Logging Interface

This system uses the standard python logging module to provide a familiar logging interface. On client processes – the ones where you create the Compiler object – you can configure python loggers like normal before submitting tasks and have the entire system honor that configuration.