`hri.Rd`

Finds *all* stable matchings in either the
hospital/residents problem (a.k.a. college
admissions problem) or the related
stable marriage problem.
Dependent on the problem, the results comprise the student and college-optimal or
the men and women-optimal matchings. The implementation allows for *incomplete preference
lists* (some agents find certain agents unacceptable) and *unbalanced instances* (unequal
number of agents on both sides). The function uses the Prosser (2014) constraint encoding based on
either given or randomly generated preferences.

hri(nStudents = ncol(s.prefs), nColleges = ncol(c.prefs), nSlots = rep(1, nColleges), s.prefs = NULL, c.prefs = NULL, s.range = NULL, c.range = NULL, randomization = NULL, seed = NULL, check_consistency = FALSE, ...)

nStudents | integer indicating the number of students (in the college admissions problem)
or men (in the stable marriage problem) in the market. Defaults to |
---|---|

nColleges | integer indicating the number of colleges (in the college admissions problem)
or women (in the stable marriage problem) in the market. Defaults to |

nSlots | vector of length |

s.prefs | matrix of dimension |

c.prefs | matrix of dimension |

s.range | range of two intergers |

c.range | range of two intergers |

randomization | determines at which level random lottery numbers for student priorities are drawn. The default is |

seed | integer setting the state for random number generation. |

check_consistency | Performs consicentcy checks (Checks if there are columns in the preference matrices that only contains zeros and drops them and checks the matrixes for consistencies if they are given by characters). Defaults to |

... | . |

`hri`

returns a list of the following elements.

student-side preference matrix for the stable marriage problem with incomplete lists (SMI).

college-side preference matrix for the stable marriage problem with incomplete lists (SMI).

student-side preference matrix for the college admissions problem (a.k.a. hospital/residents problem) with incomplete lists (HRI).

college-side preference matrix for the college admissions problem (a.k.a. hospital/residents problem) with incomplete lists (HRI).

edgelist of matched students and colleges, inculding the number of the match
(`matching`

) and two variables that indicate the student-optimal match (`sOptimal`

) and
college-optimal match (`cOptimal`

)

`hri`

requires the following combination of arguments, subject to the matching problem.

`nStudents, nColleges`

Marriage problem with random preferences.

`s.prefs, c.prefs`

Marriage problem with given preferences.

`nStudents, nSlots`

College admissions problem with random preferences.

`s.prefs, c.prefs, nSlots`

College admissions problem with given preferences.

Gale, D. and L.S. Shapley (1962). College admissions and the stability
of marriage. *The American Mathematical Monthly*, 69(1):9--15.

Morizumi, Y., T. Hayashi and Y. Ishida (2011). A network visualization of stable matching in the stable
marriage problem. *Artificial Life Robotics*, 16:40--43.

Prosser, P. (2014). Stable Roommates and Constraint Programming. *Lecture Notes in Computer Science, CPAIOR 2014 Edition*.
Springer International Publishing, 8451: 15--28.

# NOT RUN { ## ----------------------- ## --- Marriage problem ## 7 men, 6 women, random preferences: hri(nStudents=7, nColleges=6, seed=4) ## 3 men, 2 women, given preferences: s.prefs <- matrix(c(1,2, 1,2, 1,2), 2,3) c.prefs <- matrix(c(1,2,3, 1,2,3), 3,2) hri(s.prefs=s.prefs, c.prefs=c.prefs) ## 3 men, 2 women, given preferences: s.prefs <- matrix(c("x","y", "x","y", "x","y"), 2,3) colnames(s.prefs) <- c("A","B","C") c.prefs <- matrix(c("A","B","C", "A","B","C"), 3,2) colnames(c.prefs) <- c("x","y") hri(s.prefs=s.prefs, c.prefs=c.prefs) ## -------------------------------- ## --- College admission problem ## 7 students, 2 colleges with 3 slots each, random preferences: hri(nStudents=7, nSlots=c(3,3), seed=21) ## 7 students, 2 colleges with 3 slots each, given preferences: s.prefs <- matrix(c(1,2, 1,2, 1,NA, 1,2, 1,2, 1,2, 1,2), 2,7) c.prefs <- matrix(c(1,2,3,4,5,6,7, 1,2,3,4,5,NA,NA), 7,2) hri(s.prefs=s.prefs, c.prefs=c.prefs, nSlots=c(3,3)) ## 7 students, 2 colleges with 3 slots each, given preferences: s.prefs <- matrix(c("x","y", "x","y", "x",NA, "x","y", "x","y", "x","y", "x","y"), 2,7) colnames(s.prefs) <- c("A","B","C","D","E","F","G") c.prefs <- matrix(c("A","B","C","D","E","F","G", "A","B","C","D","E",NA,NA), 7,2) colnames(c.prefs) <- c("x","y") hri(s.prefs=s.prefs, c.prefs=c.prefs, nSlots=c(3,3)) ## 7 students, 3 colleges with 3 slots each, incomplete preferences: hri(nStudents=7, nSlots=c(3,3,3), seed=21, s.range=c(1,3)) ## -------------------- ## --- Summary plots ## 200 students, 200 colleges with 1 slot each res <- hri(nStudents=200, nColleges=200, seed=12) plot(res) plot(res, energy=TRUE) # }