abcvoting 2.16.0__tar.gz

abcvoting-2.16.0/.flake8

@@ -0,0 +1,15 @@
+[flake8]
+ignore = D202, W503, D103, D200, D105, D107, E203, D401, E731, FS003, PIE799
+exclude =
+    .git,
+    __pycache__,
+    docs/,
+    venv*,
+    scratch*,
+    benchmark,
+    */__init__.py,
+    .eggs,
+    .github,
+    build,
+max-complexity = 40
+max-line-length = 99

abcvoting-2.16.0/.github/codecov.yml

@@ -0,0 +1,33 @@
+codecov:
+  require_ci_to_pass: yes
+
+coverage:
+  precision: 2
+  round: down
+  range: "70...100"
+  status:
+    project:
+      default:
+        informational: true
+    patch:
+      default:
+        informational: true
+
+parsers:
+  gcov:
+    branch_detection:
+      conditional: yes
+      loop: yes
+      method: no
+      macro: no
+
+comment:
+  layout: "reach,diff,flags,files,footer"
+  behavior: default
+  require_changes: no
+
+ignore:
+    - "examples"
+    - "tests"
+    - "setup.py"
+    - "abcrules_mip.py"

abcvoting-2.16.0/.github/workflows/build.yml

@@ -0,0 +1,44 @@
+name: Build
+
+on:
+    # TODO Can we make this workflow depend on unittests to avoid building broken packages?
+    # As it seems: no, we cannot. At least not really. Jobs can depend on other jobs, but workflows
+    # cannot depend on other workflows. But jobs cannot be triggered by events, only workflows are
+    # triggered by events. That means we would need to run the build/upload job for every commit
+    # and every Python version and then check if it is the right Python version and if there is a
+    # new tag and only then really upload a package.
+    # The only additional advantage of this approach might be that we could test the package
+    # building process for every commit and every Python version comfortably.
+    #
+    # Note: building the package is also tested in unittests.yml.
+    #
+    # https://github.community/t/how-do-i-specify-job-dependency-running-in-another-workflow/16482/2
+    # https://docs.github.com/en/actions/learn-github-actions/managing-complex-workflows#creating-dependent-jobs
+    push:
+      tags:
+        - v*
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Upgrade pip and install build tools
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+
+    - name: Build a binary wheel and a source tarball
+      run: python -m build
+
+    - name: Publish distribution package to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        password: ${{ secrets.PYPI_API_TOKEN }}

abcvoting-2.16.0/.github/workflows/piptest.yml

@@ -0,0 +1,52 @@
+name: Unittests using abcvoting installed from pip, daily
+
+on:
+  schedule:
+    - cron: '0 5 * * *'  # every day at 5:00
+
+jobs:
+  unittests:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+      fail-fast: false
+
+    steps:
+      - name: get latest release with tag
+        id: latestrelease
+        run: |
+          echo "{releasetag}=$(curl -s https://api.github.com/repos/martinlackner/abcvoting/releases/latest | jq '.tag_name' | sed 's/\"//g')" >> $GITHUB_OUTPUT
+      - name: confirm release tag
+        run: |
+          echo ${{ steps.latestrelease.outputs.releasetag }}
+      - name: tagcheckout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.latestrelease.outputs.releasetag }}
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install setuptools
+          pip install abcvoting
+          pip install gmpy2
+          pip install ortools
+          pip install gurobipy
+          pip install pytest
+          pip install ortools
+
+      - name: Test with pytest
+        run: |
+          rm -r abcvoting
+          ls
+          echo $PYTHONPATH
+          export PYTHONPATH=$PYTHONPATH:$PWD
+          echo $PYTHONPATH
+          pytest -v --tb=long -m "not mip and (not gurobipy or not slow) and (not ortools or not slow) and not veryslow" -ra tests/

abcvoting-2.16.0/.github/workflows/piptestfull.yml

@@ -0,0 +1,40 @@
+name: Almost full unittests, weekly
+
+on:
+  schedule:
+    - cron: '0 20 * * Tue'  # every Tuesday
+
+jobs:
+  unittests:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # fetch all tags to be able to generate a version number for test packages
+          fetch-depth: 0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install setuptools
+          pip install -e .[dev]
+          pip install gmpy2
+          pip install ortools
+
+      - name: Test with pytest (full tests except Gurobi on large instances)
+        run: |
+          echo $PYTHONPATH
+          export PYTHONPATH=$PYTHONPATH:$PWD
+          echo $PYTHONPATH
+          pytest -v --tb=long -m "not mip and (not gurobipy or not slow) and not veryslow" -ra tests/

abcvoting-2.16.0/.github/workflows/unittests.yml

