Merge pull request #102 from drvinceknight/refactor-tag-constraint

Make tag an unavailability shortcut

Author: meatballs

docs/background/mathematical_model.rst

@@ -120,45 +120,9 @@ Using this we have the following constraint:
 We see that if :math:`{C_{e}}_{ii'}=0` then at most one of the two events can be
 scheduled across the two slots :math:`j,j'`.
 
-Talks in a given session have something in common
--------------------------------------------------
-
-It might be desirable to schedule collection of time slots in such a way that
-the events in that collection have something in common. Perhaps all talks in a
-morning session in a particular room should be welcoming to delegates of a given
-level of expertise.
-
-To do this we first need to capture each collection of slots into sessions, and
-we define the following set for every slot :math:`j`:
-
-.. math::
-   :label: same_session_set
-
-   {K}_{j} = \{1\leq j' \leq N\,|\,\text{ if }j\text{ and }j'\text{ are in the same session}\}
-
-We also assume that we have a number of collections of events. Note that these
-collections are non disjoint: any event can be in multiple collections. We refer
-to these collections as "tags": an event can for example be tagged as
-"beginner".
-
-Using this we define the following set for every event :math:`i`
-
-.. math::
-   :label: same_tag_event_set
-
-   T_i = \{1\leq i'\leq M\,|\,\text{ if }i\text{ and }j\text{ do not share a tag}\}
-
-This leads us to the following constraint:
-
-.. math::
-   :label: tag_constraint
-
-    X_{ij}  + X_{i'j'} \leq 1 \text{ for all  }j'\in K_j\text{ for all }1\leq j\leq N\text{ for all }i'\in T_i\text{ for all }1\leq i\leq M
-
-
 Expressions :eq:`all_events_scheduled_constraint`,
 :eq:`all_slots_at_most_1_event_constraint`,
-:eq:`slot_constraint`, :eq:`event_constraint` and :eq:`tag_constraint` define a
+:eq:`slot_constraint`, and :eq:`event_constraint` define a
 valid schedule and can be used by themselves.
 
 However, it might be desirable to also optimise a given objective function.
@@ -186,15 +150,15 @@ solving the following problem:
 
 Minimise :eq:`overflow_objective_function` subject to :eq:`all_events_scheduled_constraint`,
 :eq:`all_slots_at_most_1_event_constraint`,
-:eq:`slot_constraint`, :eq:`event_constraint` and :eq:`tag_constraint`.
+:eq:`slot_constraint` and :eq:`event_constraint`.
 
 Minimise change from a previous schedule
 ----------------------------------------
 
 Once a schedule has been obtained and publicised to all delegates, a new
 constraint might arise (modifying :eq:`all_events_scheduled_constraint`,
 :eq:`all_slots_at_most_1_event_constraint`,
-:eq:`slot_constraint`, :eq:`event_constraint` and :eq:`tag_constraint`). At this
+:eq:`slot_constraint` and :eq:`event_constraint`. At this
 point the original optimisation problem can be solved again leading to a
 potentially completely different schedule. An alternative to this is to use
 distance from an original schedule :math:`X_o` as the objective function. Norms
@@ -225,4 +189,4 @@ problem:
 Minimise :eq:`number_of_changes_objective_function` subject to
 :eq:`all_events_scheduled_constraint`,
 :eq:`all_slots_at_most_1_event_constraint`, :eq:`slot_constraint`,
-:eq:`event_constraint` and :eq:`tag_constraint`.
+and :eq:`event_constraint`.

docs/tutorial/index.rst

@@ -65,7 +65,7 @@ duration/location of the slots we know some of them are unavailable for a given
 
     >>> events = [Event(name='Talk 1', duration=30, tags=['beginner'], unavailability=outside_slots[:], demand=50),
     ...           Event(name='Talk 2', duration=30, tags=['beginner'], unavailability=outside_slots[:], demand=130),
-    ...           Event(name='Talk 3', duration=30, tags=['beginner'], unavailability=outside_slots[:], demand=500),
+    ...           Event(name='Talk 3', duration=30, tags=['beginner'], unavailability=outside_slots[:], demand=3000),
     ...           Event(name='Talk 4', duration=30, tags=['beginner'], unavailability=outside_slots[:], demand=30),
     ...           Event(name='Talk 5', duration=30, tags=['intermediate'], unavailability=outside_slots[:], demand=60),
     ...           Event(name='Talk 6', duration=30, tags=['intermediate'], unavailability=outside_slots[:], demand=30),
@@ -107,20 +107,20 @@ event::
     >>> schedule.sort(key=lambda item: item.slot.starts_at)
     >>> for item in schedule:
     ...     print(f"{item.event.name} at {item.slot.starts_at} in {item.slot.venue}")
-    Talk 3 at 15-Sep-2016 09:30 in Small
+    Talk 5 at 15-Sep-2016 09:30 in Small
     Talk 11 at 15-Sep-2016 09:30 in Big
     Talk 4 at 15-Sep-2016 10:00 in Small
-    Talk 8 at 15-Sep-2016 10:00 in Big
+    Talk 10 at 15-Sep-2016 10:00 in Big
     Talk 1 at 15-Sep-2016 12:30 in Small
-    Talk 5 at 15-Sep-2016 12:30 in Big
-    Talk 2 at 15-Sep-2016 13:00 in Small
-    Talk 6 at 15-Sep-2016 13:00 in Big
-    Talk 9 at 16-Sep-2016 09:30 in Big
+    Talk 6 at 15-Sep-2016 12:30 in Big
+    Talk 3 at 15-Sep-2016 13:00 in Small
+    Talk 8 at 15-Sep-2016 13:00 in Big
+    Talk 2 at 16-Sep-2016 09:30 in Big
     Workshop 2 at 16-Sep-2016 09:30 in Small
-    Talk 10 at 16-Sep-2016 10:00 in Big
-    Talk 7 at 16-Sep-2016 12:30 in Big
+    Talk 9 at 16-Sep-2016 10:00 in Big
+    Talk 12 at 16-Sep-2016 12:30 in Big
     Boardgames at 16-Sep-2016 12:30 in Outside
-    Talk 12 at 16-Sep-2016 13:00 in Big
+    Talk 7 at 16-Sep-2016 13:00 in Big
     Workshop 1 at 16-Sep-2016 13:00 in Small
     City tour at 16-Sep-2016 13:00 in Outside
 
@@ -129,10 +129,8 @@ the unavailability attribute for the events). Also we have that :code:`Talk 1`
 doesn't clash with :code:`Workshop 1`.
 Similarly, the :code:`Boardgame` does not clash with :code:`Workshop 2`.
 
-You will also note that in any given session, talks share at least one tag. This
-is another constraint of the model; if you find that your schedule has no
-solutions you can adjust it by re-categorising your talks (or giving them all a
-single category).
+You will also note that no two events with the same tags are on at the same time.
+Tags allow for a quick way to batch define unavailability.
 
 Avoiding room overcrowding
 --------------------------
@@ -150,18 +148,18 @@ our scheduler to minimise the difference between room capacity and demand::
     >>> schedule.sort(key=lambda item: item.slot.starts_at)
     >>> for item in schedule:
     ...     print(f"{item.event.name} at {item.slot.starts_at} in {item.slot.venue}")
-    Talk 4 at 15-Sep-2016 09:30 in Big
-    Talk 7 at 15-Sep-2016 09:30 in Small
-    Talk 1 at 15-Sep-2016 10:00 in Big
+    Talk 1 at 15-Sep-2016 09:30 in Big
+    Talk 12 at 15-Sep-2016 09:30 in Small
+    Talk 2 at 15-Sep-2016 10:00 in Big
     Talk 6 at 15-Sep-2016 10:00 in Small
-    Talk 8 at 15-Sep-2016 12:30 in Big
-    Talk 12 at 15-Sep-2016 12:30 in Small
-    Talk 5 at 15-Sep-2016 13:00 in Big
-    Talk 10 at 15-Sep-2016 13:00 in Small
-    Talk 3 at 16-Sep-2016 09:30 in Big
+    Talk 4 at 15-Sep-2016 12:30 in Small
+    Talk 11 at 15-Sep-2016 12:30 in Big
+    Talk 5 at 15-Sep-2016 13:00 in Small
+    Talk 10 at 15-Sep-2016 13:00 in Big
+    Talk 7 at 16-Sep-2016 09:30 in Big
     Workshop 2 at 16-Sep-2016 09:30 in Small
-    Talk 2 at 16-Sep-2016 10:00 in Big
-    Talk 11 at 16-Sep-2016 12:30 in Big
+    Talk 8 at 16-Sep-2016 10:00 in Big
+    Talk 3 at 16-Sep-2016 12:30 in Big
     Boardgames at 16-Sep-2016 12:30 in Outside
     Talk 9 at 16-Sep-2016 13:00 in Big
     Workshop 1 at 16-Sep-2016 13:00 in Small
@@ -181,7 +179,7 @@ informs us of a particular new constraints. For example, the speaker for
 
 We can enter this new constraint::
 
-    >>> events[10].add_unavailability(*slots[9:])
+    >>> events[10].add_unavailability(*slots[:9])
 
 We can now solve the problem one more time from scratch just as before::
 
@@ -190,20 +188,20 @@ We can now solve the problem one more time from scratch just as before::
     >>> alt_schedule.sort(key=lambda item: item.slot.starts_at)
     >>> for item in alt_schedule:
     ...     print(f"{item.event.name} at {item.slot.starts_at} in {item.slot.venue}")
-    Talk 1 at 15-Sep-2016 09:30 in Big
-    Talk 8 at 15-Sep-2016 09:30 in Small
-    Talk 4 at 15-Sep-2016 10:00 in Big
-    Talk 5 at 15-Sep-2016 10:00 in Small
-    Talk 3 at 15-Sep-2016 12:30 in Small
-    Talk 9 at 15-Sep-2016 12:30 in Big
-    Talk 2 at 15-Sep-2016 13:00 in Small
-    Talk 12 at 15-Sep-2016 13:00 in Big
-    Talk 11 at 16-Sep-2016 09:30 in Big
+    Talk 1 at 15-Sep-2016 09:30 in Small
+    Talk 9 at 15-Sep-2016 09:30 in Big
+    Talk 5 at 15-Sep-2016 10:00 in Big
+    Talk 10 at 15-Sep-2016 10:00 in Small
+    Talk 4 at 15-Sep-2016 12:30 in Big
+    Talk 7 at 15-Sep-2016 12:30 in Small
+    Talk 6 at 15-Sep-2016 13:00 in Big
+    Talk 12 at 15-Sep-2016 13:00 in Small
+    Talk 2 at 16-Sep-2016 09:30 in Big
     Workshop 2 at 16-Sep-2016 09:30 in Small
-    Talk 10 at 16-Sep-2016 10:00 in Big
-    Talk 6 at 16-Sep-2016 12:30 in Big
+    Talk 8 at 16-Sep-2016 10:00 in Big
+    Talk 3 at 16-Sep-2016 12:30 in Big
     Boardgames at 16-Sep-2016 12:30 in Outside
-    Talk 7 at 16-Sep-2016 13:00 in Big
+    Talk 11 at 16-Sep-2016 13:00 in Big
     Workshop 1 at 16-Sep-2016 13:00 in Small
     City tour at 16-Sep-2016 13:00 in Outside
 
@@ -219,20 +217,20 @@ old schedule::
     >>> similar_schedule.sort(key=lambda item: item.slot.starts_at)
     >>> for item in similar_schedule:
     ...     print(f"{item.event.name} at {item.slot.starts_at} in {item.slot.venue}")
-    Talk 4 at 15-Sep-2016 09:30 in Big
-    Talk 7 at 15-Sep-2016 09:30 in Small
-    Talk 1 at 15-Sep-2016 10:00 in Big
+    Talk 1 at 15-Sep-2016 09:30 in Big
+    Talk 12 at 15-Sep-2016 09:30 in Small
+    Talk 2 at 15-Sep-2016 10:00 in Big
     Talk 6 at 15-Sep-2016 10:00 in Small
-    Talk 8 at 15-Sep-2016 12:30 in Big
-    Talk 11 at 15-Sep-2016 12:30 in Small
-    Talk 5 at 15-Sep-2016 13:00 in Big
-    Talk 10 at 15-Sep-2016 13:00 in Small
-    Talk 3 at 16-Sep-2016 09:30 in Big
+    Talk 4 at 15-Sep-2016 12:30 in Small
+    Talk 9 at 15-Sep-2016 12:30 in Big
+    Talk 5 at 15-Sep-2016 13:00 in Small
+    Talk 10 at 15-Sep-2016 13:00 in Big
+    Talk 7 at 16-Sep-2016 09:30 in Big
     Workshop 2 at 16-Sep-2016 09:30 in Small
-    Talk 2 at 16-Sep-2016 10:00 in Big
-    Talk 12 at 16-Sep-2016 12:30 in Big
+    Talk 8 at 16-Sep-2016 10:00 in Big
+    Talk 3 at 16-Sep-2016 12:30 in Big
     Boardgames at 16-Sep-2016 12:30 in Outside
-    Talk 9 at 16-Sep-2016 13:00 in Big
+    Talk 11 at 16-Sep-2016 13:00 in Big
     Workshop 1 at 16-Sep-2016 13:00 in Small
     City tour at 16-Sep-2016 13:00 in Outside
 
@@ -248,37 +246,34 @@ with the original. Firstly, we can see which events moved to different slots::
     >>> event_diff = scheduler.event_schedule_difference(schedule, alt_schedule)
     >>> for item in event_diff:
     ...     print(f"{item.event.name} has moved from {item.old_slot.venue} at {item.old_slot.starts_at} to {item.new_slot.venue} at {item.new_slot.starts_at}")
-    Talk 1 has moved from Big at 15-Sep-2016 10:00 to Big at 15-Sep-2016 09:30
-    Talk 10 has moved from Small at 15-Sep-2016 13:00 to Big at 16-Sep-2016 10:00
-    Talk 11 has moved from Big at 16-Sep-2016 12:30 to Big at 16-Sep-2016 09:30
-    Talk 12 has moved from Small at 15-Sep-2016 12:30 to Big at 15-Sep-2016 13:00
-    Talk 2 has moved from Big at 16-Sep-2016 10:00 to Small at 15-Sep-2016 13:00
-    Talk 3 has moved from Big at 16-Sep-2016 09:30 to Small at 15-Sep-2016 12:30
-    Talk 4 has moved from Big at 15-Sep-2016 09:30 to Big at 15-Sep-2016 10:00
-    Talk 5 has moved from Big at 15-Sep-2016 13:00 to Small at 15-Sep-2016 10:00
-    Talk 6 has moved from Small at 15-Sep-2016 10:00 to Big at 16-Sep-2016 12:30
-    Talk 7 has moved from Small at 15-Sep-2016 09:30 to Big at 16-Sep-2016 13:00
-    Talk 8 has moved from Big at 15-Sep-2016 12:30 to Small at 15-Sep-2016 09:30
-    Talk 9 has moved from Big at 16-Sep-2016 13:00 to Big at 15-Sep-2016 12:30
+    Talk 1 has moved from Big at 15-Sep-2016 09:30 to Small at 15-Sep-2016 09:30
+    Talk 10 has moved from Big at 15-Sep-2016 13:00 to Small at 15-Sep-2016 10:00
+    Talk 11 has moved from Big at 15-Sep-2016 12:30 to Big at 16-Sep-2016 13:00
+    Talk 12 has moved from Small at 15-Sep-2016 09:30 to Small at 15-Sep-2016 13:00
+    Talk 2 has moved from Big at 15-Sep-2016 10:00 to Big at 16-Sep-2016 09:30
+    Talk 4 has moved from Small at 15-Sep-2016 12:30 to Big at 15-Sep-2016 12:30
+    Talk 5 has moved from Small at 15-Sep-2016 13:00 to Big at 15-Sep-2016 10:00
+    Talk 6 has moved from Small at 15-Sep-2016 10:00 to Big at 15-Sep-2016 13:00
+    Talk 7 has moved from Big at 16-Sep-2016 09:30 to Small at 15-Sep-2016 12:30
+    Talk 9 has moved from Big at 16-Sep-2016 13:00 to Big at 15-Sep-2016 09:30
 
 
 We can also look at slots to see which now have a different event scheduled::
 
     >>> slot_diff = scheduler.slot_schedule_difference(schedule, alt_schedule)
     >>> for item in slot_diff:
     ...     print(f"{item.slot.venue} at {item.slot.starts_at} will now host {item.new_event.name} rather than {item.old_event.name}" )
-    Big at 15-Sep-2016 09:30 will now host Talk 1 rather than Talk 4
-    Big at 15-Sep-2016 10:00 will now host Talk 4 rather than Talk 1
-    Big at 15-Sep-2016 12:30 will now host Talk 9 rather than Talk 8
-    Big at 15-Sep-2016 13:00 will now host Talk 12 rather than Talk 5
-    Big at 16-Sep-2016 09:30 will now host Talk 11 rather than Talk 3
-    Big at 16-Sep-2016 10:00 will now host Talk 10 rather than Talk 2
-    Big at 16-Sep-2016 12:30 will now host Talk 6 rather than Talk 11
-    Big at 16-Sep-2016 13:00 will now host Talk 7 rather than Talk 9
-    Small at 15-Sep-2016 09:30 will now host Talk 8 rather than Talk 7
-    Small at 15-Sep-2016 10:00 will now host Talk 5 rather than Talk 6
-    Small at 15-Sep-2016 12:30 will now host Talk 3 rather than Talk 12
-    Small at 15-Sep-2016 13:00 will now host Talk 2 rather than Talk 10
+    Big at 15-Sep-2016 09:30 will now host Talk 9 rather than Talk 1
+    Big at 15-Sep-2016 10:00 will now host Talk 5 rather than Talk 2
+    Big at 15-Sep-2016 12:30 will now host Talk 4 rather than Talk 11
+    Big at 15-Sep-2016 13:00 will now host Talk 6 rather than Talk 10
+    Big at 16-Sep-2016 09:30 will now host Talk 2 rather than Talk 7
+    Big at 16-Sep-2016 13:00 will now host Talk 11 rather than Talk 9
+    Small at 15-Sep-2016 09:30 will now host Talk 1 rather than Talk 12
+    Small at 15-Sep-2016 10:00 will now host Talk 10 rather than Talk 6
+    Small at 15-Sep-2016 12:30 will now host Talk 7 rather than Talk 4
+    Small at 15-Sep-2016 13:00 will now host Talk 12 rather than Talk 5
+
 
 
 We can use this facility to show how using :code:`number_of_changes` as our objective function
@@ -287,8 +282,9 @@ resulted in far fewer changes::
     >>> event_diff = scheduler.event_schedule_difference(schedule, similar_schedule)
     >>> for item in event_diff:
     ...     print(f"{item.event.name} has moved from {item.old_slot.venue} at {item.old_slot.starts_at} to {item.new_slot.venue} at {item.new_slot.starts_at}")
-    Talk 11 has moved from Big at 16-Sep-2016 12:30 to Small at 15-Sep-2016 12:30
-    Talk 12 has moved from Small at 15-Sep-2016 12:30 to Big at 16-Sep-2016 12:30
+    Talk 11 has moved from Big at 15-Sep-2016 12:30 to Big at 16-Sep-2016 13:00
+    Talk 9 has moved from Big at 16-Sep-2016 13:00 to Big at 15-Sep-2016 12:30
+
 
 
 Scheduling chairs

src/conference_scheduler/lp_problem/constraints.py

@@ -29,39 +29,6 @@ def _max_one_event_per_slot(events, slots, X, summation_type=None):
         )
 
 
