erelsgl / fairpy

An open-source library of fair division algorithms in Python

fairpy

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.

Installation

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

Usage

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

Features and Examples

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.

Adding new algorithms

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.

See also

• other open-source projects related to fairness.

fairpy's Issues

partitions_to_exactly_c expects collection to be type set

The function 'partitions_to_exactly_c' in partitions.py inside the 'indivisible' package expects to receive a set for collections and passes it on to 'partitions_to_at_most_c' which expects to receive a list,and in fact dose not work with a set.