Table scan: 'loop' support

Author: kasemir

Test/test_range_helper.py

@@ -3,10 +3,28 @@
 
 @author: Kay Kasemir
 """
-from scan.table.range_helper import getIterable, expandRanges
+from scan.table.range_helper import getRangeOrLoop, range_matcher, loop_matcher, getIterable, expandRanges
 import unittest
 
 class TestRangeExpansion(unittest.TestCase):
+
+    def test_range(self):
+        r = getRangeOrLoop("range(2, 5, 0.5)", range_matcher)
+        self.assertEqual(str(r), "(2.0, 5.0, 0.5)")
+
+        r = getRangeOrLoop("range(5)", range_matcher)
+        self.assertEqual(str(r), "(0, 5.0, 1)")
+
+        r = getRangeOrLoop("range(2, 5)", range_matcher)
+        self.assertEqual(str(r), "(2.0, 5.0, 1)")
+
+        r = getRangeOrLoop("loop(2, 5)", range_matcher)
+        self.assertEqual(str(r), "None")
+
+        r = getRangeOrLoop("loop(2, 5)", loop_matcher)
+        self.assertEqual(str(r), "(2.0, 5.0, 1)")
+
+        
     def test_iterable(self):
         points = getIterable("[ 2, 4 ]")
         self.assertEqual(str(points), "[2, 4]")

Test/test_table_scan.py

@@ -27,7 +27,6 @@ def getReadbackName(self, device_name):
 
 # TODO 'Comment' column can be comment command or Set('SomeCommentPV')
 # TODO Fix Log command
-# TODO Devices to always log
 # TODO Start by waiting for all motors to be idle
 #         for motor in motors:
 #             idle = self.settings.getMotorIdlePV(motor)
@@ -306,7 +305,56 @@ def testLogAlways(self):
         cmds = handle(table_scan)
         self.assertEqual(str(cmds), "[Set('X', 10.0), Delay(10), Log('neutrons', 'X')]")
 
-        
+    def testLoop(self):
+        print "\n=== Loop Cells ==="
+        # Plain loop commands
+        table_scan = TableScan(
+          [   "position" ],
+          [
+            [ "loop(2, 5, 1)" ],
+          ]
+        )
+        cmds = handle(table_scan)
+        self.assertEqual(str(cmds), "[Loop('position', 2, 5, 1)]")
+
+        table_scan = TableScan(
+          (   "position",        "camera"),
+          [
+            [ "Loop(0, 3, 0.5)", "snap"],
+          ]
+        )
+        cmds = handle(table_scan)
+        self.assertEqual(str(cmds), "[Loop('position', 0, 3, 0.5, [ Set('camera', 'snap') ])]")
+
+        table_scan = TableScan(
+          (   "X",          "Y",        "Camera"),
+          [
+            [ "loop(1,10)", "Loop(2,5)", "Snap"],
+          ]
+        )
+        cmds = handle(table_scan)
+        self.assertEqual(str(cmds), "[Loop('X', 1, 10, 1, [ Loop('Y', 2, 5, 1, [ Set('Camera', 'Snap') ]) ])]")
+
+        # Can be mixed with range or list, but note that list is expanded first.
+        # This works as nestet list & loop:
+        table_scan = TableScan(
+          (   "X",      "Y",      "Camera"),
+          [
+            [ "[1, 2]", "Loop(3)", "Snap"],
+          ]
+        )
+        cmds = handle(table_scan)
+        self.assertEqual(str(cmds), "[Set('X', 1.0), Loop('Y', 0, 3, 1, [ Set('Camera', 'Snap') ]), Set('X', 2.0), Loop('Y', 0, 3, 1, [ Set('Camera', 'Snap') ])]")
+
+        # Here, however, the list is _first_ expanded into rows
+        table_scan = TableScan(
+          (   "X",       "Y",      "Camera"),
+          [
+            [ "Loop(3)", "[1, 2]", "Snap"],
+          ]
+        )
+        cmds = handle(table_scan)
+        self.assertEqual(str(cmds), "[Loop('X', 0, 3, 1, [ Set('Y', 1.0), Set('Camera', 'Snap') ]), Loop('X', 0, 3, 1, [ Set('Y', 2.0), Set('Camera', 'Snap') ])]")
 
     def testSpecialColumns(self):
         print "\n=== Special columns ==="

doc/scan_alternate.png

@@ -30,38 +30,38 @@ class Loop(Command):
     Set `pv1` to 1, 1.5, 2, 2.5, 3, .., 9.5, 10:
         >>> cmd = Loop('pv1', 1, 10, 0.5)
     
-    Set `pv1` to 10, 9, 8, 7, .., 1:
+    Set `pv1` to 10, 9, 8, 7, .., 1, i.e. stepping down:
         >>> cmd = Loop('pv1', 10, 1, -1)
     
-    At each step of the loop, perform additional commands:    
+    At each step of the loop, perform additional commands:
         >>> cmd = Loop('pv1', 1, 10, 1, Set('daq', 1), Delay(10), Set('daq', 0))
         >>> cmd = Loop('pv1', 1, 10, 1,
         ...            body = [ Set('daq', 1), Delay(10), Set('daq', 0) ])
     
     When after loop updates `pv1`, check for its readback to match, then perform commands within the loop:
         >>> cmd = Loop('pv1', 1, 10, 1, Set('daq', 1), Delay(10), Set('daq', 0), readback=True)
     
-    Special behavior of nested loops. If step size is 'wrong', the loops will cycle direction:
-        >>> cmd = Loop('x', 1, 3, 1, body=[ Loop('y', 1, 3, -1 ])
-    
-    Will result in these values:
-    
-    =  =
-    x  y
-    =  =
-    1  1
-    1  2
-    1  3
-    2  3
-    2  2
-    2  1
-    3  1
-    3  2
-    3  3
-    =  =
+    .. _`loop-direction`:
+    
+    
+    For nested loops, note the special handling of the step direction.
+    Consider a normal nested loop for 'xpos' and 'ypos' both stepping from 0 to 5 with a positive step:
+    
+        >>> cmd = Loop('xpos', 0, 5, 1, [ Loop('ypos', 0, 5, 1 ])
+    
+    In this example, the step size for the inner loop is 'wrong'.
+    Going from 0 to 5 ordinarily means stepping up by +1 in each loop iteration,
+    but the step is instead provided as -1, as if this was a loop from 5 down to 0:
+    
+        >>> cmd = Loop('xpos', 0, 5, 1, [ Loop('ypos', 0, 5, -1 ])
+    
+    As a result, the loop will cycle its direction between +1 and -1.
+    
+    .. image:: scan_alternate.png
     
     Note how the direction of the inner loop changes.
     This can be useful for scanning the X/Y surface of a sample.    
+    
     """
     def __init__(self, device, start, end, step, body=None, *args, **kwargs):
         if not isinstance(device, str):
