Skip to content

Commit

Permalink
Doc for faster MES
Browse files Browse the repository at this point in the history
  • Loading branch information
@Simon-Rey
Simon-Rey committed Oct 24, 2023
1 parent 1f3f2a8 commit a905f52
Show file tree
Hide file tree
Showing 4 changed files with 57 additions and 24 deletions.
26 changes: 19 additions & 7 deletions docs-source/source/usage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -729,11 +729,20 @@ measure provided. For more details, see the `equalshares.net <https://equalshare
resoluteness=False
)
Two important shortcuts are also defined by defaults for MES:
MES can significantly under-use the budget. The idea of running the rule for different
initial budget for the voters has been proposed in the scientific literature as a fix
for that problem. The next section will present general methods to do so. For optimal
performances, one should use the following:

* :py:func:`~pabutools.rules.mes.mes_iterated`: corresponds to the method of equal shares used together with the exhaustion method by budget iteration (see :py:func:`~pabutools.rules.exhaustion.exhaustion_by_budget_increase`);
.. code-block:: python
outcome = method_of_equal_shares(
instance,
profile.as_multiprofile(), # Faster in general (typically if ballots repeat each others)
sat_class=Cost_Sat,
voter_budget_increment=1 # As soon as not-None, mes iterated is used
)
* :py:func:`~pabutools.rules.mes.mes_iterated_completed`: completes the result of the method from the previous bullet point with the outcome of the greedy method (see :py:func:`~pabutools.rules.exhaustion.completion_by_rule_combination`).
Exhaustion Methods
^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -815,6 +824,9 @@ method (which only does something if the outcome is not already exhaustive).
],
)
Remember that for MES specifically, it is much faster to use the `voter_budget_increment`
parameter directly to obtain the iterated version.

Rule Composition
^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -854,7 +866,7 @@ the following:
from pabutools.election import Instance, Project, ApprovalProfile, ApprovalBallot
from pabutools.election import Cost_Sat, Cardinality_Sat
from pabutools.rules import greedy_utilitarian_welfare, method_of_equal_shares
from pabutools.rules import exhaustion_by_budget_increase, popularity_comparison
from pabutools.rules import completion_by_rule_combination, popularity_comparison
p = [Project("p" + str(i), 1) for i in range(10)]
instance = Instance(p, budget_limit=5)
Expand All @@ -869,11 +881,11 @@ the following:
return completion_by_rule_combination(
instance,
profile,
[exhaustion_by_budget_increase, greedy_utilitarian_welfare],
[method_of_equal_shares, greedy_utilitarian_welfare],
[
{
"rule": method_of_equal_shares,
"rule_params": {"sat_class": Cost_Sat},
"sat_class": Cost_Sat,
"voter_budget_increment": 1,
},
{"sat_class": Cost_Sat},
],
Expand Down
26 changes: 19 additions & 7 deletions docs/_sources/usage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -729,11 +729,20 @@ measure provided. For more details, see the `equalshares.net <https://equalshare
resoluteness=False
)
Two important shortcuts are also defined by defaults for MES:
MES can significantly under-use the budget. The idea of running the rule for different
initial budget for the voters has been proposed in the scientific literature as a fix
for that problem. The next section will present general methods to do so. For optimal
performances, one should use the following:

* :py:func:`~pabutools.rules.mes.mes_iterated`: corresponds to the method of equal shares used together with the exhaustion method by budget iteration (see :py:func:`~pabutools.rules.exhaustion.exhaustion_by_budget_increase`);
.. code-block:: python
outcome = method_of_equal_shares(
instance,
profile.as_multiprofile(), # Faster in general (typically if ballots repeat each others)
sat_class=Cost_Sat,
voter_budget_increment=1 # As soon as not-None, mes iterated is used
)
* :py:func:`~pabutools.rules.mes.mes_iterated_completed`: completes the result of the method from the previous bullet point with the outcome of the greedy method (see :py:func:`~pabutools.rules.exhaustion.completion_by_rule_combination`).
Exhaustion Methods
^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -815,6 +824,9 @@ method (which only does something if the outcome is not already exhaustive).
],
)
Remember that for MES specifically, it is much faster to use the `voter_budget_increment`
parameter directly to obtain the iterated version.

