Core language reference

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, is it 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 specifying additional flags.

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.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 interleave/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()

Retrieves the current RTIO time, in machine units.

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.

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'>)

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.

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

An argument that can take a numerical value.

If ndecimals = 0, scale = 1 and step is integer, then it returns an integer value. Otherwise, it returns a floating point value. The simplest way to represent an integer argument is NumberValue(step=1, ndecimals=0).

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, 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.
• ndecimals – The number of decimals a UI should use.

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).

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.

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 (and therefore its value has potentially changed) or is modified, a warning is emitted. Archival can be turned off by setting the archive argument to False.

get_device(key)

Creates and returns a device driver.

get_device_db()

Returns the full contents of the device database.

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).

set_dataset(key, value, broadcast=False, persist=False, save=True)

Sets the contents and handling modes of a dataset.

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

Parameters:

• 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.
• save – the data is saved into the local storage of the current run (archived as a HDF5 file).

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.

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.

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.

class artiq.language.environment.Experiment

Base class for top-level experiments.

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

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.

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.

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

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

Most experiment should derive from this class.

prepare()

The default prepare method calls prepare for all children, in the order of instantiation, if the child has a prepare method.

artiq.language.scan module

Implementation and management of scan objects.

A scan object (e.g. artiq.language.scan.RangeScan) represents a one-dimensional sweep of a numerical range. Multi-dimensional scans are constructed by combining several scan objects, for example using artiq.language.scan.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.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, ndecimals=2)

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.
• ndecimals – The 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.