@@ -119,6 +119,21 @@ def setTimeout(self, timeout):
         """
         self.__timeout = timeout
 
+    def getBody(self):
+        """Obtain list of body commands.
+        
+           The Loop(..) constructor creates a safe
+           copy of the passed 'body' to prevent side effects
+           when that body is later changed and maybe
+           used to construct another Loop(..) instance.
+           
+           If there is a desire to change the loop's body
+           (before it's submitted to the scan server),
+           this method provides that list of commands.
+           :return: Loop body
+        """
+        return self.__body
+        
     def genXML(self):
         xml = ET.Element('loop')
 

scan/commands/loop.py

@@ -14,17 +14,19 @@
 # Regular expression for the range([start,] stop[, step]) command,
 # capturing the start, end and step arguments
 __re_range = "range\((?:" + __re_dbl + ",)?" + __re_dbl + "(?:," + __re_dbl +")?\)"
-range_matcher = re.compile(__re_range)
 
+# Similar for loop([start,] stop[, step])
+__re_loop = "[Ll]oop\((?:" + __re_dbl + ",)?" + __re_dbl + "(?:," + __re_dbl +")?\)"
 
-def getIterable(cell):
-    """If cell contains a range, list or tuple, return that iterable.
-       Otherwise returns None
-    """
-    cell = str(cell).strip()
+range_matcher = re.compile(__re_range)
+loop_matcher = re.compile(__re_loop)
 
-    # Check for "range(...)"    
-    m = range_matcher.match(cell)
+def getRangeOrLoop(cell, matcher):
+    """Using either the range_matcher or loop_matcher,
+       get the (start, end, step) or None
+    """
+    # Check for "range(...)" or "loop(...)"
+    m = matcher.match(cell)
     if m:
         # Evaluate yourself to support fractional steps
         # (like numpy.arange, but without requiring numpy)
@@ -33,7 +35,23 @@ def getIterable(cell):
         end = float(end)
         step = float(step) if step else 1
         if step == 0:
-            raise Exception("Illegal range(start, stop, step=0)")
+            raise Exception("Illegal step=0 in " + cell)
+        return (start, end, step)
+    else:
+        return None
+    
+def getIterable(cell):
+    """If cell contains a range, list or tuple, return that iterable.
+       Otherwise returns None
+    """
+    cell = str(cell).strip()
+
+    # Check for "range(...)"
+    rng = getRangeOrLoop(cell, range_matcher)
+    if rng is not None:
+        # Evaluate yourself to support fractional steps
+        # (like numpy.arange, but without requiring numpy)
+        (start, end, step) = rng
         value = start
         result = []
         while value < end if step > 0 else value > end: