Updated docs

docs-source/source/usage.rst

@@ -433,14 +433,16 @@ We also offer additive satisfaction functions, where the satisfaction for a set
 of projects is equal to the sum of the satisfaction of each individual project. The class
 :py:class:`~pabutools.election.satisfaction.additivesatisfaction.AdditiveSatisfaction`
 implements such functions. Its constructor takes a function as a parameter that maps
-instance, profile, ballot, and project to a score. As an example, we demonstrate
+instance, profile, ballot, project, and pre-computed values to a score. The pre-computed
+argument is used to pass fixed parameters to the function that can be used
+for expensive computations not to be done more than once. As an example, we demonstrate
 how to define the cardinality satisfaction function.
 
 .. code-block:: python
 
     from pabutools.election import AdditiveSatisfaction
 
-    def cardinality_sat_func(instance, profile, ballot, project):
+    def cardinality_sat_func(instance, profile, ballot, project, precomputed_values):
         return int(project in ballot)
 
     class Cardinality_Sat(AdditiveSatisfaction):

docs/_modules/pabutools/analysis/category.html

@@ -322,6 +322,10 @@ <h1>Source code for pabutools.analysis.category</h1><div class="highlight"><pre>
             <span class="n">app_total_cost</span> <span class="o">+=</span> <span class="n">project</span><span class="o">.</span><span class="n">cost</span>
             <span class="k">for</span> <span class="n">category</span> <span class="ow">in</span> <span class="n">project</span><span class="o">.</span><span class="n">categories</span><span class="p">:</span>
                 <span class="n">app_cost_per_category</span><span class="p">[</span><span class="n">category</span><span class="p">]</span> <span class="o">+=</span> <span class="n">project</span><span class="o">.</span><span class="n">cost</span>
+        <span class="k">if</span> <span class="n">app_total_cost</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
+            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
+                <span class="s2">&quot;Category proportionality can only be computed for instances with at least one non-empty ballot.&quot;</span>
+            <span class="p">)</span>
         <span class="k">for</span> <span class="n">category</span> <span class="ow">in</span> <span class="n">categories</span><span class="p">:</span>
             <span class="n">proportional_app_cost_per_category</span><span class="p">[</span><span class="n">category</span><span class="p">]</span> <span class="o">+=</span> <span class="p">(</span>
                 <span class="n">app_cost_per_category</span><span class="p">[</span><span class="n">category</span><span class="p">]</span>

docs/_modules/pabutools/analysis/profileproperties.html

@@ -308,6 +308,8 @@ <h1>Source code for pabutools.analysis.profileproperties</h1><div class="highlig
 <span class="sd">            The median length of the ballots in the profile.</span>
 
 <span class="sd">    &quot;&quot;&quot;</span>
+    <span class="k">if</span> <span class="n">profile</span><span class="o">.</span><span class="n">num_ballots</span><span class="p">()</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
+        <span class="k">return</span> <span class="mi">0</span>
     <span class="n">ballot_lengths</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">zeros</span><span class="p">(</span><span class="n">profile</span><span class="o">.</span><span class="n">num_ballots</span><span class="p">())</span>
     <span class="n">index</span> <span class="o">=</span> <span class="mi">0</span>
     <span class="k">for</span> <span class="n">ballot</span> <span class="ow">in</span> <span class="n">profile</span><span class="p">:</span>
@@ -356,6 +358,8 @@ <h1>Source code for pabutools.analysis.profileproperties</h1><div class="highlig
 <span class="sd">            The median cost of the ballots in the profile.</span>
 
 <span class="sd">    &quot;&quot;&quot;</span>
+    <span class="k">if</span> <span class="n">profile</span><span class="o">.</span><span class="n">num_ballots</span><span class="p">()</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
+        <span class="k">return</span> <span class="mi">0</span>
     <span class="n">ballot_costs</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">zeros</span><span class="p">(</span><span class="n">profile</span><span class="o">.</span><span class="n">num_ballots</span><span class="p">())</span>
     <span class="n">index</span> <span class="o">=</span> <span class="mi">0</span>
     <span class="k">for</span> <span class="n">ballot</span> <span class="ow">in</span> <span class="n">profile</span><span class="p">:</span>
@@ -404,6 +408,8 @@ <h1>Source code for pabutools.analysis.profileproperties</h1><div class="highlig
 <span class="sd">            The median approval score of projects.</span>
 
 <span class="sd">    &quot;&quot;&quot;</span>
+    <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">instance</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
+        <span class="k">return</span> <span class="mi">0</span>
     <span class="k">return</span> <span class="nb">float</span><span class="p">(</span>
         <span class="n">np</span><span class="o">.</span><span class="n">median</span><span class="p">([</span><span class="n">frac</span><span class="p">(</span><span class="n">profile</span><span class="o">.</span><span class="n">approval_score</span><span class="p">(</span><span class="n">project</span><span class="p">))</span> <span class="k">for</span> <span class="n">project</span> <span class="ow">in</span> <span class="n">instance</span><span class="p">])</span>
     <span class="p">)</span></div>
@@ -446,6 +452,8 @@ <h1>Source code for pabutools.analysis.profileproperties</h1><div class="highlig
 <span class="sd">            The median score assigned to a project.</span>
 
 <span class="sd">    &quot;&quot;&quot;</span>
+    <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">instance</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
+        <span class="k">return</span> <span class="mi">0</span>
     <span class="k">return</span> <span class="nb">float</span><span class="p">(</span>
         <span class="n">np</span><span class="o">.</span><span class="n">median</span><span class="p">([</span><span class="n">frac</span><span class="p">(</span><span class="n">profile</span><span class="o">.</span><span class="n">total_score</span><span class="p">(</span><span class="n">project</span><span class="p">))</span> <span class="k">for</span> <span class="n">project</span> <span class="ow">in</span> <span class="n">instance</span><span class="p">])</span>
     <span class="p">)</span></div>

docs/_modules/pabutools/election/profile/approvalprofile.html

@@ -572,7 +572,7 @@ <h1>Source code for pabutools.election.profile.approvalprofile</h1><div class="h
 
 <div class="viewcode-block" id="get_all_approval_profiles"><a class="viewcode-back" href="../../../../reference/election/profile.html#pabutools.election.profile.approvalprofile.get_all_approval_profiles">[docs]</a><span class="k">def</span> <span class="nf">get_all_approval_profiles</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">num_agents</span><span class="p">:</span> <span class="nb">int</span>
-<span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Generator</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="p">)</span> <span class="o">-&gt;</span> <span class="n">Generator</span><span class="p">[</span><span class="n">ApprovalProfile</span><span class="p">]:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Returns a generator over all the possible profile for a given instance of a given length.</span>
 
