Merge pull request #143 from CiwPython/time-dependent-batches

Time dependent batches

Author: geraintpalmer

AUTHORS.rst

@@ -10,3 +10,4 @@ Ciw has been developed by the following contributors:
 + `Alex Carney <https://github.com/alcarney/>`_
 + `Adam Johnson <https://github.com/adamchainz/>`_
 + `Nikoleta Glynatsi <https://github.com/Nikoleta-v3/>`_
++ `caipirginka <https://github.com/caipirginka>`_

ciw/arrival_node.py

@@ -89,7 +89,8 @@ def have_event(self):
             self.next_event_date))
         self.batch_size_dict[self.next_node][
             self.next_class] = self.batch_size(
-            self.next_node, self.next_class)
+            self.next_node, self.next_class,
+            self.next_event_date)
         self.find_next_event_date()
 
     def increment_time(self, original, increment):
@@ -116,7 +117,7 @@ def initialise_batch_size_dict(self):
         for nd in self.batch_size_dict:
             for clss in self.batch_size_dict[nd]:
                 self.batch_size_dict[nd][
-                clss] = self.batch_size(nd, clss)
+                clss] = self.batch_size(nd, clss, 0.0)
 
     def inter_arrival(self, nd, clss, current_time):
         """
@@ -127,10 +128,15 @@ def inter_arrival(self, nd, clss, current_time):
             return self.simulation.inter_arrival_times[nd][clss](current_time)
         return self.simulation.inter_arrival_times[nd][clss]()
 
-    def batch_size(self, nd, clss):
+    def batch_size(self, nd, clss, current_time):
         """
         Samples the batch size for next class and node.
         """
+        if self.simulation.network.customer_classes[
+            clss].batching_distributions[nd-1][0] == "TimeDependent":
+            return self.simulation.batch_sizes[nd][clss](
+                self.event_dates_dict[nd][clss]
+                )
         return self.simulation.batch_sizes[nd][clss]()
 
     def record_baulk(self, next_node):

ciw/import_params.py

@@ -221,7 +221,7 @@ def validify_dictionary(params):
     batch_dists = [params['Batching_distributions']['Class ' + str(i)][j][0] for i in range(params['Number_of_classes']) for j in range(params['Number_of_nodes'])]
     if not set(batch_dists).issubset(set([
         'Deterministic', 'Empirical', 'Custom',
-        'Sequential'])):
+        'Sequential','TimeDependent'])):
         raise ValueError('Ensure that valid Batching Distributions are used.')
     neg_numservers = any([(isinstance(obs, int) and obs < 0) for obs in params['Number_of_servers']])
     valid_capacities = all([((isinstance(obs, int) and obs >= 0) or obs=='Inf') for obs in params['Queue_capacities']])

ciw/simulation.py

@@ -68,10 +68,12 @@ def check_userdef_dist(self, func):
             raise ValueError("UserDefined func must return positive float.")
         return sample
 
-    def check_timedependent_dist(self, func, current_time):
+    def check_timedependent_dist(self, func, kind, current_time):
         sample = func(current_time)
-        if not isinstance(sample, float) or sample < 0:
+        if kind in ['Arr', 'Ser'] and not isinstance(sample, float) or sample < 0:
             raise ValueError("TimeDependent func must return positive float.")
+        if kind in ['Bch'] and not isinstance(sample, int) or sample < 0:
+            raise ValueError("TimeDependent batching func must return positive integer.")
         return sample
 
 
@@ -142,7 +144,7 @@ def find_distributions(self, n, c, kind):
                 return lambda : random_choice(empirical_dist)
             return lambda : random_choice(self.source(c, n, kind)[1])
         if self.source(c, n, kind)[0] == 'TimeDependent':
-            return lambda t : self.check_timedependent_dist(self.source(c, n, kind)[1], t)
+            return lambda t : self.check_timedependent_dist(self.source(c, n, kind)[1], kind, t)
         if self.source(c, n, kind)[0] == 'Sequential':
             return lambda : next(self.generators[kind][n][c])
 

ciw/tests/test_arrival_node.py

@@ -1,6 +1,11 @@
 import unittest
 import ciw
 
+def time_dependent_batches(current_time):
+    if current_time < 11.0:
+        return 5
+    return 1
+
 class TestArrivalNode(unittest.TestCase):
 
     def test_init_method(self):
@@ -341,3 +346,31 @@ def test_batching_multi_classes(self):
         self.assertEqual(arrivals, [20, 20, 20, 23, 23, 25])
         self.assertEqual(nodes, [1, 1, 1, 1, 1, 1])
         self.assertEqual(classes, [0, 0, 0, 1, 1, 2])
+
+    def test_batching_time_dependent(self):
+        N = ciw.create_network(
+            Arrival_distributions=[['Sequential', [5.0, 5.0, 2.0, 1.0, 1000.0]]],
+            Service_distributions=[['Deterministic', 2]],
+            Number_of_servers=[1],
+            Batching_distributions=[['TimeDependent', time_dependent_batches]]
+        )
+        Q = ciw.Simulation(N)
+        Q.simulate_until_max_time(30.0)
+        recs = Q.get_all_records()
+
+        self.assertEqual(len(Q.nodes[-1].all_individuals), 12)
+        self.assertEqual(len(Q.nodes[1].all_individuals), 0)
+
+        recs = Q.get_all_records()
+        self.assertEqual([r.arrival_date for r in recs], [5.0, 5.0, 5.0, 5.0, 5.0, 10.0, 10.0, 10.0, 10.0, 10.0, 12.0, 13.0])
+        self.assertEqual([r.exit_date for r in recs], [7.0, 9.0, 11.0, 13.0, 15.0, 17.0, 19.0, 21.0, 23.0, 25.0, 27.0, 29.0])
+
+    def test_error_batching_time_dependent(self):
+        params = {
+            'Arrival_distributions': [['Sequential', [5.0, 5.0, 2.0, 1.0, 1000.0]]],
+            'Service_distributions': [['Deterministic', 2]],
+            'Number_of_servers': [1],
+            'Batching_distributions': [['TimeDependent', lambda t: 1.5]]
+        }
+        N = ciw.create_network(**params)
+        self.assertRaises(ValueError, ciw.Simulation, N)

docs/Guides/batching.rst

@@ -46,6 +46,44 @@ Note:
      + :code:`Empirical`
      + :code:`Custom`
      + :code:`Sequential`
+     + :code:`TimeDependent`
   + If the keyword :code:`Batching_distributions` is omitted, then no batching is assumed. That is only one customer arrives at a time. Equivalent to :code:`['Deterministic', 1]`.
   + If some nodes/customer classes require no batching, but others do, please use :code:`['Deterministic', 1]`.
-  + Batch arrivals may lead to :ref:`simultaneous events <simultaneous_events>`, please take care.
+  + Batch arrivals may lead to :ref:`simultaneous events <simultaneous_events>`, please take care.
+
+
+---------------------------------
+How to Set Time Dependent Batches
+---------------------------------
+
+Ciw allows batching distributions to be time dependent.
+That is the batch size, the number of customers arriving simultaneously, is sampled from a distribution that varies with time.
+
+Let's show an example, we wish to have batch sizes of 2 for the first 10 time units, but batch sizes of 1 thereafter.
+Define a time dependent batching distribution::
+
+    >>> def time_dependent_batches(t):
+    ...     if t < 10.0:
+    ...         return 2
+    ...     return 1
+
+Now use this when defining a network:
+
+    >>> import ciw
+    >>> N = ciw.create_network(
+    ...     Arrival_distributions=[['Deterministic', 3.0]],
+    ...     Service_distributions=[['Deterministic', 0.5]],
+    ...     Batching_distributions=[['TimeDependent', time_dependent_batches]],
+    ...     Number_of_servers=[1]
+    ... )
+
+We'll simulate this for 16 time units.
+Now at times 3, 6, and 9 we would expect 2 customers arriving (a total of 6).
+And at times 12 and 15 we would expect 1 customer arriving (a total of 2).
+So 8 customers in total should finish service::
+
+    >>> Q = ciw.Simulation(N)
+    >>> Q.simulate_until_max_time(16.0)
+    >>> len(Q.nodes[-1].all_individuals)
+    8
+

docs/Guides/time_dependent.rst

@@ -4,7 +4,7 @@
 How to Define Time Dependent Distributions
 ==========================================
 
-In Ciw we can get a time dependent distribution, that is a service time or inter-arrival time distribution that changes as the simulation time progresses.
+In Ciw we can get a time dependent distribution, that is a service time, inter-arrival time, or batching distribution that changes as the simulation time progresses.
 In order to do this a time dependent function, that returns a sampled time, must be defined.
 This must take in a time variable `t`.