atomiq.components.coil ====================== .. py:module:: atomiq.components.coil Classes ------- .. autoapisummary:: atomiq.components.coil.Coil atomiq.components.coil.CoilPair Module Contents --------------- .. py:class:: Coil(current_source, calibration, switch = None, *args, **kwargs) Bases: :py:obj:`atomiq.components.primitives.Component`, :py:obj:`atomiq.components.primitives.Parametrizable`, :py:obj:`atomiq.components.primitives.Switchable` A single coil driven by a current source. It is characterized by a calibration that returns the B field for a given current through the coil. :param current_source: The current source that drives the coil :param calibration: The conversion between current in the coil and magnetic field at the point of interest. :param switch: An optional switch to switch on and off the current in the coil. If none is given and the current source is switchable, the current source is used for switching. If no switch is given and the current source is not switchable, an error is raised. .. py:attribute:: kernel_invariants .. py:attribute:: current_source .. py:attribute:: calibration .. py:method:: set_field(field) Set the `current_source` attached to the coil by using the given `calibration` to translate between `field` and current. :param field: Magnetic field to be set in units as dictated by the `calibration` .. py:method:: on() Use the `switch` (or `current_source`, see :class:`Coil`) to turn on the coil. .. py:method:: off() Use the `switch` (or `current_source`, see :class:`Coil`) to turn off the coil. .. 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:method:: set_parameter(value, channel = None) .. py:method:: is_on(channel = None) :abstractmethod: .. py:method:: toggle(channel = None) .. py:method:: pulse(pulsetime, channel = '') .. py:class:: CoilPair(current_source_coil1, current_source_coil2, calibration_field, calibration_gradient, switch = None, helmholtz_config = 1, default_field = 0.0, default_gradient = 0.0, *args, **kwargs) Bases: :py:obj:`atomiq.components.primitives.Component`, :py:obj:`atomiq.components.primitives.Parametrizable`, :py:obj:`atomiq.components.primitives.Switchable` A pair of identical coils driven by a common or two individual current sources. It is assumed that the pair of coils is placed symmetrically around the region of interest. It is characterized by a calibration (field_calibration) for the returns the B field for a given current through the coil and a calibration of the field gradient :param current_source_coil1: The current source for the first coil. :param current_source_coil2: The current source for the second coil. If the second coil is tied to the same current source as the first coil, specify the same current source here. Use the `helmholtz_config` parameter to specify the b-field orientation of the second coil. :param field_calibration: Calibration that gives the B field as a function of the current at the position of interest if the coilpair is in Helmholtz configuration :param gradient_calibration: Calibration that gives the B field gradient as a function of the current difference between the coils at the position of interest if the coilpair is in anti-Helmholtz configuration :param switch: Switch that switches the coil pair on and off. If none is given the current source is used to switch the coils (if it supports switching). (default None) :param helmholtz_config: if set to 1, same polarity of current in both coils creates a Helmholtz field. If set to -1 same polarity of current in both coils creates an anti-Helmholtz field. (default 1) :param default_field: Field to initialize the coil pair with (default 0) :param default_gradient: Gradient to initialize the coil pair with (default 0) .. py:attribute:: kernel_invariants .. py:attribute:: current_source_coil1 .. py:attribute:: current_source_coil2 .. py:attribute:: single_source .. py:attribute:: helmholtz_config :value: 1 .. py:attribute:: calibration_field .. py:attribute:: calibration_gradient .. py:attribute:: field :value: 0.0 .. py:attribute:: gradient :value: 0.0 .. 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:method:: _set_currents() .. py:method:: set_field(field, update = True) Set the field of the coil pair at the position if interest. :param field: Field to be set in the units of the calibration `field_calibration` :param update: immediately apply the change to the hardware .. py:method:: set_gradient(gradient, update = True) Set the field gradient of the coil pair at the position of interest. :param gradient: Field gradient to be set in the units of the calibration `field_calibration` :param update: immediately apply the change to the hardware .. py:method:: ramp_field_and_gradient(duration, field_end, gradient_end, field_start = float('nan'), gradient_start = float('nan'), ramp_timestep = 0.001) Ramp the field and gradient thereof created by a pair of coils. Note that this only works as expected with two independent current sources. This method advances the timeline by `duration`. :param duration: duration of the ramp :param field_end: final field at the end of the ramp :param gradient_end: final gradient at the end of the ramp :param field_start: starting field of the ramp. Current field is used if not given. :param gradient_start: starting gradient of the ramp. Current gradient is used if not given. :param ramp_timestep: sampling interval of the ramp .. py:method:: ramp_field(duration, field_end, field_start = float('nan'), ramp_timestep = 0.001) Ramp the field created by pair of coils. This method advances the timeline by `duration`. :param duration: duration of the ramp :param field_end: final field at the end of the ramp :param field_start: starting field of the ramp. Current field is used if not given. :param ramp_timestep: sampling interval of the ramp .. py:method:: ramp_gradient(duration, gradient_end, gradient_start = float('nan'), ramp_timestep = 0.001) Ramp the gradient created by pair of coils. This method advances the timeline by `duration`. :param duration: duration of the ramp :param gradient_end: final gradient at the end of the ramp :param gradient_start: starting gradient of the ramp. Current gradient is used if not given. :param ramp_timestep: sampling interval of the ramp .. py:method:: on() .. py:method:: off() .. py:method:: _switch_on_via_currentsource() .. py:method:: _switch_off_via_currentsource() .. 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: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:method:: set_parameter(value, channel = None) .. py:method:: is_on(channel = None) :abstractmethod: .. py:method:: toggle(channel = None) .. py:method:: pulse(pulsetime, channel = '')