# fairpyx
[](https://badge.fury.io/py/fairpyx)
`fairpyx` is a Python library containing various algorithms for fair allocation, with an emphasis on [Course allocation](https://en.wikipedia.org/wiki/Course_allocation). It 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
For the stable version:
pip install fairpyx
For the latest version:
pip install git+https://github.com/ariel-research/fairpyx.git
To verify that everything was installed correctly, run one of the example programs, e.g.
cd fairpyx
python examples/courses.py
python examples/input_formats.py
or run the tests:
pytest
## Usage
To activate a fair division algorithm, first construct a `fairpyx.instance`:
import fairpyx
valuations = {"Alice": {"w":11,"x":22,"y":44,"z":0}, "George": {"w":22,"x":11,"y":66,"z":33}}
instance = fairpyx.Instance(valuations=valuations)
An instance can have other fields, such as: agent capacities, item capacities, agent conflicts and item conflicts. These fields are used by some of the algorithms. See [instance.py](fairpyx/instance.py) for details.
Then, use the function `fairpyx.divide` to run an algorithm on the instance. For example:
allocation = fairpyx.divide(algorithm=fairpyx.algorithms.iterated_maximum_matching, instance=instance)
print(allocation)
## Features and Examples
1. [Course allocation algorithms](examples/courses.md);
1. [Various input formats](examples/input_formats.md), to easily use by both researchers and end-users;
## Contributing new algorithms
1. Fork `fairpyx` and install your fork locally as follows:
```
clone https://github.com/<your-username>/fairpyx.git
cd fairpyx
pip install -e .
```
2. Write a function that accepts a parameter of type `AllocationBuilder`, as well as any custom parameters your algorithm needs. The `AllocationBuilder` argument sent to your function is already initialized with an empty allocation. Your function has to modify this argument using the method `give`, which gives an item to an agent and updates the capacities. Your function need not return any value; the allocation is read from the modified parameter. See:
* [picking_sequence.py](fairpyx/algorithms/picking_sequence.py) and [iterated_maximum_matching.py](fairpyx/algorithms/iterated_maximum_matching.py) for examples of algorithms;
* [allocations.py](fairpyx/allocations.py) for more details on the `AllocationBuilder` object.
## See also
* [fairpy](https://github.com/erelsgl/fairpy) is an older library with the same goals. It contains more algorithms for fair item allocation, as well as algorithms for fair cake-cutting. `fairpyx` was created in order to provide a simpler interface, that also allows capacities and conflicts, which are important for fair course allocation.
* [Other open-source projects related to fairness](related.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/ariel-research/fairpyx",
"name": "fairpyx",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "fair division algorithms",
"author": "Erel Segal-Halevi",
"author_email": "erelsgl@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/29/0c/a0ab0f4157438829d90c93139eedf0f7d6da5c6630f613843191c3ad8a8d/fairpyx-0.0.4.tar.gz",
"platform": null,
"description": "# fairpyx\r\n\r\n\r\n[](https://badge.fury.io/py/fairpyx)\r\n\r\n`fairpyx` is a Python library containing various algorithms for fair allocation, with an emphasis on [Course allocation](https://en.wikipedia.org/wiki/Course_allocation). It is designed for three target audiences:\r\n\r\n* Laypeople, who want to use existing fair division algorithms for real-life problems.\r\n* Researchers, who develop new fair division algorithms and want to quickly implement them and compare to existing algorithms.\r\n* Students, who want to trace the execution of algorithms to understand how they work.\r\n\r\n## Installation\r\n\r\nFor the stable version:\r\n\r\n pip install fairpyx\r\n\r\nFor the latest version:\r\n\r\n pip install git+https://github.com/ariel-research/fairpyx.git\r\n\r\nTo verify that everything was installed correctly, run one of the example programs, e.g.\r\n\r\n cd fairpyx\r\n python examples/courses.py\r\n python examples/input_formats.py\r\n\r\nor run the tests:\r\n\r\n pytest\r\n\r\n## Usage\r\n\r\nTo activate a fair division algorithm, first construct a `fairpyx.instance`:\r\n\r\n import fairpyx\r\n valuations = {\"Alice\": {\"w\":11,\"x\":22,\"y\":44,\"z\":0}, \"George\": {\"w\":22,\"x\":11,\"y\":66,\"z\":33}}\r\n instance = fairpyx.Instance(valuations=valuations)\r\n\r\nAn instance can have other fields, such as: agent capacities, item capacities, agent conflicts and item conflicts. These fields are used by some of the algorithms. See [instance.py](fairpyx/instance.py) for details.\r\n\r\nThen, use the function `fairpyx.divide` to run an algorithm on the instance. For example:\r\n\r\n allocation = fairpyx.divide(algorithm=fairpyx.algorithms.iterated_maximum_matching, instance=instance)\r\n print(allocation)\r\n\r\n## Features and Examples\r\n\r\n1. [Course allocation algorithms](examples/courses.md);\r\n\r\n1. [Various input formats](examples/input_formats.md), to easily use by both researchers and end-users;\r\n\r\n\r\n## Contributing new algorithms\r\n\r\n1. Fork `fairpyx` and install your fork locally as follows:\r\n\r\n ```\r\n clone https://github.com/<your-username>/fairpyx.git\r\n cd fairpyx\r\n pip install -e .\r\n ```\r\n\r\n2. Write a function that accepts a parameter of type `AllocationBuilder`, as well as any custom parameters your algorithm needs. The `AllocationBuilder` argument sent to your function is already initialized with an empty allocation. Your function has to modify this argument using the method `give`, which gives an item to an agent and updates the capacities. Your function need not return any value; the allocation is read from the modified parameter. See:\r\n\r\n* [picking_sequence.py](fairpyx/algorithms/picking_sequence.py) and [iterated_maximum_matching.py](fairpyx/algorithms/iterated_maximum_matching.py) for examples of algorithms;\r\n* [allocations.py](fairpyx/allocations.py) for more details on the `AllocationBuilder` object.\r\n\r\n## See also\r\n\r\n* [fairpy](https://github.com/erelsgl/fairpy) is an older library with the same goals. It contains more algorithms for fair item allocation, as well as algorithms for fair cake-cutting. `fairpyx` was created in order to provide a simpler interface, that also allows capacities and conflicts, which are important for fair course allocation.\r\n* [Other open-source projects related to fairness](related.md).\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Fair division algorithms in Python",
"version": "0.0.4",
"project_urls": {
"Bug Reports": "https://github.com/ariel-research/fairpyx/issues",
"Documentation": "https://github.com/ariel-research/fairpyx",
"Homepage": "https://github.com/ariel-research/fairpyx",
"Source Code": "https://github.com/ariel-research/fairpyx"
},
"split_keywords": [
"fair",
"division",
"algorithms"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "96c96a7acda00e4bea2f74ebcde7365448cc2cb9a1ea3cc589ae5be413e3713d",
"md5": "e080c95d213b1c1bd7aa521d55ccf1fe",
"sha256": "b3380cef10a285d62b85daba3f3f04c68c26c63a01e8b6ae1bb0329aaa20e558"
},
"downloads": -1,
"filename": "fairpyx-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e080c95d213b1c1bd7aa521d55ccf1fe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 36945,
"upload_time": "2023-10-20T13:58:06",
"upload_time_iso_8601": "2023-10-20T13:58:06.389051Z",
"url": "https://files.pythonhosted.org/packages/96/c9/6a7acda00e4bea2f74ebcde7365448cc2cb9a1ea3cc589ae5be413e3713d/fairpyx-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "290ca0ab0f4157438829d90c93139eedf0f7d6da5c6630f613843191c3ad8a8d",
"md5": "3677e77db7598f40d2850cbc1f738c04",
"sha256": "363b23d40908e9c8ce623b052808470fabd05a7b03f7c50f50f6bd615182cf9f"
},
"downloads": -1,
"filename": "fairpyx-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "3677e77db7598f40d2850cbc1f738c04",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 33598,
"upload_time": "2023-10-20T13:58:07",
"upload_time_iso_8601": "2023-10-20T13:58:07.894045Z",
"url": "https://files.pythonhosted.org/packages/29/0c/a0ab0f4157438829d90c93139eedf0f7d6da5c6630f613843191c3ad8a8d/fairpyx-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-20 13:58:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ariel-research",
"github_project": "fairpyx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "fairpyx"
}
JSON
