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.

Files for py-school-match, version 0.2.0
Filename, size File type Python version Upload date Hashes
Filename, size py_school_match-0.2.0-py2-none-any.whl (28.5 kB) File type Wheel Python version py2 Upload date Hashes View
Filename, size py-school-match-0.2.0.tar.gz (15.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page