Frontend-agnostic core¶

Notebook integration for the Qibocal executor.

Executor is a drop-in replacement of qibocal.Executor, composed of three roles:

a Runner, deciding where and how the steps run (Local by default, or Remote);
Middleware, wrapping every step;
Frontend objects, displaying every output.

from qibocal_widgets import Executor
from qibocal_widgets.marimo import Marimo

executor = Executor.create(platform="mock", path="var/report", frontends=[Marimo()])

Frontends live in their own modules:

qibocal_widgets.marimo (requires the marimo extra)
qibocal_widgets.jupyter (requires the jupyter extra)

Executions are recorded in a Session folder, appended for as long as the executor lives. Without an explicit path, Executor.create and Executor.open use a fresh folder of the session’s reports folder (reports_dir()).

The calibration state of the platform can be explored and updated by path, programmatically or with an interactive explorer (PlatformState, executor.platform_state).

This module also exposes the frontend-agnostic building blocks, useful to write further runners, middleware, and frontends.

class qibocal_widgets.Completed(task=None, path=None, _data=None, _results=None, data_time=0, results_time=0, bound=None, reports=None, protocol_id=None, error=None, success=True, _targets=None, notes=<factory>, views=<factory>, updates=None)¶

Bases: Completed

Execution carrying views for notebook frontends.

Views are keyed by the display protocol they implement. Without a view for a protocol, the execution falls back to its plain representation, so views for several frontends can coexist on the same object.

Parameters:

task (Task | None)
path (Path | None)
_data (Data | None)
_results (Results | None)
data_time (float)
results_time (float)
bound (BoundProtocol | None)
reports (Any)
protocol_id (str | None)
error (Exception | None)
success (bool)
_targets (list[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]] | list[Annotated[tuple[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])], Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]], BeforeValidator(func=~qibocal.calibration.calibration.<lambda>, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~qibocal.calibration.calibration.<lambda>, return_type=PydanticUndefined, when_used=always)]] | list[tuple[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])], ...]] | None)
notes (list[Note])
views (dict[str, View])
updates (Updates | None)

views: dict[str, View]¶: Views registered by frontends, keyed by display protocol.

updates: Updates | None = None¶: Its platform update, and the targets applied, if produced by an executor of this package (shared by its copies).

update(targets=None)¶

Apply the platform update of the execution, after validating its fit.

To all targets, or to some (e.g. completed.update([0, 2])); those already applied are skipped. The same as its Update buttons.

Returns:: The targets the update was applied to now.
Raises:: ValueError – if there is no update to apply, or the execution was not produced by an executor of this package.
Parameters:: targets (Any)
Return type:: list

with_view(key, view)¶

A copy of the execution, with an additional view.

Parameters:

key (str)
view (Callable[[Completed], Any])

Return type:

Completed

class qibocal_widgets.Entry(id, parent, at, kind, changes, task=None, targets=None, source=None, paths=None)¶

Bases: object

A change of the platform state.

Parameters:

id (int)
parent (int | None)
at (datetime)
kind (str)
changes (dict[str, tuple[Any, Any]])
task (str | None)
targets (list | None)
source (int | None)
paths (list[str] | None)

id: int¶: Position in the history, from 0 (the start).

parent: int | None¶

the previous one, unless restoring a state.

Type:: The entry it applies to

at: datetime¶: When it was recorded (UTC).

kind: str¶: start, update, edit, restore, or external.

changes: dict[str, tuple[Any, Any]]¶: Changed leaves, as (before, after) (None for missing ones).

task: str | None = None¶: The execution updating the platform (its folder name, e.g. rabi-0).

targets: list | None = None¶: The targets updated.

source: int | None = None¶: The entry restored.

paths: list[str] | None = None¶: The paths restored, if not all.

describe()¶

A one-line summary.

Return type:: str

class qibocal_widgets.Estimate(seconds, at, kind='execution')¶

Bases: object

An estimate of the acquisition duration, logged by qibolab or its driver.

Parameters:

seconds (float)
at (datetime)
kind (str)

seconds: float¶: Estimated duration.

