Implement Exact Equal Shares with add-opt rule and enhance logging

[yonatang8675]

Summary

This PR adds an implementation of Exact Equal Shares (EES) and the add-opt completion procedure from Streamlining Equal Shares by Kraiczy, Robinson, and Elkind.

The new rule implementation lives in pabutools.rules.ees_addopt and includes:

• exact_equal_shares, implementing EES for uniform utilities
• EESAllocationDetails, storing per-voter payments for an EES run
• get_leftover_budgets, computing each voter's remaining budget
• get_leximax_payment, computing leximax payment vectors
• greedy_project_change, implementing GreedyProjectChange
• add_opt, computing the minimum per-voter budget increase certifying instability
• ees_add_opt_completion, completing EES by iteratively increasing the virtual budget via add-opt

The public rule exports are also updated so the main EES/add-opt API can be imported from pabutools.rules.

What Changed

EES/add-opt implementation

Adds pabutools/rules/ees_addopt.py, including:

• Exact Equal Shares selection with per-voter budget tracking
• Payment details attached to returned BudgetAllocation objects
• Lexicographic tie-breaking for stable project selection
• Helpers for leftover budgets and leximax payment vectors
• GreedyProjectChange and add-opt routines
• EES completion by repeated virtual-budget increases
• Logging throughout the EES/add-opt workflow

Public API

Updates pabutools/rules/__init__.py to export:

• exact_equal_shares
• greedy_project_change
• add_opt
• EESAllocationDetails

Tests

Adds tests/rules/test_ees_addopt.py with coverage for:

• Basic EES behavior
• Empty and infeasible instances
• Equal cost splitting and payment details
• Leftover budget computation
• Leximax payment ordering
• GreedyProjectChange behavior
• add-opt improvements
• Randomized EES/GPC/rerun validity checks
• EES add-opt completion examples and feasibility guarantees

[Simon-Rey]

Hello, thank you for your submission. I will soon look at it in more details. For now at least, can you please only include the code for ees and the tests? Your experiments and your examples do not need to be included in the package.

[Simon-Rey]

The package uses unittest for the tests, can you please switch your code to it? :)