@@ -0,0 +1,95 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see:
+# https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Unittests
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+  workflow_dispatch:
+    branches: [ "master" ]
+
+jobs:
+  unittests:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+      fail-fast: false
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        # fetch all tags to be able to generate a version number for test packages
+        fetch-depth: 0
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install setuptools
+        pip install -e .[dev]
+        pip install gmpy2
+        pip install ortools
+
+        # these are optional requirements, but we want GLPK_MI to be installed to run more unitests
+        # TODO: cvxpy pip install is not working currently
+        # pip install cvxpy
+        # pip install cvxopt
+
+    # cvxpy is currently not used
+    #- name: Test if solver GLPK_MI is installed
+      # this is just a paranoia check, because unit tests won't fail, they would be silently skipped
+      # run: python -c "import cvxpy as cp; assert cp.GLPK_MI in cp.installed_solvers(), 'GLPKI_MI not installed'"
+
+    - name: Lint with flake8
+      run: |
+        pip install flake8
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+
+    - name: Check for correct black formatting
+      run: black --check .
+
+    - name: Test with pytest
+      run: |
+        coverage run --source=. -m pytest -v --tb=long -m "not mip and (not gurobipy or not slow) and (not ortools or not slow) and not veryslow" -ra tests/
+
+    - name: Generate coverage report
+      run: coverage xml
+
+    - name: Upload coverage metrics to codecov
+      uses: codecov/codecov-action@v4
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+    # tests the package, the release is done in build.yml
+    - name: Build a binary wheel and a source tarball
+      run: |
+        pip install build
+        python -m build
+      env:
+        # does not increment on re-run... :(
+        # this means this will fail in the last step, when uploading the same package again to PyPI
+        # because PyPI requires unique file names for uploaded packages
+        BUILD_NUMBER: ${{ github.run_number }}
+
+    # tests uploading the package to the test repo, but only if API_KEY is defined
+    - name: Publish distribution package to Test PyPI
+      env:
+        TEST_PYPI_API_TOKEN: ${{ secrets.TEST_PYPI_API_TOKEN }}
+      if: (env.TEST_PYPI_API_TOKEN != null) && (matrix.python-version == '3.8') && (github.ref == 'refs/heads/master')
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+        repository-url: https://test.pypi.org/legacy/

abcvoting-2.16.0/.gitignore

@@ -0,0 +1,88 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*.pyc
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.pytest_cache
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+Test Results*
+
+# Jupyter NB Checkpoints
+.ipynb_checkpoints/
+
+# VS Code
+.vscode/
+
+# Spyder
+.spyproject/
+
+# PyDev
+.pydevproject
+.project
+.settings
+
+# Mac OS-specific storage files
+.DS_Store
+
+# VIM
+*.swp
+*.swo
+
+# Pycharm
+.idea
+
+gurobi.log
+
+# LaTex
+*.log
+*.aux
+*.bbl
+*.bcf
+*.blg
+*.toc
+*.snm
+*.nav
+*.run.xml
+
+# Sphinx
+docs/_build
+
+# Other
+excluded
+*.cache
+venv*
+/coverage.sh
+scratchpad
+*_py.new
+benchmark

abcvoting-2.16.0/.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+repos:
+    - repo: https://github.com/psf/black
+      rev: 25.11.0
+      hooks:
+        - id: black
+          language_version: python3.12
+
+    -   repo: https://github.com/pycqa/flake8
+        rev: 7.3.0
+        hooks:
+        - id: flake8

abcvoting-2.16.0/.readthedocs.yaml

@@ -0,0 +1,26 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.10"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/requirements.txt
+

abcvoting-2.16.0/CITATION.cff

@@ -0,0 +1,24 @@
+cff-version: 1.2.0
+title: "abcvoting"
+message: >-
+  If you would like to acknowledge our work in a
+  scientific paper, please use the following citation:
+preferred-citation:
+  type: article
+  journal: "Journal of Open Source Software"
+  title: "abcvoting: A Python package for approval-based multi-winner voting rules"
+  volume: 8
+  issue: 81
+  start: 4880
+  year: 2023
+  doi: 10.21105/joss.04880
+  url: 'https://github.com/martinlackner/abcvoting'
+  authors:
+    - given-names: Martin
+      family-names: Lackner
+      orcid: 'https://orcid.org/0000-0003-2170-0770'
+    - given-names: Peter
+      family-names: Regner
+      orcid: 'https://orcid.org/0000-0001-8480-4900'
+    - given-names: Benjamin
+      family-names: Krenn