at: datetime¶

the acquisition starts after it.

Type:: When it was received (UTC)

kind: str = 'execution'¶: execution, for a whole execution on the platform (from qibolab), or batch, for one of its batches (refined by the driver, e.g. Qblox).

class qibocal_widgets.Executor(platform, *, runner=None, middleware=(), frontends=(), session=None, restore_platform=True, confirm=False, reuse=False, **kwargs)¶

Bases: Executor

Qibocal executor composed of a runner, middleware, and frontends.

All the constructors of qibocal.Executor (create, open, and the default one) are available, and accept the same additional keyword arguments. create and open also default the output path to a fresh folder of the session’s reports folder, if any (see reports_dir()).

An executor with an output path records every execution in its Session folder, appending for as long as the instance lives, until a new session is started (new_session()). A new executor can continue an existing folder (attach()).

Parameters:

platform – as in qibocal.Executor.
runner (Runner | None) – where and how the steps run. Defaults to Local.
middleware (Iterable[Middleware]) – wrapping every step, the first being the outermost.
frontends (Iterable[Frontend]) – displaying every output.
session (Session | None) – the session recording the executions. Defaults to a new session in path, if given, and to none otherwise.
restore_platform (bool) – when given an existing session (see Session.attach()), continue from the latest platform state recorded in its folder.
confirm (bool) – default of submit()’s confirm.
reuse (bool) – default of submit()’s reuse.
**kwargs (Any) – forwarded to qibocal.Executor.

Raises:

TypeError – for objects given in the wrong role.

session: Session | None¶: The session recording the executions, if any.

confirm¶: Whether submitted executions wait for confirmation, by default.

reuse¶: Whether submitted executions reuse identical ones, by default.

history¶

compared, and restored (see PlatformHistory).

Type:: The platform states of the session, as diffs

classmethod create(path=None, targets=None, platform=None, **kwargs)¶

Create an executor writing its output to path.

Parameters:

path (PathLike | None) – the output folder. If omitted, a fresh subfolder of the session’s reports folder (QIBOCAMP_REPORTS_DIR) is used.
targets (list[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]] | list[Annotated[tuple[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])], Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]], BeforeValidator(func=~qibocal.calibration.calibration.<lambda>, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~qibocal.calibration.calibration.<lambda>, return_type=PydanticUndefined, when_used=always)]] | list[tuple[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])], ...]] | None) – as in qibocal.Executor.create().
platform (Any) – as in qibocal.Executor.create().
**kwargs (Any) – as in the constructor.

Raises:

TypeError – without path, when no reports folder is set.

Return type:

Executor

classmethod open(path=None, targets=None, force=False, platform=None, update=None, **kwargs)¶

Enter the execution context, as qibocal.Executor.open().

The output path defaults as in create().

Parameters:

path (PathLike | None)
targets (list[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]] | list[Annotated[tuple[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])], Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]], BeforeValidator(func=~qibocal.calibration.calibration.<lambda>, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~qibocal.calibration.calibration.<lambda>, return_type=PydanticUndefined, when_used=always)]] | list[tuple[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])], ...]] | None)
force (bool)
platform (Any)
update (bool | None)
kwargs (Any)

Return type:

Iterator[Executor]

classmethod attach(path, targets=None, platform=None, *, restore_platform=True, **kwargs)¶

Create an executor appending to an existing session folder.

Parameters:

path (PathLike) – the session folder.
targets (list[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]] | list[Annotated[tuple[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])], Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]], BeforeValidator(func=~qibocal.calibration.calibration.<lambda>, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~qibocal.calibration.calibration.<lambda>, return_type=PydanticUndefined, when_used=always)]] | list[tuple[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])], ...]] | None) – as in create().
platform (Any) – as in create(). Defaults to the platform recorded in the session metadata.
restore_platform (bool) – apply the latest platform state recorded in the folder, continuing the calibration where the session left it.
**kwargs (Any) – as in the constructor.

Raises:

FileNotFoundError – if the folder holds no session.

Return type:

Executor

new_session(path=None)¶

Record the following executions in a new session folder.

