Core language and environment

The most commonly used features from the ARTIQ language modules and from the core device modules are bundled together in artiq.experiment and can be imported with from artiq.experiment import *.

artiq.language.core module

Core ARTIQ extensions to the Python language.

class artiq.language.core.Kernel

class artiq.language.core.KernelInvariant

class artiq.language.core.virtual

artiq.language.core.extern(function)

Decorates a function declaration defined by the core device runtime.

artiq.language.core.kernel(function_or_method)

Decorates a function or method to be executed on the core device.

artiq.language.core.portable(function)

Decorates a function or method to be executed on the same device (host/core device) as the caller.

artiq.language.core.compile(cls)

Registers a class to be compiled by ARTIQ. All classes containing kernels or portable methods must use this decorator.

artiq.language.core.rpc(arg=None, flags={})

This decorator marks a function for execution on the host interpreter.

class artiq.language.core.Option(v: T)

exception artiq.language.core.UnwrapNoneError

Raised when unwrapping a none Option.

artiq.language.core.set_time_manager(time_manager)

Set the time manager used for simulating kernels by running them directly inside the Python interpreter. The time manager responds to the entering and leaving of parallel/sequential blocks, delays, etc. and provides a time-stamped logging facility for events.

artiq.language.core.delay_mu(duration)

Increases the RTIO time by the given amount (in machine units).

artiq.language.core.now_mu()

Retrieve the current RTIO timeline cursor, in machine units. Note the conceptual difference between this and the current value of the hardware RTIO counter; see e.g. artiq.coredevice.core.Core.get_rtio_counter_mu() for the latter.

artiq.language.core.at_mu(time)

Sets the RTIO time to the specified absolute value, in machine units.

exception artiq.language.core.TerminationRequested

Raised by pause() when the user has requested termination.

artiq.language.environment module

class artiq.language.environment.NoDefault

Represents the absence of a default value.

exception artiq.language.environment.DefaultMissing

Raised by the default method of argument processors when no default value is available.

class artiq.language.environment.PYONValue(default=<class 'artiq.language.environment.NoDefault'>)

An argument that can be any PYON-serializable value.

class artiq.language.environment.BooleanValue(default=<class 'artiq.language.environment.NoDefault'>)

A boolean argument.

class artiq.language.environment.EnumerationValue(choices, default=<class 'artiq.language.environment.NoDefault'>, quickstyle=False)

An argument that can take a string value among a predefined set of values.

Parameters:

• choices – A list of string representing the possible values of the argument.

• quickstyle – Enables the choices to be displayed in the GUI as a list of buttons that submit the experiment when clicked.

class artiq.language.environment.NumberValue(default=<class 'artiq.language.environment.NoDefault'>, unit='', *, scale=None, step=None, min=None, max=None, precision=2, type='auto', ndecimals=None)

An argument that can take a numerical value.

If type=="auto", the result will be a float unless precision = 0, scale = 1 and step is an integer. Setting type to int will also result in an error unless these conditions are met.

When scale is not specified, and the unit is a common one (i.e. defined in units), then the scale is obtained from the unit using a simple string match. For example, milliseconds ("ms") units set the scale to 0.001. No unit (default) corresponds to a scale of 1.0.

For arguments with uncommon or complex units, use both the unit parameter (a string for display) and the scale parameter (a numerical scale for experiments). For example, NumberValue(1, unit="xyz", scale=0.001) will display as 1 xyz in the GUI window because of the unit setting, and appear as the numerical value 0.001 in the code because of the scale setting.

Parameters:

• unit – A string representing the unit of the value.

• scale – A numerical scaling factor by which the displayed value is multiplied when referenced in the experiment.

• step – The step with which the value should be modified by up/down buttons in a UI. The default is the scale divided by 10.

• min – The minimum value of the argument.

• max – The maximum value of the argument.

• precision – The maximum number of decimals a UI should use.

• type – Type of this number. Accepts "float", "int" or "auto". Defaults to "auto".

class artiq.language.environment.StringValue(default=<class 'artiq.language.environment.NoDefault'>)

A string argument.

class artiq.language.environment.HasEnvironment(managers_or_parent, *args, **kwargs)

Provides methods to manage the environment of an experiment (arguments, devices, datasets).

call_child_method(method, *args, **kwargs)

Calls the named method for each child, if it exists for that child, in the order of registration.

Parameters:

• method (str) – Name of the method to call

• args – Tuple of positional arguments to pass to all children

