sync

README.md

@@ -3,7 +3,7 @@ bibliography: REFERENCES.bib
 ...
 
 # Carousel
-*A simple Stable Matching Solver.*
+*A simple Stable Matching solver.*
 
 `carousel` is a solver for the 
 [Envy-free](https://en.wikipedia.org/wiki/Envy-free_matching)
@@ -14,30 +14,29 @@ bibliography: REFERENCES.bib
 
 ### Gale-Shapley Deferred Acceptance
 
-The most basic version(s) of the stable matching problem was outlined and solved in [@gale&shapley1962] and won Shapley the 
-[2012 Nobel Prize in Economics](https://www.nobelprize.org/prizes/economic-sciences/2012/popular-information/).
+- Gives a solution to the basic problem.
 
-The basic problem being solved is as follows:
+### GS + Rotation Enumeration of Solutions
 
-#### Stable Marriage Problem
-The "Stable Marriage problem" TODO
+- Can implement post-selection measures/constraints/criteria.
 
-TODO
+### Integer Programming (Huang++)
 
-#### College Admissions Problem 
-Solving the stable marriage problem also provides a solution to the "College Admissions Problem", 
-with just a little more work.
+### Polytope Solution Sampling (Large Problems)
 
-TODO
+### Brute-Force Combinatoric Search
+A benchmark/testbed implementation. Beware.
+
+### More?
+Contribute!
 
 ## Data - Input/Output
 All [input table formats supported by `polars`](https://docs.pola.rs/user-guide/io/) 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 three forms:
+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, 
@@ -61,10 +60,13 @@ e.g. Alice, Bob and Charlie rank the fruit apples, bananas and cherries as:
 | 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, *or* a matrix encoding both rankings at once:
+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   |
 |---------|------------|---------|-----------|
@@ -72,6 +74,25 @@ a pair of corresponding rankings, *or* a matrix encoding both rankings at once:
 | 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
@@ -112,6 +133,9 @@ using the [pages.uoregon.edu CGI feature](https://service.uoregon.edu/TDClient/2
 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
@@ -141,13 +165,13 @@ TODO
 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.
+by a post-selection on a sampling of solutions.
 
 
 ## Examples
 Here are some usage examples:
 
-### Departmental TA Assignments
+### University of Oregon Physics Department Graduate TA Assignments
 TODO
 
 ### Caltech Housing Rotation