3.9 KiB
bibliography: REFERENCES.bib ...
Carousel
A simple Stable Matching Solver.
carousel is a solver for the
Envy-free
Stable matching problem based on some naive modifications to the
Gale-Shapley Algorithm, written in Python.
Algorithms
Gale-Shapley Deferred Acceptance
The most basic versions of the stable matching problem was outlined and solved by [@gale&shapley1962].
TODO
Usage
Using carousel is pretty simple once it's set up: given some input rankings, and some post-selection criteria
the program should generate a landscape of valid matching solutions for you to choose from (and can generate more on request).
Installation, Setup, Dependencies & Tooling
There are a number of ways to guarantee you have the required dependencies to run carousel.
The most complete method is using uv (with nix and direnv), but a plain/more barebones setup using venv is also possible.
Setup and run with uv
carousel was developed using the the uv package and project manager.
TODO
Raw setup with venv
It's possible to only use only default Python tooling, if so desired, via the
venv module.
TODO
Convenience direnv and nix environment management.
TODO
Matching: Input & Output
All input table formats supported by polars are supported by carousel.
Input data should be in one of three forms:
Preferences
Preferences enumerate by-name some preferences in descending order, e.g. the fruit preferences of Alice, Bob and Charlie are:
| Alice | Bob | Charlie |
|---|---|---|
| apple | banana | cherry |
| cherry | apple | banana |
| banana | cherry | apple |
where for e.g. Alice prefers apples to cherries (so they appear higher in her preferences).
Rankings
Rankings are like preferences, but are numerically ordered against a list of things; e.g. Alice, Bob and Charlie rank the fruit apples, bananas and cherries as:
| fruit | Alice | Bob | Charlie |
|---|---|---|---|
| apple | 1 | 2 | 3 |
| banana | 3 | 1 | 2 |
| cherry | 2 | 3 | 1 |
Ranking Matrix
In order to perform a matching, carousel either needs a pair of preferences
(e.g. a set of doctor's preferences for residencies, and a set of residencies' preferences for doctors),
a pair of corresponding rankings, or a matrix encoding both rankings at once:
| names | Alice | Bob | Charlie |
|---|---|---|---|
| Baylor | (1, 3) | (2, 2) | (3, 1) |
| CaseMed | (3, 2) | (1, 1) | (2, 3) |
| Emory | (2, 1) | (3, 3) | (1, 2) |
Matching
A matching is a table whose rows list the applicants matched to each reviewer e.g. a matching from the med-school ranking matrix in the previous section might look like
| Baylor | CaseMed | Emory |
|---|---|---|
| Alice | Bob | Charlie |
None |
Daina | None |
Assignments
An assignment is a table whose row lists which reviewer each applicant was matched to. e.g.
| Alice | Bob | Charlie | Daina |
|---|---|---|---|
| Baylor | CaseMed | Emory | CaseMed |
TODO check/make stable.
TODO matching more people per school e.g.
Matching: Post-Selection
It's often desirable to enforce additional criteria on solutions that are not well-posed within the core optimization problem. Since the solver itself is stochastic, these are often most easily implemented by a post-selection.
Examples
Here are some usage examples:
Departmental TA Assignments
TODO
Caltech Housing Rotation
TODO
References
See REFERENCES.bib
[1]:
TODO