Parameters:: path (PathLike | None) – the new folder. If omitted, a fresh subfolder of the session’s reports folder (QIBOCAMP_REPORTS_DIR) is used.
Raises:: TypeError – without path, when no reports folder is set.
Return type:: Session

property platform_state: PlatformState¶

The calibration state of the platform, to explore and update by path.

It is the state the steps run on, as known by the runner: the local platform, or the state kept by a remote runner (asked to the remote machine, if not known yet). Updates are applied through the runner, and recorded in the session, as protocol updates are.

note(content, completed=None, *, author=None)¶

Add a note to the session, or to one of its executions.

See Session.note().

Raises:

ValueError – if the executor has no session.

Parameters:

content (str)
completed (Completed | None)
author (str | None)

submit(bound, skip_fit=False, *, reuse=None, confirm=None, **kwargs)¶

Execute a protocol in the background, as executor(bound).

Returns immediately, leaving the notebook free while the execution runs: get its result with pending.result(), await pending, or peek at it with pending(). In Marimo notebooks, the pending execution is reactive state: cells referencing it run again when it completes.

With a remote runner, acquisitions are independent jobs, queued together; with the local runner, they wait for each other, sharing the instruments. The execution manages the platform connection itself: no with executor: is needed.
Executions are recorded, fitted, reported, and update the platform in the order they start (submission, or confirmation), whatever the order their acquisitions complete in. An acquisition uses the platform state at the time it starts: acquisitions submitted together do not see each other’s updates.

Parameters:

bound (BoundProtocol) – the protocol to execute.
skip_fit (bool) – as in executor(bound).
reuse (bool | None) – return an identical execution instead of acquiring again, if any: one still running, or one recorded in the session (loaded from disk; only for protocols registered in qibocal.protocols, which Qibocal can load back). Executions are identical with the same protocol, parameters, overrides, and targets, whatever the platform state: updates of other executions do not cause acquiring again. Useful where cells may run again unintentionally, as in reactive notebooks; submit without it to acquire again. Defaults to the executor’s.
confirm (bool | None) – wait for confirmation before starting: the execution is ready, displayed as a Run button, until clicked, or pending.start(). Only where a frontend can show it (e.g. in notebooks); elsewhere, it starts at once. Reused executions need no confirmation. Defaults to the executor’s.
**kwargs (Any) – execution overrides, as in executor(bound).

Return type:

Pending

close()¶: Close execution.

acquire(bound, **kwargs)¶

Execute only the acquisition phase.

Parameters:

bound (BoundProtocol) – The bound protocol to acquire data from.
**kwargs (Any) – Execution overrides, including targets and acquisition settings. The platform cannot be overridden.

Returns:

A new Completed instance retaining data and the bound protocol.

Return type:

Completed

fit(completed, *, targets=None)¶

Execute the fit phase on existing data.

This can be used to re-fit data that was previously acquired, or to apply a different fitting strategy.

Parameters:

completed (Completed) – An acquired execution, optionally loaded from disk.
targets (list[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]] | list[Annotated[tuple[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])], Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]], BeforeValidator(func=~qibocal.calibration.calibration.<lambda>, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~qibocal.calibration.calibration.<lambda>, return_type=PydanticUndefined, when_used=always)]] | list[tuple[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])], ...]] | None) – Optional override of the targets recorded at acquisition.

Returns:

A new Completed instance with fitting results attached.

Raises:

ValueError – If the protocol does not have a fit function.

Return type:

Completed

report(completed, *, targets=None)¶

Execute the report phase.

Parameters:

completed (Completed) – An acquired or fitted execution.
targets (list[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]] | list[Annotated[tuple[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])], Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]], BeforeValidator(func=~qibocal.calibration.calibration.<lambda>, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~qibocal.calibration.calibration.<lambda>, return_type=PydanticUndefined, when_used=always)]] | list[tuple[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])], ...]] | None) – Optional override of the targets recorded at acquisition.

Returns:

A new Completed instance with report output attached.

Raises:

ValueError – If the protocol does not have a report function.

Return type:

Completed

