artiq_run,master: introduce __artiq_unit__ attribute to mark and name experiments

artiq/frontend/artiq_run.py

@@ -114,8 +114,7 @@ def main():
                 units = [(k, v) for k, v in module.__dict__.items()
                          if k[0] != "_"
                             and isclass(v)
-                            and issubclass(v, AutoDB)
+                            and hasattr(v, "__artiq_unit__")]
-                            and v is not AutoDB]
                 l = len(units)
                 if l == 0:
                     print("No units found in module")
@@ -123,7 +122,7 @@ def main():
                 elif l > 1:
                     print("More than one unit found in module:")
                     for k, v in sorted(units, key=itemgetter(0)):
-                        print("    " + k)
+                        print("    {} ({})".format(k, v.__artiq_unit__))
                     print("Use -u to specify which unit to use.")
                     sys.exit(1)
                 else:

artiq/master/worker_impl.py

@@ -6,7 +6,6 @@ import h5py
 
 from artiq.protocols import pyon
 from artiq.tools import file_import
-from artiq.language.db import AutoDB
 from artiq.master.db import DBHub, ResultDB
 
 
@@ -72,8 +71,7 @@ def get_unit(file, unit):
         units = [v for k, v in module.__dict__.items()
                  if k[0] != "_"
                     and isclass(v)
-                    and issubclass(v, AutoDB)
+                    and hasattr(v, "__artiq_unit__")]
-                    and v is not AutoDB]
         if len(units) != 1:
             raise ValueError("Found {} units in module".format(len(units)))
         return units[0]

benchmarks/all.py

@@ -2,10 +2,14 @@ from artiq import *
 
 import pulse_rate, rtio_skew, rpc_timing
 
+from pulse_rate import PulseRate
+from rtio_skew import RTIOSkew
 
 _units = [pulse_rate.PulseRate, rtio_skew.RTIOSkew, rpc_timing.RPCTiming]
 
 class AllBenchmarks(AutoDB):
+    __artiq_unit__ = "All benchmarks"
+
     def build(self):
         self.se = []
         for unit in _units:

benchmarks/pulse_rate.py

@@ -3,6 +3,8 @@ from artiq.coredevice.runtime_exceptions import RTIOUnderflow
 
 
 class PulseRate(AutoDB):
+    __artiq_unit__ = "Pulse rate"
+
     class DBKeys:
         ttl0 = Device()
         pulse_rate = Result()

benchmarks/rpc_timing.py

@@ -4,6 +4,8 @@ from artiq import *
 
 
 class RPCTiming(AutoDB):
+    __artiq_unit__ = "RPC timing"
+
     class DBKeys:
         repeats = Argument(100)
         rpc_time_mean = Result()

benchmarks/rtio_skew.py

@@ -6,6 +6,8 @@ class PulseNotReceived(Exception):
 
 
 class RTIOSkew(AutoDB):
+    __artiq_unit__ = "RTIO skew"
+
     class DBKeys:
         pmt0 = Device()
         ttl0 = Device()

doc/manual/getting_started.rst

@@ -10,6 +10,8 @@ As a very first step, we will turn on a LED on the core device. Create a file ``
 
 
     class LED(AutoDB):
+        __artiq_unit__ = "ARTIQ tutorial"
+
         class DBKeys:
             led = Device()
 
@@ -20,6 +22,8 @@ As a very first step, we will turn on a LED on the core device. Create a file ``
 
 The central part of our code is our ``LED`` class, that derives from :class:`artiq.language.db.AutoDB`. ``AutoDB`` is part of the mechanism that attaches device drivers and retrieves parameters according to a database. Our ``DBKeys`` class lists the devices (and parameters) that ``LED`` needs in order to operate, and the names of the attributes (e.g. ``led``) are used to search the database. ``AutoDB`` replaces them with the actual device drivers (and parameter values). Finally, the ``@kernel`` decorator tells the system that the ``run`` method must be executed on the core device (instead of the host).
 
+The ``__artiq_unit__`` attribute tells the ARTIQ tools that our class is a "unit" (an entry point for an experiment) and gives it a name. The name can be any string, and its purpose is to name the experiment in user interfaces.
+
 Copy the files ``ddb.pyon`` and ``pdb.pyon`` (containing the device and parameter databases) from the ``examples`` folder of ARTIQ into the same directory as ``led.py`` (alternatively, you can use the ``-d`` and ``-p`` options of ``artiq_run.py``). You can open the database files using a text editor - their contents are in a human-readable format.
 
 Run your code using ``artiq_run.py``, which is part of the ARTIQ front-end tools: ::
@@ -39,6 +43,8 @@ Modify the code as follows: ::
         return int(input("Enter desired LED state: "))
 
     class LED(AutoDB):
+        __artiq_unit__ = "ARTIQ tutorial"
+
         class DBKeys:
             led = Device()
 
@@ -82,6 +88,8 @@ Create a new file ``rtio.py`` containing the following: ::
     from artiq import *
 
     class Tutorial(AutoDB):
+        __artiq_unit__ = "ARTIQ tutorial"
+
         class DBKeys:
             ttl0 = Device()
 
@@ -104,6 +112,8 @@ Try reducing the period of the generated waveform until the CPU cannot keep up w
         print("RTIO underflow occured")
 
     class Tutorial(AutoDB):
+        __artiq_unit__ = "ARTIQ tutorial"
+
         class DBKeys:
             led = Device()
             ttl0 = Device()

examples/dds_test.py

@@ -2,6 +2,8 @@ from artiq import *
 
 
 class DDSTest(AutoDB):
+    __artiq_unit__ = "DDS test"
+
     class DBKeys:
         dds0 = Device()
         dds1 = Device()

examples/flopping_f_simulation.py

@@ -24,6 +24,8 @@ def model_numpy(xdata, F0):
 
 
 class FloppingF(AutoDB):
+    __artiq_unit__ = "Flopping F simulation"
+
     class DBKeys:
         implicit_core = False
 

examples/mandelbrot.py

@@ -4,6 +4,8 @@ from artiq import *
 
 
 class Mandelbrot(AutoDB):
+    __artiq_unit__ = "Mandelbrot set demo"
+
     def col(self, i):
         sys.stdout.write(" .,-:;i+hHM$*#@ "[i])
 

examples/photon_histogram.py

@@ -2,6 +2,8 @@ from artiq import *
 
 
 class PhotonHistogram(AutoDB):
+    __artiq_unit__ = "Photon histogram"
+
     class DBKeys:
         bd = Device()
         bdd = Device()

examples/simple_simulation.py

@@ -2,6 +2,8 @@ from artiq import *
 
 
 class SimpleSimulation(AutoDB):
+    __artiq_unit__ = "Simple simulation"
+
     class DBKeys:
         a = Device()
         b = Device()

examples/transport.py

@@ -11,6 +11,8 @@ transport_data = dict(
 )
 
 class Transport(AutoDB):
+    __artiq_unit__ = "Transport"
+
     class DBKeys:
         bd = Device()
         bdd = Device()