doc: scans

This commit is contained in:
Sebastien Bourdeauducq 2015-08-21 13:32:53 +08:00
parent a8575fe2ac
commit ac5dd0a7e5
2 changed files with 44 additions and 0 deletions

View File

@ -1,3 +1,23 @@
"""
Implementation and management of scan objects.
A scan object (e.g. :class:`artiq.language.scan.LinearScan`) represents a
one-dimensional sweep of a numerical range. Multi-dimensional scans are
constructed by combining several scan objects.
Iterate on a scan object to scan it, e.g. ::
for variable in self.scan:
do_something(variable)
Iterating multiple times on the same scan object is possible, with the scan
restarting at the minimum value each time. Iterating concurrently on the
same scan object (e.g. via nested loops) is also supported, and the
iterators are independent from each other.
Scan objects are supported both on the host and the core device.
"""
from random import Random, shuffle from random import Random, shuffle
import inspect import inspect
@ -9,6 +29,7 @@ __all__ = ["NoScan", "LinearScan", "RandomScan", "ExplicitScan", "Scannable"]
class NoScan: class NoScan:
"""A scan object that yields a single value."""
def __init__(self, value): def __init__(self, value):
self.value = value self.value = value
@ -25,6 +46,8 @@ class NoScan:
class LinearScan: class LinearScan:
"""A scan object that yields a fixed number of increasing evenly
spaced values in a range."""
def __init__(self, min, max, npoints): def __init__(self, min, max, npoints):
self.min = min self.min = min
self.max = max self.max = max
@ -47,6 +70,8 @@ class LinearScan:
class RandomScan: class RandomScan:
"""A scan object that yields a fixed number of randomly ordered evenly
spaced values in a range."""
def __init__(self, min, max, npoints, seed=0): def __init__(self, min, max, npoints, seed=0):
self.sequence = list(LinearScan(min, max, npoints)) self.sequence = list(LinearScan(min, max, npoints))
shuffle(self.sequence, Random(seed).random) shuffle(self.sequence, Random(seed).random)
@ -61,6 +86,7 @@ class RandomScan:
class ExplicitScan: class ExplicitScan:
"""A scan object that yields values from a explicitly defined sequence."""
def __init__(self, sequence): def __init__(self, sequence):
self.sequence = sequence self.sequence = sequence
@ -81,6 +107,18 @@ _ty_to_scan = {
class Scannable: class Scannable:
"""An argument (as defined in :class:`artiq.language.environment`) that
takes a scan object.
:param global_min: The minimum value taken by the scanned variable, common
to all scan modes. The user interface takes this value to set the
range of its input widgets.
:param global_max: Same as global_min, but for the maximum value.
:param global_step: The step with which the value should be modified by
up/down buttons in a user interface.
:param unit: A string representing the unit of the scanned variable, for user
interface purposes.
"""
def __init__(self, global_min=None, global_max=None, global_step=None, def __init__(self, global_min=None, global_max=None, global_step=None,
unit="", default=NoDefault): unit="", default=NoDefault):
self.global_min = global_min self.global_min = global_min

View File

@ -15,6 +15,12 @@ The most commonly used features from those modules can be imported with ``from a
.. automodule:: artiq.language.environment .. automodule:: artiq.language.environment
:members: :members:
:mod:`artiq.language.scan` module
----------------------------------------
.. automodule:: artiq.language.scan
:members:
:mod:`artiq.language.units` module :mod:`artiq.language.units` module
---------------------------------- ----------------------------------