update(completed, *, targets=None)¶

Execute the update phase to apply results to platform.

Parameters:

completed (Completed) – A fitted execution.
targets (list[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]] | list[Annotated[tuple[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])], Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])]], BeforeValidator(func=~qibocal.calibration.calibration.<lambda>, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~qibocal.calibration.calibration.<lambda>, return_type=PydanticUndefined, when_used=always)]] | list[tuple[Annotated[int | str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(union_mode='left_to_right')])], ...]] | None) – Optional override of the targets recorded at acquisition.

Returns:

A new Completed instance after applying the platform update.

Raises:

ValueError – If the protocol has no update function or no platform is configured.

Return type:

Completed

load(path)¶

Load a previously dumped execution, transformed and displayed.

Parameters:: path (Any)
Return type:: Completed

class qibocal_widgets.Frontend¶

Bases: object

Base frontend.

Subclasses set protocol and implement render().

protocol: ClassVar[str]¶: Display protocol implemented, i.e. the key of the view.

render(completed)¶

Displayable object for an execution.

Parameters:: completed (Completed)
Return type:: Any

attach(completed, executor=None)¶

A copy of the execution, displayed by this frontend.

Parameters:

completed (QibocalCompleted) – any execution.
executor (Executor | None) – the executor which produced it, if any. Frontends whose views interact with the executor override this method.

Return type:

Completed

background()¶

The pending type and thread type of background executions.

For frontends needing them integrated with their runtime (e.g. Marimo’s reactive state and threads); None keeps the defaults. The first frontend providing them is used.

Return type:: tuple[type[Pending], type[threading.Thread]] | None

confirmable()¶

Whether executions can be confirmed here, e.g. with a button.

Executions submitted with confirm only wait for confirmation if a frontend can show it; elsewhere (e.g. in scripts) they start at once.

Return type:: bool

submitted(pending)¶

Called with every execution returned by Executor.submit.

In the context of the call, e.g. the notebook cell: the execution may be new, or reused, possibly already completed. Frontends following the executions where they are displayed override it.

Parameters:: pending (Pending)
Return type:: None

render_pending(pending)¶

Displayable object for an execution running in the background.

By default, its state, or its result once completed; frontends able to update a displayed output override it.

Parameters:: pending (Pending)
Return type:: Any

class qibocal_widgets.Local¶

Bases: qibocal_widgets.runner.Runner

Run every step in the current process (the default runner).

class qibocal_widgets.Middleware¶

Bases: object

Base middleware: every hook passes through unchanged.

Subclasses override only the hooks they need.

open(executor, call_next, *args, **kwargs)¶

Around the initialization of the execution context.

Parameters:

executor (Executor)
call_next (Next)
args (Any)
kwargs (Any)

close(executor, call_next, *args, **kwargs)¶

Around the finalization of the execution context.

Parameters:

executor (Executor)
call_next (Next)
args (Any)
kwargs (Any)

acquire(executor, call_next, *args, **kwargs)¶

Around the acquisition.

Parameters:

executor (Executor)
call_next (Next)
args (Any)
kwargs (Any)

Return type:

Completed

fit(executor, call_next, *args, **kwargs)¶

Around the fit.

Parameters:

executor (Executor)
call_next (Next)
args (Any)
kwargs (Any)

Return type:

Completed

report(executor, call_next, *args, **kwargs)¶

Around the report.

Parameters:

executor (Executor)
call_next (Next)
args (Any)
kwargs (Any)

Return type:

Completed

update(executor, call_next, *args, **kwargs)¶

Around the update.

Parameters:

executor (Executor)
call_next (Next)
args (Any)
kwargs (Any)

Return type:

Completed

result(executor, completed)¶

Transform the output of every step.

Parameters:

executor (Executor)
completed (Completed)

Return type:

Completed

exception qibocal_widgets.NotStartedError¶

Bases: RuntimeError

An execution waiting for confirmation was waited for.

class qibocal_widgets.Pending(bound)¶

Bases: object

An execution running in the background, returned by Executor.submit.

Get its result synchronously, blocking until it is available:

completed = pending.result()

