Skip to main content

Py-school-match, a Python package that implements matching algorithms for the student-to-school assignation problem.

Project description


Py-school-match is an open-source Python package that implements multiple matching algorithms in order to assign students to schools.

It provides multiple algorithms ready to use:

  • Top Trading Cycles (TTC)

  • Deferred acceptance with multiple tie-breaking (DAMTB)

  • Deferred acceptance with single tie-breaking (DASTB)

  • Stable improvement cycles (SIC)

  • Deferred Acceptance with multiple tie-breaking, plus stable cycles (MSIC)

  • Deferred Acceptance with single tie-breaking, plus non-stable cycles (NSIC)

Py-school-match is designed specifically for the student-to-school assignation problem. Because of this, you can focus on evaluating different settings and algorithms, without the need to adapt or develop a complete solution.

Sample code

import py_school_match as psm

# Creating three students.
st0 = psm.Student()
st1 = psm.Student()
st2 = psm.Student()

# Creating a criteria. This means 'vulnerable' is now a boolean.
vulnerable = psm.Criteria('vulnerable', bool)

# Assigning st1 as vulnerable
student_vulnerable = psm.Characteristic(vulnerable, True)

# Creating three schools, each with one seat available.
sc0 = psm.School(1)
sc1 = psm.School(1)
sc2 = psm.School(1)

# Defining preferences (from most desired to least desired)
st0.preferences = [sc0, sc1, sc2]
st1.preferences = [sc0, sc2, sc1]
st2.preferences = [sc2, sc1, sc0]

# Creating a lists with the students and schools defined above.
schools = [sc0, sc1, sc2]
students = [st0, st1, st2]

# Defining a ruleset
ruleset = psm.RuleSet()

# Defining a new rule from the criteria above.
rule_vulnerable = psm.Rule(vulnerable)

# Adding the rule to the ruleset. This means that a 'vulnerable' student has a higher priority.
# Note that rules are added in order (from higher priority to lower priority)

# Creating a social planner using the objects above.
planner = psm.SocialPlanner(students, schools, ruleset)

# Selecting an algorithm
algorithm = psm.SIC()

# Running the algorithm.

# inspecting the obtained assignation
for student in students:
    print("Student {} was assigned to School {}".format(,



  • graph-tool (>= 2.27)

User installation

pip install py-school-match

Or you can clone the repo and install it:

git clone
cd py-school-match
python install

Remember to first install graph-tool.


Contributions are more than welcome. Feel free to open an issue or contact me!
Remember that this package does not provide ANY WARRANTY OF ANY KIND.

How to cite?

Insert citation here.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

py-school-match-0.2.0.tar.gz (15.3 kB view hashes)

Uploaded source

Built Distribution

py_school_match-0.2.0-py2-none-any.whl (28.5 kB view hashes)

Uploaded py2

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page