abcvoting-2.16.0/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Welcome to abcvoting
+
+Thank you for taking a closer look at our project! 
+
+We are very happy about all contributions! As this is a small project, 
+the best way to contribute is to simply get in contact with me (Martin Lackner, lackner@dbai.tuwien.ac.at) or to
+post an [issue](https://github.com/martinlackner/abcvoting/issues).
+
+Further comments:
+- Documentation is available at https://abcvoting.readthedocs.io/en/latest/.
+- If you would like to contribute but don't have a concrete idea, take a look the open [issues](https://github.com/martinlackner/abcvoting/issues) or
+contact me directly (Martin Lackner, lackner@dbai.tuwien.ac.at).
+- If you would like to contribute your favourite approval-based committee voting rules or axiom, you are very welcome to do so! 
+Take a look at [abcrules.py](https://github.com/martinlackner/abcvoting/blob/master/abcvoting/abcrules.py), where you find
+implementations of most standard rules. I am happy to help with integrating your new rule in the code (unit tests, etc.).
+- If you would like to contribute code, please clone the repository and make a pull request (PR) once you have a working version. 
+We can then discuss your code in detail. Feel free to get in touch before or while you are working on something.

abcvoting-2.16.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Martin Lackner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

abcvoting-2.16.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: abcvoting
+Version: 2.16.0
+Summary: A Python library of approval-based committee (ABC) rules
+Author-email: Martin Lackner <unexpected@sent.at>
+License: MIT License
+Project-URL: Homepage, https://github.com/martinlackner/abcvoting/
+Project-URL: Bug Tracker, https://github.com/martinlackner/abcvoting/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx[default]>=2.6.3
+Requires-Dist: ruamel.yaml>=0.17
+Requires-Dist: numpy>=1.21
+Requires-Dist: gurobipy>=11.0
+Requires-Dist: preflibtools>=2.0.12
+Requires-Dist: prefsampling>=0.1.19
+Requires-Dist: pabutools>=1.1.15
+Requires-Dist: pulp[open_py]>=3.2
+Provides-Extra: dev
+Requires-Dist: pytest>=6; extra == "dev"
+Requires-Dist: coverage[toml]>=5.3; extra == "dev"
+Requires-Dist: black==25.1; extra == "dev"
+Requires-Dist: flake8==7.3.0; extra == "dev"
+Requires-Dist: Sphinx>=7.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "dev"
+Requires-Dist: numpydoc>=1.5; extra == "dev"
+Requires-Dist: sphinx-codeautolink>=0.15; extra == "dev"
+Requires-Dist: matplotlib>=3.4.3; extra == "dev"
+Dynamic: license-file
+
+[![DOI](https://zenodo.org/badge/192713860.svg)](https://zenodo.org/badge/latestdoi/192713860)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.04880/status.svg)](https://doi.org/10.21105/joss.04880)
+[![PyPi](https://badgen.net/pypi/v/abcvoting)](https://pypi.org/project/abcvoting/)
+![Python versions](https://badgen.net/pypi/python/abcvoting)
+[![Build badge](https://github.com/martinlackner/abcvoting/workflows/Build/badge.svg)](https://github.com/martinlackner/abcvoting/actions)
+[![Unittests badge](https://github.com/martinlackner/abcvoting/workflows/Unittests/badge.svg)](https://github.com/martinlackner/abcvoting/actions)
+[![docs](https://readthedocs.org/projects/abcvoting/badge/?version=latest&style=plastic)](https://abcvoting.readthedocs.io/en/latest/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![codecov](https://codecov.io/gh/martinlackner/abcvoting/branch/master/graph/badge.svg)](https://codecov.io/gh/martinlackner/abcvoting)
+
+# abcvoting
+
+> [!NOTE]
+> - [**Documentation**](https://abcvoting.readthedocs.io/)
+> - [**Installation**](https://abcvoting.readthedocs.io/en/latest/installation.html)  
+> - [**How to cite the abcvoting library**](https://abcvoting.readthedocs.io/en/latest/howtocite.html)
+> - [**Acknowledgements and contributors**](https://abcvoting.readthedocs.io/en/latest/acks.html)
+> - [**► abcvoting web app**](https://pref.tools/abcvoting/)
+
+For an overview of other software tools related to Computational Social Choice, see the [COMSOC community page](https://comsoc-community.org/tools).
+
+## A Python library of approval-based committee (ABC) rules
+
+**A**pproval-**b**ased **c**ommittee rules (ABC rules) are voting methods for selecting a committee, i.e., a fixed-size subset of candidates.
+ABC rules are also known as approval-based multi-winner rules.
+The input of such rules are
+[approval ballots](https://en.wikipedia.org/wiki/Approval_voting#/media/File:Approval_ballot.svg).
+We recommend the book
+([Multi-Winner Voting with Approval Preferences](https://link.springer.com/book/10.1007/978-3-031-09016-5))
+by Lackner and Skowron [2] as a detailed introduction to ABC rules and related research directions.
+In addition, the
+[survey by Faliszewski et al.](http://research.illc.uva.nl/COST-IC1205/BookDocs/Chapters/TrendsCOMSOC-02.pdf) [1]
+is useful as a more general introduction to committee voting (not limited to approval ballots).
+
+The following ABC rules are implemented:
+
+* Approval Voting (AV)
+
+* Satisfaction Approval Voting (SAV)
+
+* Proportional Approval Voting (PAV)
+
+* Sequential Proportional Approval Voting (seq-PAV)
+
+* Reverse Sequential Proportional Approval Voting (revseq-PAV)
+
+* Approval Chamberlin-Courant (CC)
+
+* Phragmén's sequential rule
+
+* Monroe's rule
+
+* Minimax Approval Voting (MAV)
+
+* Greedy Monroe
+
+* Method of Equal Shares (Rule X)
+
+* Phragmén's First Method (Enestr&ouml;m's Method)
+
+* and many more ...
+
+In addition, one can verify axiomatic properties such as
+
+* Justified Representation (JR)
+
+* Propotional Justified Representation (PJR)
+
+* Extended Justified Representation (EJR)
+
+* Priceability
+
+* The core property
+
+Instead of using the abcvoting Python library, you can also use the 
+[**abcvoting web application**](https://pref.tools/abcvoting/) by Dominik Peters
+(which is based on this Python library).
+
+## Installation
+
+As simple as:
+
+```bash
+pip install abcvoting
+```
+
+Further details can be found [here](https://abcvoting.readthedocs.io/en/latest/installation.html).
+
+## Development
+
+Install all dependencies including development requirements and the abcvoting package in
+[development mode](https://setuptools.readthedocs.io/en/latest/userguide/development_mode.html):
+
+```bash
+pip install -e ".[dev]"
+```
+
+Basic unit tests can be run by excluding tests which require additional dependencies:
+
+```bash
+pytest  -m "not mip and not ortools and not gmpy2 and not slow" tests/
+```
+
+For development, configure the black formatter and pre-commit hooks - see below. Also installing
+all optional dependencies is recommended.
+
+A development package is build for every commit on the master branch and uploaded to the test
+instance of PyPI. It can be installed using the following command:
+
+```bash
+python3 -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple abcvoting
+```
+
+
+### Black formatting
+
+Code needs to be formatted using the [black formatter](https://black.readthedocs.io/en/stable/). This is
+checked by Github actions.
+[Configure your editor](https://black.readthedocs.io/en/stable/integrations/editors.html) to run the
+black formatter.
+
+### Pre-commit hooks
+
+Pre-commit hooks are not required, but they are recommended for development.
+[Pre-commit](https://pre-commit.com/) is used to manage and maintain pre-commit hooks. Install
+pre-commit (e.g. via apt, conda or pip) and then run `$ pre-commit install` to install the hooks.
+
+
+## References
+
+[1] Piotr Faliszewski, Piotr Skowron, Arkadii Slinko, and Nimrod Talmon. Multiwinner voting: A
+new challenge for social choice theory. In Ulle Endriss, editor, Trends in Computational Social
+Choice, chapter 2, pages 27–47. AI Access, 2017. http://research.illc.uva.nl/COST-IC1205/BookDocs/Chapters/TrendsCOMSOC-02.pdf
+
+[2] Lackner, Martin, and Piotr Skowron. "Multi-Winner Voting with Approval Preferences". 
+Springer International Publishing, SpringerBriefs in Intelligent Systems , 2023.
+https://link.springer.com/book/10.1007/978-3-031-09016-5
+
+<!--
+[2] Markus Brill, Rupert Freeman, Svante Janson and Martin Lackner. Phragmén's Voting Methods and Justified Representation. In Proceedings of the 31st AAAI Conference on Artificial Intelligence (AAAI 2017), pages 406-413, AAAI Press, 2017. https://arxiv.org/abs/2102.12305
+
+[3] Steven J Brams, D Marc Kilgour, and M Remzi Sanver. A minimax procedure for electing committees. Public Choice, 132(3-4):401–420, 2007.
+
+[4] Martin Lackner, Piotr Skowron.
+A Quantitative Analysis of Multi-Winner Rules. arXiv preprint arXiv:1801.01527. 2018. https://arxiv.org/abs/1801.01527
+
+[5] Properties of multiwinner voting rules.
+Edith Elkind, Piotr Faliszewski, Piotr Skowron, and Arkadii Slinko.
+Social Choice and Welfare volume 48, pages 599–632. 2017. https://link.springer.com/article/10.1007/s00355-017-1026-z
+
+[6] Peters, Dominik, and Piotr Skowron.
+Proportionality and the Limits of Welfarism. arXiv preprint arXiv:1911.11747. 2019. https://arxiv.org/abs/1911.11747
+
+-->