asynchronously, where top-level await is available:

completed = await pending

or peek at it, without blocking: pending() is the result, or None while running (and raises if the execution failed).

Submitted with confirm, it is ready and waits for confirmation before starting: its Run button, or start(). Once completed, it can run again, with its Run again button, or rerun().

Displayed, it shows its state; frontends may update the display when the execution completes. Frontends may also provide a subclass (see Frontend.background), e.g. reactive in Marimo.

Parameters:: bound (BoundProtocol)

bound¶: The protocol being executed.

future: Future[Completed]¶: The underlying future.

submitted_at¶: When the execution was submitted (UTC).

views: dict[str, Callable[[Completed], Any]]¶: Views registered by frontends, keyed by display protocol.

estimates: list[Estimate]¶

each one refines the previous ones, and restarts the progress bar.

Type:: Duration estimates received while acquiring, in order

overrides: dict[str, Any]¶: Execution overrides (e.g. targets), as given to submit.

property status: str¶: One of ready, waiting, acquiring, processing, done, failed.

start()¶

Start an execution waiting for confirmation (ready).

As its Run button does; nothing happens if already started.

Return type:: None

update(targets=None)¶

Apply the platform update of the completed execution, as Completed.update.

Raises:: ValueError – if not completed successfully.
Parameters:: targets (Any)
Return type:: list

rerun()¶

Run a completed execution again, as its Run again button does.

The same handle follows the new execution: pending() is None again until it completes, result() waits for it. It ignores reuse: the protocol is acquired again, and recorded anew in the session. Nothing happens while running, or waiting for confirmation.

Return type:: None

property name: str¶: The protocol name, for display.

on_change(callback)¶

Call callback(pending) on every change of state, from any thread.

Changes of state include new estimates. Returns a function removing the callback.

Parameters:: callback (Callable[[Pending], None])
Return type:: Callable[[], None]

done()¶

Whether the execution completed, successfully or not.

Return type:: bool

result(timeout=None)¶

The completed execution, waiting for it if needed.

Raises:

NotStartedError – if waiting for confirmation (waiting for it would block the confirmation itself).
TimeoutError – if not completed within timeout seconds.
Exception – the error of the execution, if it failed.

Parameters:

timeout (float | None)

Return type:

Completed

exception(timeout=None)¶

The error of the execution, if it failed.

Parameters:: timeout (float | None)
Return type:: BaseException | None

describe()¶

A short description of the state.

Return type:: str

property batches: int¶: Batches started in the current execution on the platform, as estimated by the driver: all but the last are done.

progress()¶

A progress bar, as HTML, while acquiring with an estimate.

It fills in the latest estimated duration, from when the estimate was received, with a CSS animation: no further update is needed. The first estimate is shown for comparison, and the batches done, once the driver estimates them (their total is not known in advance).

Return type:: str | None

class qibocal_widgets.PlatformHistory(executor, records=None)¶

Bases: object

The platform states of a session, as Executor.history.

Entries are addressed by their id, by negative index (-1 is the latest), or by the folder name of the execution updating the platform (history["rabi-0"]). Restoring a state continues from it: the following entries fork from there.

Parameters:

executor (Executor)
records (list[dict] | None)

classmethod load(executor)¶

The history recorded in the executor’s session folder, if any.

Parameters:: executor (Executor)
Return type:: PlatformHistory

property entries: list[Entry]¶: All the entries, in recording order.

property head: Entry | None¶: The entry of the current state, if any.

lineage(ref=-1)¶

The entries leading to one, from the start.

Parameters:: ref (int | str | Entry)
Return type:: list[Entry]

state(ref=-1)¶

The platform state after an entry, as a read-only snapshot.

Parameters:: ref (int | str | Entry)
Return type:: PlatformState

diff(a, b=None)¶

Leaves differing between two entries, as (a, b) values.

b defaults to the current state, so that diff(a) is what changed since a.

Parameters:

a (int | str | Entry)
b (int | str | Entry | None)

Return type:

dict[str, tuple[Any, Any]]

applied(task)¶

