From 1c253e99671fa94571cf7f73d53422af5e9e5dda Mon Sep 17 00:00:00 2001
From: Alec Li <smartspot2@gmail.com>
Date: Sun, 11 Aug 2024 21:52:14 -0700
Subject: [PATCH] Add matcher slot description, reformat match solver

---
 .../EnrollmentAutomationTypes.tsx             |  1 +
 .../MentorSectionPreferences.tsx              | 13 ++++-
 .../coordinator/CoordinatorMatcherForm.tsx    |  5 +-
 .../coordinator/CreateStage.tsx               | 49 +++++++++++++++++--
 .../frontend/src/css/enrollment_matcher.scss  | 17 ++++++-
 .../frontend/src/utils/queries/matcher.tsx    |  1 +
 .../0033_matcherslot_description.py           | 17 +++++++
 csm_web/scheduler/models.py                   | 13 ++---
 csm_web/scheduler/serializers.py              |  2 +-
 csm_web/scheduler/utils/match_solver.py       | 44 +++++++++++------
 csm_web/scheduler/views/matcher.py            | 14 +++++-
 11 files changed, 142 insertions(+), 34 deletions(-)
 create mode 100644 csm_web/scheduler/migrations/0033_matcherslot_description.py

diff --git a/csm_web/frontend/src/components/enrollment_automation/EnrollmentAutomationTypes.tsx b/csm_web/frontend/src/components/enrollment_automation/EnrollmentAutomationTypes.tsx
index 13d8b971..0e945e6f 100644
--- a/csm_web/frontend/src/components/enrollment_automation/EnrollmentAutomationTypes.tsx
+++ b/csm_web/frontend/src/components/enrollment_automation/EnrollmentAutomationTypes.tsx
@@ -9,6 +9,7 @@ export interface Time {
 export interface Slot {
   id?: number;
   times: Time[];
+  description?: string;
   [key: string]: any;
 }
 
diff --git a/csm_web/frontend/src/components/enrollment_automation/MentorSectionPreferences.tsx b/csm_web/frontend/src/components/enrollment_automation/MentorSectionPreferences.tsx
index b2451ea9..f48274ae 100644
--- a/csm_web/frontend/src/components/enrollment_automation/MentorSectionPreferences.tsx
+++ b/csm_web/frontend/src/components/enrollment_automation/MentorSectionPreferences.tsx
@@ -67,7 +67,8 @@ export function MentorSectionPreferences({
         id: slot.id,
         // replace single quotes for JSON
         times: times,
-        preference: 0
+        preference: 0,
+        description: slot.description
       };
       newSlots.push(parsed_slot);
     }
@@ -169,7 +170,7 @@ export function MentorSectionPreferences({
     const event = selectedEvents[0];
     sidebarContents = (
       <div className="matcher-sidebar-selected">
-        <div className="mathcer-sidebar-selected-top">
+        <div className="matcher-sidebar-selected-top">
           {selectedEvents.length === 1 ? (
             // exactly one selected event
             <React.Fragment>
@@ -188,6 +189,14 @@ export function MentorSectionPreferences({
             // multiple selected events
             <div className="matcher-sidebar-header">Multiple selected events</div>
           )}
+          <div className="matcher-sidebar-metadata-container">
+            {event.description !== "" && (
+              <>
+                <div className="matcher-sidebar-subheader">Description:</div>
+                <div className="matcher-description-text">{event.description}</div>
+              </>
+            )}
+          </div>
           <label className="matcher-pref-input-label">
             Preference:
             <input
diff --git a/csm_web/frontend/src/components/enrollment_automation/coordinator/CoordinatorMatcherForm.tsx b/csm_web/frontend/src/components/enrollment_automation/coordinator/CoordinatorMatcherForm.tsx
index 802f8ced..e9b304ee 100644
--- a/csm_web/frontend/src/components/enrollment_automation/coordinator/CoordinatorMatcherForm.tsx
+++ b/csm_web/frontend/src/components/enrollment_automation/coordinator/CoordinatorMatcherForm.tsx
@@ -61,7 +61,7 @@ export function CoordinatorMatcherForm({
     }
 
     // convert times to numbers
-    const new_slots: Slot[] = jsonSlots.slots.map((slot: { id: number; times: StrTime[] }) => {
+    const new_slots: Slot[] = jsonSlots.slots.map((slot: { id: number; times: StrTime[]; description: string }) => {
       const new_times: Time[] = slot.times.map((time: StrTime) => {
         return {
           interval: Interval.fromDateTimes(parseTime(time.startTime), parseTime(time.endTime)),
@@ -71,7 +71,8 @@ export function CoordinatorMatcherForm({
       });
       return {
         id: slot.id,
-        times: new_times
+        times: new_times,
+        description: slot.description
       };
     });
 
diff --git a/csm_web/frontend/src/components/enrollment_automation/coordinator/CreateStage.tsx b/csm_web/frontend/src/components/enrollment_automation/coordinator/CreateStage.tsx
index 2d0b74fd..741171eb 100644
--- a/csm_web/frontend/src/components/enrollment_automation/coordinator/CreateStage.tsx
+++ b/csm_web/frontend/src/components/enrollment_automation/coordinator/CreateStage.tsx
@@ -67,6 +67,8 @@ export function CreateStage({ profile, initialSlots, nextStage }: CreateStagePro
     length: Duration.fromObject({ hours: 1 })
   });
 
+  const [curSlotDescription, setCurSlotDescription] = useState<string>("");
+
   /**
    * Whether or not anything has been edited
    */
@@ -275,6 +277,7 @@ export function CreateStage({ profile, initialSlots, nextStage }: CreateStagePro
     } else {
       setCurCreatedTimes([]);
     }
+    setCurSlotDescription("");
     setCreatingTiledEvents(checked);
   };
 
@@ -325,7 +328,7 @@ export function CreateStage({ profile, initialSlots, nextStage }: CreateStagePro
     const newSlots = [];
     for (let t = tileDetails.start; t <= tileDetails.end.minus(tileDetails.length); t = t.plus(tileDetails.length)) {
       if (tileDetails.daysLinked) {
-        const newEvent: CalendarEvent = { times: [] };
+        const newEvent: CalendarEvent = { times: [], description: curSlotDescription };
         for (const day of tileDetails.days) {
           newEvent.times.push({
             day: day,
@@ -337,7 +340,14 @@ export function CreateStage({ profile, initialSlots, nextStage }: CreateStagePro
       } else {
         for (const day of tileDetails.days) {
           newSlots.push({
-            times: [{ day: day, interval: Interval.fromDateTimes(t, t.plus(tileDetails.length)), isLinked: false }]
+            times: [
+              {
+                day: day,
+                interval: Interval.fromDateTimes(t, t.plus(tileDetails.length)),
+                isLinked: false
+              }
+            ],
+            description: curSlotDescription
           });
         }
       }
@@ -352,8 +362,9 @@ export function CreateStage({ profile, initialSlots, nextStage }: CreateStagePro
    * Save the newly created event and times
    */
   const saveEvent = () => {
-    const newEvent = { times: curCreatedTimes };
+    const newEvent = { times: curCreatedTimes, description: curSlotDescription };
     setSlots([...slots, newEvent]);
+    setCurSlotDescription("");
     setCurCreatedTimes([]);
     setSavedExistingEvent(null);
     setSelectedEvents([]);
@@ -379,6 +390,7 @@ export function CreateStage({ profile, initialSlots, nextStage }: CreateStagePro
     setCurCreatedTimes([]);
     setSelectedEvents([]);
     setSelectedEventIndices([]);
+    setCurSlotDescription("");
   };
 
   /**
@@ -389,6 +401,7 @@ export function CreateStage({ profile, initialSlots, nextStage }: CreateStagePro
       const event = selectedEvents[0];
       // copy event
       setCurCreatedTimes(_.cloneDeep(event.times));
+      setCurSlotDescription(event.description);
       setSavedExistingEvent(_.cloneDeep(event)); // duplicate event
       // delete event
       deleteSelectedEvent();
@@ -619,6 +632,17 @@ export function CreateStage({ profile, initialSlots, nextStage }: CreateStagePro
                 mins
               </div>
             </div>
+            <div className="matcher-tiling-metadata-container">
+              <div className="matcher-tiling-subheader">Description:</div>
+              <div className="matcher-tiling-description-input-container">
+                <input
+                  className="matcher-tiling-description-input form-input light"
+                  type="text"
+                  value={curSlotDescription}
+                  onChange={e => setCurSlotDescription(e.target.value)}
+                />
+              </div>
+            </div>
           </div>
         </div>
         <div className="matcher-sidebar-tiling-bottom">
@@ -677,6 +701,17 @@ export function CreateStage({ profile, initialSlots, nextStage }: CreateStagePro
             ))}
           </div>
         </div>
+        <div className="matcher-sidebar-metadata-container">
+          <div className="matcher-sidebar-subheader">Description:</div>
+          <div className="matcher-sidebar-description-input-container">
+            <input
+              className="matcher-sidebar-description-input form-input light"
+              type="text"
+              value={curSlotDescription}
+              onChange={e => setCurSlotDescription(e.target.value)}
+            />
+          </div>
+        </div>
         <div className="matcher-sidebar-create-bottom">
           <div className="matcher-sidebar-create-bottom-row">
             <button className="secondary-btn" onClick={cancelEvent}>
@@ -713,6 +748,14 @@ export function CreateStage({ profile, initialSlots, nextStage }: CreateStagePro
                   </li>
                 ))}
               </ul>
+              <div className="matcher-sidebar-metadata-container">
+                {selectedEvents[0].description !== "" && (
+                  <>
+                    <div className="matcher-sidebar-subheader">Description:</div>
+                    <div className="matcher-sidebar-description-text">{selectedEvents[0].description}</div>
+                  </>
+                )}
+              </div>
             </React.Fragment>
           ) : (
             // multiple selected events
diff --git a/csm_web/frontend/src/css/enrollment_matcher.scss b/csm_web/frontend/src/css/enrollment_matcher.scss
index af65624c..4c5dc2d0 100644
--- a/csm_web/frontend/src/css/enrollment_matcher.scss
+++ b/csm_web/frontend/src/css/enrollment_matcher.scss
@@ -361,7 +361,8 @@
   color: $csm-danger-darkened;
 }
 
-.matcher-tiling-subheader {
+.matcher-tiling-subheader,
+.matcher-sidebar-subheader {
   /* font-style: italic; */
   font-weight: 600;
 }
@@ -432,6 +433,19 @@
   max-width: 250px;
 }
 
+.matcher-tiling-metadata-container,
+.matcher-sidebar-metadata-container {
+  padding-top: 5px;
+}
+
+.matcher-description-text {
+  max-width: 350px;
+  margin-top: 5px;
+  margin-left: 5px;
+
+  overflow-wrap: break-word;
+}
+
 .matcher-unsaved-changes-container {
   height: fit-content;
   margin-right: 15px;
@@ -620,6 +634,7 @@
   gap: 8px;
   align-items: center;
   margin-top: 8px;
+  font-weight: bold;
 }
 
 /* ConfigureStage.tsx */
diff --git a/csm_web/frontend/src/utils/queries/matcher.tsx b/csm_web/frontend/src/utils/queries/matcher.tsx
index cca48d2f..c6ea880f 100644
--- a/csm_web/frontend/src/utils/queries/matcher.tsx
+++ b/csm_web/frontend/src/utils/queries/matcher.tsx
@@ -35,6 +35,7 @@ interface MatcherSlotsResponse {
   slots: Array<{
     id: number;
     times: MatcherSlotsResponseTime[];
+    description: string;
   }>;
 }
 
diff --git a/csm_web/scheduler/migrations/0033_matcherslot_description.py b/csm_web/scheduler/migrations/0033_matcherslot_description.py
new file mode 100644
index 00000000..e7ac65a5
--- /dev/null
+++ b/csm_web/scheduler/migrations/0033_matcherslot_description.py
@@ -0,0 +1,17 @@
+# Generated by Django 4.2.7 on 2024-08-12 04:12
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("scheduler", "0032_word_of_the_day"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="matcherslot",
+            name="description",
+            field=models.TextField(blank=True, default=""),
+        ),
+    ]
diff --git a/csm_web/scheduler/models.py b/csm_web/scheduler/models.py
index 9e367ab6..0c842c68 100644
--- a/csm_web/scheduler/models.py
+++ b/csm_web/scheduler/models.py
@@ -260,19 +260,15 @@ def save(self, *args, **kwargs):
             ):
                 if settings.DJANGO_ENV != settings.DEVELOPMENT:
                     logger.info(
-                        (
-                            "<SectionOccurrence> SO automatically created for student"
-                            " %s in course %s for date %s"
-                        ),
+                        "<SectionOccurrence> SO automatically created for student"
+                        " %s in course %s for date %s",
                         self.user.email,
                         course.name,
                         now.date(),
                     )
                     logger.info(
-                        (
-                            "<Attendance> Attendance automatically created for student"
-                            " %s in course %s for date %s"
-                        ),
+                        "<Attendance> Attendance automatically created for student"
+                        " %s in course %s for date %s",
                         self.user.email,
                         course.name,
                         now.date(),
@@ -575,6 +571,7 @@ class MatcherSlot(ValidatingModel):
     times = models.JSONField()
     min_mentors = models.PositiveSmallIntegerField()
     max_mentors = models.PositiveSmallIntegerField()
+    description = models.TextField(default="", blank=True)
 
     def clean(self):
         super().clean()
diff --git a/csm_web/scheduler/serializers.py b/csm_web/scheduler/serializers.py
index cd31f741..c2b938c9 100644
--- a/csm_web/scheduler/serializers.py
+++ b/csm_web/scheduler/serializers.py
@@ -386,7 +386,7 @@ class Meta:
 class MatcherSlotSerializer(serializers.ModelSerializer):
     class Meta:
         model = MatcherSlot
-        fields = ["id", "matcher", "times"]
+        fields = ["id", "matcher", "times", "description"]
 
 
 class MatcherPreferenceSerializer(serializers.ModelSerializer):
diff --git a/csm_web/scheduler/utils/match_solver.py b/csm_web/scheduler/utils/match_solver.py
index f80953fb..07fed39d 100644
--- a/csm_web/scheduler/utils/match_solver.py
+++ b/csm_web/scheduler/utils/match_solver.py
@@ -1,6 +1,7 @@
-import networkx as nx
-from collections import namedtuple
 import itertools
+from collections import namedtuple
+
+import networkx as nx
 
 SOURCE = "source"
 SINK = "sink"
@@ -9,7 +10,7 @@
 MENTOR_NODE_PREFIX = "mentor"
 
 MentorTuple = namedtuple("MentorTuple", "id")
-SlotTuple = namedtuple("SlotTuple", "id min_mentors max_mentors")
+SlotTuple = namedtuple("SlotTuple", "id min_mentors max_mentors description")
 PreferenceTuple = namedtuple("PreferenceTuple", "mentor_id slot_id preference_value")
 
 
@@ -20,42 +21,53 @@ class MatcherValidationError(ValueError):
 
 
 def slot_node_name(slot_id):
+    """Compute the slot node name from its ID."""
     return SLOT_NODE_PREFIX + str(slot_id)
 
 
 def mentor_node_name(mentor_id):
+    """Compute the mentor node name from its ID."""
     return MENTOR_NODE_PREFIX + str(mentor_id)
 
 
 def slot_id_from_node(node_name):
+    """
+    Compute the slot ID from its node name.
+    """
     return int(node_name.replace(SLOT_NODE_PREFIX, ""))
 
 
 def mentor_id_from_node(node_name):
+    """Compute the mentor ID from its node name."""
     return int(node_name.replace(MENTOR_NODE_PREFIX, ""))
 
 
 def get_matches(mentors, slots, preferences):
-    total_min_capacities = sum([slot.min_mentors for slot in slots])
-    total_max_capacities = sum([slot.max_mentors for slot in slots])
+    """
+    Run a min-cost max-flow algorithm to find the best matches between mentors and slots,
+    given each mentor's preferences for each slot.
+    """
+    total_min_capacities = sum(slot.min_mentors for slot in slots)
+    total_max_capacities = sum(slot.max_mentors for slot in slots)
     # validate capacities
     if total_min_capacities > total_max_capacities:
         raise MatcherValidationError(
-            "Total minimum slot capacities are greater than total maximum slot capacities."
+            "Total minimum slot capacities are greater than total maximum slot"
+            " capacities."
         )
     # validate number of slots
     if total_max_capacities < len(mentors):
         raise MatcherValidationError("There are more mentors than available slots.")
     if total_min_capacities > len(mentors):
         raise MatcherValidationError("Not enough mentors to fulfill slot requirements.")
-    G = nx.DiGraph()
-    G.add_node(SOURCE, demand=-len(mentors))
-    G.add_node(SINK, demand=len(mentors) - total_min_capacities)
+    graph = nx.DiGraph()
+    graph.add_node(SOURCE, demand=-len(mentors))
+    graph.add_node(SINK, demand=len(mentors) - total_min_capacities)
     # add mentor nodes and edges from source
     for mentor in mentors:
         mentor_id = mentor.id
-        G.add_node(mentor_node_name(mentor_id), demand=0)
-        G.add_edge(SOURCE, mentor_node_name(mentor_id), weight=1, capacity=1)
+        graph.add_node(mentor_node_name(mentor_id), demand=0)
+        graph.add_edge(SOURCE, mentor_node_name(mentor_id), weight=1, capacity=1)
     # add slot nodes and edges to sink
     for slot in slots:
         slot_id, min_mentors, max_mentors = slot.id, slot.min_mentors, slot.max_mentors
@@ -64,8 +76,8 @@ def get_matches(mentors, slots, preferences):
                 "Minimum slot capacity is greater than maximum slot capacity."
             )
         node_name = slot_node_name(slot_id)
-        G.add_node(node_name, demand=min_mentors)
-        G.add_edge(node_name, SINK, weight=1, capacity=max_mentors - min_mentors)
+        graph.add_node(node_name, demand=min_mentors)
+        graph.add_edge(node_name, SINK, weight=1, capacity=max_mentors - min_mentors)
 
     # create edges from mentor nodes to slot nodes
     for preference in preferences:
@@ -78,13 +90,13 @@ def get_matches(mentors, slots, preferences):
             preference_weight = UNMATCHABLE_EDGE_WEIGHT
         else:
             preference_weight = round(1 / preference_num * 100, 0)
-        G.add_edge(
+        graph.add_edge(
             mentor_node_name(mentor_id),
             slot_node_name(slot_id),
             weight=preference_weight,
             capacity=1,
         )
-    flow_cost, flow_dict = nx.network_simplex(G)
+    _flow_cost, flow_dict = nx.network_simplex(graph)
     mentors_set = set(itertools.chain(*mentors))
     assignments = {}
     for u in flow_dict:
@@ -93,7 +105,7 @@ def get_matches(mentors, slots, preferences):
                 flow_dict[u][v] >= 1
                 and u != SOURCE
                 and v != SINK
-                and G[u][v]["weight"] != UNMATCHABLE_EDGE_WEIGHT
+                and graph[u][v]["weight"] != UNMATCHABLE_EDGE_WEIGHT
             ):
                 assignments[mentor_id_from_node(u)] = slot_id_from_node(v)
                 mentors_set.remove(mentor_id_from_node(u))
diff --git a/csm_web/scheduler/views/matcher.py b/csm_web/scheduler/views/matcher.py
index 21d0b97b..23a786a8 100644
--- a/csm_web/scheduler/views/matcher.py
+++ b/csm_web/scheduler/views/matcher.py
@@ -139,6 +139,9 @@ def slots(request, pk=None):
                 max_mentors = (
                     slot_json["maxMentors"] if "maxMentors" in slot_json else 10
                 )
+                description = (
+                    slot_json["description"] if "description" in slot_json else ""
+                )
                 if min_mentors > max_mentors:
                     return Response(
                         {
@@ -157,10 +160,12 @@ def slots(request, pk=None):
                         times=times,
                         min_mentors=min_mentors,
                         max_mentors=max_mentors,
+                        description=description,
                     )
                 else:
                     slot.min_mentors = min_mentors
                     slot.max_mentors = max_mentors
+                    slot.description = description
                     slot.save()
 
         return Response(status=status.HTTP_202_ACCEPTED)
@@ -410,13 +415,20 @@ def configure(request, pk=None):
                 matcher_assignment, unmatched = run_matcher(course)
             except Exception as e:  # pylint: disable=broad-except
                 return Response({"error": str(e)}, status=status.HTTP_400_BAD_REQUEST)
+
+            matcher_slots = MatcherSlot.objects.filter(matcher=course.matcher)
+            matcher_slot_map = {slot.id: slot for slot in matcher_slots}
+
             # assignment is of the form {"mentor", "capacity"};
             # add a "section" key with default values of capacity and description
             updated_assignment = [
                 {
                     "slot": int(slot),
                     "mentor": int(mentor),
-                    "section": {"capacity": DEFAULT_CAPACITY, "description": ""},
+                    "section": {
+                        "capacity": DEFAULT_CAPACITY,
+                        "description": matcher_slot_map[slot].description,
+                    },
                 }
                 for (mentor, slot) in matcher_assignment.items()
             ]