add flexible process based routing

Author: geraintpalmer

ciw/routing/routing.py

@@ -101,6 +101,67 @@ def next_node_for_rerouting(self, ind, node_id):
         """
         return self.next_node(ind, node_id)
 
+class FlexibleProcessBased(ProcessBased):
+    """
+    A class to route an individual based on a pre-defined process.
+    """
+    def __init__(self, route_function, rule, choice):
+        """
+        Initialises the routing object.
+
+        Takes:
+            - route_function: a function that returns a pre-defined route 
+        """
+        self.route_function = route_function
+        if rule not in ['any', 'all']:
+            raise ValueError("Flexible routing rules must be one of 'any' or 'all'.")
+        if choice not in ['random', 'jsq', 'lb']:
+            raise ValueError("Flexible routing choices must be one of 'random', 'jsq', or 'lb'.")
+        self.rule = rule
+        self.choice = choice
+
+    def find_next_node_from_subset(self, subset, ind):
+        """
+        Finds the next node within a subset of nodes
+        according to the 'choice' parameter
+        """
+        if self.choice == 'random':
+            return ciw.random_choice(subset)
+        if self.choice == 'jsq':
+            temp_router = JoinShortestQueue(destinations=subset)
+            temp_router.initialise(self.simulation, None)
+            nd = temp_router.next_node(ind)
+            return nd.id_number
+        if self.choice == 'lb':
+            temp_router = LoadBalancing(destinations=subset)
+            temp_router.initialise(self.simulation, None)
+            nd = temp_router.next_node(ind)
+            return nd.id_number
+
+    def update_individual_route(self, ind, next_node_id):
+        """
+        Updates the individual route by removing chosen nodes
+        along the route, according to the 'rule' parameter
+        """
+        if self.rule == 'any':
+            ind.route = ind.route[1:]
+        if self.rule == 'all':
+            ind.route[0].remove(next_node_id)
+            if len(ind.route[0]) == 0:
+                ind.route = ind.route[1:]
+
+    def next_node(self, ind, node_id):
+        """
+        Chooses the next node from the process-based pre-defined route.
+        """
+        if len(ind.route) == 0:
+            node_index = -1
+        else:
+            node_index = self.find_next_node_from_subset(ind.route[0], ind)
+            self.update_individual_route(ind, node_index)
+        return self.simulation.nodes[node_index]
+
+
 
 class NodeRouting:
     """

ciw/tests/test_process_based.py

@@ -3,7 +3,6 @@
 import random
 from collections import Counter
 
-
 def generator_function_1(ind, simulation):
     return [1, 1]
 
@@ -29,6 +28,8 @@ def __init__(self, n):
     def generator_method(self, ind, simulation):
         return [1, 1]
 
+def flexible_generator_1(ind, simulation):
+    return [[2], [3, 4, 5], [6]]
 
 class TestProcessBased(unittest.TestCase):
     def test_network_takes_routing_function(self):
@@ -152,3 +153,103 @@ def test_process_based_takes_methods(self):
         inds = Q.nodes[1].all_individuals
         for ind in inds:
             self.assertEqual(ind.route, [1, 1])
