Main front-end tools

These are the top-level commands used to run and manage ARTIQ experiments. Not all of the ARTIQ front-end is described here (many additional useful commands are presented in this manual in Utilities) but these together comprise the main points of access for using ARTIQ as a system.

`artiq.frontend.artiq_run`

Local experiment running tool

usage: artiq_run [-h] [--version] [-v] [-q] [--device-db DEVICE_DB]
                 [--dataset-db DATASET_DB] [-c CLASS_NAME] [-o HDF5]
                 FILE [ARGUMENTS ...]

Positional Arguments

FILE: file containing the experiment to run
ARGUMENTS: run arguments, use format KEY=VALUE

Named Arguments

--version: print the ARTIQ version number
--device-db: device database file (default: ‘’device_db.py’’)
--dataset-db: dataset file (default: ‘’dataset_db.mdb’’)
-c, --class-name: name of the class to run
-o, --hdf5: write results to specified HDF5 file (default: print them)

verbosity

-v, --verbose: increase logging level
-q, --quiet: decrease logging level

`artiq.frontend.artiq_master`

ARTIQ master

usage: artiq_master [-h] [--version] [--bind BIND] [--no-localhost-bind]
                    [--port-notify PORT_NOTIFY] [--port-control PORT_CONTROL]
                    [--port-logging PORT_LOGGING]
                    [--port-broadcast PORT_BROADCAST] [--ssl CERT KEY PEER]
                    [--device-db DEVICE_DB] [--dataset-db DATASET_DB] [-g]
                    [-r REPOSITORY] [--experiment-subdir EXPERIMENT_SUBDIR]
                    [-v] [-q] [--log-file LOG_FILE]
                    [--log-backup-count LOG_BACKUP_COUNT] [--name NAME]
                    [--log-submissions LOG_SUBMISSIONS]

Named Arguments

--version: print the ARTIQ version number
--name: friendly name, displayed in dashboards to identify master instead of server address
--log-submissions: log experiment submissions to specified file

network server

--bind: additional hostname or IP address to bind to; use ‘*’ to bind to all interfaces (default: [])
--no-localhost-bind: do not implicitly also bind to localhost addresses
--port-notify: TCP port for notifications connections (default: 3250)
--port-control: TCP port for control connections (default: 3251)
--port-logging: TCP port for remote logging connections (default: 1066)
--port-broadcast: TCP port for broadcasts connections (default: 1067)
--ssl: Enable SSL authentication: CERT: server certificate file, KEY: server private key, PEER: client certificate to trust (default: None)

databases

--device-db: device database file (default: ‘device_db.py’)
--dataset-db: dataset file (default: ‘dataset_db.mdb’)

repository

-g, --git: use the Git repository backend (default: False)
-r, --repository: path to the repository (default: ‘repository’)
--experiment-subdir: path to the experiment folder from the repository root (default: ‘’)

logging

-v, --verbose: increase logging level of the master process
-q, --quiet: decrease logging level of the master process
--log-file: store logs in rotated files; set the base filename
--log-backup-count: number of old log files to keep, or 0 to keep all log files. ‘.<yyyy>-<mm>-<dd>’ is added to the base filename (default: 0)

`artiq.frontend.artiq_client`

ARTIQ CLI client

usage: artiq_client [-h] [-s SERVER] [--port PORT] [--version]
                    [--ssl CERT KEY PEER] [-v] [-q]
                    {submit,delete,set-dataset,del-dataset,supply-interactive,cancel-interactive,show,scan-devices,scan-repository,ls,terminate} ...

Positional Arguments

action: Possible choices: submit, delete, set-dataset, del-dataset, supply-interactive, cancel-interactive, show, scan-devices, scan-repository, ls, terminate

Named Arguments

-s, --server: hostname or IP of the master to connect to (default: ‘::1’)
--port: TCP port to use to connect to the master (default: None)
--version: print the ARTIQ version number
--ssl: Enable SSL authentication: CERT: client certificate file, KEY: client private key, PEER: server certificate to trust (default: None)

verbosity

-v, --verbose: increase logging level
-q, --quiet: decrease logging level

Sub-commands

submit

submit an experiment

