Runtime

The execution-facing layer: the contract every backend adapter implements, the configuration model, and the command-line entry point.

Executor

Base abstraction for quantum circuit executors.

This module defines the contract that all quantum backend adapters must implement, including circuit creation, application construction, and application execution.

It belongs to the runtime layer, so imports from backend-specific packages such as netqasm or cunqa must not appear here.

class netqmpi.runtime.executor.Executor

Bases: ABC

Abstract base class for quantum backend executors.

This interface combines three responsibilities into a single adapter contract:

1. Circuit factory through create_circuit().

2. Application builder through build_apps().

3. Application runner through run().

Variables:

• size – Number of nodes or resources managed by the executor.

• config – Backend-specific configuration dictionary.

__init__(size, config)

Initialize the executor.

Parameters:

• size (int) – Number of available nodes or resources.

• config (RunConfig) – Backend-specific configuration dictionary.

Return type:

None

property size: int

Return the number of nodes or resources managed by this executor.

Returns:

The executor size.

property config: Dict[str, Any]

Return the backend-specific configuration.

Returns:

The configuration dictionary.

abstractmethod create_circuit(num_qubits, num_clbits, comm)

Create a backend-specific quantum circuit.

Parameters:

• num_qubits (int) – Number of qubits in the circuit.

• num_clbits (int) – Number of classical bits in the circuit.

• comm (QMPICommunicator) – Communicator associated with the circuit.

Returns:

A backend-specific Circuit.

Return type:

Circuit

abstractmethod build_apps(file, size)

Load a script and build the rank-specific application instances.

Each rank receives an injected Environment exposing this executor’s create_circuit() factory.

Parameters:

• file (str) – Path to the NetQMPI Python script. It must contain a main(env=None) function.

• size (int) – Number of parallel quantum nodes to simulate.

Returns:

A backend-specific application instance ready to be passed to run().

Return type:

Any

abstractmethod run(apps)

Execute an application instance with the given configuration.

Parameters:

• app_instance – Object returned by build_apps().

• config – Simulation or execution parameters. Backend adapters may accept a subclass of RunConfig with additional backend-specific fields.

• apps (Any)

Return type:

None

Run configuration

Backend-agnostic configuration for running a NetQMPI application.

This module defines a runtime configuration object that uses only primitive Python types, ensuring that the runtime layer remains fully decoupled from any specific backend (e.g. NetQASM, CUNQA, Qoala).

Backend adapters may subclass RunConfig to introduce additional fields required by their simulator or hardware. All configuration is loaded from a single YAML file (see read_config_block()) instead of per-backend command-line flags, so the CLI stays small as backends grow.

class netqmpi.runtime.run_config.RunConfig

Bases: object

Configuration for a single NetQMPI simulation run.

All fields rely on plain Python types. Backend-specific parameters (such as NetQASM formalism or Qoala qdevice noise) should be provided by subclasses defined in the corresponding adapter packages.

Variables:

shots (int) – Number of times the simulation is repeated.

shots: int = 1024

classmethod from_dict(data)

Build a config from a plain dict, mapping keys to dataclass fields.

Unknown keys raise ValueError so typos in a YAML config surface immediately instead of being silently ignored. Subclasses with nested/structured fields (e.g. a qdevice block) should override this to translate those keys before delegating here.

Parameters:

data (Dict[str, Any]) – Mapping of field names to values.

Returns:

A config instance of cls.

Return type:

_T

__init__(shots=1024)

Parameters:

shots (int)

Return type:

None

netqmpi.runtime.run_config.read_config_block(path, backend)

Read a NetQMPI YAML config file and return the settings for one backend.

The file mixes generic (shared) settings at the top level with optional per-backend blocks keyed by backend name. Only the block for backend is merged on top of the generic settings; blocks for other backends are ignored. Example:

shots: 1000
seed: 7
qoala:
  link_fidelity: 0.8
  hardware:
    t1: 0

Reading this with backend="qoala" yields {"shots": 1000, "seed": 7, "link_fidelity": 0.8, "hardware": {...}}.

Parameters:

• path (str) – Path to the YAML config file.

• backend (str) – Backend whose block should be merged in.

Returns:

The merged settings dict, ready for RunConfig.from_dict.

Raises:

ValueError – If the file or the backend block is not a mapping.

Return type:

Dict[str, Any]

Command-line interface

NetQMPI command-line entry point.

This module is intentionally free of backend-specific imports from the core runtime logic. All simulator-specific behavior is delegated to an Executor implementation provided by the corresponding adapter package.

netqmpi.runtime.cli.simulate(script, num_procs=1, executor=None, config=None, timer=False)

Build and run a NetQMPI script using the given backend executor.

Parameters:

• script (str) – Path to the NetQMPI Python script.

• num_procs (int) – Number of parallel quantum nodes.

• executor (Executor | None) – Backend executor to use. If None, a NetQASMExecutorAdapter is used by default.

• config (RunConfig | None) – Simulation parameters. If None, a default RunConfig instance is used.

• timer (bool) – If True, print the wall-clock execution time.

Return type:

None

netqmpi.runtime.cli.main()

Parse command-line arguments and execute the requested NetQMPI script.

The selected backend adapter is instantiated from the provided flags and passed to simulate().

Helpers

netqmpi.helpers.load_main(path)