Remote

Remote execution.

The Remote runner dispatches the acquisition to the machine with access to the instruments, according to a Connection:

from qibocal_widgets import Executor
from qibocal_widgets.marimo import Marimo
from qibocal_widgets.remote import Remote

remote = Remote("lab")  # named connection, from the configuration file
remote.install()  # once, or whenever the requirements change
executor = Executor(None, targets=[0, 1], runner=remote, frontends=[Marimo()])
executor(bound)  # acquired remotely, fitted and reported locally

Connections are stored in remotes.json, in the configuration directory shared with Qibocamp, and managed with save_connection(), remove_connection(), and connections().

class qibocal_widgets.remote.Connection(*, ssh=None, queue=None, slurm=None, workdir=None, venv='qibocal', python=None, requirements=None, rebuild_on_compute=False, platform=None, platforms_dir=None, timeout=None)

Bases: BaseModel

How to reach the machine with access to the instruments.

The tier is determined by the options, not detected:

  • neither ssh nor queue/slurm: the current process already runs where the instruments are, and nothing is dispatched;

  • queue or slurm: every remote step is a blocking srun job, submitted from the current machine (the access node);

  • ssh: the same, through SSH (from a laptop to the access node). Without queue/slurm, steps run directly on the SSH destination.

Parameters:

  • ssh (str | None)

  • queue (str | None)

  • slurm (str | None)

  • workdir (str | None)

  • venv (str)

  • python (str | None)

  • requirements (str | None)

  • rebuild_on_compute (bool)

  • platform (str | None)

  • platforms_dir (str | None)

  • timeout (float | None)

model_config = {'extra': 'forbid', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ssh: str | None

SSH arguments, ending with the destination (e.g. "-J bastion me@login").

Host aliases and jump hosts from ~/.ssh/config are honored.

queue: str | None

SLURM partition.

slurm: str | None

Further srun options (e.g. "--time=10 --qos=normal").

workdir: str | None

Remote working directory.

venv: str

Environment name, under ~/.cache/qibocamp/envs, or path.

python: str | None

Interpreter, or version with uv, used to create the environment.

requirements: str | None

Environment requirements, in requirements.txt format.

Qibocal is included by default, unless already named (e.g. to pin a branch). Further entries make external protocols available.

rebuild_on_compute: bool

Install the environment on a compute node, rather than the access node.

platform: str | None

Platform name, resolved on the remote machine.

platforms_dir: str | None

Folder of the platforms on the remote machine (QIBOLAB_PLATFORMS).

It replaces the variable of the remote environment, if any; ~ is expanded remotely. The same field as Qibocamp’s agent configurations.

timeout: float | None

Maximum duration of a remote step, in seconds, queue time included.

property dispatched: bool

Whether steps are executed elsewhere.

property scheduled: bool

Whether steps go through the queue.

destination()

Split the SSH options from the destination.

Return type:

tuple[list[str], str]

exception qibocal_widgets.remote.IncompatibleConfig

Bases: RuntimeError

The configuration file has an unsupported version.

class qibocal_widgets.remote.Remote(connection=None, **options)

Bases: qibocal_widgets.runner.Runner

Execute the steps needing the instruments on another machine.

Only the acquisition needs the instruments: it is dispatched according to the connection (see Connection), while fit and report always run locally. The update runs locally when the executor has a platform, whose state is then sent along with every acquisition; otherwise it runs remotely, on the access node, and the runner keeps the resulting state.

When the connection dispatches nothing (the process already runs where the instruments are), every step passes through unchanged, so the same notebook works on every tier.

Parameters:

  • connection (str | Connection | None) – a named connection from the configuration file, or a Connection. If omitted, the connection named by the QIBOCAL_WIDGETS_CONNECTION environment variable is used, or none.

  • **options (Any) – Connection fields, overriding the connection’s.

connection

The effective connection.

state: dict | None

Calibration state of the remote platform, after remote updates.

install(*, rebuild=False)

Prepare the remote environment, installing the requirements.

Separate from execution: steps never install anything, and fail if the environment is missing. Installation runs on the access node, unless rebuild_on_compute is set.

Parameters:

rebuild (bool) – remove and recreate the environment.

Return type:

dict

property concurrent: bool

Dispatched acquisitions are independent jobs, queued together.

platform_name(executor)

Name of the platform the steps run on, if known.

Parameters:

executor (Executor)

Return type:

str | None

queue(*, partition=None, user=None, states=None, timeout=30.0)

The SLURM queue of the connection, asked once.

By default, the whole partition the acquisitions are submitted to, so that the jobs ahead are visible; the jobs of the remote user are flagged as mine, those of this runner as ours. The query and its fields are the ones of Qibocamp.

Parameters:

  • partition (str | None) – defaults to the queue of the connection.

  • user (str | None) – restrict to the jobs of a user.

  • states (list[str] | None) – restrict to some job states (e.g. ["PENDING"]).

  • timeout (float) – seconds to wait for the answer.

Return type:

dict

monitor(*, interval=30.0, mine=False, **options)

A refreshable view of the queue, for Jupyter and Marimo.

Parameters:

  • interval (float) – seconds between automatic refreshes, while displayed; 0 refreshes only on request.

  • mine (bool) – show only the jobs of the remote user.

  • **options – forwarded to queue().

Requires anywidget (in the jupyter and marimo extras).

describe(executor)

The calibration state of the remote platform, as found remotely.

Runs on the access node, outside of the queue: the platform is created, but not connected.

Parameters:

executor (Executor)

Return type:

dict

platform_state(executor)

Current calibration state of the platform the steps run on, if known.

Parameters:

executor (Executor)

Return type:

dict | None

set_platform_state(executor, state)

Apply a calibration state (e.g. attaching a session, or edited).

Parameters:
Return type:

None

save_platform(executor, state, overwrite=False)

Write a state in the platform folder: on the remote machine, without a local platform (in platforms_dir, if configured), outside of the queue.

Parameters:
Return type:

str

open(executor)

Enter the execution context: connect the platform.

The output folder is managed by the executor’s session, not by the runner.

Parameters:

executor (Executor)

Return type:

None

close(executor)

Exit the execution context: disconnect the platform.

Parameters:

executor (Executor)

Return type:

None

acquire(executor, bound, **kwargs)

Acquire data, as qibocal.Executor.acquire().

Parameters:

  • executor (Executor)

  • bound (BoundProtocol)

Return type:

Completed

update(executor, completed, **kwargs)

Update the platform, as qibocal.Executor.update().

Parameters:
Return type:

Completed

exception qibocal_widgets.remote.RemoteError(message, details='')

Bases: RuntimeError

A remote step failed.

Parameters:
TAIL = 20

Lines of details included in the message.

details

Remote traceback, or standard error, when available.

qibocal_widgets.remote.config_path()

Location of the remote connections file.

Return type:

Path

qibocal_widgets.remote.connections()

All the named connections in the configuration file.

Return type:

dict[str, Connection]

qibocal_widgets.remote.environment_name(name)

The environment a named connection uses, unless it names one.

Its name made safe for a folder, under _remote/: distinct connections, and notebook sessions of the same name, do not share one unless it is named on purpose. The same rule as Qibocamp’s desktop application.

Parameters:

name (str)

Return type:

str

qibocal_widgets.remote.load_connection(name)

A named connection from the configuration file.

Raises:

KeyError – if no connection has that name.

Parameters:

name (str)

Return type:

Connection

qibocal_widgets.remote.remove_connection(name)

Remove a named connection from the configuration file.

Parameters:

name (str)

Return type:

None

qibocal_widgets.remote.save_connection(name, connection)

Add or replace a named connection in the configuration file.

Parameters:
Return type:

None