add cycle routing object

Author: geraintpalmer

ciw/routing/routing.py

@@ -1,4 +1,5 @@
 import ciw
+import itertools
 
 class NetworkRouting:
     """
@@ -248,3 +249,29 @@ def get_queue_size(self, node_index):
         Gets the size of the queue at the node_index.
         """
         return self.simulation.nodes[node_index].number_of_individuals
+
+
+class Cycle(NodeRouting):
+    """
+    A router that cycles through destinations, repeating the cycle once ended.
+    """
+    def __init__(self, cycle):
+        """
+        Initialises the routing object.
+
+        Takes:
+            - cycle: an ordered sequence of nodes.
+        """
+        self.cycle = cycle
+        self.generator = itertools.cycle(self.cycle)
+
+    def error_check_at_initialise(self):
+        if not set(self.cycle).issubset(set([nd.id_number for nd in self.simulation.nodes[1:]])):
+            raise ValueError("Routing destinations should be a subset of the nodes in the network.")
+
+    def next_node(self, ind):
+        """
+        Chooses the node 'to' with probability 1.
+        """
+        next_node_index = next(self.generator)
+        return self.simulation.nodes[next_node_index]

ciw/tests/test_routing.py

@@ -309,3 +309,27 @@ def test_load_balancing(self):
         self.assertEqual([samples_1[i] for i in [1, 2, 3, -1]], [507, 493, 0, 0])
         self.assertTrue(all(r == 1 for r in samples_2))
         self.assertTrue(all(r == 2 for r in samples_3))
+
+
+    def test_cycle_routing(self):
+        ciw.seed(0)
+        Q = ciw.Simulation(N)
+        R1 = ciw.routing.Cycle(cycle=[2, 3, 3])
+        R2 = ciw.routing.Cycle(cycle=[1, 2])
+        R3 = ciw.routing.Cycle(cycle=[1, -1, 2, -1])
+        R1.initialise(Q, 1)
+        R2.initialise(Q, 2)
+        R3.initialise(Q, 3)
+        ind = ciw.Individual(1)
+        samples_1 = [r.id_number for r in [R1.next_node(ind) for _ in range(20)]]
+        samples_2 = [r.id_number for r in [R2.next_node(ind) for _ in range(20)]]
+        samples_3 = [r.id_number for r in [R3.next_node(ind) for _ in range(20)]]
+        self.assertEqual([2, 3, 3, 2, 3, 3, 2, 3, 3, 2, 3, 3, 2, 3, 3, 2, 3, 3, 2, 3], samples_1)
+        self.assertEqual([1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2], samples_2)
+        self.assertEqual([1, -1, 2, -1, 1, -1, 2, -1, 1, -1, 2, -1, 1, -1, 2, -1, 1, -1, 2, -1], samples_3)
+
+    def test_cycle_routing_raises_errors(self):
+        ciw.seed(0)
+        Q = ciw.Simulation(N)
+        R1 = ciw.routing.Cycle(cycle=[1, 2, 7])
+        self.assertRaises(ValueError, R1.initialise, Q, 1)

docs/Reference/routers.rst

@@ -18,6 +18,7 @@ The following node routers are currently supported:
 - :ref:`probabilistic`
 - :ref:`jsq`
 - :ref:`load_balancing`
+- :ref:`cycle`
 
 
 
@@ -126,7 +127,6 @@ The :code:`tie_break` argument is optional, and can take one of two strings: :co
 
 .. _load_balancing:
 
-
 --------------
 Load Balancing
 --------------
@@ -136,3 +136,15 @@ The customer goes :ref:`joins the node with the least amount of customers presen
     ciw.routing.LoadBalancing(destinations=[1, 3], tie_break='random')
 
 The :code:`tie_break` argument is optional, and can take one of two strings: :code:`'random'` or :code:`'order'`. When there is a tie between the nodes with the least amount of customers present, tie breaks are either dealt with by choosing randomly between the ties (:code:`'random'`), or take precedence by the order listed in the :code:`destinations` list (:code:`'order'`). If omitted, random tie-breaking is used.
+
+
+.. _cycle:
+
+-----
+Cycle
+-----
+
+The customers' destinations out of the node cycles through a given list. For example, the first customer is routed to Node 1, the second to Node 1, the third to Node 3, the fourth to Node 2, then henceforth the order cycles, so the fifth is routed to Node 1, the sixth to Node 1, and so on::
+
+    ciw.routing.Cycle(cycle=[1, 1, 3, 2])
+