Updated docs

COMSOC-Community · Oct 9, 2023 · ad77c0c · ad77c0c
1 parent 411dbd1
commit ad77c0c
Show file tree

Hide file tree

Showing 14 changed files with 336 additions and 72 deletions.
diff --git a/docs-source/source/reference/rules/index.rst b/docs-source/source/reference/rules/index.rst
@@ -11,6 +11,10 @@ Rules module
 
 .. autofunction:: pabutools.rules.mes.method_of_equal_shares
 
+.. autofunction:: pabutools.rules.mes.mes_iterated
+
+.. autofunction:: pabutools.rules.mes.mes_iterated_completed
+
 .. autofunction:: pabutools.rules.exhaustion.completion_by_rule_combination
 
 .. autofunction:: pabutools.rules.exhaustion.exhaustion_by_budget_increase

diff --git a/docs-source/source/usage.rst b/docs-source/source/usage.rst
@@ -671,8 +671,8 @@ previous two as it does not rely on a satisfaction measure.
         resoluteness=False
     )
 
-Method of Equal Shares
-^^^^^^^^^^^^^^^^^^^^^^
+Method of Equal Shares (MES)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The Method of Equal Shares is another rule that returns budget allocations based on the satisfaction
 measure provided. For more details, see the `equalshares.net <https://equalshares.net/>`_ website.
@@ -729,6 +729,12 @@ measure provided. For more details, see the `equalshares.net <https://equalshare
         resoluteness=False
     )
 
+Two important shortcuts are also defined by defaults for MES:
+
+* :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`);
+
+* :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
 ^^^^^^^^^^^^^^^^^^
 

diff --git a/docs/_modules/index.html b/docs/_modules/index.html
@@ -254,8 +254,7 @@ <h1></h1>
                 <article class="bd-article" role="main">
 
   <h1>All modules for which code is available</h1>
-<ul><li><a href="collections.html">collections</a></li>
-<li><a href="pabutools/analysis/category.html">pabutools.analysis.category</a></li>
+<ul><li><a href="pabutools/analysis/category.html">pabutools.analysis.category</a></li>
 <li><a href="pabutools/analysis/instanceproperties.html">pabutools.analysis.instanceproperties</a></li>
 <li><a href="pabutools/analysis/profileproperties.html">pabutools.analysis.profileproperties</a></li>
 <li><a href="pabutools/analysis/votersatisfaction.html">pabutools.analysis.votersatisfaction</a></li>

diff --git a/docs/_modules/pabutools/rules/exhaustion.html b/docs/_modules/pabutools/rules/exhaustion.html
diff --git a/docs/_modules/pabutools/rules/mes.html b/docs/_modules/pabutools/rules/mes.html
@@ -257,25 +257,22 @@ <h1>Source code for pabutools.rules.mes</h1><div class="highlight"><pre>
 <span></span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">The method of equal shares.</span>
 <span class="sd">&quot;&quot;&quot;</span>
-<span class="kn">from</span> <span class="nn">itertools</span> <span class="kn">import</span> <span class="n">chain</span>
 <span class="kn">from</span> <span class="nn">copy</span> <span class="kn">import</span> <span class="n">copy</span><span class="p">,</span> <span class="n">deepcopy</span>
 <span class="kn">from</span> <span class="nn">collections.abc</span> <span class="kn">import</span> <span class="n">Iterable</span>
 <span class="kn">from</span> <span class="nn">numbers</span> <span class="kn">import</span> <span class="n">Number</span>
 
 <span class="kn">from</span> <span class="nn">pabutools.election.satisfaction.satisfactionmeasure</span> <span class="kn">import</span> <span class="n">GroupSatisfactionMeasure</span>
-
-<span class="kn">from</span> <span class="nn">pabutools.election</span> <span class="kn">import</span> <span class="p">(</span>
-    <span class="n">MultiProfile</span><span class="p">,</span>
-    <span class="n">SatisfactionMultiProfile</span><span class="p">,</span>
-    <span class="n">AbstractBallot</span><span class="p">,</span>
-    <span class="n">AbstractProfile</span><span class="p">,</span>
-<span class="p">)</span>
+<span class="kn">from</span> <span class="nn">pabutools.election.ballot.ballot</span> <span class="kn">import</span> <span class="n">AbstractBallot</span>
 <span class="kn">from</span> <span class="nn">pabutools.election.instance</span> <span class="kn">import</span> <span class="n">Instance</span><span class="p">,</span> <span class="n">Project</span>
