atomiq.components.basics.calibration ==================================== .. py:module:: atomiq.components.basics.calibration .. autoapi-nested-parse:: In all experiments, calibrations are ubiquious. Examples are * voltage - power relation on a photodiode * Relation between the current through a coil and the created magentic field * RF power in an AOM and light power in the diffracted order * The current-voltage relation for a voltage-controlled current supply * ... In atomiq calibrations are comoponents just like every other piece of your experiment. Every calibration inherits from the abstract :class:`Calibration` class. A special subclass of calibration functions are invertable calibrations that can be analytically inverted. The most frequently used example is a linear calibration function. Invertable calibrations inherit from :class:`InvertableCalibration`. Classes ------- .. autoapisummary:: atomiq.components.basics.calibration.Calibration atomiq.components.basics.calibration.InvertableCalibration atomiq.components.basics.calibration.DummyCalibration atomiq.components.basics.calibration.SplineCalibration atomiq.components.basics.calibration.InvertableSplineCalibration atomiq.components.basics.calibration.PolynomialCalibration atomiq.components.basics.calibration.LinearCalibration atomiq.components.basics.calibration.SigmoidCalibration atomiq.components.basics.calibration.InvSigmoidCalibration Functions --------- .. autoapisummary:: atomiq.components.basics.calibration.exp atomiq.components.basics.calibration.ln Module Contents --------------- .. py:function:: exp(x) .. py:function:: ln(x, n = 10000.0) .. py:class:: Calibration(input_unit, output_unit, *args, **kwargs) Bases: :py:obj:`atomiq.components.primitives.Component` An abstract Calibration This is an abstract class to describe a calibration. :param input_unit: A string determining the input unit (e.g. 'mW', 'V', or 'uA') :param output_unit: A string determining the output unit (e.g. 'mW', 'V', or 'uA') .. py:attribute:: kernel_invariants .. py:attribute:: input_unit .. py:attribute:: output_unit .. py:method:: transform(input_value) :abstractmethod: Transform a value according to the calibration :param input_value: value to be transformed :returns: transformed value :rtype: TFloat .. py:attribute:: experiment .. py:attribute:: identifier .. py:attribute:: debug_output :value: False .. py:attribute:: core .. py:attribute:: _kernel_invariants .. py:attribute:: _prepare_done :value: False .. py:attribute:: _build_done :value: False .. py:attribute:: _hooks_done :value: [] .. py:method:: _recursive_prepare() .. py:method:: _prepare() Specify here what should be done for this component in the prepare phase .. py:method:: _recursive_build() .. py:method:: _build() Specify here what should be done for this component in the build phase .. py:method:: _do_prerun() .. py:method:: required_components(ancestors=[]) .. py:method:: _prerun() Specify here what should be done for this component before the run starts. In contrast to the _build() method, the _prerun() routine is executed on the core device before the actual experiment starts. .. py:attribute:: children :value: [] .. py:attribute:: __in_build :value: True .. py:method:: register_child(child) .. py:method:: call_child_method(method, *args, **kwargs) Calls the named method for each child, if it exists for that child, in the order of registration. :param method: Name of the method to call :type method: str :param args: Tuple of positional arguments to pass to all children :param kwargs: Dict of keyword arguments to pass to all children .. py:method:: 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 :meth:`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). .. py:method:: get_argument(key, processor, group=None, tooltip=None) Retrieves and returns the value of an argument. This function should only be called from ``build``. :param key: Name of the argument. :param processor: A description of how to process the argument, such as instances of :mod:`~artiq.language.environment.BooleanValue` and :mod:`~artiq.language.environment.NumberValue`. :param group: An optional string that defines what group the argument belongs to, for user interface purposes. :param tooltip: An optional string to describe the argument in more detail, applied as a tooltip to the argument name in the user interface. .. py:method:: 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. .. py:method:: interactive(title='') Request arguments from the user interactively. This context manager returns a namespace object on which the method :meth:`~artiq.language.environment.HasEnvironment.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 :exc:`~artiq.language.environment.CancelledArgsError`. .. py:method:: get_device_db() Returns the full contents of the device database. .. py:method:: get_device(key) Creates and returns a device driver. .. py:method:: 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. .. py:method:: 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. :param unit: A string representing the unit of the value. :param 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. :param 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. :param broadcast: the data is sent in real-time to the master, which dispatches it. :param persist: the master should store the data on-disk. Implies broadcast. :param archive: the data is saved into the local storage of the current run (archived as a HDF5 file). .. py:method:: 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). .. py:method:: 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. .. py:method:: get_dataset(key, default=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. :param archive: Set to ``False`` to prevent archival together with the run's results. Default is ``True``. .. py:method:: get_dataset_metadata(key, default=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 :meth:`set_dataset` for documentation of metadata items. .. py:method:: setattr_dataset(key, default=NoDefault, archive=True) Sets the contents of a dataset as attribute. The names of the dataset and of the attribute are the same. .. py:method:: set_default_scheduling(priority=None, pipeline_name=None, flush=None) Sets the default scheduling options. This function should only be called from ``build``. .. py:class:: InvertableCalibration(input_unit, output_unit, *args, **kwargs) Bases: :py:obj:`Calibration` An abstract Calibration This is an abstract class to describe a calibration. :param input_unit: A string determining the input unit (e.g. 'mW', 'V', or 'uA') :param output_unit: A string determining the output unit (e.g. 'mW', 'V', or 'uA') .. py:method:: transform_inv(input_value) :abstractmethod: Perform inverse transform of a value according to the calibration :param input_value: value to be inversely transformed. Must be given in units of the output unit :returns: transformed value. The returned value is in units of the input unit :rtype: TFloat .. py:attribute:: kernel_invariants .. py:attribute:: input_unit .. py:attribute:: output_unit .. py:method:: transform(input_value) :abstractmethod: Transform a value according to the calibration :param input_value: value to be transformed :returns: transformed value :rtype: TFloat .. py:attribute:: experiment .. py:attribute:: identifier .. py:attribute:: debug_output :value: False .. py:attribute:: core .. py:attribute:: _kernel_invariants .. py:attribute:: _prepare_done :value: False .. py:attribute:: _build_done :value: False .. py:attribute:: _hooks_done :value: [] .. py:method:: _recursive_prepare() .. py:method:: _prepare() Specify here what should be done for this component in the prepare phase .. py:method:: _recursive_build() .. py:method:: _build() Specify here what should be done for this component in the build phase .. py:method:: _do_prerun() .. py:method:: required_components(ancestors=[]) .. py:method:: _prerun() Specify here what should be done for this component before the run starts. In contrast to the _build() method, the _prerun() routine is executed on the core device before the actual experiment starts. .. py:attribute:: children :value: [] .. py:attribute:: __in_build :value: True .. py:method:: register_child(child) .. py:method:: call_child_method(method, *args, **kwargs) Calls the named method for each child, if it exists for that child, in the order of registration. :param method: Name of the method to call :type method: str :param args: Tuple of positional arguments to pass to all children :param kwargs: Dict of keyword arguments to pass to all children .. py:method:: 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 :meth:`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). .. py:method:: get_argument(key, processor, group=None, tooltip=None) Retrieves and returns the value of an argument. This function should only be called from ``build``. :param key: Name of the argument. :param processor: A description of how to process the argument, such as instances of :mod:`~artiq.language.environment.BooleanValue` and :mod:`~artiq.language.environment.NumberValue`. :param group: An optional string that defines what group the argument belongs to, for user interface purposes. :param tooltip: An optional string to describe the argument in more detail, applied as a tooltip to the argument name in the user interface. .. py:method:: 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. .. py:method:: interactive(title='') Request arguments from the user interactively. This context manager returns a namespace object on which the method :meth:`~artiq.language.environment.HasEnvironment.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 :exc:`~artiq.language.environment.CancelledArgsError`. .. py:method:: get_device_db() Returns the full contents of the device database. .. py:method:: get_device(key) Creates and returns a device driver. .. py:method:: 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. .. py:method:: 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. :param unit: A string representing the unit of the value. :param 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. :param 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. :param broadcast: the data is sent in real-time to the master, which dispatches it. :param persist: the master should store the data on-disk. Implies broadcast. :param archive: the data is saved into the local storage of the current run (archived as a HDF5 file). .. py:method:: 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). .. py:method:: 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. .. py:method:: get_dataset(key, default=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. :param archive: Set to ``False`` to prevent archival together with the run's results. Default is ``True``. .. py:method:: get_dataset_metadata(key, default=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 :meth:`set_dataset` for documentation of metadata items. .. py:method:: setattr_dataset(key, default=NoDefault, archive=True) Sets the contents of a dataset as attribute. The names of the dataset and of the attribute are the same. .. py:method:: set_default_scheduling(priority=None, pipeline_name=None, flush=None) Sets the default scheduling options. This function should only be called from ``build``. .. py:class:: DummyCalibration(*args, **kwargs) Bases: :py:obj:`Calibration` An abstract Calibration This is an abstract class to describe a calibration. :param input_unit: A string determining the input unit (e.g. 'mW', 'V', or 'uA') :param output_unit: A string determining the output unit (e.g. 'mW', 'V', or 'uA') .. py:method:: transform(input_value) Transform a value according to the calibration :param input_value: value to be transformed :returns: transformed value :rtype: TFloat .. py:attribute:: kernel_invariants .. py:attribute:: input_unit .. py:attribute:: output_unit .. py:attribute:: experiment .. py:attribute:: identifier .. py:attribute:: debug_output :value: False .. py:attribute:: core .. py:attribute:: _kernel_invariants .. py:attribute:: _prepare_done :value: False .. py:attribute:: _build_done :value: False .. py:attribute:: _hooks_done :value: [] .. py:method:: _recursive_prepare() .. py:method:: _prepare() Specify here what should be done for this component in the prepare phase .. py:method:: _recursive_build() .. py:method:: _build() Specify here what should be done for this component in the build phase .. py:method:: _do_prerun() .. py:method:: required_components(ancestors=[]) .. py:method:: _prerun() Specify here what should be done for this component before the run starts. In contrast to the _build() method, the _prerun() routine is executed on the core device before the actual experiment starts. .. py:attribute:: children :value: [] .. py:attribute:: __in_build :value: True .. py:method:: register_child(child) .. py:method:: call_child_method(method, *args, **kwargs) Calls the named method for each child, if it exists for that child, in the order of registration. :param method: Name of the method to call :type method: str :param args: Tuple of positional arguments to pass to all children :param kwargs: Dict of keyword arguments to pass to all children .. py:method:: 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 :meth:`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). .. py:method:: get_argument(key, processor, group=None, tooltip=None) Retrieves and returns the value of an argument. This function should only be called from ``build``. :param key: Name of the argument. :param processor: A description of how to process the argument, such as instances of :mod:`~artiq.language.environment.BooleanValue` and :mod:`~artiq.language.environment.NumberValue`. :param group: An optional string that defines what group the argument belongs to, for user interface purposes. :param tooltip: An optional string to describe the argument in more detail, applied as a tooltip to the argument name in the user interface. .. py:method:: 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. .. py:method:: interactive(title='') Request arguments from the user interactively. This context manager returns a namespace object on which the method :meth:`~artiq.language.environment.HasEnvironment.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 :exc:`~artiq.language.environment.CancelledArgsError`. .. py:method:: get_device_db() Returns the full contents of the device database. .. py:method:: get_device(key) Creates and returns a device driver. .. py:method:: 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. .. py:method:: 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. :param unit: A string representing the unit of the value. :param 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. :param 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. :param broadcast: the data is sent in real-time to the master, which dispatches it. :param persist: the master should store the data on-disk. Implies broadcast. :param archive: the data is saved into the local storage of the current run (archived as a HDF5 file). .. py:method:: 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). .. py:method:: 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. .. py:method:: get_dataset(key, default=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. :param archive: Set to ``False`` to prevent archival together with the run's results. Default is ``True``. .. py:method:: get_dataset_metadata(key, default=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 :meth:`set_dataset` for documentation of metadata items. .. py:method:: setattr_dataset(key, default=NoDefault, archive=True) Sets the contents of a dataset as attribute. The names of the dataset and of the attribute are the same. .. py:method:: set_default_scheduling(priority=None, pipeline_name=None, flush=None) Sets the default scheduling options. This function should only be called from ``build``. .. py:class:: SplineCalibration(calibration_points, *args, **kwargs) Bases: :py:obj:`Calibration` Calibration via data points Data points are interpolated with linear splines :param calibration_points: List of tuples (x, y) containing the calibration data. The data must be ordered monotonously in `x` .. py:attribute:: kernel_invariants .. py:attribute:: calibration_points .. py:method:: transform(input_value, invert = False) Transform a value according to the calibration :param input_value: value to be transformed :returns: transformed value :rtype: TFloat .. py:attribute:: input_unit .. py:attribute:: output_unit .. py:attribute:: experiment .. py:attribute:: identifier .. py:attribute:: debug_output :value: False .. py:attribute:: core .. py:attribute:: _kernel_invariants .. py:attribute:: _prepare_done :value: False .. py:attribute:: _build_done :value: False .. py:attribute:: _hooks_done :value: [] .. py:method:: _recursive_prepare() .. py:method:: _prepare() Specify here what should be done for this component in the prepare phase .. py:method:: _recursive_build() .. py:method:: _build() Specify here what should be done for this component in the build phase .. py:method:: _do_prerun() .. py:method:: required_components(ancestors=[]) .. py:method:: _prerun() Specify here what should be done for this component before the run starts. In contrast to the _build() method, the _prerun() routine is executed on the core device before the actual experiment starts. .. py:attribute:: children :value: [] .. py:attribute:: __in_build :value: True .. py:method:: register_child(child) .. py:method:: call_child_method(method, *args, **kwargs) Calls the named method for each child, if it exists for that child, in the order of registration. :param method: Name of the method to call :type method: str :param args: Tuple of positional arguments to pass to all children :param kwargs: Dict of keyword arguments to pass to all children .. py:method:: 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 :meth:`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). .. py:method:: get_argument(key, processor, group=None, tooltip=None) Retrieves and returns the value of an argument. This function should only be called from ``build``. :param key: Name of the argument. :param processor: A description of how to process the argument, such as instances of :mod:`~artiq.language.environment.BooleanValue` and :mod:`~artiq.language.environment.NumberValue`. :param group: An optional string that defines what group the argument belongs to, for user interface purposes. :param tooltip: An optional string to describe the argument in more detail, applied as a tooltip to the argument name in the user interface. .. py:method:: 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. .. py:method:: interactive(title='') Request arguments from the user interactively. This context manager returns a namespace object on which the method :meth:`~artiq.language.environment.HasEnvironment.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 :exc:`~artiq.language.environment.CancelledArgsError`. .. py:method:: get_device_db() Returns the full contents of the device database. .. py:method:: get_device(key) Creates and returns a device driver. .. py:method:: 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. .. py:method:: 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. :param unit: A string representing the unit of the value. :param 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. :param 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. :param broadcast: the data is sent in real-time to the master, which dispatches it. :param persist: the master should store the data on-disk. Implies broadcast. :param archive: the data is saved into the local storage of the current run (archived as a HDF5 file). .. py:method:: 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). .. py:method:: 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. .. py:method:: get_dataset(key, default=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. :param archive: Set to ``False`` to prevent archival together with the run's results. Default is ``True``. .. py:method:: get_dataset_metadata(key, default=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 :meth:`set_dataset` for documentation of metadata items. .. py:method:: setattr_dataset(key, default=NoDefault, archive=True) Sets the contents of a dataset as attribute. The names of the dataset and of the attribute are the same. .. py:method:: set_default_scheduling(priority=None, pipeline_name=None, flush=None) Sets the default scheduling options. This function should only be called from ``build``. .. py:class:: InvertableSplineCalibration(*args, **kwargs) Bases: :py:obj:`InvertableCalibration`, :py:obj:`SplineCalibration` Calibration via data points that can be inverted Data points are interpolated with linear splines. For the inversion to work, both `x` and `y` of the calibration data must be monotonous. .. py:method:: transform_inv(input_value) Perform inverse transform of a value according to the calibration :param input_value: value to be inversely transformed. Must be given in units of the output unit :returns: transformed value. The returned value is in units of the input unit :rtype: TFloat .. py:attribute:: kernel_invariants .. py:attribute:: input_unit .. py:attribute:: output_unit .. py:method:: transform(input_value) :abstractmethod: Transform a value according to the calibration :param input_value: value to be transformed :returns: transformed value :rtype: TFloat .. py:attribute:: experiment .. py:attribute:: identifier .. py:attribute:: debug_output :value: False .. py:attribute:: core .. py:attribute:: _kernel_invariants .. py:attribute:: _prepare_done :value: False .. py:attribute:: _build_done :value: False .. py:attribute:: _hooks_done :value: [] .. py:method:: _recursive_prepare() .. py:method:: _prepare() Specify here what should be done for this component in the prepare phase .. py:method:: _recursive_build() .. py:method:: _build() Specify here what should be done for this component in the build phase .. py:method:: _do_prerun() .. py:method:: required_components(ancestors=[]) .. py:method:: _prerun() Specify here what should be done for this component before the run starts. In contrast to the _build() method, the _prerun() routine is executed on the core device before the actual experiment starts. .. py:attribute:: children :value: [] .. py:attribute:: __in_build :value: True .. py:method:: register_child(child) .. py:method:: call_child_method(method, *args, **kwargs) Calls the named method for each child, if it exists for that child, in the order of registration. :param method: Name of the method to call :type method: str :param args: Tuple of positional arguments to pass to all children :param kwargs: Dict of keyword arguments to pass to all children .. py:method:: 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 :meth:`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). .. py:method:: get_argument(key, processor, group=None, tooltip=None) Retrieves and returns the value of an argument. This function should only be called from ``build``. :param key: Name of the argument. :param processor: A description of how to process the argument, such as instances of :mod:`~artiq.language.environment.BooleanValue` and :mod:`~artiq.language.environment.NumberValue`. :param group: An optional string that defines what group the argument belongs to, for user interface purposes. :param tooltip: An optional string to describe the argument in more detail, applied as a tooltip to the argument name in the user interface. .. py:method:: 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. .. py:method:: interactive(title='') Request arguments from the user interactively. This context manager returns a namespace object on which the method :meth:`~artiq.language.environment.HasEnvironment.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 :exc:`~artiq.language.environment.CancelledArgsError`. .. py:method:: get_device_db() Returns the full contents of the device database. .. py:method:: get_device(key) Creates and returns a device driver. .. py:method:: 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. .. py:method:: 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. :param unit: A string representing the unit of the value. :param 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. :param 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. :param broadcast: the data is sent in real-time to the master, which dispatches it. :param persist: the master should store the data on-disk. Implies broadcast. :param archive: the data is saved into the local storage of the current run (archived as a HDF5 file). .. py:method:: 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). .. py:method:: 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. .. py:method:: get_dataset(key, default=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. :param archive: Set to ``False`` to prevent archival together with the run's results. Default is ``True``. .. py:method:: get_dataset_metadata(key, default=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 :meth:`set_dataset` for documentation of metadata items. .. py:method:: setattr_dataset(key, default=NoDefault, archive=True) Sets the contents of a dataset as attribute. The names of the dataset and of the attribute are the same. .. py:method:: set_default_scheduling(priority=None, pipeline_name=None, flush=None) Sets the default scheduling options. This function should only be called from ``build``. .. py:attribute:: calibration_points .. py:class:: PolynomialCalibration(*args, coefficients, **kwargs) Bases: :py:obj:`Calibration` Calibration described by a polynomial The calibration is given by the function $$f(x) = \sum_i c_i x^i$$ :param coefficients: List of coefficients $c_i$ of the polynomial, start from the lowest order. .. py:attribute:: kernel_invariants .. py:attribute:: coefficients .. py:method:: transform(input_value) Transform a value according to the calibration :param input_value: value to be transformed :returns: transformed value :rtype: TFloat .. py:attribute:: input_unit .. py:attribute:: output_unit .. py:attribute:: experiment .. py:attribute:: identifier .. py:attribute:: debug_output :value: False .. py:attribute:: core .. py:attribute:: _kernel_invariants .. py:attribute:: _prepare_done :value: False .. py:attribute:: _build_done :value: False .. py:attribute:: _hooks_done :value: [] .. py:method:: _recursive_prepare() .. py:method:: _prepare() Specify here what should be done for this component in the prepare phase .. py:method:: _recursive_build() .. py:method:: _build() Specify here what should be done for this component in the build phase .. py:method:: _do_prerun() .. py:method:: required_components(ancestors=[]) .. py:method:: _prerun() Specify here what should be done for this component before the run starts. In contrast to the _build() method, the _prerun() routine is executed on the core device before the actual experiment starts. .. py:attribute:: children :value: [] .. py:attribute:: __in_build :value: True .. py:method:: register_child(child) .. py:method:: call_child_method(method, *args, **kwargs) Calls the named method for each child, if it exists for that child, in the order of registration. :param method: Name of the method to call :type method: str :param args: Tuple of positional arguments to pass to all children :param kwargs: Dict of keyword arguments to pass to all children .. py:method:: 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 :meth:`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). .. py:method:: get_argument(key, processor, group=None, tooltip=None) Retrieves and returns the value of an argument. This function should only be called from ``build``. :param key: Name of the argument. :param processor: A description of how to process the argument, such as instances of :mod:`~artiq.language.environment.BooleanValue` and :mod:`~artiq.language.environment.NumberValue`. :param group: An optional string that defines what group the argument belongs to, for user interface purposes. :param tooltip: An optional string to describe the argument in more detail, applied as a tooltip to the argument name in the user interface. .. py:method:: 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. .. py:method:: interactive(title='') Request arguments from the user interactively. This context manager returns a namespace object on which the method :meth:`~artiq.language.environment.HasEnvironment.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 :exc:`~artiq.language.environment.CancelledArgsError`. .. py:method:: get_device_db() Returns the full contents of the device database. .. py:method:: get_device(key) Creates and returns a device driver. .. py:method:: 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. .. py:method:: 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. :param unit: A string representing the unit of the value. :param 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. :param 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. :param broadcast: the data is sent in real-time to the master, which dispatches it. :param persist: the master should store the data on-disk. Implies broadcast. :param archive: the data is saved into the local storage of the current run (archived as a HDF5 file). .. py:method:: 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). .. py:method:: 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. .. py:method:: get_dataset(key, default=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. :param archive: Set to ``False`` to prevent archival together with the run's results. Default is ``True``. .. py:method:: get_dataset_metadata(key, default=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 :meth:`set_dataset` for documentation of metadata items. .. py:method:: setattr_dataset(key, default=NoDefault, archive=True) Sets the contents of a dataset as attribute. The names of the dataset and of the attribute are the same. .. py:method:: set_default_scheduling(priority=None, pipeline_name=None, flush=None) Sets the default scheduling options. This function should only be called from ``build``. .. py:class:: LinearCalibration(a, b, *args, **kwargs) Bases: :py:obj:`InvertableCalibration` Linear calibration The calibration is given by the function $$f(x) = ax + b$$ :param input_unit: Unit of the input :param output_unit: Unit of the output :param a: Calibration coefficient a :param b: Calibration coefficient b .. py:attribute:: kernel_invariants .. py:attribute:: a .. py:attribute:: b .. py:method:: transform(input_value) Transform a value according to the calibration :param input_value: value to be transformed :returns: transformed value :rtype: TFloat .. py:method:: transform_inv(output_value) Perform inverse transform of a value according to the calibration :param input_value: value to be inversely transformed. Must be given in units of the output unit :returns: transformed value. The returned value is in units of the input unit :rtype: TFloat .. py:attribute:: input_unit .. py:attribute:: output_unit .. py:attribute:: experiment .. py:attribute:: identifier .. py:attribute:: debug_output :value: False .. py:attribute:: core .. py:attribute:: _kernel_invariants .. py:attribute:: _prepare_done :value: False .. py:attribute:: _build_done :value: False .. py:attribute:: _hooks_done :value: [] .. py:method:: _recursive_prepare() .. py:method:: _prepare() Specify here what should be done for this component in the prepare phase .. py:method:: _recursive_build() .. py:method:: _build() Specify here what should be done for this component in the build phase .. py:method:: _do_prerun() .. py:method:: required_components(ancestors=[]) .. py:method:: _prerun() Specify here what should be done for this component before the run starts. In contrast to the _build() method, the _prerun() routine is executed on the core device before the actual experiment starts. .. py:attribute:: children :value: [] .. py:attribute:: __in_build :value: True .. py:method:: register_child(child) .. py:method:: call_child_method(method, *args, **kwargs) Calls the named method for each child, if it exists for that child, in the order of registration. :param method: Name of the method to call :type method: str :param args: Tuple of positional arguments to pass to all children :param kwargs: Dict of keyword arguments to pass to all children .. py:method:: 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 :meth:`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). .. py:method:: get_argument(key, processor, group=None, tooltip=None) Retrieves and returns the value of an argument. This function should only be called from ``build``. :param key: Name of the argument. :param processor: A description of how to process the argument, such as instances of :mod:`~artiq.language.environment.BooleanValue` and :mod:`~artiq.language.environment.NumberValue`. :param group: An optional string that defines what group the argument belongs to, for user interface purposes. :param tooltip: An optional string to describe the argument in more detail, applied as a tooltip to the argument name in the user interface. .. py:method:: 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. .. py:method:: interactive(title='') Request arguments from the user interactively. This context manager returns a namespace object on which the method :meth:`~artiq.language.environment.HasEnvironment.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 :exc:`~artiq.language.environment.CancelledArgsError`. .. py:method:: get_device_db() Returns the full contents of the device database. .. py:method:: get_device(key) Creates and returns a device driver. .. py:method:: 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. .. py:method:: 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. :param unit: A string representing the unit of the value. :param 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. :param 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. :param broadcast: the data is sent in real-time to the master, which dispatches it. :param persist: the master should store the data on-disk. Implies broadcast. :param archive: the data is saved into the local storage of the current run (archived as a HDF5 file). .. py:method:: 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). .. py:method:: 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. .. py:method:: get_dataset(key, default=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. :param archive: Set to ``False`` to prevent archival together with the run's results. Default is ``True``. .. py:method:: get_dataset_metadata(key, default=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 :meth:`set_dataset` for documentation of metadata items. .. py:method:: setattr_dataset(key, default=NoDefault, archive=True) Sets the contents of a dataset as attribute. The names of the dataset and of the attribute are the same. .. py:method:: set_default_scheduling(priority=None, pipeline_name=None, flush=None) Sets the default scheduling options. This function should only be called from ``build``. .. py:class:: SigmoidCalibration(*args, A, k, x_offset = 0, y_offset = 0, **kwargs) Bases: :py:obj:`Calibration` Sigmoid calibration ``` output = A / ( 1 + e^k*(input - x_offset)) + y_offset ``` :param input_unit: Unit of the input :param output_unit: Unit of the output :param A: Amplitude of the sigmoid :param k: stretching of the sigmoid :param x_offset: offset on the x axis :param y_offset: offset on the y axis .. py:attribute:: kernel_invariants .. py:attribute:: A .. py:attribute:: k .. py:attribute:: x_offset :value: 0 .. py:attribute:: y_offset :value: 0 .. py:method:: transform(input_value) Transform a value according to the calibration :param input_value: value to be transformed :returns: transformed value :rtype: TFloat .. py:attribute:: input_unit .. py:attribute:: output_unit .. py:attribute:: experiment .. py:attribute:: identifier .. py:attribute:: debug_output :value: False .. py:attribute:: core .. py:attribute:: _kernel_invariants .. py:attribute:: _prepare_done :value: False .. py:attribute:: _build_done :value: False .. py:attribute:: _hooks_done :value: [] .. py:method:: _recursive_prepare() .. py:method:: _prepare() Specify here what should be done for this component in the prepare phase .. py:method:: _recursive_build() .. py:method:: _build() Specify here what should be done for this component in the build phase .. py:method:: _do_prerun() .. py:method:: required_components(ancestors=[]) .. py:method:: _prerun() Specify here what should be done for this component before the run starts. In contrast to the _build() method, the _prerun() routine is executed on the core device before the actual experiment starts. .. py:attribute:: children :value: [] .. py:attribute:: __in_build :value: True .. py:method:: register_child(child) .. py:method:: call_child_method(method, *args, **kwargs) Calls the named method for each child, if it exists for that child, in the order of registration. :param method: Name of the method to call :type method: str :param args: Tuple of positional arguments to pass to all children :param kwargs: Dict of keyword arguments to pass to all children .. py:method:: 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 :meth:`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). .. py:method:: get_argument(key, processor, group=None, tooltip=None) Retrieves and returns the value of an argument. This function should only be called from ``build``. :param key: Name of the argument. :param processor: A description of how to process the argument, such as instances of :mod:`~artiq.language.environment.BooleanValue` and :mod:`~artiq.language.environment.NumberValue`. :param group: An optional string that defines what group the argument belongs to, for user interface purposes. :param tooltip: An optional string to describe the argument in more detail, applied as a tooltip to the argument name in the user interface. .. py:method:: 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. .. py:method:: interactive(title='') Request arguments from the user interactively. This context manager returns a namespace object on which the method :meth:`~artiq.language.environment.HasEnvironment.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 :exc:`~artiq.language.environment.CancelledArgsError`. .. py:method:: get_device_db() Returns the full contents of the device database. .. py:method:: get_device(key) Creates and returns a device driver. .. py:method:: 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. .. py:method:: 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. :param unit: A string representing the unit of the value. :param 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. :param 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. :param broadcast: the data is sent in real-time to the master, which dispatches it. :param persist: the master should store the data on-disk. Implies broadcast. :param archive: the data is saved into the local storage of the current run (archived as a HDF5 file). .. py:method:: 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). .. py:method:: 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. .. py:method:: get_dataset(key, default=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. :param archive: Set to ``False`` to prevent archival together with the run's results. Default is ``True``. .. py:method:: get_dataset_metadata(key, default=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 :meth:`set_dataset` for documentation of metadata items. .. py:method:: setattr_dataset(key, default=NoDefault, archive=True) Sets the contents of a dataset as attribute. The names of the dataset and of the attribute are the same. .. py:method:: set_default_scheduling(priority=None, pipeline_name=None, flush=None) Sets the default scheduling options. This function should only be called from ``build``. .. py:class:: InvSigmoidCalibration(*args, A, k, x_offset = 0, y_offset = 0, **kwargs) Bases: :py:obj:`Calibration` Inverse sigmoid calibration ``` output = -ln( A / (input - y_offset) - 1) / k + x_offset ``` The parameters are defined in a way that they match the sigmoid definition. :param input_unit: Unit of the input :param output_unit: Unit of the output :param A: Amplitude of the sigmoid :param k: stretching of the sigmoid :param x_offset: offset on the x axis :param y_offset: offset on the y axis .. py:attribute:: kernel_invariants .. py:attribute:: A .. py:attribute:: k .. py:attribute:: x_offset :value: 0 .. py:attribute:: y_offset :value: 0 .. py:method:: transform(input_value) Transform a value according to the calibration :param input_value: value to be transformed :returns: transformed value :rtype: TFloat .. py:attribute:: input_unit .. py:attribute:: output_unit .. py:attribute:: experiment .. py:attribute:: identifier .. py:attribute:: debug_output :value: False .. py:attribute:: core .. py:attribute:: _kernel_invariants .. py:attribute:: _prepare_done :value: False .. py:attribute:: _build_done :value: False .. py:attribute:: _hooks_done :value: [] .. py:method:: _recursive_prepare() .. py:method:: _prepare() Specify here what should be done for this component in the prepare phase .. py:method:: _recursive_build() .. py:method:: _build() Specify here what should be done for this component in the build phase .. py:method:: _do_prerun() .. py:method:: required_components(ancestors=[]) .. py:method:: _prerun() Specify here what should be done for this component before the run starts. In contrast to the _build() method, the _prerun() routine is executed on the core device before the actual experiment starts. .. py:attribute:: children :value: [] .. py:attribute:: __in_build :value: True .. py:method:: register_child(child) .. py:method:: call_child_method(method, *args, **kwargs) Calls the named method for each child, if it exists for that child, in the order of registration. :param method: Name of the method to call :type method: str :param args: Tuple of positional arguments to pass to all children :param kwargs: Dict of keyword arguments to pass to all children .. py:method:: 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 :meth:`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). .. py:method:: get_argument(key, processor, group=None, tooltip=None) Retrieves and returns the value of an argument. This function should only be called from ``build``. :param key: Name of the argument. :param processor: A description of how to process the argument, such as instances of :mod:`~artiq.language.environment.BooleanValue` and :mod:`~artiq.language.environment.NumberValue`. :param group: An optional string that defines what group the argument belongs to, for user interface purposes. :param tooltip: An optional string to describe the argument in more detail, applied as a tooltip to the argument name in the user interface. .. py:method:: 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. .. py:method:: interactive(title='') Request arguments from the user interactively. This context manager returns a namespace object on which the method :meth:`~artiq.language.environment.HasEnvironment.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 :exc:`~artiq.language.environment.CancelledArgsError`. .. py:method:: get_device_db() Returns the full contents of the device database. .. py:method:: get_device(key) Creates and returns a device driver. .. py:method:: 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. .. py:method:: 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. :param unit: A string representing the unit of the value. :param 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. :param 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. :param broadcast: the data is sent in real-time to the master, which dispatches it. :param persist: the master should store the data on-disk. Implies broadcast. :param archive: the data is saved into the local storage of the current run (archived as a HDF5 file). .. py:method:: 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). .. py:method:: 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. .. py:method:: get_dataset(key, default=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. :param archive: Set to ``False`` to prevent archival together with the run's results. Default is ``True``. .. py:method:: get_dataset_metadata(key, default=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 :meth:`set_dataset` for documentation of metadata items. .. py:method:: setattr_dataset(key, default=NoDefault, archive=True) Sets the contents of a dataset as attribute. The names of the dataset and of the attribute are the same. .. py:method:: set_default_scheduling(priority=None, pipeline_name=None, flush=None) Sets the default scheduling options. This function should only be called from ``build``.