fairpy is an open-source library of fair division algorithms in Python.
** NOTE: fairpyx is a newer library, that provides cleaner handling of fair allocation with constraints, e.g. course-seat allocation. Please visit there first. **
fairpy is designed for three target audiences:
- Laypeople, who want to use existing fair division algorithms for real-life problems.
- Researchers, who develop new fair division algorithms and want to quickly implement them and compare to existing algorithms.
- Students, who want to trace the execution of algorithms to understand how they work.
clone https://github.com/erelsgl/fairpy.git
cd fairpy
pip install -r requirements.txt
pip install -e .
To verify that everything was installed correctly, run one of the example programs, e.g.
python examples/items.py
python examples/cake.py
or run the tests:
pytest
The function fairpy.divide can be used to activate all fair division algorithms. For example:
import fairpy
valuations = {"Alice": {"w":11,"x":22,"y":44,"z":0}, "George": {"w":22,"x":11,"y":66,"z":33}}
### Allocating indivisible items using the Iterated Maximum Matching algorithm:
fairpy.divide(algorithm=fairpy.items.iterated_maximum_matching, input=valuations)
### Allocating divisible goods using the leximin algorithm:
fairpy.divide(fairpy.items.leximin, valuations)
### Dividing a cake using cut-and-choose:
from fairpy import PiecewiseConstantAgent
Alice = PiecewiseConstantAgent([33,33], "Alice")
George = PiecewiseConstantAgent([11,55], "George")
fairpy.divide(algorithm=fairpy.cake.cut_and_choose.asymmetric_protocol, input=[George, Alice])
-
Item allocation algorithms, for both divisible and indivisible items;
-
Various input formats, to easily use by both researchers and end-users;
-
Optional logging, to learn and understand how the algorithms work.
To add a new algorithm for item allocation, write a function that accepts one of the following parameters:
- AgentList - a list of Agent objects. See e.g. the implementation of Round Robin for usage example.
- ValuationMatrix - a matrix v where v[i,j] is the value of agent i to item j. See e.g. the implementation of Leximin for usage example.
Your function may accept any other custom parameters.