{"id":31211481,"url":"https://github.com/cyberagentailab/fairreciprocalrecommendation","last_synced_at":"2025-09-21T05:27:17.134Z","repository":{"id":253762243,"uuid":"842849308","full_name":"CyberAgentAILab/FairReciprocalRecommendation","owner":"CyberAgentAILab","description":"This repository contains the algorithms and synthetic data generation codes used in the experimental section of the paper 'Fair Reciprocal Recommendation in Matching Markets' by Yoji Tomita and Tomohiko Yokoyama, RecSys2024.","archived":false,"fork":false,"pushed_at":"2025-09-05T04:57:24.000Z","size":45,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-10T19:51:03.866Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CyberAgentAILab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-15T08:19:19.000Z","updated_at":"2025-09-05T04:57:29.000Z","dependencies_parsed_at":"2024-08-19T11:25:31.798Z","dependency_job_id":null,"html_url":"https://github.com/CyberAgentAILab/FairReciprocalRecommendation","commit_stats":null,"previous_names":["cyberagentailab/fairreciprocalrecommendation"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CyberAgentAILab/FairReciprocalRecommendation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyberAgentAILab%2FFairReciprocalRecommendation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyberAgentAILab%2FFairReciprocalRecommendation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyberAgentAILab%2FFairReciprocalRecommendation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyberAgentAILab%2FFairReciprocalRecommendation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CyberAgentAILab","download_url":"https://codeload.github.com/CyberAgentAILab/FairReciprocalRecommendation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyberAgentAILab%2FFairReciprocalRecommendation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276195621,"owners_count":25601151,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-21T02:00:07.055Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-21T05:27:13.453Z","updated_at":"2025-09-21T05:27:17.121Z","avatar_url":"https://github.com/CyberAgentAILab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fair Reciprocal Recommendation in Matching Markets\n\nThis repository contains the algorithms and synthetic data generation codes used in the experimental sections of the following papers:\n- [1] Yoji Tomita and Tomohiko Yokoyama. 2024. \"[Fair Reciprocal Recommendation in Matching Markets.](https://dl.acm.org/doi/10.1145/3640457.3688130)\" Proceedings of the 18th ACM Conference on Recommender Systems (RecSys'24).\n- [2] Yoji Tomita and Tomohiko Yokoyama. 2025. \"Balancing Fairness and High Match Rates in Reciprocal Recommender Systems: A Nash Social Welfare Approach.\" Working Paper.\n\n## Requirements\n\nIf you can use [Rye](https://github.com/astral-sh/rye), you can set up the environment just by running the following command:\n```\nrye sync\n```\n\nIf you need to set up the Python environment manually, we require the followings:\n- Python \u003e= 3.9\n- numpy \u003e= 2.0.1\n- cvxpy \u003e= 1.5.2\n- jupyter \u003e= 1.0.0\n- torch \u003e= 2.8.0\n\n## Files\n\nIn the [`src`](https://github.com/CyberAgentAILab/FairReciprocalRecommendation/tree/main/src) directory, there are the following files:\n\n - `market.py`: The class definition of the matching markets, including the synthetic preference data generation and the checking function of the envy-freeness.\n - `utils.py`: The utility functions.\n - `naive.py`: The algorithm for the naive method (baseline).\n - `prod.py`: The algorithm for the prod method (baseline).\n - `tu_matching.py`: The algorithm for the TU-matching method (baseline).\n - `iter_lp.py`: The algorithm for the iterative LP method (baseline).\n - `alternate_fw.py`\n   - `sw_maximize`: The alogirhtm for the SW maximization via the alternate Frank-Wolfe method (proposed in Section 3 of Tomita and Yokoyama [1]).\n   - `nsw_maximize`: The alogirhtm for the NSW maximization via the alternate Frank-Wolfe method (proposed in Section 4 of Tomita and Yokoyama [1]).\n   - `alpha_sw_maximize`: The algorithm for the α-SW maximization method (proposed in Section 6 of Tomita and Yokoyama [2]).\n - `alternate_fw_sinkhorn`\n   - `sw_sinkhorn` : The approximate algorithm for the SW maximization via the Sinkhorn algorithm (proposed in Section 7 of Tomita and Yokoyama [2]).\n   - `nsw_sinkhorn`: The approximate algorithm for the NSW maximization via the Sinkhorn algorithm (proposed in Section 7 of Tomita and Yokoyama [2]).\n - `experiments.py`: Conduct synthetic data experiments (Section 5.1 of Tomita and Yokoyama [1], Section 8.2-8.4 of Tomita and Yokoyama [2]).\n\n## Example Usage\n```\ncd src\n```\n```python\nfrom market import Market\nfrom alternate_fw import nsw_maximize\n\n# Make a market with 30 left agents and 20 right agents, and generate preferences\nmkt = Market(num_left=30, num_right=20)\nmkt.generate_preferences(pref_seed=0)\n\n# Run the NSW maximization algorithm\npolicy_for_left, policy_for_right = nsw_maximize(mkt.pref_left_to_right, mkt.pref_right_to_left, mkt.v_left, mkt.v_right)\n\n# Compute the matching probabilities and check the envy-freeness\nmatch_prob = mkt.get_match_prob(policy_for_left, policy_for_right)\nprint(\"Expected number of matches:\", match_prob.sum())\nenvy = mkt.check_envy(policy_for_left, policy_for_right, match_prob=match_prob)\nprint(\"Number of envies for left agents:\", len(envy[\"left\"]))\nprint(\"Number of envies for right agents:\", len(envy[\"right\"]))\n```\nFor more detailed examples, see:\n - [`notebooks/example.ipynb`](https://github.com/CyberAgentAILab/FairReciprocalRecommendation/blob/main/notebooks/example.ipynb) for basic usages of the proposed algorithms.\n - [`notebooks/experiments.ipynb`](https://github.com/CyberAgentAILab/FairReciprocalRecommendation/blob/main/notebooks/experiments.ipynb) for the synthetic data experiments.\n\n## Citations\n- Yoji Tomita and Tomohiko Yokoyama. 2024. \"[Fair Reciprocal Recommendation in Matching Markets.](https://dl.acm.org/doi/10.1145/3640457.3688130)\" Proceedings of the 18th ACM Conference on Recommender Systems (RecSys'24).\n  ```\n  @inproceedings{tomita2024fair,\n    title={Fair Reciprocal Recommendation in Matching Markets},\n    author={Tomita, Yoji and Yokoyama, Tomohiko},\n    booktitle={Proceedings of the 18th ACM Conference on Recommender Systems},\n    pages={209--218},\n    year={2024}\n  }\n  ```\n- Yoji Tomita and Tomohiko Yokoyama. 2025. \"Balancing Fairness and High Match Rates in Reciprocal Recommender Systems: A Nash Social Welfare Approach.\" Working Paper.\n  ```\n  @unpublished{tomita2025balancing,\n    title={Balancing Fairness and High Match Rates in Reciprocal Recommender Systems: A Nash Social Welfare Approach},\n    author={Tomita, Yoji and Yokoyama, Tomohiko},\n    year={2025}\n  }\n  ```\n\n## License\nThis repository is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyberagentailab%2Ffairreciprocalrecommendation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyberagentailab%2Ffairreciprocalrecommendation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyberagentailab%2Ffairreciprocalrecommendation/lists"}