-<span class="kn">from</span> <span class="nn">pabutools.election.profile</span> <span class="kn">import</span> <span class="n">Profile</span>
-<span class="kn">from</span> <span class="nn">pabutools.election.satisfaction</span> <span class="kn">import</span> <span class="n">SatisfactionMeasure</span><span class="p">,</span> <span class="n">SatisfactionProfile</span>
+<span class="kn">from</span> <span class="nn">pabutools.election.profile</span> <span class="kn">import</span> <span class="n">AbstractProfile</span>
+<span class="kn">from</span> <span class="nn">pabutools.election.satisfaction</span> <span class="kn">import</span> <span class="n">SatisfactionMeasure</span>
 <span class="kn">from</span> <span class="nn">pabutools.tiebreaking</span> <span class="kn">import</span> <span class="n">lexico_tie_breaking</span>
 <span class="kn">from</span> <span class="nn">pabutools.fractions</span> <span class="kn">import</span> <span class="n">frac</span>
 <span class="kn">from</span> <span class="nn">pabutools.tiebreaking</span> <span class="kn">import</span> <span class="n">TieBreakingRule</span>
+<span class="kn">from</span> <span class="nn">pabutools.rules.exhaustion</span> <span class="kn">import</span> <span class="n">exhaustion_by_budget_increase</span>
+<span class="kn">from</span> <span class="nn">pabutools.rules.exhaustion</span> <span class="kn">import</span> <span class="n">completion_by_rule_combination</span>
+<span class="kn">from</span> <span class="nn">pabutools.rules.composition</span> <span class="kn">import</span> <span class="n">popularity_comparison</span>
+<span class="kn">from</span> <span class="nn">pabutools.rules.greedywelfare</span> <span class="kn">import</span> <span class="n">greedy_utilitarian_welfare</span>
 
 
 <span class="k">class</span> <span class="nc">MESVoter</span><span class="p">:</span>
@@ -364,7 +361,7 @@ <h1>Source code for pabutools.rules.mes</h1><div class="highlight"><pre>
 
 <span class="k">def</span> <span class="nf">mes_scheme</span><span class="p">(</span>
     <span class="n">instance</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="n">Profile</span><span class="p">,</span>
+    <span class="n">profile</span><span class="p">:</span> <span class="n">AbstractProfile</span><span class="p">,</span>
     <span class="n">sat_profile</span><span class="p">:</span> <span class="n">GroupSatisfactionMeasure</span><span class="p">,</span>
     <span class="n">initial_budget</span><span class="p">:</span> <span class="n">Number</span><span class="p">,</span>
     <span class="n">initial_budget_allocation</span><span class="p">:</span> <span class="n">Iterable</span><span class="p">[</span><span class="n">Project</span><span class="p">],</span>
@@ -596,6 +593,113 @@ <h1>Source code for pabutools.rules.mes</h1><div class="highlight"><pre>
         <span class="n">tie_breaking</span><span class="p">,</span>
         <span class="n">resoluteness</span><span class="o">=</span><span class="n">resoluteness</span><span class="p">,</span>
     <span class="p">)</span></div>
