This document details the housing allotment rules, priority pooling policies, preference processing algorithms, and lottery mechanism used by the ICTS Housing Cell for allocating campus housing to **Postdoctoral Fellows (PDFs)** and **Graduate Students (PhD / Int-PhD)**.
---
## 1. Overview & Allotment Workflow
The housing allocation process automates the distribution of limited hostel rooms and campus apartments based on:
1.**Applicant Group**: Postdoctoral Fellows vs. Graduate Students.
2.**Priority Pools**: Institutional policy rules prioritizing medical needs, dependents, gender, and academic seniority.
3.**Preference Vectors**: Applicant choices ranked from 1 (most preferred) downwards.
4.**Lottery Tie-Breaking**: Pseudo-random shuffling within each priority pool using a fixed RNG seed for reproducibility.
5.**Sequential Greedy Allocation**: Candidate-by-candidate allocation in lottery rank order, assigning their highest-ranked available accommodation.
---
## 2. Accommodation Types & Mapping
### Postdoctoral Fellows (Index 0 – 7)
| Index | Accommodation Category | Description & Eligibility |
| :---: | :--- | :--- |
| `0` | On campus Studios | Studio apartments on campus |
| `8` | On campus Studios | Restricted / PDF priority |
---
## 3. Preference Parsing & Order Construction
Google Form responses collect numerical ranks for each option (e.g. `1` for top choice, `2` for second, etc.).
-**Unranked Options**: Represented as `NaN` or `99`.
-**Conversion to Preference Vector**:
1. The raw rank list `[r_0, r_1, ..., r_N]` is converted into an ordered list of accommodation indices `[pref_0, pref_1, ...]`.
2. Choices with lower numerical ranks appear earlier in the preference vector.
3. Tied or repeated ranks are ordered deterministically in reverse column order.
4. Unranked choices (rank `99`) are appended at the end of the candidate's preference vector.
---
## 4. Priority Pool Rules
Applicants are grouped into priority pools. Allocations are executed pool by pool in numerical order (Pool 1 gets highest priority, followed by Pool 2, Pool 3, etc.).
### A. Postdoctoral Fellows Priority Pools (Pools 1 to 5)
1.**Pool 1 (Highest Priority - Medical & Disability Family)**:
- Must prefer Family accommodation (`student_or_postdoc == "postdoc_family"`).
- Must have a registered medical/disability condition (`disability_check == 1`).
- Must have at least 1 dependent (`num_dependents > 0`).
2.**Pool 2 (High Family Priority)**:
- Family postdocs with `num_dependents > 2`, OR
- Female family postdocs with `num_dependents >= 2`.
3.**Pool 3 (Family with 2+ Dependents)**:
- Family postdocs with `num_dependents >= 2`.
4.**Pool 4 (Family with 1 Dependent)**:
- Family postdocs with `num_dependents == 1`.
5.**Pool 5 (General Postdocs)**:
- All single postdocs and remaining family postdocs not meeting higher pool criteria.
### B. Graduate Students Priority Pools (Pools 1 to 3)
*Note on Academic Year*: Before the start of the new session in July, student academic years are normalized (e.g. 1st year incoming is year 1).
1.**Pool 1 (Highest Priority - 1st Year Female Students)**:
- Female graduate students entering or in 1st year (`female == 1` AND `year == 1`).
2.**Pool 2 (1st Year Male & Senior PhD Students)**:
- 1st year male students (`year == 1`), OR
- Senior PhD students: PhD year $\ge 5$ OR Int-PhD year $\ge 6$.
3.**Pool 3 (General Graduate Students)**:
- All other registered graduate students (2nd, 3rd, 4th year PhD; 2nd, 3rd, 4th, 5th year Int-PhD).
---
## 5. Lottery & Allocation Algorithm
1.**Random Seed Initialization**:
- A random seed is configured (e.g., standard noon timestamp `datetime(2026, 6, 7, 12, 0, 0)`).
2.**Sequential Pool Execution**:
- For each pool ID in `[1, 2, ...]`:
-**Shuffle Candidates**: Randomize candidate order within the pool using `random.shuffle(pool_candidates)`.
-**Greedy Allocation**: For each candidate in shuffled order:
- Iterate through candidate's preference vector `[pref_0, pref_1, ...]`.
- Assign the first housing category `pref_i` with `remaining_availability[pref_i] > 0`.
- Decrement `remaining_availability[pref_i]` by 1.
- If all preferred housing options are exhausted (capacity 0), the candidate remains unallocated.
This document details the housing allotment rules, priority pooling policies, preference processing algorithms, and lottery mechanism used by the ICTS Housing Cell for allocating campus housing to **Postdoctoral Fellows (PDFs)** and **Graduate Students (PhD / Int-PhD)**.
---
## 1. Overview & Allotment Workflow
The housing allocation process automates the distribution of limited hostel rooms and campus apartments based on:
1.**Applicant Group**: Postdoctoral Fellows vs. Graduate Students.
2.**Priority Pools**: Institutional policy rules prioritizing medical needs, dependents, gender, and academic seniority.
3.**Preference Vectors**: Applicant choices ranked from 1 (most preferred) downwards.
4.**Lottery Tie-Breaking**: Pseudo-random shuffling within each priority pool using a fixed RNG seed for reproducibility.
5.**Sequential Greedy Allocation**: Candidate-by-candidate allocation in lottery rank order, assigning their highest-ranked available accommodation.
---
## 2. Accommodation Types & Mapping
### Postdoctoral Fellows (Index 0 – 7)
| Index | Accommodation Category | Description & Eligibility |
| :---: | :--- | :--- |
| `0` | On campus Studios | Studio apartments on campus |
| `8` | On campus Studios | Restricted / PDF priority |
---
## 3. Preference Parsing & Order Construction
Google Form responses collect numerical ranks for each option (e.g. `1` for top choice, `2` for second, etc.).
-**Unranked Options**: Represented as `NaN` or `99`.
-**Conversion to Preference Vector**:
1. The raw rank list `[r_0, r_1, ..., r_N]` is converted into an ordered list of accommodation indices `[pref_0, pref_1, ...]`.
2. Choices with lower numerical ranks appear earlier in the preference vector.
3. Tied or repeated ranks are ordered deterministically in reverse column order.
4. Unranked choices (rank `99`) are appended at the end of the candidate's preference vector.
---
## 4. Priority Pool Rules
Applicants are grouped into priority pools. Allocations are executed pool by pool in numerical order (Pool 1 gets highest priority, followed by Pool 2, Pool 3, etc.).
### A. Postdoctoral Fellows Priority Pools (Pools 1 to 5)
1.**Pool 1 (Highest Priority - Medical & Disability Family)**:
- Must prefer Family accommodation (`student_or_postdoc == "postdoc_family"`).
- Must have a registered medical/disability condition (`disability_check == 1`).
- Must have at least 1 dependent (`num_dependents > 0`).
2.**Pool 2 (High Family Priority)**:
- Family postdocs with `num_dependents > 2`, OR
- Female family postdocs with `num_dependents >= 2`.
3.**Pool 3 (Family with 2+ Dependents)**:
- Family postdocs with `num_dependents >= 2`.
4.**Pool 4 (Family with 1 Dependent)**:
- Family postdocs with `num_dependents == 1`.
5.**Pool 5 (General Postdocs)**:
- All single postdocs and remaining family postdocs not meeting higher pool criteria.
### B. Graduate Students Priority Pools (Pools 1 to 3)
*Note on Academic Year*: Before the start of the new session in July, student academic years are normalized (e.g. 1st year incoming is year 1).
1.**Pool 1 (Highest Priority - 1st Year Female Students)**:
- Female graduate students entering or in 1st year (`female == 1` AND `year == 1`).
2.**Pool 2 (1st Year Male & Senior PhD Students)**:
- 1st year male students (`year == 1`), OR
- Senior PhD students: PhD year $\ge 5$ OR Int-PhD year $\ge 6$.
3.**Pool 3 (General Graduate Students)**:
- All other registered graduate students (2nd, 3rd, 4th year PhD; 2nd, 3rd, 4th, 5th year Int-PhD).
---
## 5. Lottery & Allocation Algorithm
1.**Random Seed Initialization**:
- A random seed is configured (e.g., standard noon timestamp `datetime(2026, 6, 7, 12, 0, 0)`).
2.**Sequential Pool Execution**:
- For each pool ID in `[1, 2, ...]`:
-**Shuffle Candidates**: Randomize candidate order within the pool using `random.shuffle(pool_candidates)`.
-**Greedy Allocation**: For each candidate in shuffled order:
- Iterate through candidate's preference vector `[pref_0, pref_1, ...]`.
- Assign the first housing category `pref_i` with `remaining_availability[pref_i] > 0`.
- Decrement `remaining_availability[pref_i]` by 1.
- If all preferred housing options are exhausted (capacity 0), the candidate remains unallocated.
