An intelligent roommate assignment system that uses a modified Irving's stable roommate algorithm to optimally match students into rooms based on their preferences while respecting constraints like same-gender groupings and grade level compatibility.
- Preference-based matching using student survey responses
- Same-gender room enforcement
- Configurable grade level restrictions
- Configurable room sizes
- Multiple optimization passes for best results
- Detailed error reporting for invalid preferences
-
Clone this repository or download the zip file.
-
Install pip if you haven't already.
-
Open Terminal or Command Prompt and navigate to the project directory.
-
Install dependencies:
pip install -r requirements.txt
Create a Google Form with the following questions:
Important: Enable the "Collect email addresses" option. Questions marked with (*) are required for the program. Questions must match the exact wording shown below.
Verify your Google Sheet has these columns:
Download the spreadsheet as a CSV file.
Run the program:
python main.pyYou will be prompted for:
- Maximum students per room: The maximum number of students allowed in each room (default: 4)
- Maximum grade level difference: How many grades apart students can be to room together (default: 1)
- CSV file path: Path to your downloaded Google Form responses
The program generates two files:
rooms.csv: Room assignments with student names, genders, and gradeserrors.csv: Any preference errors (e.g., preferences for students not in the dataset, cross-gender preferences, or grade constraint violations)
The matching algorithm:
- Separates students by gender to ensure same-gender rooms
- Builds a preference matrix from survey responses (1st choice = 10 points, 2nd = 7, 3rd = 4)
- Runs multiple matching attempts with random initialization
- Optimizes for maximum preference satisfaction
- Returns the best result across all attempts
- Python 3.7+
- pandas
- numpy
MIT License