Management system interface

ARTIQ makes certain provisions to allow interactions between different components when using the management system. An experiment may make requests of the master or clients using virtual devices to represent the necessary line of communication; applets may interact with databases, the dashboard, and directly with the user (through argument widgets). This page collects the references for these features.

In experiments

scheduler virtual device

The scheduler is exposed to the experiments via a virtual device called scheduler. It can be requested like any other device, and the methods below, as well as pause(), can be called on the returned object.

The scheduler virtual device also contains the attributes rid, pipeline_name, priority and expid, which contain the corresponding information about the current run.

class artiq.master.scheduler.Scheduler(ridc, worker_handlers, experiment_db, log_submissions)

check_pause(rid)

Returns True if there is a condition that could make pause() not return immediately (termination requested or higher priority run).

The typical purpose of this function is to check from a kernel whether returning control to the host and pausing would have an effect, in order to avoid the cost of switching kernels in the common case where pause() does nothing.

This function does not have side effects, and does not have to be followed by a call to pause().

check_termination(rid)

Returns True if termination is requested.

delete(rid)

Kills the run with the specified RID.

get_status()

Returns a dictionary containing information about the runs currently tracked by the scheduler.

Must not be modified.

request_termination(rid)

Requests graceful termination of the run with the specified RID.

submit(pipeline_name, expid, priority=0, due_date=None, flush=False)

Submits a new run.

When called through an experiment, the default values of pipeline_name, expid and priority correspond to those of the current run.

ccb virtual device

Client control broadcasts (CCBs) are requests made by experiments for clients to perform some action. Experiments do so by requesting the ccb virtual device and calling its issue method. The first argument of the issue method is the name of the broadcast, and any further positional and keyword arguments are passed to the broadcast.

CCBs are especially used by experiments to configure applets in the dashboard, for example for plotting purposes.

class artiq.dashboard.applets_ccb.AppletsCCBDock(*args, **kwargs)

ccb_create_applet(name, command, group=None, code=None)

Requests the creation of a new applet.

An applet is identified by its name and an optional list of groups that represent a path (nested groups). If group is a string, it corresponds to a single group. If group is None or an empty list, it corresponds to the root.

command gives the command line used to run the applet, as if it was started from a shell. The dashboard substitutes variables such as $python that gives the complete file name of the Python interpreter running the dashboard.

If the name already exists (after following any specified groups), the command or code of the existing applet with that name is replaced, and the applet is restarted and shown at its previous position. If not, a new applet entry is created and the applet is shown at any position on the screen.

If the group(s) do not exist, they are created.

If code is not None, it should be a string that contains the full source code of the applet. In this case, command is used to specify (optional) command-line arguments to the applet.

This function is called when a CCB create_applet is issued.

ccb_disable_applet(name, group=None)

Disables an applet.

The applet is identified by its name, after following any specified groups.

This function is called when a CCB disable_applet is issued.

ccb_disable_applet_group(group)

Disables all the applets in a group.

If the group is nested, group should be a list, with the names of the parents preceding the name of the group to disable.

This function is called when a CCB disable_applet_group is issued.

ccb_restart_applet(name, group=None)

Restarts an applet.

The applet is identified by its name, after following any specified groups. If the applet is not currently running, this command has no effect.

This function is called when a CCB restart_applet is issued.

In applets

Applet request interfaces

Applet request interfaces allow applets to perform actions on the master database and set arguments in the dashboard. Applets may inherit from artiq.applets.simple.SimpleApplet and call the methods defined below through the req attribute.

Embedded applets should use AppletRequestIPC, while standalone applets use AppletRequestRPC. SimpleApplet automatically chooses the correct interface on initialization.

class artiq.applets.simple._AppletRequestInterface

append_to_dataset(key, value)

Append to a dataset. See documentation of append_to_dataset().

mutate_dataset(key, index, value)

Mutate a dataset. See documentation of mutate_dataset().

set_argument_value(expurl, key, value)

Temporarily set the value of an argument in a experiment in the dashboard. The value resets to default value when recomputing the argument.

Parameters:

• expurl – Experiment URL identifying the experiment in the dashboard. Example: ‘repo:ArgumentsDemo’.

• key – Name of the argument in the experiment.

• value – Object representing the new temporary value of the argument. For Scannable arguments, this parameter should be a ScanObject. The type of the ScanObject will be set as the selected type when this function is called.

set_dataset(key, value, unit=None, scale=None, precision=None, persist=None)

Set a dataset. See documentation of set_dataset().

Applet entry area

Argument widgets can be used in applets through the EntryArea class. Below is a simple example code snippet:

entry_area = EntryArea()

# Create a new widget
entry_area.setattr_argument("bl", BooleanValue(True))

# Get the value of the widget (output: True)
print(entry_area.bl)

# Set the value
entry_area.set_value("bl", False)

# False
print(entry_area.bl)

The EntryArea object can then be added to a layout and integrated with the applet GUI. Multiple EntryArea objects can be used in a single applet.

class artiq.gui.applets.EntryArea

setattr_argument(name, proc, group=None, tooltip=None)

Sets an argument as attribute. The names of the argument and of the attribute are the same.

Parameters:

• name – Argument name

• proc – Argument processor, for example NumberValue

• group – Used to group together arguments in the GUI under a common category

• tooltip – Tooltip displayed when hovering over the entry widget

get_value(name)

Get the value of an entry widget.

Parameters:

name – Argument name

get_values()

Get all values in the EntryArea as a dictionary. Names are stored as keys, and argument values as values.

set_value(name, value)

Set the value of an entry widget. The change is temporary and will reset to default when the reset button is clicked.

Parameters:

• name – Argument name

• value – Object representing the new value of the argument. For Scannable arguments, this parameter should be a ScanObject. The type of the ScanObject will be set as the selected type when this function is called.

set_values(values)

Set multiple values from a dictionary input. Calls set_value() for each key-value pair.

Parameters:

values – Dictionary with names as keys and new argument values as values.