Rule Composition
^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -854,7 +866,7 @@ the following:
from pabutools.election import Instance, Project, ApprovalProfile, ApprovalBallot
from pabutools.election import Cost_Sat, Cardinality_Sat
from pabutools.rules import greedy_utilitarian_welfare, method_of_equal_shares
from pabutools.rules import exhaustion_by_budget_increase, popularity_comparison
from pabutools.rules import completion_by_rule_combination, popularity_comparison
p = [Project("p" + str(i), 1) for i in range(10)]
instance = Instance(p, budget_limit=5)
Expand All @@ -869,11 +881,11 @@ the following:
return completion_by_rule_combination(
instance,
profile,
[exhaustion_by_budget_increase, greedy_utilitarian_welfare],
[method_of_equal_shares, greedy_utilitarian_welfare],
[
{
"rule": method_of_equal_shares,
"rule_params": {"sat_class": Cost_Sat},
"sat_class": Cost_Sat,
"voter_budget_increment": 1,
},
{"sat_class": Cost_Sat},
],
Expand Down
2 changes: 1 addition & 1 deletion docs/searchindex.js
View file

Large diffs are not rendered by default.

27 changes: 18 additions & 9 deletions docs/usage.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -988,11 +988,18 @@ <h3>Method of Equal Shares (MES)<a class="headerlink" href="#method-of-equal-sha
<span class="p">)</span>
</pre></div>
</div>
<p>Two important shortcuts are also defined by defaults for MES:</p>
<ul class="simple">
<li><p><a class="reference internal" href="reference/rules/index.html#pabutools.rules.mes.mes_iterated" title="pabutools.rules.mes.mes_iterated"><code class="xref py py-func docutils literal notranslate"><span class="pre">mes_iterated()</span></code></a>: corresponds to the method of equal shares used together with the exhaustion method by budget iteration (see <a class="reference internal" href="reference/rules/index.html#pabutools.rules.exhaustion.exhaustion_by_budget_increase" title="pabutools.rules.exhaustion.exhaustion_by_budget_increase"><code class="xref py py-func docutils literal notranslate"><span class="pre">exhaustion_by_budget_increase()</span></code></a>);</p></li>
<li><p><a class="reference internal" href="reference/rules/index.html#pabutools.rules.mes.mes_iterated_completed" title="pabutools.rules.mes.mes_iterated_completed"><code class="xref py py-func docutils literal notranslate"><span class="pre">mes_iterated_completed()</span></code></a>: completes the result of the method from the previous bullet point with the outcome of the greedy method (see <a class="reference internal" href="reference/rules/index.html#pabutools.rules.exhaustion.completion_by_rule_combination" title="pabutools.rules.exhaustion.completion_by_rule_combination"><code class="xref py py-func docutils literal notranslate"><span class="pre">completion_by_rule_combination()</span></code></a>).</p></li>
</ul>
<p>MES can significantly under-use the budget. The idea of running the rule for different
initial budget for the voters has been proposed in the scientific literature as a fix
for that problem. The next section will present general methods to do so. For optimal
performances, one should use the following:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">outcome</span> <span class="o">=</span> <span class="n">method_of_equal_shares</span><span class="p">(</span>
<span class="n">instance</span><span class="p">,</span>
<span class="n">profile</span><span class="o">.</span><span class="n">as_multiprofile</span><span class="p">(),</span> <span class="c1"># Faster in general (typically if ballots repeat each others)</span>
<span class="n">sat_class</span><span class="o">=</span><span class="n">Cost_Sat</span><span class="p">,</span>
<span class="n">voter_budget_increment</span><span class="o">=</span><span class="mi">1</span> <span class="c1"># As soon as not-None, mes iterated is used</span>
<span class="p">)</span>
</pre></div>
</div>
</section>
<section id="exhaustion-methods">
<h3>Exhaustion Methods<a class="headerlink" href="#exhaustion-methods" title="Permalink to this heading">#</a></h3>
Expand Down Expand Up @@ -1066,6 +1073,8 @@ <h3>Exhaustion Methods<a class="headerlink" href="#exhaustion-methods" title="Pe
<span class="p">)</span>
</pre></div>
</div>
<p>Remember that for MES specifically, it is much faster to use the <cite>voter_budget_increment</cite>
parameter directly to obtain the iterated version.</p>
</section>
<section id="rule-composition">
<h3>Rule Composition<a class="headerlink" href="#rule-composition" title="Permalink to this heading">#</a></h3>
Expand Down Expand Up @@ -1100,7 +1109,7 @@ <h3>Rule Composition<a class="headerlink" href="#rule-composition" title="Permal
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">pabutools.election</span> <span class="kn">import</span> <span class="n">Instance</span><span class="p">,</span> <span class="n">Project</span><span class="p">,</span> <span class="n">ApprovalProfile</span><span class="p">,</span> <span class="n">ApprovalBallot</span>
<span class="kn">from</span> <span class="nn">pabutools.election</span> <span class="kn">import</span> <span class="n">Cost_Sat</span><span class="p">,</span> <span class="n">Cardinality_Sat</span>
<span class="kn">from</span> <span class="nn">pabutools.rules</span> <span class="kn">import</span> <span class="n">greedy_utilitarian_welfare</span><span class="p">,</span> <span class="n">method_of_equal_shares</span>
<span class="kn">from</span> <span class="nn">pabutools.rules</span> <span class="kn">import</span> <span class="n">exhaustion_by_budget_increase</span><span class="p">,</span> <span class="n">popularity_comparison</span>
<span class="kn">from</span> <span class="nn">pabutools.rules</span> <span class="kn">import</span> <span class="n">completion_by_rule_combination</span><span class="p">,</span> <span class="n">popularity_comparison</span>