-def _events_in_session_share_a_tag(events, slots, X, summation_type=None):
-    """
-    Constraint that ensures that if an event has a tag and
-    is in a given session then it must
-    share at least one tag with all other event in that session.
-    """
-
-    session_array, tag_array = lpu.session_array(slots), lpu.tag_array(events)
-    summation = lpu.summation_functions[summation_type]
-
-    label = 'Dissimilar events schedule in same session'
-    event_indices = range(len(tag_array))
-    session_indices = range(len(session_array))
-    for session in session_indices:
-        slots = lpu._slots_in_session(session, session_array)
-        for slot, event in it.product(slots, event_indices):
-            if len(events[event].tags) > 0:
-                other_events = lpu._events_with_diff_tag(event, tag_array)
-                for other_slot, other_event in it.product(slots, other_events):
-                    if other_slot != slot and other_event != event:
-                        # If they have different tags they cannot be scheduled
-                        # together
-                        yield Constraint(
-                            f'{label} - event: {event}, slot: {slot}',
-                            summation(
-                                (
-                                    X[(event, slot)],
-                                    X[(other_event, other_slot)]
-                                )
-                            ) <= 1
-                        )
-
-
 def _events_available_in_scheduled_slot(events, slots, X, **kwargs):
     """
     Constraint that ensures that an event is scheduled in slots for which it is
@@ -85,7 +52,8 @@ def _events_available_during_other_events(
 ):
     """
     Constraint that ensures that an event is not scheduled at the same time as
-    another event for which it is unavailable.
+    another event for which it is unavailable. Unavailability of events is
+    either because it is explicitly defined or because they share a tag.
     """
     summation = lpu.summation_functions[summation_type]
     event_availability_array = lpu.event_availability_array(events)
@@ -114,7 +82,6 @@ def all_constraints(events, slots, X, summation_type=None):
     generators = (
         _schedule_all_events,
         _max_one_event_per_slot,
-        _events_in_session_share_a_tag,
         _events_available_in_scheduled_slot,
         _events_available_during_other_events,
     )

src/conference_scheduler/lp_problem/utils.py

@@ -91,9 +91,12 @@ def event_availability_array(events):
     array = np.ones((len(events), len(events)))
     for row, event in enumerate(events):
         for col, other_event in enumerate(events):
-            if other_event in event.unavailability:
-                array[row, col] = 0
-                array[col, row] = 0
+            if row != col:
+                tags = set(event.tags)
+                events_share_tag = len(tags.intersection(other_event.tags)) > 0
+                if (other_event in event.unavailability) or events_share_tag:
+                    array[row, col] = 0
+                    array[col, row] = 0
     return array