Command-line interface¶

NetQMPI installs a single console entry point, netqmpi, defined in netqmpi.runtime.cli.

netqmpi -n <NUM_NODES> <script.py> [--cunqa | --netqasm | --aer | --qoala]
        [--shots N] [--config config.yaml]

Arguments¶

-n, --num-procs (required)

Number of parallel quantum nodes — the communicator size. Must be at least 1.

script (required, positional)

Path to the NetQMPI Python script. It must be a .py file defining a main() function; both conditions are checked before anything is built.

--cunqa / --netqasm / --aer / --qoala

Backend selection. Mutually exclusive. If none is given, NetQMPI falls back to NetQASM and says so:

No backend flag; using default (NetQASM)

--shots N

Number of shots. Overrides the value in --config, if any, so a quick run can bump the shot count without editing the file. Defaults to 1024.

--config PATH

Path to a YAML file with generic settings and an optional per-backend block. This replaces per-backend command-line flags — see Configuration.

Examples¶

# The reference backend, attaching to already-raised vQPUs
netqmpi -n 3 examples/3_scatter.py --cunqa --shots 1024

# ... with a hardware/vQPU configuration file
netqmpi -n 3 examples/5_qft_expose.py --cunqa --config cunqa.yaml

# Quantum-network simulation
netqmpi -n 2 examples/1_send_recv.py --netqasm

# Circuit simulation, no special setup needed
netqmpi -n 2 examples/1_send_recv.py --aer --shots 1024

# Node execution environment, with a noise model
netqmpi -n 2 examples/1_send_recv.py --qoala --config qoala.yaml

Which NetQMPI is this?¶

netqmpi --version
# NetQMPI 0.3.1 (tag v0.3.1 + 1 commit, commit 662436b0544560689612d7546eab9089a423f783)

It prints the release declared in setup.py, the latest git tag, how many commits the code is past it, the full commit hash, and whether the working tree had uncommitted changes. From Python, netqmpi.__version__ is the release and netqmpi.get_build_info() returns every field, as_dict() included, to store next to results.

An installed wheel or sdist reports the tag and commit it was built from: setup.py freezes them into netqmpi/_build_info.py in the build (never in the sources). A checkout — plain or installed with pip install -e . — asks git when first asked, so it always describes the code that is checked out now.

Lazy backend imports¶

The CLI imports no backend at module level. The adapter package is imported only inside the branch its flag selects, so a user with just qiskit-aer installed can run --aer without CUNQA, NetQASM or Qoala being importable.

This is also what lets the --netqasm and --qoala backends coexist in the codebase despite their incompatible netqasm versions: only one of them is ever imported in a given run.

Programmatic use¶

simulate() is the same path the CLI takes, and can be called directly when you want to drive runs from Python — a parameter sweep, for instance:

from netqmpi.runtime.cli import simulate
from netqmpi.runtime.adapters.cunqa import CunqaExecutorAdapter, CunqaRunConfig

config = CunqaRunConfig(shots=4096, family="my_family")
executor = CunqaExecutorAdapter(size=3, config=config)

simulate(script="app.py", num_procs=3, executor=executor, timer=True)

timer=True prints the wall-clock execution time:

finished simulation in 12.47 seconds

The experiment drivers under scripts/experiments/ use this entry point to sweep hardware parameters across many runs.