<span class="n">p</span> <span class="o">=</span> <span class="p">[</span><span class="n">Project</span><span class="p">(</span><span class="s2">&quot;p&quot;</span> <span class="o">+</span> <span class="nb">str</span><span class="p">(</span><span class="n">i</span><span class="p">),</span> <span class="mi">1</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">)]</span>
<span class="n">instance</span> <span class="o">=</span> <span class="n">Instance</span><span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="n">budget_limit</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
Expand All @@ -1115,11 +1124,11 @@ <h3>Rule Composition<a class="headerlink" href="#rule-composition" title="Permal
<span class="k">return</span> <span class="n">completion_by_rule_combination</span><span class="p">(</span>
<span class="n">instance</span><span class="p">,</span>
<span class="n">profile</span><span class="p">,</span>
<span class="p">[</span><span class="n">exhaustion_by_budget_increase</span><span class="p">,</span> <span class="n">greedy_utilitarian_welfare</span><span class="p">],</span>
<span class="p">[</span><span class="n">method_of_equal_shares</span><span class="p">,</span> <span class="n">greedy_utilitarian_welfare</span><span class="p">],</span>
<span class="p">[</span>
<span class="p">{</span>
<span class="s2">&quot;rule&quot;</span><span class="p">:</span> <span class="n">method_of_equal_shares</span><span class="p">,</span>
<span class="s2">&quot;rule_params&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;sat_class&quot;</span><span class="p">:</span> <span class="n">Cost_Sat</span><span class="p">},</span>
<span class="s2">&quot;sat_class&quot;</span><span class="p">:</span> <span class="n">Cost_Sat</span><span class="p">,</span>
<span class="s2">&quot;voter_budget_increment&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>
<span class="p">},</span>
<span class="p">{</span><span class="s2">&quot;sat_class&quot;</span><span class="p">:</span> <span class="n">Cost_Sat</span><span class="p">},</span>
<span class="p">],</span>
Expand Down

0 comments on commit a905f52

Please sign in to comment.