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]) 

1. Item allocation algorithms, for both divisible and indivisible items;

2. Cake-cutting algorithms;

3. Various input formats, to easily use by both researchers and end-users;

4. Various output formats;

5. 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.

• other open-source projects related to fairness.