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.

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

This decorator marks an object’s method for execution on the core device.

When a decorated method is called from the Python interpreter, the core attribute of the object is retrieved and used as core device driver. The core device driver will typically compile, transfer and run the method (kernel) on the device.

When kernels call another method:

• if the method is a kernel for the same core device, it is compiled and sent in the same binary. Calls between kernels happen entirely on the device.

• if the method is a regular Python method (not a kernel), it generates a remote procedure call (RPC) for execution on the host.

The decorator takes an optional parameter that defaults to core and specifies the name of the attribute to use as core device driver.

This decorator must be present in the global namespace of all modules using it for the import cache to work properly.

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

This decorator marks a function for execution on the same device as its caller.

In other words, a decorated function called from the interpreter on the host will be executed on the host (no compilation and execution on the core device). A decorated function called from a kernel will be executed on the core device (no RPC).

This decorator must be present in the global namespace of all modules using it for the import cache to work properly.

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

This decorator marks a function for execution on the host interpreter. This is also the default behavior of ARTIQ; however, this decorator allows for specifying additional flags.

artiq.language.core.subkernel(arg=None, destination=0, flags={})

This decorator marks an object’s method or function for execution on a satellite device. Destination must be given, and it must be between 1 and 255 (inclusive).

Subkernels behave similarly to kernels, with few key differences:

• they are started from main kernels,

• they do not support RPCs,

• but they can call other kernels or subkernels.

Subkernels can accept arguments and return values. However, they must be fully annotated with ARTIQ types.

To call a subkernel, call it like a normal function.

To await its finishing execution, call subkernel_await(subkernel, [timeout]). The timeout parameter is optional, and by default is equal to 10000 (miliseconds). This time can be adjusted for subkernels that take a long time to execute.

The compiled subkernel is copied to satellites, but not yet to the kernel core until it’s called. For bigger subkernels it may take some time before they actually start running. To help with that, subkernels can be preloaded, with subkernel_preload(subkernel) function. A call to a preloaded subkernel will take less time, but only one subkernel can be preloaded at a time.

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

This decorator marks a function as a system call. When executed on a core device, a C function with the provided name (or the same name as the Python function, if not provided) will be called. When executed on host, the Python function will be called as usual.

Every argument and the return value must be annotated with ARTIQ types.

Only drivers should normally define syscalls.

artiq.language.core.host_only(function)

This decorator marks a function so that it can only be executed in the host Python interpreter.

artiq.language.core.kernel_from_string(parameters, body_code, decorator=<function kernel>)

Build a kernel function from the supplied source code in string form, similar to exec()/eval().

Operating on pieces of source code as strings is a very brittle form of metaprogramming; kernels generated like this are hard to debug, and inconvenient to write. Nevertheless, this can sometimes be useful to work around restrictions in ARTIQ Python. In that instance, care should be taken to keep string-generated code to a minimum and cleanly separate it from surrounding code.

The resulting function declaration is also evaluated using exec() for use from host Python code. To encourage a modicum of code hygiene, no global symbols are available by default; any objects accessed by the function body must be passed in explicitly as parameters.

Parameters:

• parameters – A list of parameter names the generated functions accepts. Each entry can either be a string or a tuple of two strings; if the latter, the second element specifies the type annotation.

• body_code – The code for the function body, in string form. return statements can be used to return values, as usual.

• decorator – One of kernel or portable (optionally with parameters) to specify how the function will be executed.

Returns:

The function generated from the arguments.

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.

exception artiq.language.core.TerminationRequested

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

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.

artiq.language.core.delay(duration)

Increases the RTIO time by the given amount (in seconds).

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.