Targets updated by an execution, from its folder name.

Parameters:: task (str)
Return type:: list

log()¶

The entries as a table (a pandas DataFrame).

Return type:: Any

explore(a=None, b=None)¶

An explorer comparing two entries, and restoring them.

Requires anywidget (in the jupyter and marimo extras).

Parameters:

a (int | None)
b (int | None)

Return type:

Any

on_change(callback)¶

Call callback(history) whenever an entry is recorded.

Parameters:: callback (Callable[[PlatformHistory], None])
Return type:: None

restore(ref, paths=None)¶

Restore the state after an entry, entirely or for some paths.

Restored entirely, the following entries continue from it, forking the history. Restoring some paths (leaves, or branches such as a whole qubit, in any form accepted by PlatformState) sets their values as they were, on top of the current state.

Returns:

The entry recording the restore.

Raises:

KeyError – for paths not found in either state.
ValueError – if the restored state is not valid.

Parameters:

ref (int | str | Entry)
paths (Iterable[str] | None)

Return type:

Entry

class qibocal_widgets.PlatformState(source, sink=None, *, name='state', saver=None)¶

Bases: object

The calibration state of a platform, addressed by path.

A state is either bound to a platform (reading its current state, and writing updates back), or a read-only snapshot. Use the constructors: of() (a platform object), load() (a folder), snapshot(), or Executor.platform_state.

Parameters:

source (Callable[[], platforms.State | None]) – returns the current state.
sink (Callable[[platforms.State], None] | None) – applies an updated state; None for read-only states.
name (str) – how the state is referred to in code, in the snippets shown by the explorer.
saver (Callable[[platforms.State, bool], str] | None) – writes a state in the platform folder, given overwrite, returning where (see save()); None if not known.

classmethod of(platform, *, name='state')¶

The state of a platform object, bound to it.

Parameters:

platform (Any)
name (str)

Return type:

PlatformState

classmethod load(path, *, name='state')¶

A snapshot of a state dumped in a folder.

Parameters:

path (str | Path) – a platform dump (with parameters.json), or a session folder, whose latest state is taken (new_platform/, else platform/).
name (str)

Raises:

FileNotFoundError – if no state is found.

Return type:

PlatformState

save(path=None, *, overwrite=False)¶

Write the state as a platform folder: parameters.json and calibration.json, formatted as qibolab dumps them.

Parameters:

path (str | Path | None) – the folder; by default, the folder of the platform, e.g. in QIBOLAB_PLATFORMS, on the remote machine for remote runners without a local platform.
overwrite (bool) – replace existing files outside of a git working tree. In a git working tree, they are always replaced: git keeps the previous version, and the changes are reviewed and committed there (e.g. with Qibocamp).

Returns:

The folder written, on the machine where it is.

Raises:

ValueError – without a path, when the platform folder is not known.
FileExistsError – replacing files outside of a git working tree, without overwrite.

Return type:

str

classmethod frozen(state, *, name='state')¶

A read-only snapshot of a state.

Parameters:

state (dict[str, str | None])
name (str)

Return type:

PlatformState

snapshot()¶

A read-only copy of the current state, e.g. to compare later.

Return type:: PlatformState

property readonly: bool¶: Whether updates are rejected.

state()¶

The current state, as JSON strings.

Raises:: LookupError – if the state is not known (e.g. no platform).
Return type:: dict[str, str | None]

documents()¶

The current state, as parsed JSON documents.

Return type:: dict[str, Any]

get(path, default=None)¶

The value at a path, or a default.

Parameters:

path (str)
default (Any)

Return type:

Any

resolve(text)¶

The canonical path designated by some text, if any.

Accepted forms, so that paths can be pasted from anywhere:

a full path: parameters.configs.0/drive.frequency;
a path within a document, as copied from the Qibocamp dashboard (which shows one file at a time) or written for qibolab’s Platform.update: configs.0/drive.frequency;
any text quoting a path, as an API call or its output: state["parameters.configs.0/drive.frequency"].

All methods taking a path accept the same forms.

Parameters:: text (str)
Return type:: str | None

