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.

exception artiq.language.core.TerminationRequested

Raised by pause when the user has requested termination.

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.core.delay_mu(duration)

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

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(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 :attr`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.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.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.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.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.

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.environment module

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

A boolean argument.

exception artiq.language.environment.DefaultMissing

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

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

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.HasEnvironment(managers_or_parent, *args, **kwargs)

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

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.

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

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

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 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_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, 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:

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

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

Sets the default scheduling options.

This function should only be called from build.

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

Represents the absence of a default value.

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

An argument that can take a numerical value.

If type=="auto", the result will be a float unless ndecimals = 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 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.

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

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

An argument that can be any PYON-serializable value.

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

A string argument.

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

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

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.