Nexus worker¶

A Tierkreis worker that interacts with the Quantinuum Nexus API.

The Nexus worker largely wraps the functionality from the qnexus library. In addition to the elementary tasks exposed, there are also prepackaged graphs to make using the Nexus worker more convenient.

Installation¶

pip install tkr-nexus-worker

will install an executable Python script tkr_nexus_worker into your virtual environment.

Authentication¶

The worker uses the default mechanism provided by the qnexus Python package.

uv run python -c "from qnexus.client.auth import login; login()"

will put the a token in the appropriate filesystem location for subsequent operations to use.

Elementary tasks¶

The Nexus worker exposes the following elementary tasks to the user.

upload_circuit. A wrapper around qnexus.circuits.upload, which is intended to be parallelised using a Tierkreis map.
start_execute_job. A wrapper around qnuexs.jobs.start_execute_job that takes a BackendConfig to specify what hardware the circuits should be run on.
is_running. A wrapper around qnexus.jobs.status that will fail if an unsuccessful terminal state is received, return False if the job is successfully completed and return True otherwise.

Prepackaged graphs¶

The Tierkreis Python package provides a couple of prepackaged graphs to make it easier to interact with the Nexus API.

tierkreis.graphs.nexus.submit_poll.nexus_submit_and_poll is intended to automate the whole process of (parallelised) circuit upload, submission, status polling and result retrieval. It can be included within a custom graph using GraphBuilder.eval or run as a standalone graph. The function nexus_submit_and_poll takes an optional argument to specify the minimum delay between successive polls in the status polling loop. The default is to poll every 30 seconds.

An example use is in examples/nexus_polling.py in the Tierkreis repo, which looks like:

backend_config = ...select the right hardware by specifying the BackendConfig instance...
circuits = ...your circuits here...

storage = FileStorage(UUID(int=107), do_cleanup=True)
executor = UvExecutor(PACKAGE_PATH / ".." / "tierkreis_workers", storage.logs_path)

run_graph(
    storage,
    executor,
    nexus_submit_and_poll(),
    {
        "project_name": "2025-tkr-test",
        "job_name": "job-1",
        "circuits": circuits,
        "n_shots": [30] * len(circuits),
        "backend_config": backend_config,
    },
    polling_interval_seconds=1,
)
res = read_outputs(g, storage)
print(res)

The subgraphs tierkreis.graphs.nexus.submit_poll.upload_circuit_graph and tierkreis.graphs.nexus.submit_poll.polling_loop_body can also be used if the user wants to customise the main submit and poll graph.