• kwargs – Dict of keyword arguments to pass to all children

build()

Should be implemented by the user to request arguments.

Other initialization steps such as requesting devices may also be performed here.

There are two situations where the requested devices are replaced by DummyDevice() and arguments are set to their defaults (or None) instead: when the repository is scanned to build the list of available experiments and when the dataset browser artiq_browser is used to open or run the analysis stage of an experiment. Do not rely on being able to operate on devices or arguments in build().

Datasets are read-only in this method.

Leftover positional and keyword arguments from the constructor are forwarded to this method. This is intended for experiments that are only meant to be executed programmatically (not from the GUI).

get_argument(key, processor, group=None, tooltip=None)

Retrieves and returns the value of an argument.

This function should only be called from build.

Parameters:

• key – Name of the argument.

• processor – A description of how to process the argument, such as instances of BooleanValue and NumberValue.

• group – An optional string that defines what group the argument belongs to, for user interface purposes.

• tooltip – An optional string to describe the argument in more detail, applied as a tooltip to the argument name in the user interface.

setattr_argument(key, processor=None, group=None, tooltip=None)

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

The key is added to the instance’s kernel invariants.

interactive(title='')

Request arguments from the user interactively.

This context manager returns a namespace object on which the method setattr_argument() should be called, with the usual semantics.

When the context manager terminates, the experiment is blocked and the user is presented with the requested argument widgets. After the user enters values, the experiment is resumed and the namespace contains the values of the arguments.

If the interactive arguments request is cancelled, raises CancelledArgsError.

get_device_db()

Returns the full contents of the device database.

get_device(key)

Creates and returns a device driver.

setattr_device(key)

Sets a device driver as attribute. The names of the device driver and of the attribute are the same.

The key is added to the instance’s kernel invariants.

set_dataset(key, value, *, unit=None, scale=None, precision=None, broadcast=False, persist=False, archive=True)

Sets the contents and handling modes of a dataset.

Datasets must be scalars (bool, int, float or NumPy scalar) or NumPy arrays.

Parameters:

• unit – A string representing the unit of the value.

• scale – A numerical factor that is used to adjust the value of the dataset to match the scale or units of the experiment’s reference frame when the value is displayed.

• precision – The maximum number of digits to print after the decimal point. Set precision=None to print as many digits as necessary to uniquely specify the value. Uses IEEE unbiased rounding.

• broadcast – the data is sent in real-time to the master, which dispatches it.

• persist – the master should store the data on-disk. Implies broadcast.

• archive – the data is saved into the local storage of the current run (archived as a HDF5 file).

mutate_dataset(key, index, value)

Mutate an existing dataset at the given index (e.g. set a value at a given position in a NumPy array)

If the dataset was created in broadcast mode, the modification is immediately transmitted.

If the index is a tuple of integers, it is interpreted as slice(*index). If the index is a tuple of tuples, each sub-tuple is interpreted as slice(*sub_tuple) (multi-dimensional slicing).

append_to_dataset(key, value)

Append a value to a dataset.

The target dataset must be a list (i.e. support append()), and must have previously been set from this experiment.

The broadcast/persist/archive mode of the given key remains unchanged from when the dataset was last set. Appended values are transmitted efficiently as incremental modifications in broadcast mode.

get_dataset(key, default=<class 'artiq.language.environment.NoDefault'>, archive=True)

Returns the contents of a dataset.

The local storage is searched first, followed by the master storage (which contains the broadcasted datasets from all experiments) if the key was not found initially.

If the dataset does not exist, returns the default value. If no default is provided, raises KeyError.

By default, datasets obtained by this method are archived into the output HDF5 file of the experiment. If an archived dataset is requested more than one time or is modified, only the value at the time of the first call is archived. This may impact reproducibility of experiments.

Parameters:

archive – Set to False to prevent archival together with the run’s results. Default is True.

get_dataset_metadata(key, default=<class 'artiq.language.environment.NoDefault'>)

Returns the metadata of a dataset.

Returns dictionary with items describing the dataset, including the units, scale and precision.

This function is used to get additional information for displaying the dataset.

See set_dataset() for documentation of metadata items.

setattr_dataset(key, default=<class 'artiq.language.environment.NoDefault'>, archive=True)

Sets the contents of a dataset as attribute. The names of the dataset and of the attribute are the same.

set_default_scheduling(priority=None, pipeline_name=None, flush=None)

Sets the default scheduling options.

This function should only be called from build.

class artiq.language.environment.Experiment

