Merge fork for interoperability of KoMa solver

The KoMa developed a tool to approximate an optimal conference schedule based on constraints and participant preferences. The aim of this MR is to enable interoperability with that solver. To do this, two functionalities are added:

• A workflow to export data from this tool (rooms, AKs, timeslots, ...) in a JSON format that can be fed to the solver
• A workflow to import the schedule of the solver back into this

Note that the solver also needs preferences of all participants. As this tool does not collect such data (for now at least), one needs to employ a third tool, e.g. this very basic one.

Export data to the solver

The key functionality is the AKJSONExportView which generates a JSON string that can be imported into the solver.

Notably, the KoMa solver models timeslots differently to this tool. Where this tool basically allows for arbitrary time slot design, the KoMa solver has a more constricted notion: The timeslots are modeled as blocks (i.e. simple lists) of consecutive timeslots of a fixed length. The AKs simply store an integer duration, i.e. the number of consecutive timeslots covered by the AK.

To convert the data of this tool into the solver's model, the following strategy is implemented (see Event::default_time_slots, Event::merge_blocks):

• all DefaultSlot instances are discretized into timeslots of a uniform length (beginning at the start and dropping partial timeslots at the end) → each DefaultSlot forms a "block"
• Consecutive blocks are merged. Overlapping timeslots are identified with each other, but partial overlap errors out

The unit tests are expanded quite a bit to test the correctness of the export.

Import a schedule from the solver

This is realized in the form JSONImportForm and the corresponding view AKJSONImportView. The JSON string is simply read from the form and passed to Event::schedule_from_json.

Minor changes

• Bump python version to 3.10
• Availability::{merge_with,intersect_with}: If both objects are from the same Event, set the event also for the returned Availability object
• Add utility class-method Availibility::is_event_covered to check if Event is covered by a list of Availability objects
  • (Possible bug in Availability::with_event_length: To my understanding the returned availability does in fact not have the exact duration of `event
• ak_requirements_changed_handler: Skip slots with no set room
• Add beautifulsoup4 to test requirements

Changes to model objects (AKModel/models.py)

Event

• Event::_generate_slots_from_block: Given a start and time as well as a slot duration, discretizes it into blocks of consecutive discrete time slots.
  • Slots are dropped if no room is available for the slot.
  • If end - start is not a multiple of duration, the last slot is dropped as well.
• Event::uniform_time_slots to uniformly discretize the full event into blocks of time slots:
  • For the block creation, see Event::_generate_slots_from_block
  • Adds constraints to allow all AKCategories in each timeslot
• Event::default_time_slots to derive blocks by uniformly discretizing DefaultSlots
  • Splits each DefaultSlotof the event into one block.
  • Adds constraints such that only AKs from the DefaultSlot's primary categories are allowed to be scheduled in the block
• Event::merge_blocks: Merge blocks in iterable
  • Flatten blocks into list of all timeslots
  • If two slots overlap:
    • If start and end match: merge slots
    • If overlap only partial: error out
  • group consecutive slots into block
• Event::discretize_timeslots: To select the discretization scheme
• Event::schedule_from_json: Load scheduling from json file, i.e. assign each slot a room, start time and duration
• Add field export_slot to Event to store the discretization granularity for the JSON export

AKCategory

• AKOwner::create_category_constraints: static method to create constraint strings for all AKCategories in iterable

Room

• Room::as_json: Export JSON representation for the room object

AKSlot

• AKSlot::as_json: Export JSON representation for the AKobject of this slot

Open ToDos

• Check data consistency at import
• Add tests for JSON import
• Close discussion on "proxy rooms"

AKModel/models.py

@@ -2,7 +2,7 @@ import itertools
 import json
 from dataclasses import dataclass
 from datetime import datetime, timedelta
-from typing import Iterable
+from typing import Iterable, Generator
 
 from django.db import models
 from django.apps import apps
@@ -17,10 +17,15 @@ from timezone_field import TimeZoneField
 
 @dataclass
 class OptimizerTimeslot:
-    """Class describing a timeslot. Used to interface with an optimizer."""
+    """Class describing a discrete timeslot. Used to interface with an optimizer."""
 
+    """The availability object corresponding to this timeslot."""
     avail: "Availability"
+
+    """The unique index of this optimizer timeslot."""
     idx: int
+
+    """The set of time constraints fulfilled by this object."""
     constraints: set[str]
 
     def merge(self, other: "OptimizerTimeslot") -> "OptimizerTimeslot":
@@ -33,7 +38,6 @@ class OptimizerTimeslot:
         """
         avail = self.avail.merge_with(other.avail)
         constraints = self.constraints.union(other.constraints)
-        # we simply use the index of result[-1]
         return OptimizerTimeslot(
             avail=avail, idx=self.idx, constraints=constraints
         )
@@ -200,10 +204,10 @@ class Event(models.Model):
         slot_duration: timedelta,
         slot_index: int = 0,
         constraints: set[str] | None = None,
-    ) -> Iterable[TimeslotBlock]:
+    ) -> Generator[TimeslotBlock, None, int]:
         """Discretize a time range into timeslots.
 
-        Uses a uniform discretization into blocks of length `slot_duration`,
+        Uses a uniform discretization into discrete slots of length `slot_duration`,
         starting at `start`. No incomplete timeslots are generated, i.e.
         if (`end` - `start`) is not a whole number multiple of `slot_duration`
         then the last incomplete timeslot is dropped.
@@ -214,7 +218,11 @@ class Event(models.Model):
         :param slot_index: index of the first timeslot. Defaults to 0.
 
         :yield: Block of optimizer timeslots as the discretization result.
-        :ytype: list of TimeslotBlock
+        :ytype: list of OptimizerTimeslot
+
+        :return: The first slot index after the yielded blocks, i.e.
+            `slot_index` + total # generated timeslots
+        :rtype: int
         """
         # local import to prevent cyclic import
         # pylint: disable=import-outside-toplevel
@@ -264,12 +272,15 @@ class Event(models.Model):
         return slot_index
 
     def uniform_time_slots(self, *, slots_in_an_hour: float = 1.0) -> Iterable[TimeslotBlock]:
-        """Uniformly discretize the entire event into a single block of timeslots.
+        """Uniformly discretize the entire event into blocks of timeslots.
+
+        Discretizes entire event uniformly. May not necessarily result in a single block
+        as slots with no room availability are dropped.
 
         :param slots_in_an_hour: The percentage of an hour covered by a single slot.
             Determines the discretization granularity.
         :yield: Block of optimizer timeslots as the discretization result.
-        :ytype: a single list of TimeslotBlock
+        :ytype: list of OptimizerTimeslot
         """
         all_category_constraints = AKCategory.create_category_constraints(
             AKCategory.objects.filter(event=self).all()