Merge pull request #190 from randomir/remove-int-ident

Remove interruptable identity

README.rst

@@ -80,7 +80,6 @@ Example
 
     # Define the workflow
     iteration = hybrid.RacingBranches(
-        hybrid.InterruptableIdentity(),
         hybrid.InterruptableTabuSampler(),
         hybrid.EnergyImpactDecomposer(size=2)
         | hybrid.QPUSubproblemAutoEmbeddingSampler()

docs/reference/flow.rst

@@ -17,7 +17,7 @@ Classes
 .. autoclass:: Const
 .. autoclass:: Dup
 .. autoclass:: Identity
-.. autofunction:: InterruptableIdentity
+.. autoclass:: BlockingIdentity
 .. autoclass:: Lambda
 .. autoclass:: Loop
 .. autoclass:: LoopUntilNoImprovement

examples/hybrid-sampler.py

@@ -31,7 +31,6 @@
 # define the workflow
 workflow = hybrid.Loop(
     hybrid.Race(
-        hybrid.InterruptableIdentity(),
         hybrid.InterruptableTabuSampler(),
         hybrid.EnergyImpactDecomposer(size=50, rolling=True, traversal='bfs')
         | hybrid.QPUSubproblemAutoEmbeddingSampler()

examples/nested-branches.py

@@ -31,7 +31,6 @@
 
 # construct a workflow that races Simulated Annealing against SA/Tabu on a subproblem
 iteration = hybrid.Race(
-    hybrid.InterruptableIdentity(),
     hybrid.SimulatedAnnealingProblemSampler(),
     hybrid.EnergyImpactDecomposer(size=50)
         | hybrid.RacingBranches(

examples/qbsolv-like-alt.py

@@ -52,10 +52,9 @@ def merge_substates(_, substates):
 subsampler = hybrid.Parallel(qpu, random) | hybrid.ArgMin()
 
 iteration = hybrid.Race(
-    hybrid.InterruptableIdentity(),
     hybrid.InterruptableTabuSampler(),
     subproblems | subsampler
-) | hybrid.ArgMin()
+) | hybrid.ArgMin() | hybrid.TrackMin(output=True)
 
 main = hybrid.Loop(iteration, max_iter=10, convergence=3)
 

examples/qbsolv-like.py

@@ -30,12 +30,11 @@
 
 # define the workflow
 iteration = hybrid.Race(
-    hybrid.InterruptableIdentity(),
     hybrid.InterruptableTabuSampler(),
     hybrid.EnergyImpactDecomposer(size=50, rolling=True, rolling_history=0.15)
     | hybrid.QPUSubproblemAutoEmbeddingSampler()
     | hybrid.SplatComposer()
-) | hybrid.ArgMin()
+) | hybrid.ArgMin() | hybrid.TrackMin(output=True)
 
 main = hybrid.Loop(iteration, max_iter=10, convergence=3)
 

examples/tabu-postprocessing.py

@@ -30,7 +30,6 @@
 
 # run Tabu in parallel with QPU, but post-process QPU samples with very short Tabu
 iteration = hybrid.Race(
-    hybrid.InterruptableIdentity(),
     hybrid.InterruptableTabuSampler(),
     hybrid.EnergyImpactDecomposer(size=50)
     | hybrid.QPUSubproblemAutoEmbeddingSampler(num_reads=100)

hybrid/flow.py

@@ -31,7 +31,7 @@
     'Branch', 'Branches', 'RacingBranches', 'Race', 'ParallelBranches', 'Parallel',
     'Map', 'Reduce', 'Lambda', 'ArgMin', 'Unwind', 'TrackMin',
     'Loop', 'LoopUntilNoImprovement', 'LoopWhileNoImprovement',
-    'Identity', 'InterruptableIdentity', 'Dup', 'Const', 'Wait'
+    'Identity', 'BlockingIdentity', 'Dup', 'Const', 'Wait'
 ]
 
 logger = logging.getLogger(__name__)
@@ -649,14 +649,18 @@ class TrackMin(traits.NotValidated, Runnable):
             If `output=True`, then this defines the variable/key name in the
             input state that shall be included in the output state.
 
-        output_key (str, optional, default='best_samples')
+        output_key (str, optional, default='samples')
             If `output=True`, then the key under which the `input_key` from the
             best state seen so far is stored in the output state.
 
+    Note:
+        If `output` option is turned on, and `output_key` is not changed, the
+        output will by default change the state's `samples` on output.
+
     """
 
     def __init__(self, key=None, output=False, input_key='samples',
-                 output_key='best_samples', **runopts):
+                 output_key='samples', **runopts):
         super(TrackMin, self).__init__(**runopts)
         if key is None:
             key = 'samples.first.energy'
@@ -1018,13 +1022,20 @@ def next(self, state, **runopts):
         return state.updated()
 
 
-def InterruptableIdentity(**runopts):
-    """Trivial interruptable identity runnable. The output is a direct copy of
-    the input, with a distinction from :class:`.Identity` that it will halt
-    until explicitly stopped (useful for example in :class:`.RacingBranches`
-    to prevent short-circuiting of racing branches with the identity branch).
+class BlockingIdentity(Wait):
+    """Trivial identity runnable that blocks indefinitely before producing
+    output, but is interruptable. The output is a direct copy of
+    the input, but to receive the output, the block has to be explicitly stopped
+    (useful for example in :class:`.RacingBranches` to prevent short-circuiting
+    of racing branches with the identity branch).
+
+    ::
+
+        BlockingIdentity := Identity | Wait
+
+    Due to nature of :class:`.Identity`, :class:`.BlockingIdentity` is
+    functionally equivalent to :class:`.Wait`.
     """
-    return Identity(**runopts) | Wait(**runopts)
 
 
 class Const(traits.NotValidated, Runnable):

hybrid/reference/kerberos.py

@@ -89,7 +89,7 @@ def Kerberos(max_iter=100, max_time=None, convergence=3, energy_threshold=None,
         energy_reached = lambda en: en <= energy_threshold
 
     iteration = hybrid.Race(
-        hybrid.InterruptableIdentity(),
+        hybrid.BlockingIdentity(),
         hybrid.InterruptableTabuSampler(
             timeout=tabu_timeout),
         hybrid.InterruptableSimulatedAnnealingProblemSampler(

hybrid/reference/qbsolv.py

@@ -34,13 +34,12 @@ def SimplifiedQbsolv(max_iter=10, max_time=None, convergence=3,
 
     workflow = hybrid.Loop(
         hybrid.Race(
-            hybrid.InterruptableIdentity(),
             hybrid.InterruptableTabuSampler(),
             hybrid.EnergyImpactDecomposer(
                 size=max_subproblem_size, rolling=True, rolling_history=0.15)
             | hybrid.QPUSubproblemAutoEmbeddingSampler()
             | hybrid.SplatComposer()
-        ) | hybrid.ArgMin(),
+        ) | hybrid.ArgMin() | hybrid.TrackMin(output=True),
         max_iter=max_iter, max_time=max_time,
         convergence=convergence, terminate=energy_reached)
 

tests/test_flow.py

@@ -27,7 +27,7 @@
     Branch, Branches, RacingBranches, ParallelBranches,
     ArgMin, Map, Reduce, Lambda, Unwind, TrackMin,
     LoopUntilNoImprovement, LoopWhileNoImprovement, SimpleIterator, Loop,
-    Identity, InterruptableIdentity, Dup, Const, Wait
+    Identity, BlockingIdentity, Dup, Const, Wait
 )
 from hybrid.core import State, States, Runnable, Present
 from hybrid.utils import min_sample, max_sample
@@ -272,7 +272,7 @@ def halt(self):
         self.assertEqual([s.x for s in res], [2, 1, 2])
 
         # "endomorphic case"
-        rb = RacingBranches(InterruptableIdentity(), Slow(), Fast(), Slow())
+        rb = RacingBranches(BlockingIdentity(), Slow(), Fast(), Slow())
         res = rb.run(State(x=0)).result()
         self.assertEqual([s.x for s in res], [0, 2, 1, 2])
 
@@ -872,10 +872,10 @@ def test_input_type_invariant(self):
         self.assertEqual(Identity().run(inp2).result(), inp2)
 
 
-class TestInterruptableIdentity(unittest.TestCase):
+class TestBlockingIdentity(unittest.TestCase):
 
     def test_basic(self):
-        ident = InterruptableIdentity()
+        ident = BlockingIdentity()
         state = State(x=1, y='a', z=[1,2,3])
 
         inp = copy.deepcopy(state)
@@ -887,7 +887,7 @@ def test_basic(self):
         self.assertFalse(out is inp)
 
     def test_interruptable(self):
-        ident = InterruptableIdentity()
+        ident = BlockingIdentity()
         state = State(x=1)
         out = ident.run(state)
 
@@ -907,14 +907,14 @@ def test_interruptable(self):
 
     def test_input_type_invariant(self):
         inp = State(x=1)
-        ii = InterruptableIdentity()
+        ii = BlockingIdentity()
         fut = ii.run(inp)
         ii.stop()
         out = fut.result()
         self.assertEqual(out, inp)
 
         inp = States(State(x=1), State(x=2))
-        ii = InterruptableIdentity()
+        ii = BlockingIdentity()
         fut = ii.run(inp)
         ii.stop()
         out = fut.result()