Base class for top-level experiments.

Deriving from this class enables automatic experiment discovery in Python modules.

prepare()

Entry point for pre-computing data necessary for running the experiment.

Doing such computations outside of run() enables more efficient scheduling of multiple experiments that need to access the shared hardware during part of their execution.

This method must not interact with the hardware.

run()

The main entry point of the experiment.

This method must be overloaded by the user to implement the main control flow of the experiment.

This method may interact with the hardware.

The experiment may call the scheduler’s pause() method while in run().

analyze()

Entry point for analyzing the results of the experiment.

This method may be overloaded by the user to implement the analysis phase of the experiment, for example fitting curves.

Splitting this phase from run() enables tweaking the analysis algorithm on pre-existing data, and CPU-bound analyses to be run overlapped with the next experiment in a pipelined manner.

This method must not interact with the hardware.

class artiq.language.environment.EnvExperiment(managers_or_parent, *args, **kwargs)

Base class for top-level experiments that use the HasEnvironment environment manager.

Most experiments should derive from this class.

prepare()

This default prepare method calls prepare() for all children, in the order of registration, if the child has a prepare() method.

exception artiq.language.environment.CancelledArgsError

Raised by the interactive() context manager when an interactive arguments request is cancelled.

artiq.language.scan module

Implementation and management of scan objects.

class artiq.language.scan.ScanObject

Represents a one-dimensional sweep of a numerical range. Multi-dimensional scans are constructed by combining several scan objects, for example using MultiScanManager.

Iterate on a scan object to scan it, e.g.

for variable in self.scan:
    do_something(variable)

Iterating multiple times on the same scan object is possible, with the scan yielding the same values each time. Iterating concurrently on the same scan object (e.g. via nested loops) is also supported, and the iterators are independent from each other.

class artiq.language.scan.NoScan(value, repetitions=1)

A scan object that yields a single value for a specified number of repetitions.

class artiq.language.scan.RangeScan(start, stop, npoints, randomize=False, seed=None)

A scan object that yields a fixed number of evenly spaced values in a range. If randomize is True the points are randomly ordered.

class artiq.language.scan.CenterScan(center, span, step, randomize=False, seed=None)

A scan object that yields evenly spaced values within a span around a center. If step is finite, then center is always included. Values outside span around center are never included. If randomize is True the points are randomly ordered.

class artiq.language.scan.ExplicitScan(sequence)

A scan object that yields values from an explicitly defined sequence.

class artiq.language.scan.Scannable(default=<class 'artiq.language.environment.NoDefault'>, unit='', *, scale=None, global_step=None, global_min=None, global_max=None, precision=2, ndecimals=None)

An argument (as defined in artiq.language.environment) that takes a scan object.

When scale is not specified, and the unit is a common one (i.e. defined in artiq.language.units), then the scale is obtained from the unit using a simple string match. For example, milliseconds ("ms") units set the scale to 0.001. No unit (default) corresponds to a scale of 1.0.

For arguments with uncommon or complex units, use both the unit parameter (a string for display) and the scale parameter (a numerical scale for experiments). For example, a scan shown between 1 xyz and 10 xyz in the GUI with scale=0.001 and unit="xyz" results in values between 0.001 and 0.01 being scanned.

Parameters:

• default – The default scan object. This parameter can be a list of scan objects, in which case the first one is used as default and the others are used to configure the default values of scan types that are not initially selected in the GUI.

• global_min – The minimum value taken by the scanned variable, common to all scan modes. The user interface takes this value to set the range of its input widgets.

• global_max – Same as global_min, but for the maximum value.

• global_step – The step with which the value should be modified by up/down buttons in a user interface. The default is the scale divided by 10.

• unit – A string representing the unit of the scanned variable.

• scale – A numerical scaling factor by which the displayed values are multiplied when referenced in the experiment.

• precision – The maximum number of decimals a UI should use.

class artiq.language.scan.MultiScanManager(*args)

Makes an iterator that returns elements from the first scan object until it is exhausted, then proceeds to the next iterable, until all of the scan objects are exhausted. Used for treating consecutive scans as a single scan.

Scan objects must be passed as a list of tuples (name, scan_object). Íteration produces scan points that have attributes that correspond to the names of the scan objects, and have the last value yielded by that scan object.

artiq.language.units module

This module contains floating point constants that correspond to common physical units (ns, MHz, …). They are provided for convenience (e.g write MHz instead of 1000000.0) and code clarity purposes.