leaves(path='')¶

All the leaves under a path, by full path.

Parameters:: path (str)
Return type:: dict[str, Any]

find(query)¶

Leaves whose path contains some text (case insensitive).

Parameters:: query (str)
Return type:: dict[str, Any]

diff(other)¶

Leaves differing from another state, as (other, self) values.

Leaves missing on one side are reported as None on that side.

Parameters:: other (PlatformState)
Return type:: dict[str, tuple[Any, Any]]

update(changes)¶

Set values by path, validating the whole state.

All changes are applied at once: if any of them is invalid, none is.

Raises:

ReadOnlyState – for snapshots.
KeyError – for paths which do not exist (no new entries are created, so that typos are not silently accepted).
ValueError – if the updated state is not valid.

Parameters:

changes (Mapping[str, Any])

Return type:

None

explore(path='', *, editable=False, compare=None)¶

An interactive explorer, for Jupyter and Marimo.

Parameters:

path (str) – where to start; any text accepted by resolve().
editable (bool) – allow editing values, through update().
compare (PlatformState | None) – highlight differences with another state (e.g. a snapshot taken earlier, or the start of a session).

Requires anywidget (in the jupyter and marimo extras).

exception qibocal_widgets.ReadOnlyState¶

Bases: RuntimeError

The state is a snapshot, not bound to any platform.

class qibocal_widgets.Report(figures=<factory>, table='', extra=<factory>)¶

Bases: object

Normalized report content for a single target.

Parameters:

figures (list[Figure])
table (str)
extra (list[Any])

figures: list[Figure]¶: Plotly figures.

table: str = ''¶: HTML fragment with the fitting report table (possibly empty).

extra: list[Any]¶: Any other objects returned by the protocol, rendered as text.

class qibocal_widgets.Runner¶

Bases: object

Base runner: every step runs locally, as in qibocal.Executor.

property concurrent: bool¶

Whether acquisitions may run at the same time (see Executor.submit).

Local acquisitions share the instruments, so they run one at a time.

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

platform_name(executor)¶

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

Parameters:: executor (Executor)
Return type:: str | None

platform_state(executor)¶

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

Parameters:: executor (Executor)
Return type:: platforms.State | None

set_platform_state(executor, state)¶

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

Parameters:

executor (Executor)
state (platforms.State)

Return type:

None

save_platform(executor, state, overwrite=False)¶

Write a calibration state in the folder of the platform.

Returns:

The folder written, on the machine of the platform.

Raises:

ValueError – without a platform.
FileExistsError – see platforms.export().

Parameters:

executor (Executor)
state (platforms.State)
overwrite (bool)

Return type:

str

acquire(executor, bound, **kwargs)¶

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

Parameters:

executor (Executor)
bound (BoundProtocol)
kwargs (Any)

Return type:

Completed

fit(executor, completed, **kwargs)¶

Fit data, as qibocal.Executor.fit().

Parameters:

executor (Executor)
completed (Completed)
kwargs (Any)

Return type:

Completed

report(executor, completed, **kwargs)¶

Report results, as qibocal.Executor.report().

Parameters:

executor (Executor)
completed (Completed)
kwargs (Any)

Return type:

Completed

update(executor, completed, **kwargs)¶

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

Parameters:

executor (Executor)
completed (Completed)
kwargs (Any)

Return type:

Completed

class qibocal_widgets.Session(path, meta=None)¶

Bases: object

The folder recording the executions of an executor.

The folder is created when the session starts, i.e. at the first context entry or recorded execution, whichever comes first.

Parameters:

path (str | Path) – the session folder.
meta (Metadata | None) – the session metadata. If omitted, it is generated from the executor when the session starts.

path¶: The session folder.

meta¶: Session metadata, written to meta.json.

order: list[str]¶: Recorded tasks listed in history.json, in execution order.

started¶: Whether the folder exists and holds the session.

classmethod attach(path)¶

Continue an existing session folder.

Raises:: FileNotFoundError – if the folder holds no session (no meta.json).
Parameters:: path (str | Path)
Return type:: Session

start(executor, force=False)¶

