TSA/chapter-organizer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor TeamScheduler, easier to read and maintain

Browse Source
This commit is contained in:
James Kolpack
2025-12-01 06:58:56 -05:00
parent 69dd517d73
commit 3461f94854
7 changed files with 161 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Core/Calculation/TeamScheduleTimeSlot.cs
+27 -4
View File
@@ -2,15 +2,38 @@
namespace Core.Calculation;
/// <summary>
/// Represents a single time slot in the team meeting schedule.
/// </summary>
public class TeamScheduleTimeSlot
{
/// <summary>
/// Gets or sets the name of this time slot.
/// </summary>
public string Name { get; set; }
public Team[] Teams;
public Student[] UnscheduledStudents;
public IEnumerable<Tuple<Student, IEnumerable<Team>>> StudentOverlaps;
/// <summary>
/// Gets or sets the teams scheduled in this time slot.
/// </summary>
public Team[] Teams;
/// <summary>
/// Gets or sets the students who are not scheduled in any team during this time slot.
/// </summary>
public Student[] UnscheduledStudents;
/// <summary>
/// Gets or sets the students who have overlapping team meetings in this time slot.
/// </summary>
public IEnumerable<(Student student, IEnumerable<Team> teams)> StudentOverlaps;
/// <summary>
/// Checks if a student has overlapping team meetings in this time slot.
/// </summary>
/// <param name="student">The student to check</param>
/// <returns>True if the student has overlaps, otherwise false</returns>
public bool StudentHasOverlaps(Student student)
{
return StudentOverlaps.FirstOrDefault(o => o.Item1.Equals(student)) != null;
return StudentOverlaps.Any(o => o.student.Equals(student));
}
}
Core/Calculation/TeamScheduler.cs
+66 -25
View File
@@ -3,69 +3,110 @@ using Core.Entities;
using Google.OrTools.Sat;
namespace Core.Calculation;
/// <summary>
/// Solves the team meeting scheduling problem using constraint programming.
/// Assigns teams to time slots while minimizing student schedule conflicts.
/// </summary>
public class TeamScheduler
{
private readonly IList<Student> _studentObjects;
private readonly IList<Team> _teamObjects;
private readonly double _maxSolveTimeSeconds;
private readonly int[] _students;
private readonly int[] _teams;
private readonly int[] _timeSlots;
private readonly List<Tuple<int,int>> _scheduleSeparateTeams = [];
private readonly List<(int team1, int team2)> _scheduleSeparateTeams = [];
public TeamScheduler(IEnumerable<Team> teams, int numTimeSlots, IEnumerable<Student> allStudents)
/// <summary>
/// Creates a new team scheduler instance.
/// </summary>
/// <param name="teams">The teams to schedule (must not be null or empty)</param>
/// <param name="numTimeSlots">The number of available time slots (must be positive)</param>
/// <param name="allStudents">All students participating in teams (must not be null or empty)</param>
/// <param name="maxSolveTimeSeconds">Maximum solver time in seconds (default: 10.0)</param>
/// <exception cref="ArgumentNullException">Thrown when teams or allStudents is null</exception>
/// <exception cref="ArgumentException">Thrown when collections are empty or numTimeSlots is invalid</exception>
public TeamScheduler(IEnumerable<Team> teams, int numTimeSlots, IEnumerable<Student> allStudents, double maxSolveTimeSeconds = 10.0)
{
if (teams == null)
throw new ArgumentNullException(nameof(teams));
if (allStudents == null)
throw new ArgumentNullException(nameof(allStudents));
if (numTimeSlots <= 0)
throw new ArgumentException("Number of time slots must be positive", nameof(numTimeSlots));
_teamObjects = teams.ToArray();
//_studentObjects = teams.SelectMany(t => t.Students).Distinct().ToList();
_studentObjects = allStudents.ToList();
_studentObjects = allStudents.ToList();
_maxSolveTimeSeconds = maxSolveTimeSeconds;
if (_teamObjects.Count == 0)
throw new ArgumentException("Teams collection cannot be empty", nameof(teams));
if (_studentObjects.Count == 0)
throw new ArgumentException("Students collection cannot be empty", nameof(allStudents));
_students = Enumerable.Range(0, _studentObjects.Count).ToArray();
_teams = Enumerable.Range(0, _teamObjects.Count).ToArray();
_timeSlots = Enumerable.Range(0, numTimeSlots).ToArray();
}
/// <summary>
/// Adds a constraint requiring two teams to be scheduled in different time slots.
/// </summary>
/// <param name="team1">First team</param>
/// <param name="team2">Second team</param>
/// <exception cref="ArgumentException">Thrown when either team is not found in the scheduler</exception>
public void ScheduleSeparate(Team team1, Team team2)
{
var one = _teamObjects.IndexOf(team1);
var two = _teamObjects.IndexOf(team2);
_scheduleSeparateTeams.Add(Tuple.Create(one,two));
}
public static TeamScheduler CreateInstance(IEnumerable<Team> teams, int numTimeSlots, IEnumerable<Student> allStudents)
{
return new TeamScheduler(teams, numTimeSlots, allStudents);
if (one == -1)
throw new ArgumentException($"Team '{team1}' not found in scheduler", nameof(team1));
if (two == -1)
throw new ArgumentException($"Team '{team2}' not found in scheduler", nameof(team2));
_scheduleSeparateTeams.Add((one, two));
}
/// <summary>
/// Solves the team scheduling problem using constraint programming.
/// Minimizes the number of time slots where students have conflicting team meetings.
/// </summary>
/// <returns>A solution containing team assignments to time slots and conflict information</returns>
public TeamSchedulerSolution Solve()
{
// Model.
// Create constraint programming model
var model = new CpModel();
// Data
// Build membership matrix: m[i,t] = 1 if student i is on team t, else 0
var m = new int[_students.Length,_teams.Length];
foreach (var i in _students)
foreach (var t in _teams)
m[i, t] = _studentObjects[i].Teams.Contains(_teamObjects[t]) ? 1 : 0;
// Variables.
// x - 1 if meeting of team t takes place at time slot s, else 0
// Decision variables:
// x[t,s] = 1 if meeting of team t takes place at time slot s, else 0
var x = new IntVar[_teams.Length, _timeSlots.Length];
foreach (var t in _teams)
foreach (var s in _timeSlots)
x[t, s] = model.NewIntVar(0, 1,$"team time slots[{t},{s}]");
// y - 1 if individual i has meetings at time slot s, 0 otherwise
// y[i,s] = 1 if student i has at least one meeting at time slot s, else 0
var y = new IntVar[_students.Length, _timeSlots.Length];
foreach (var i in _students)
foreach (var s in _timeSlots)
y[i, s] = model.NewIntVar(0, 1, $"individual time slots[{i},{s}]");
// each team meets exactly one time
// Constraint: each team meets exactly once
foreach (var t in _teams)
model.AddLinearConstraint(LinearExpr.Sum(_timeSlots.Select(s => x[t, s])), 1L, 1L);
// individual must have at least one team meeting at the given time slot to attend
// Constraint: Link y[i,s] to whether student i has meetings at slot s
// y[i,s] <= sum over all teams t of (m[i,t] * x[t,s])
// This forces y[i,s] to be 1 if student i has at least one team meeting at slot s
foreach (var i in _students)
foreach (var s in _timeSlots)
model.Add(
@@ -74,19 +115,21 @@ public class TeamScheduler
LinearExpr.Sum(_teams.Select(t => m[i, t] * x[t, s])),
false));
// maximize number of times individuals meet
// Objective: minimize the sum of y[i,s] values (minimize student conflicts)
var indTimeSlotVars = LinearExpr.NewBuilder();
foreach (var i in _students)
foreach (var s in _timeSlots)
indTimeSlotVars.Add(y[i, s]);
model.Minimize(indTimeSlotVars);
foreach (var ts in _scheduleSeparateTeams)
// Constraint: teams marked as "separate" must be in different time slots
foreach (var (team1, team2) in _scheduleSeparateTeams)
foreach (var s in _timeSlots)
model.Add(x[ts.Item1, s] != x[ts.Item2, s]);
model.Add(x[team1, s] != x[team2, s]);
// Configure and run solver
var solver = new CpSolver();
solver.StringParameters = "max_time_in_seconds:2.0";
solver.StringParameters = $"max_time_in_seconds:{_maxSolveTimeSeconds}";
var cpSolverStatus = solver.Solve(model);
Debug.WriteLine($"Solver status: {cpSolverStatus}");
@@ -95,15 +138,13 @@ public class TeamScheduler
if (cpSolverStatus is not (CpSolverStatus.Optimal or CpSolverStatus.Feasible))
return new TeamSchedulerSolution(timeSlotTeams, _studentObjects.ToArray(), cpSolverStatus.ToString());
// Debug.WriteLine($"Total cost: {solver.ObjectiveValue}\n");
// Extract solution: which teams are assigned to each time slot
foreach (var s in _timeSlots)
{
var teams = (from t in _teams where solver.Value(x[t, s]) > 0 select _teamObjects[t]).ToArray();
timeSlotTeams[s] = teams;
}
//Debug.WriteLine("No solution found.");
return new TeamSchedulerSolution(timeSlotTeams, _studentObjects.ToArray(), cpSolverStatus.ToString());
}
}
Core/Calculation/TeamSchedulerSolution.cs
+45 -14
View File
@@ -2,57 +2,88 @@
namespace Core.Calculation;
/// <summary>
/// Represents a solution to the team scheduling problem.
/// Contains team assignments to time slots and information about student scheduling conflicts.
/// </summary>
public class TeamSchedulerSolution(
Team[][] timeSlots,
Student[] students,
string status)
{
/// <summary>
/// Gets the solver status (e.g., "Optimal", "Feasible", "Infeasible").
/// </summary>
public string Status { get; } = status;
public TeamScheduleTimeSlot[] TimeSlots { get; set; }
= timeSlots.Select( (teams,i) =>
/// <summary>
/// Gets the scheduled time slots with team assignments and conflict information.
/// </summary>
public TeamScheduleTimeSlot[] TimeSlots { get; set; }
= timeSlots.Select( (teams,i) =>
new TeamScheduleTimeSlot{
Name = "Time Slot " + (i + 1),
Name = "Time Slot " + (i + 1),
Teams = teams,
StudentOverlaps = GetStudentTeamOverlaps(teams),
StudentOverlaps = GetStudentTeamOverlaps(teams),
UnscheduledStudents = GetStudentsNotInTimSlot(teams, students)
}
).ToArray();
/// <summary>
/// Calculates the total number of student conflicts across all time slots.
/// </summary>
/// <param name="timeSlots">The scheduled time slots</param>
/// <returns>Total count of students with overlapping team meetings</returns>
public static int GetStudentTeamOverlapCount(Team[][] timeSlots)
{
return timeSlots.Sum(GetStudentTeamOverlapCount);
}
/// <summary>
/// Calculates the number of student conflicts in a single time slot.
/// </summary>
/// <param name="timeSlot">The time slot to analyze</param>
/// <returns>Count of students with multiple team meetings in this slot</returns>
private static int GetStudentTeamOverlapCount(Team[] timeSlot)
{
return GetStudentTeamOverlaps(timeSlot).Count();
}
public static IEnumerable<Tuple<Student, IEnumerable<Team>>> GetStudentTeamOverlaps(Team[] timeSlot)
/// <summary>
/// Identifies students who have multiple team meetings in the same time slot.
/// </summary>
/// <param name="timeSlot">The time slot to analyze</param>
/// <returns>Students and their conflicting teams in this time slot</returns>
public static IEnumerable<(Student student, IEnumerable<Team> teams)> GetStudentTeamOverlaps(Team[] timeSlot)
{
return
from s in timeSlot.SelectMany(ts => ts.Students).Distinct()
group s by timeSlot.Where(t => t.Students.Contains(s))
into gs
where gs.Key.Count() > 1
select Tuple.Create(gs.First(), gs.Key);
select (gs.First(), gs.Key);
}
/// <summary>
/// Identifies students who have no team meetings in the given time slot.
/// </summary>
/// <param name="timeSlot">The time slot to analyze</param>
/// <param name="students">All students</param>
/// <returns>Students not scheduled in this time slot</returns>
public static Student[] GetStudentsNotInTimSlot(Team[] timeSlot, Student[] students)
{
var studentsInTimeSlot = timeSlot.SelectMany(ts => ts.Students).Distinct();
return
(from allStudent in students
where studentsInTimeSlot.FirstOrDefault(e => e.Equals(allStudent)) == null
select allStudent
).ToArray();
var studentsInTimeSlot = timeSlot.SelectMany(ts => ts.Students).Distinct().ToHashSet();
return students.Where(s => !studentsInTimeSlot.Contains(s)).ToArray();
}
/// <summary>
/// Gets the teams a student is on that weren't assigned to any time slot.
/// </summary>
/// <param name="student">The student to check</param>
/// <returns>Teams the student is on that have no scheduled meeting</returns>
public Team[] StudentUnassignedTeams(Student student)
{
var meetingTeams = TimeSlots.SelectMany(t => t.Teams);
return
student.Teams.Where(e => !meetingTeams.Contains(e)).ToArray();
return student.Teams.Where(e => !meetingTeams.Contains(e)).ToArray();
}
}
Tests/Calculation/TeamSchedulerTest.cs
+2 -2
View File
@@ -39,7 +39,7 @@ public class TeamSchedulerTest
TeamSchedulerSolution solution;
if (true)
{
var teamScheduler = TeamScheduler.CreateInstance(teams, 3, students);
var teamScheduler = new TeamScheduler(teams, 3, students);
solution = teamScheduler.Solve();
}
else
@@ -69,7 +69,7 @@ public class TeamSchedulerTest
Console.WriteLine("\toverlaps");
foreach (var overlap in overlaps)
Console.WriteLine(
$"\t\t{overlap.Item1.Name} : {string.Join(", ", overlap.Item2.Select(t => t.Event.Name))}");
$"\t\t{overlap.student.Name} : {string.Join(", ", overlap.teams.Select(t => t.Event.Name))}");
}
var unassigned = UnassignedStudentScheduler.UnassignedStudents(students, slot.Teams).ToList();
Web-Original/Views/Home/Schedule.cshtml
+3 -3
View File
@@ -12,13 +12,13 @@
var allMeetingTeams = schedule.SelectMany(t => t).Distinct();
}
<div class="bluewhite p-5">
<div class="bluewhite p-5">
@{
List<Tuple<Student, IEnumerable<Team>>> overlaps;
List<(Student student, IEnumerable<Team> teams)> overlaps;
}
@foreach (var timeslot in schedule)
{
overlaps = Team.GetStudentTeamOverlaps(timeslot).ToList();
overlaps = TeamSchedulerSolution.GetStudentTeamOverlaps(timeslot).ToList();
var partialTeams = timeslot.Where(t => t is PartialTeam && t.EventDefinition.EventFormat is not EventFormat.Individual);
var fullTeams = timeslot.Where(t => !partialTeams.Contains(t));
Web-Original/Views/Home/ScheduleTeamPartial.cshtml
+2 -2
View File
@@ -1,5 +1,5 @@
@using Core.Entities
@model Tuple<Core.Entities.Team, List<Tuple<Student, IEnumerable<Team>>>, string[]?>
@model Tuple<Core.Entities.Team, List<(Student student, IEnumerable<Team> teams)>, string[]?>
@{
var team = Model.Item1;
@@ -36,7 +36,7 @@
{
first = false;
}
@if (overlaps.Any(t => t.Item1 == student))
@if (overlaps.Any(t => t.student == student))
{
<span style="color: #F66">@student.FirstName</span>
}
WebApp/Components/Pages/MeetingSchedulePages/Index.razor
+16
View File
@@ -207,9 +207,25 @@
{
_isSolving = true;
// Check if there are any teams to schedule
if (!_scheduledTeams.Any())
{
_isSolving = false;
_solution = new TeamSchedulerSolution([], [], "No teams selected");
return new TableData<TeamScheduleTimeSlot> { Items = [] };
}
// Filter out absent students
var availableStudents = _students.Where(s => !_absentStudents.Contains(s)).ToArray();
// Check if there are any available students
if (availableStudents.Length == 0)
{
_isSolving = false;
_solution = new TeamSchedulerSolution([], [], "No available students");
return new TableData<TeamScheduleTimeSlot> { Items = [] };
}
// Update parameters with absent student names
_parameters.AbsentStudents = _absentStudents.Select(s => s.FirstNameLastName).ToArray();