+
+    def test_flexible_process_based(self):
+        ## First test 'any-random':
+        N = ciw.create_network(
+            arrival_distributions=[ciw.dists.Exponential(rate=1), None, None, None, None, None],
+            service_distributions=[ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2)],
+            number_of_servers=[3, 3, 3, 3, 3, 3],
+            routing=ciw.routing.FlexibleProcessBased(
+                route_function=flexible_generator_1,
+                rule='any',
+                choice='random'
+            )
+        )
+        ciw.seed(0)
+        Q = ciw.Simulation(N)
+        Q.simulate_until_max_customers(1000)
+        inds = Q.nodes[-1].all_individuals
+        routes_counter = Counter(
+            [tuple(dr.node for dr in ind.data_records) for ind in inds]
+        )
+        self.assertEqual(
+            routes_counter,
+            Counter({(1, 2, 4, 6): 350, (1, 2, 5, 6): 333, (1, 2, 3, 6): 317}), # all evenly spread
+        )
+
+        ## Now test 'any-jsq' (flooding Node 4 so no customers ever go here):
+        N = ciw.create_network(
+            arrival_distributions=[ciw.dists.Exponential(rate=1), None, None, None, None, None],
+            service_distributions=[ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2), ciw.dists.Deterministic(value=200000), ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2)],
+            number_of_servers=[3, 3, 3, 3, 3, 3],
+            routing=ciw.routing.FlexibleProcessBased(
+                route_function=flexible_generator_1,
+                rule='any',
+                choice='jsq'
+            )
+        )
+        ciw.seed(0)
+        Q = ciw.Simulation(N)
+        Q.simulate_until_max_customers(1000)
+        inds = Q.nodes[-1].all_individuals
+        routes_counter = Counter(
+            [tuple(dr.node for dr in ind.data_records) for ind in inds]
+        )
+        self.assertEqual(
+            routes_counter,
+            Counter({(1, 2, 5, 6): 503, (1, 2, 3, 6): 497}),  # evenly spread between the two unflooded nodes
+        )
+
+        ## Now test 'any-lb' (flooding Node 4 so no customers ever go here):
+        N = ciw.create_network(
+            arrival_distributions=[ciw.dists.Exponential(rate=1), None, None, None, None, None],
+            service_distributions=[ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2), ciw.dists.Deterministic(value=200000), ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2)],
+            number_of_servers=[3, 3, 3, 3, 3, 3],
+            routing=ciw.routing.FlexibleProcessBased(
+                route_function=flexible_generator_1,
+                rule='any',
+                choice='lb'
+            )
+        )
+        ciw.seed(0)
+        Q = ciw.Simulation(N)
+        Q.simulate_until_max_customers(1000)
+        inds = Q.nodes[-1].all_individuals
+        routes_counter = Counter(
+            [tuple(dr.node for dr in ind.data_records) for ind in inds]
+        )
+        self.assertEqual(
+            routes_counter,
+            Counter({(1, 2, 5, 6): 508, (1, 2, 3, 6): 492}),  # evenly spread between the two unflooded nodes
+        )
+
+
+        ## Now test 'all-random':
+        N = ciw.create_network(
+            arrival_distributions=[ciw.dists.Exponential(rate=1), None, None, None, None, None],
+            service_distributions=[ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2), ciw.dists.Exponential(rate=2)],
+            number_of_servers=[3, 3, 3, 3, 3, 3],
+            routing=ciw.routing.FlexibleProcessBased(
+                route_function=flexible_generator_1,
+                rule='all',
+                choice='random'
+            )
+        )
+        ciw.seed(0)
+        Q = ciw.Simulation(N)
+        Q.simulate_until_max_customers(1000)
+        inds = Q.nodes[-1].all_individuals
+        routes_counter = Counter(
+            [tuple(dr.node for dr in ind.data_records) for ind in inds]
+        )
+        self.assertEqual(routes_counter[(1, 2, 3, 4, 5, 6)], 169)
+        self.assertEqual(routes_counter[(1, 2, 3, 5, 4, 6)], 139)
+        self.assertEqual(routes_counter[(1, 2, 4, 3, 5, 6)], 185)
+        self.assertEqual(routes_counter[(1, 2, 4, 5, 3, 6)], 166)
+        self.assertEqual(routes_counter[(1, 2, 5, 3, 4, 6)], 186)
+        self.assertEqual(routes_counter[(1, 2, 5, 4, 3, 6)], 155)
+
+    def test_flexible_process_based_error_raising(self):
+        self.assertRaises(ValueError, ciw.routing.FlexibleProcessBased, flexible_generator_1, 'something', 'random')
+        self.assertRaises(ValueError, ciw.routing.FlexibleProcessBased, flexible_generator_1, 'all', 'something')

docs/Reference/routers.rst

@@ -10,6 +10,7 @@ The following network routers are currently supported:
 - :ref:`network_router`
 - :ref:`trans_mat`
 - :ref:`pb_route`
+- :ref:`pb_flex`
 
 The following node routers are currently supported:
 
@@ -71,6 +72,28 @@ The :ref:`process based<process-based>` router takes in a function that returns
     )
 
 
+.. _pb_flex:
+
+---------------------------------
+The Flexible Process Based Routed
+---------------------------------
+
+The flexible process based router is an extension of the above process based router, where the routing function gives a list of sets (defined by lists). For example::
+
+    ciw.routing.FlexibleProcessBased(
+        routing_function=lambda ind, simulation: [[2, 1], [1], [1, 2, 3]],
+        rule='any',
+        choice='jsq'
+    )
+
+Arguments:
+ - The :code:`rule` argument can take one of two strings: :code:`'any'` or :code:`'all'`. For each set of nodes in the pre-defined route, using :code:`'any'` means that the customer must visit only one of the nodes in the set; while using :code:`'all'` means that the customer should visit all the nodes in that set, but not necessarily in that order.
+ - The :code:`choice` argument can take one of a number of strings. When using the :code:`'any'` rule, it determines how a node is chosen from the set. When using the :code:`'all'` rule, it determines at each instance, the choice of next node out of the set. The current options are:
+    - :code:`'random'`: randomly chooses a node from the set.
+    - :code:`'jsq'`: chooses the node with the smallest queue from the set (like the :ref:`join-shortest-queue<jsq>` router).
+    - :code:`'lb'`: chooses the node with the least number of customers present from the set (like the :ref:`load-balancing<load_balancing>` router).
+
+
 
 
 Node Routing Objects
@@ -125,6 +148,7 @@ The customer goes :ref:`joins the shortest queue<join-shortest-queue>` out of a
 
 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 shortest queue, 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.
 
+
 .. _load_balancing:
 
 --------------