---

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

• Gives a solution to the basic problem.

GS + Rotation Enumeration of Solutions

• Can implement post-selection measures/constraints/criteria.

Integer Programming (Huang++)

Polytope Solution Sampling (Large Problems)

Brute-Force Combinatoric Search

A benchmark/testbed implementation. Beware.

More?

Contribute!

Data - Input/Output

All input table formats supported by polars are supported by carousel (csv, excel, json to name a few), which accepts a few inter-related tabular schemes for the input/output data.

Input

Input describes the preferences/rankings of the "applicants" of "reviewers" to which they will be matched (possibly many-to-one, as in the "College Admission Problem"), as well as the preferences/rankings for the reviwers of applicants. Input should be in one of two 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

Intermediate

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. A ranking matrix is a concise way to express a pair of rankings - used to display rankings:

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)

Priorities

Internally, preferences/rankings are often serialized to rows as a priority listing of the form:

App.	Rank	Rev
Alice	1	apple
Alice	2	cherry
Alice	3	banana
Bob	1	banana
Bob	2	apple
Bob	3	cherry
Charlie	1	cherry
Charlie	2	banana
Charlie	3	apple

(in no specific row order). This is not a supported input format in the frontends, but may be relevant when interacting with the package programmatically - priorities can be followed as edges in a graph.

Output

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.

Usage

There are 4 main ways to use Carousel:

UO Pages Server - CGI Form

An HTML form submission interface is hosted at

https://pages.uoregon.edu/tgorordo/forms/carousel.html

using the pages.uoregon.edu CGI feature.

Submit your applicant and reviewer preferences in tabular form, or as excel uploads and the server will return a table of matches for you to choose from.

This resource has very limited compute, so excessive usage might result in limitations or restricted access. Try not to ruin a good thing! A moderate number of problems on the scale of those in the Examples section below should be sustainable.

Command Line Binary

TODO

GUI Binary

TODO

Python Library/Development

If you prefer to invoke carousel directly (or incorporate it as a library into another script) in a python environment instead of using any of the bundled/released versions of the program described above (or wish to reproduce those bundles), you can do so using the uv environment/package/project manager or a raw python virtual environment using the venv module (if you need an intro to python venvs see this page).

Some extra command-line development conveniences are available if you use the tools:

• just is a taskrunner that can execute the provided justfile of some common useful commands.
• direnv with nix (shell) can guarantee minimal development tooling without polluting your broader environment. i.e. they can auto-install and run all of carousel's tooling in an environment specific to your development directory.

but everything provided by these tools can also be done using more standard/default shell tooling. uv as your package/environment manager is highly recommended, however.

TODO

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 to some extent, these are often most easily implemented by a post-selection on a sampling of solutions.

Examples

Here are some usage examples:

University of Oregon Physics Department Graduate TA Assignments

TODO

Caltech Housing Rotation

TODO

References

See REFERENCES.bib

[1]:

TODO