@@ -588,7 +588,8 @@ <h1>Source code for pabutools.election.profile.approvalprofile</h1><div class="h
 <span class="sd">        Generator[Iterable[:py:class:`~pabutools.election.instance.Project`]]</span>
 <span class="sd">            Generator over subsets of projects.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
-    <span class="k">return</span> <span class="n">product</span><span class="p">(</span><span class="n">powerset</span><span class="p">(</span><span class="n">instance</span><span class="p">),</span> <span class="n">repeat</span><span class="o">=</span><span class="n">num_agents</span><span class="p">)</span></div>
+    <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">product</span><span class="p">(</span><span class="n">powerset</span><span class="p">(</span><span class="n">instance</span><span class="p">),</span> <span class="n">repeat</span><span class="o">=</span><span class="n">num_agents</span><span class="p">):</span>
+        <span class="k">yield</span> <span class="n">ApprovalProfile</span><span class="p">([</span><span class="n">ApprovalBallot</span><span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="k">for</span> <span class="n">b</span> <span class="ow">in</span> <span class="n">p</span><span class="p">],</span> <span class="n">instance</span><span class="o">=</span><span class="n">instance</span><span class="p">)</span></div>
 
 
 <div class="viewcode-block" id="ApprovalMultiProfile"><a class="viewcode-back" href="../../../../reference/election/profile.html#pabutools.election.profile.approvalprofile.ApprovalMultiProfile">[docs]</a><span class="k">class</span> <span class="nc">ApprovalMultiProfile</span><span class="p">(</span><span class="n">MultiProfile</span><span class="p">,</span> <span class="n">AbstractApprovalProfile</span><span class="p">):</span>

docs/_modules/pabutools/election/satisfaction/satisfactionmeasure.html

@@ -395,7 +395,30 @@ <h1>Source code for pabutools.election.satisfaction.satisfactionmeasure</h1><div
         <span class="n">res</span> <span class="o">=</span> <span class="mi">0</span>
         <span class="k">for</span> <span class="n">sat</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
             <span class="n">res</span> <span class="o">+=</span> <span class="n">sat</span><span class="o">.</span><span class="n">sat</span><span class="p">(</span><span class="n">projects</span><span class="p">)</span> <span class="o">*</span> <span class="bp">self</span><span class="o">.</span><span class="n">multiplicity</span><span class="p">(</span><span class="n">sat</span><span class="p">)</span>
-        <span class="k">return</span> <span class="n">res</span></div></div>
+        <span class="k">return</span> <span class="n">res</span></div>
+
+<div class="viewcode-block" id="GroupSatisfactionMeasure.remove_satisfied"><a class="viewcode-back" href="../../../../reference/election/satisfaction.html#pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure.remove_satisfied">[docs]</a>    <span class="nd">@abstractmethod</span>
+    <span class="k">def</span> <span class="nf">remove_satisfied</span><span class="p">(</span>
+        <span class="bp">self</span><span class="p">,</span> <span class="n">sat_bound</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="n">AbstractBallot</span><span class="p">,</span> <span class="n">Number</span><span class="p">],</span> <span class="n">projects</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="p">)</span> <span class="o">-&gt;</span> <span class="n">GroupSatisfactionMeasure</span><span class="p">:</span>
+<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">        Returns a new satisfaction profile excluding the satisfaction measurs corresponding to satisfied voters, i.e.,</span>
+<span class="sd">        who have met or exceeded their satisfaction bound for a given collection of projects.</span>
+
+<span class="sd">        Parameters</span>
+<span class="sd">        ----------</span>
+<span class="sd">            sat_bound : dict[str, Number]</span>
+<span class="sd">                A dictionary of ballot names to numbers, specifying for each ballot the satisfaction bound above which</span>
+<span class="sd">                the voter is considered satisfied. Note that the keys are ballot names, and that nothing ensures ballot</span>
+<span class="sd">                names to be unique, so be careful here.</span>
+<span class="sd">            projects : Iterable[:py:class:`~pabutools.election.instance.Project`]</span>
+<span class="sd">                The collection of projects.</span>
+
+<span class="sd">        Returns</span>
+<span class="sd">        -------</span>
+<span class="sd">            :py:class:`~pabutools.election.satisfaction.satisfactionmeasure.GroupSatisfactionMeasure`</span>
+<span class="sd">                The new satisfaction profile.</span>
+<span class="sd">        &quot;&quot;&quot;</span></div></div>
 </pre></div>
 
                 </article>