Create the folder, unless already started.

Parameters:

executor (Executor) – the owner of the session.
force (bool) – replace an existing folder.

Raises:

SessionExists – if the folder already exists and is not empty, and force is not set.

Return type:

None

flush()¶

Return type:: None

platform_state()¶

The latest platform state recorded in the folder, if any.

Return type:: dict[str, str | None] | None

restore(executor)¶

Continue from the latest platform state recorded in the folder.

The state is handed to the executor’s runner: applied to the local platform, or kept by remote runners for their next jobs.

Parameters:: executor (Executor)
Return type:: None

note(content, completed=None, *, author=None)¶

Add a note to the session, or to one of its executions.

Notes are appended to the notes.json of the session folder, or of the execution folder, safely with respect to the report server, which may add notes concurrently.

Parameters:

content (str) – the note text.
completed (Completed | None) – an execution recorded in this session.
author (str | None) – defaults to the author of the session metadata.

Raises:

ValueError – if the session has not started, or the execution is not recorded in it.

Return type:

Note

notes(completed=None)¶

Notes of the session, or of one of its executions.

Parameters:: completed (Completed | None)
Return type:: list[Note]

contains(completed)¶

Whether an execution is already recorded in this session.

Parameters:: completed (Completed)
Return type:: bool

ensure(executor, completed)¶

Record an execution as a new task, unless already recorded.

Parameters:

executor (Executor)
completed (Completed)

Return type:

Completed

add(executor, completed)¶

Record an execution as a new task.

Returns:

The execution, bound to its task folder. Executions which cannot be recorded (e.g. with parameters not representable in YAML) are returned unchanged, with a warning.

Parameters:

executor (Executor)
completed (Completed)

Return type:

Completed

tag(completed, key)¶

Record the reuse key of an execution (see Executor.submit).

Parameters:

completed (Completed)
key (str)

Return type:

None

find(key)¶

The folder of the latest execution recorded with a reuse key, if any.

The latest is the last iteration of the task (<id>-<n>), e.g. after running it again.

Parameters:: key (str)
Return type:: Path | None

results(completed)¶

Write the fit results of a recorded execution.

Parameters:: completed (Completed)
Return type:: None

platform(executor)¶

Record the updated platform state, as known by the runner.

Parameters:: executor (Executor)
Return type:: None

exception qibocal_widgets.SessionExists¶

Bases: FileExistsError

A new session would overwrite an existing folder.

qibocal_widgets.convert(completed, completed_type=<class 'qibocal_widgets._core.completed.Completed'>)¶

Re-wrap an execution into another qibocal.auto.task.Completed subclass.

The operation is idempotent: instances already of the requested type are returned unchanged. Lazily loaded attributes (data and results stored on disk) are copied as they are, without triggering any loading.

Parameters:

completed (Completed)
completed_type (type[_CompletedT])

Return type:

_CompletedT

qibocal_widgets.data_frames(data)¶

Tabulate acquired data, one table per target.

Parameters:: data (Any) – a Qibocal Data instance, or any object with a data dictionary mapping targets to arrays. A bare dictionary is also accepted.
Returns:: Mapping from target to its table. Targets without array-like content are skipped.
Return type:: dict[Any, DataFrame]

qibocal_widgets.reports(completed)¶

Normalized reports of an execution (empty if the report phase did not run).

Parameters:: completed (Completed)
Return type:: dict[Any, Report]

qibocal_widgets.reports_dir()¶

The session’s reports folder, if any.

Read from the QIBOCAMP_REPORTS_DIR environment variable, set by Qibocamp for sessions with a reports folder (or by hand). Relative values are taken relative to the current working directory.

Returns:: The absolute folder, or None when the variable is unset or empty.
Return type:: Path | None

qibocal_widgets.reports_of(reports)¶

Normalize protocol reports into per-target Report objects.

Qibocal report callbacks accepting a target argument produce a mapping from target to (figures, table); callbacks without it produce a single object. Both shapes are accepted: the latter is stored under the None key.

Parameters:: reports (Any)
Return type:: dict[Any, Report]