+
+
+<span class="k">def</span> <span class="nf">mes_iterated</span><span class="p">(</span>
+    <span class="n">instance</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="n">AbstractProfile</span><span class="p">,</span>
+    <span class="n">sat_class</span><span class="p">:</span> <span class="nb">type</span><span class="p">[</span><span class="n">SatisfactionMeasure</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+    <span class="n">sat_profile</span><span class="p">:</span> <span class="n">GroupSatisfactionMeasure</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+    <span class="n">initial_budget_allocation</span><span class="p">:</span> <span class="n">Iterable</span><span class="p">[</span><span class="n">Project</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+    <span class="n">resoluteness</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span>
+    <span class="n">budget_step</span><span class="p">:</span> <span class="n">Number</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+<span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Iterable</span><span class="p">[</span><span class="n">Project</span><span class="p">]:</span>
+<span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">    Shortcut for the method of equal shares used with the exhaustion by budget increase method.</span>
+
+<span class="sd">    Parameters</span>
+<span class="sd">    ----------</span>
+<span class="sd">        instance: :py:class:`~pabutools.election.instance.Instance`</span>
+<span class="sd">            The instance.</span>
+<span class="sd">        profile : :py:class:`~pabutools.election.profile.profile.AbstractProfile`</span>
+<span class="sd">            The profile.</span>
+<span class="sd">        sat_class : type[:py:class:`~pabutools.election.satisfaction.satisfactionmeasure.SatisfactionMeasure`]</span>
+<span class="sd">            The class defining the satisfaction function used to measure the social welfare. It should be a class</span>
+<span class="sd">            inhereting from pabutools.instance.satisfaction.Satisfaction.</span>
+<span class="sd">            If no satisfaction is provided, a satisfaction profile needs to be provided. If a satisfation profile is</span>
+<span class="sd">            provided, the satisfaction argument is disregarded.</span>
+<span class="sd">        sat_profile : :py:class:`~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure`</span>
+<span class="sd">            The satisfaction profile corresponding to the instance and the profile. If no satisfaction profile is</span>
+<span class="sd">            provided, but a satisfaction function is, the former is computed from the latter.</span>
+<span class="sd">        initial_budget_allocation : Iterable[:py:class:`~pabutools.election.instance.Project`]</span>
+<span class="sd">            An initial budget allocation, typically empty.</span>
+<span class="sd">        resoluteness : bool, optional</span>
+<span class="sd">            Set to `False` to obtain an irresolute outcome, where all tied budget allocations are returned.</span>
+<span class="sd">            Defaults to True.</span>
+<span class="sd">        budget_step: Number</span>
+<span class="sd">            The budget increase in each step. Defaults to 1% of the budget limit.</span>
+
+<span class="sd">    Returns</span>
+<span class="sd">    -------</span>
+<span class="sd">        Iterable[Project]</span>
+<span class="sd">            The selected projects.</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+    <span class="k">return</span> <span class="n">exhaustion_by_budget_increase</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="n">method_of_equal_shares</span><span class="p">,</span>
+        <span class="p">{</span><span class="s2">&quot;sat_class&quot;</span><span class="p">:</span> <span class="n">sat_class</span><span class="p">,</span> <span class="s2">&quot;sat_profile&quot;</span><span class="p">:</span> <span class="n">sat_profile</span><span class="p">},</span>
+        <span class="n">initial_budget_allocation</span><span class="o">=</span><span class="n">initial_budget_allocation</span><span class="p">,</span>
+        <span class="n">resoluteness</span><span class="o">=</span><span class="n">resoluteness</span><span class="p">,</span>
+        <span class="n">budget_step</span><span class="o">=</span><span class="n">budget_step</span><span class="p">,</span>
+    <span class="p">)</span>
+
+
+<span class="k">def</span> <span class="nf">mes_iterated_completed</span><span class="p">(</span>
+    <span class="n">instance</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="n">AbstractProfile</span><span class="p">,</span>
+    <span class="n">sat_class</span><span class="p">:</span> <span class="nb">type</span><span class="p">[</span><span class="n">SatisfactionMeasure</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+    <span class="n">sat_profile</span><span class="p">:</span> <span class="n">GroupSatisfactionMeasure</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+    <span class="n">initial_budget_allocation</span><span class="p">:</span> <span class="n">Iterable</span><span class="p">[</span><span class="n">Project</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+    <span class="n">resoluteness</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span>
+    <span class="n">budget_step</span><span class="p">:</span> <span class="n">Number</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+<span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Iterable</span><span class="p">[</span><span class="n">Project</span><span class="p">]:</span>
+<span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">    Shortcut for the method of equal shares used with the exhaustion by budget increase method and then complete by the</span>
+<span class="sd">    greedy utilitarian welfare maximiser.</span>
+
+<span class="sd">    Parameters</span>
+<span class="sd">    ----------</span>
+<span class="sd">        instance: :py:class:`~pabutools.election.instance.Instance`</span>
+<span class="sd">            The instance.</span>
+<span class="sd">        profile : :py:class:`~pabutools.election.profile.profile.AbstractProfile`</span>
+<span class="sd">            The profile.</span>
+<span class="sd">        sat_class : type[:py:class:`~pabutools.election.satisfaction.satisfactionmeasure.SatisfactionMeasure`]</span>
+<span class="sd">            The class defining the satisfaction function used to measure the social welfare. It should be a class</span>
+<span class="sd">            inhereting from pabutools.instance.satisfaction.Satisfaction.</span>
+<span class="sd">            If no satisfaction is provided, a satisfaction profile needs to be provided. If a satisfation profile is</span>
+<span class="sd">            provided, the satisfaction argument is disregarded.</span>
+<span class="sd">        sat_profile : :py:class:`~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure`</span>
+<span class="sd">            The satisfaction profile corresponding to the instance and the profile. If no satisfaction profile is</span>
+<span class="sd">            provided, but a satisfaction function is, the former is computed from the latter.</span>
+<span class="sd">        initial_budget_allocation : Iterable[:py:class:`~pabutools.election.instance.Project`]</span>
+<span class="sd">            An initial budget allocation, typically empty.</span>
+<span class="sd">        resoluteness : bool, optional</span>
+<span class="sd">            Set to `False` to obtain an irresolute outcome, where all tied budget allocations are returned.</span>
+<span class="sd">            Defaults to True.</span>
+<span class="sd">        budget_step: Number</span>
+<span class="sd">            The budget increase in each step for the iterated MES part. Defaults to 1% of the budget limit.</span>
+
+<span class="sd">    Returns</span>
+<span class="sd">    -------</span>
+<span class="sd">        Iterable[Project]</span>
+<span class="sd">            The selected projects.</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+    <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">mes_iterated</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;sat_class&quot;</span><span class="p">:</span> <span class="n">sat_class</span><span class="p">,</span>
+                <span class="s2">&quot;sat_profile&quot;</span><span class="p">:</span> <span class="n">sat_profile</span><span class="p">,</span>
+                <span class="s2">&quot;budget_step&quot;</span><span class="p">:</span> <span class="n">budget_step</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">sat_class</span><span class="p">,</span> <span class="s2">&quot;sat_profile&quot;</span><span class="p">:</span> <span class="n">sat_profile</span><span class="p">},</span>
+        <span class="p">],</span>
+        <span class="n">initial_budget_allocation</span><span class="o">=</span><span class="n">initial_budget_allocation</span><span class="p">,</span>
+        <span class="n">resoluteness</span><span class="o">=</span><span class="n">resoluteness</span><span class="p">,</span>
+    <span class="p">)</span>
 </pre></div>
 
                 </article>

diff --git a/docs/_sources/reference/rules/index.rst b/docs/_sources/reference/rules/index.rst
@@ -11,6 +11,10 @@ Rules module
 
 .. autofunction:: pabutools.rules.mes.method_of_equal_shares
 
+.. autofunction:: pabutools.rules.mes.mes_iterated
+
+.. autofunction:: pabutools.rules.mes.mes_iterated_completed
+
 .. autofunction:: pabutools.rules.exhaustion.completion_by_rule_combination
 
 .. autofunction:: pabutools.rules.exhaustion.exhaustion_by_budget_increase

diff --git a/docs/_sources/usage.rst b/docs/_sources/usage.rst
@@ -671,8 +671,8 @@ previous two as it does not rely on a satisfaction measure.
         resoluteness=False
     )
 
-Method of Equal Shares
-^^^^^^^^^^^^^^^^^^^^^^
+Method of Equal Shares (MES)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The Method of Equal Shares is another rule that returns budget allocations based on the satisfaction
 measure provided. For more details, see the `equalshares.net <https://equalshares.net/>`_ website.
@@ -729,6 +729,12 @@ measure provided. For more details, see the `equalshares.net <https://equalshare
         resoluteness=False
     )
 
+Two important shortcuts are also defined by defaults for MES:
+
+* :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`);
+
+* :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
 ^^^^^^^^^^^^^^^^^^
 

diff --git a/docs/genindex.html b/docs/genindex.html
@@ -1096,6 +1096,10 @@ <h2 id="M">M</h2>
       <li><a href="reference/analysis/index.html#pabutools.analysis.instanceproperties.median_project_cost">median_project_cost() (in module pabutools.analysis.instanceproperties)</a>
 </li>
       <li><a href="reference/analysis/index.html#pabutools.analysis.profileproperties.median_total_score">median_total_score() (in module pabutools.analysis.profileproperties)</a>
+</li>
+      <li><a href="reference/rules/index.html#pabutools.rules.mes.mes_iterated">mes_iterated() (in module pabutools.rules.mes)</a>
+</li>
+      <li><a href="reference/rules/index.html#pabutools.rules.mes.mes_iterated_completed">mes_iterated_completed() (in module pabutools.rules.mes)</a>
 </li>
       <li><a href="reference/election/ballot.html#pabutools.election.ballot.ballot.AbstractBallot.meta">meta (AbstractBallot attribute)</a>
 

diff --git a/docs/objects.inv b/docs/objects.inv