artiq_client submit [-h] [-p PIPELINE] [-P PRIORITY] [-t TIMED] [-f] [-R]
                    [-r REVISION] [--devarg-override DEVARG_OVERRIDE]
                    [--content] [-c CLASS_NAME]
                    FILE [ARGUMENTS ...]

Positional Arguments

FILE: file containing the experiment to run
ARGUMENTS: run arguments, use format KEY=VALUE

Named Arguments

-p, --pipeline: pipeline to run the experiment in (default: ‘main’)
-P, --priority: priority (higher value means sooner scheduling, default: 0)
-t, --timed: set a due date for the experiment (default: None)
-f, --flush: flush the pipeline before preparing the experiment
-R, --repository: use the experiment repository
-r, --revision: use a specific repository revision (defaults to head, ignored without -R)
--devarg-override: specify device arguments to override
--content: submit by content
-c, --class-name: name of the class to run

delete

delete an experiment from the schedule

artiq_client delete [-h] [-g] RID

Positional Arguments

RID: run identifier (RID)

Named Arguments

-g: request graceful termination

set-dataset

add or modify a dataset

artiq_client set-dataset [-h] [--unit UNIT] [--scale SCALE]
                         [--precision PRECISION] [-p | -n]
                         NAME VALUE

Positional Arguments

NAME: name of the dataset
VALUE: value in PYON format

Named Arguments

--unit: physical unit of the dataset
--scale: factor to multiply value of dataset in displays
--precision: maximum number of decimals to print in displays
-p, --persist: make the dataset persistent
-n, --no-persist: make the dataset non-persistent

del-dataset

delete a dataset

artiq_client del-dataset [-h] name

Positional Arguments

name: name of the dataset

supply-interactive

supply interactive arguments

artiq_client supply-interactive [-h] RID [ARGUMENTS ...]

Positional Arguments

RID: RID of target experiment
ARGUMENTS: interactive arguments

cancel-interactive

cancel interactive arguments

artiq_client cancel-interactive [-h] RID

Positional Arguments

RID: RID of target experiment

show

show schedule, log, devices or datasets

artiq_client show [-h] WHAT

Positional Arguments

WHAT

Possible choices: schedule, log, ccb, devices, datasets, interactive-args

select object to show: [‘schedule’, ‘log’, ‘ccb’, ‘devices’, ‘datasets’, ‘interactive-args’]

scan-devices

trigger a device database (re)scan

artiq_client scan-devices [-h]

scan-repository

trigger a repository (re)scan

artiq_client scan-repository [-h] [--async] [REVISION]

Positional Arguments

REVISION: use a specific repository revision (defaults to head)

Named Arguments

--async: trigger scan and return immediately

ls

list a directory on the master

artiq_client ls [-h] [directory]

Positional Arguments

directory

terminate

terminate the ARTIQ master

artiq_client terminate [-h]

`artiq.frontend.artiq_dashboard`

ARTIQ Dashboard

usage: artiq_dashboard [-h] [--version] [-s SERVER]
                       [--port-notify PORT_NOTIFY]
                       [--port-control PORT_CONTROL]
                       [--port-broadcast PORT_BROADCAST] [--ssl CERT KEY PEER]
                       [--db-file DB_FILE] [-p PLUGIN_MODULES]
                       [--analyzer-proxy-timeout ANALYZER_PROXY_TIMEOUT]
                       [--analyzer-proxy-timer ANALYZER_PROXY_TIMER]
                       [--analyzer-proxy-timer-backoff ANALYZER_PROXY_TIMER_BACKOFF]
                       [-v] [-q]

Named Arguments

--version: print the ARTIQ version number
-s, --server: hostname or IP of the master to connect to (default: ‘::1’)
--port-notify: TCP port to connect to for notifications (default: 3250)
--port-control: TCP port to connect to for control (default: 3251)
--port-broadcast: TCP port to connect to for broadcasts (default: 1067)
--ssl: Enable SSL authentication: CERT: client certificate file, KEY: client private key, PEER: server certificate to trust (default: None)
--db-file: database file for local GUI settings (default: None)
-p, --load-plugin: Python module to load on startup
--analyzer-proxy-timeout: connection timeout to core analyzer proxy (default: 5)
--analyzer-proxy-timer: retry timer to core analyzer proxy (default: 5)
--analyzer-proxy-timer-backoff: retry timer backoff multiplier to core analyzer proxy, (default: 1.1)

verbosity

-v, --verbose: increase logging level
-q, --quiet: decrease logging level

`artiq.frontend.artiq_browser`

ARTIQ Browser

usage: artiq_browser [-h] [--version] [--db-file DB_FILE]
                     [--browse-root BROWSE_ROOT] [-s SERVER] [--port PORT]
                     [-v] [-q]
                     [SELECT]

Positional Arguments

SELECT: directory to browse or file to load

Named Arguments

--version: print the ARTIQ version number
--db-file: database file for local browser settings (default: None)
--browse-root: root path for directory tree (default ‘’)
-s, --server: hostname or IP of the master to connect to when uploading datasets
--port: TCP port to use to connect to the master

verbosity

-v, --verbose: increase logging level
-q, --quiet: decrease logging level

`artiq.frontend.artiq_session`

ARTIQ session manager. Automatically runs the master, dashboard and local controller manager on the current machine. The latter requires the artiq-comtools package to be installed.

When supplying arguments to individual front-end tools, use = to avoid ambiguity in argument parsing, e.g.:

artiq_session -m=-g -m=--device-db=alternate_device_db.py -c=-v

and so on.

usage: artiq_session [-h] [--version] [-m M] [-c C] [-d D]

Named Arguments

--version: print the ARTIQ version number
-m: add argument to the master command line
-c: add argument to the controller manager command line
-d: add argument to the dashboard command line

`artiq_comtools.artiq_ctlmgr`

ARTIQ controller manager. Supplied in the separate package artiq-comtools, which is included with a standard ARTIQ installation but can also be installed standalone, with the intention of making it easier to run controllers and controller managers on machines where a full ARTIQ installation may not be necessary or convenient.

usage: artiq_ctlmgr [-h] [-v] [-q] [-s SERVER] [--port-notify PORT_NOTIFY]
                    [--port-logging PORT_LOGGING] [--ssl CERT KEY PEER]
                    [--retry-master RETRY_MASTER] [--host-filter HOST_FILTER]
                    [--bind BIND] [--no-localhost-bind]
                    [--port-control PORT_CONTROL]

Named Arguments

-s, --server: hostname or IP of the master to connect to
--port-notify: TCP port to connect to for notifications
--port-logging: TCP port to connect to for logging
--ssl: Enable SSL for master connections: CERT: client certificate file, KEY: client private key, PEER: master certificate to trust (default: None)
--retry-master: retry timer for reconnecting to master
--host-filter: IP address of controllers to launch (local address of master connection by default)

verbosity

-v, --verbose: increase logging level
-q, --quiet: decrease logging level

network server

--bind: additional hostname or IP address to bind to; use ‘*’ to bind to all interfaces (default: [])
--no-localhost-bind: do not implicitly also bind to localhost addresses
--port-control: TCP port for control connections (default: 3249)

Main front-end tools

artiq.frontend.artiq_run

Positional Arguments

Named Arguments

verbosity

artiq.frontend.artiq_master

Named Arguments

network server

databases

repository

logging

artiq.frontend.artiq_client

Positional Arguments

Named Arguments

verbosity

Sub-commands

submit

Positional Arguments

Named Arguments

delete

Positional Arguments

Named Arguments

set-dataset

Positional Arguments

Named Arguments

del-dataset

Positional Arguments

supply-interactive

Positional Arguments

cancel-interactive

Positional Arguments

show

Positional Arguments

scan-devices

scan-repository

Positional Arguments

Named Arguments

ls

Positional Arguments

terminate

artiq.frontend.artiq_dashboard

Named Arguments

verbosity

artiq.frontend.artiq_browser

Positional Arguments

Named Arguments

verbosity

artiq.frontend.artiq_session

Named Arguments

artiq_comtools.artiq_ctlmgr

Named Arguments

verbosity

network server

`artiq.frontend.artiq_run`

`artiq.frontend.artiq_master`

`artiq.frontend.artiq_client`

`artiq.frontend.artiq_dashboard`

`artiq.frontend.artiq_browser`

`artiq.frontend.artiq_session`

`artiq_comtools.artiq_ctlmgr`