decidim-stratified_sortitions 0.0.1

data/app/services/decidim/stratified_sortitions/leximin/constraint_builder.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module Leximin
+      # Builds constraint matrices and quota structures for the LEXIMIN algorithm.
+      #
+      # Extracts volunteer information, category memberships, and quota constraints
+      # from the database models into efficient data structures for optimization.
+      #
+      class ConstraintBuilder
+        attr_reader :stratified_sortition
+
+        def initialize(stratified_sortition)
+          @stratified_sortition = stratified_sortition
+          @cached_data = nil
+        end
+
+        # Panel size (k) - number of candidates to select
+        #
+        # @return [Integer]
+        def panel_size
+          @panel_size ||= stratified_sortition.num_candidates
+        end
+
+        # All volunteers in the pool
+        #
+        # @return [Array<Integer>] volunteer IDs
+        def volunteer_ids
+          build_cache unless @cached_data
+          @cached_data[:volunteer_ids]
+        end
+
+        # Number of volunteers
+        #
+        # @return [Integer]
+        def num_volunteers
+          volunteer_ids.size
+        end
+
+        # All substratum (category) IDs
+        #
+        # @return [Array<Integer>]
+        def category_ids
+          build_cache unless @cached_data
+          @cached_data[:category_ids]
+        end
+
+        # Quota constraints for each category
+        # min_quota is always 0, max_quota is calculated from percentage
+        #
+        # @return [Hash{Integer => Hash{Symbol => Integer}}]
+        #   { substratum_id => { min: 0, max: Integer } }
+        def quotas
+          build_cache unless @cached_data
+          @cached_data[:quotas]
+        end
+
+        # Membership matrix: which volunteers belong to which categories
+        #
+        # @return [Hash{Integer => Set<Integer>}]
+        #   { volunteer_id => Set of substratum_ids }
+        def volunteer_categories
+          build_cache unless @cached_data
+          @cached_data[:volunteer_categories]
+        end
+
+        # Inverse membership: which volunteers belong to a category
+        #
+        # @return [Hash{Integer => Set<Integer>}]
+        #   { substratum_id => Set of volunteer_ids }
+        def category_volunteers
+          build_cache unless @cached_data
+          @cached_data[:category_volunteers]
+        end
+
+        # Get volunteer index for ILP variables
+        #
+        # @param volunteer_id [Integer]
+        # @return [Integer] index in the volunteer array
+        def volunteer_index(volunteer_id)
+          @volunteer_index_map ||= volunteer_ids.each_with_index.to_h
+          @volunteer_index_map[volunteer_id]
+        end
+
+        # Get category index for constraint rows
+        #
+        # @param category_id [Integer]
+        # @return [Integer] index in the category array
+        def category_index(category_id)
+          @category_index_map ||= category_ids.each_with_index.to_h
+          @category_index_map[category_id]
+        end
+
+        # Stratum information for debugging and validation
+        #
+        # @return [Array<Hash>] Array of stratum info with substrata
+        def strata_info
+          build_cache unless @cached_data
+          @cached_data[:strata_info]
+        end
+
+        private
+
+        def build_cache
+          @cached_data = {
+            volunteer_ids: [],
+            category_ids: [],
+            quotas: {},
+            volunteer_categories: Hash.new { |h, k| h[k] = Set.new },
+            category_volunteers: Hash.new { |h, k| h[k] = Set.new },
+            strata_info: [],
+          }
+
+          load_volunteers
+          load_strata_and_quotas
+          load_memberships
+        end
+
+        def load_volunteers
+          @cached_data[:volunteer_ids] = stratified_sortition
+                                         .sample_participants
+                                         .pluck(:id)
+        end
+
+        def load_strata_and_quotas
+          stratified_sortition.strata.includes(:substrata).find_each do |stratum|
+            stratum_info = {
+              id: stratum.id,
+              name: stratum.name,
+              kind: stratum.kind,
+              substrata: [],
+            }
+
+            stratum.substrata.each do |substratum|
+              @cached_data[:category_ids] << substratum.id
+
+              # Calculate max quota from percentage
+              # max_quota_percentage is stored as a string like "25.5" meaning 25.5%
+              percentage = substratum.max_quota_percentage.to_f
+              max_quota = if percentage.positive?
+                            (percentage / 100.0 * panel_size).ceil
+                          else
+                            panel_size # No restriction if percentage is 0 or not set
+                          end
+
+              @cached_data[:quotas][substratum.id] = {
+                min: 0, # Always 0 as per requirements
+                max: max_quota,
+              }
+
+              stratum_info[:substrata] << {
+                id: substratum.id,
+                name: substratum.name,
+                percentage:,
+                max_quota:,
+              }
+            end
+
+            @cached_data[:strata_info] << stratum_info
+          end
+        end
+
+        def load_memberships
+          # Load all participant-substratum relationships efficiently
+          SampleParticipantStratum
+            .where(
+              decidim_stratified_sortitions_sample_participant_id: @cached_data[:volunteer_ids]
+            )
+            .where.not(decidim_stratified_sortitions_substratum_id: nil)
+            .pluck(:decidim_stratified_sortitions_sample_participant_id, :decidim_stratified_sortitions_substratum_id)
+            .each do |volunteer_id, category_id|
+              @cached_data[:volunteer_categories][volunteer_id] << category_id
+              @cached_data[:category_volunteers][category_id] << volunteer_id
+            end
+        end
+      end
+    end
+  end
+end

data/app/services/decidim/stratified_sortitions/leximin/distribution_solver.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module Leximin
+      # Computes the LEXIMIN-optimal probability distribution over panels.
+      #
+      # The LEXIMIN criterion maximizes fairness by:
+      # 1. Maximizing the minimum selection probability
+      # 2. Then maximizing the second-minimum probability (with the first fixed)
+      # 3. And so on...
+      #
+      # Uses Linear Programming (LP) with the CBC solver.
+      #
+      class DistributionSolver
+        class CbcNotAvailableError < StandardError; end
+
+        # Small epsilon for numerical stability
+        EPSILON = 1e-9
+
+        def initialize(constraint_builder)
+          @cb = constraint_builder
+          require_cbc!
+        end
+
+        private
+
+        def require_cbc!
+          require "ruby-cbc"
+        rescue LoadError
+          raise CbcNotAvailableError,
+                "The CBC solver is required for LEXIMIN selection. " \
+                "Install the gem with: bundle add ruby-cbc\n" \
+                "And system libraries: sudo apt install coinor-cbc coinor-libcbc-dev"
+        end
+
+        public
+
+        # Compute the LEXIMIN-optimal distribution over panels
+        #
+        # @param panels [Array<Array<Integer>>] Array of panels (each panel is array of volunteer IDs)
+        # @return [Hash] { probabilities: Array<Float>, dual_prices: Hash<Integer, Float> }
+        def compute(panels)
+          return empty_result if panels.empty?
+
+          # Build panel-volunteer incidence matrix
+          # incidence[i][p] = 1 if volunteer i is in panel p
+          incidence = build_incidence_matrix(panels)
+
+          # Compute LEXIMIN distribution using iterative LP
+          probabilities, _selection_probs = solve_leximin_lp(panels, incidence)
+
+          # Compute dual prices for column generation
+          dual_prices = compute_dual_prices(panels, probabilities, incidence)
+
+          {
+            probabilities:,
+            dual_prices:,
+          }
+        end
+
+        private
+
+        def empty_result
+          { probabilities: [], dual_prices: {} }
+        end
+
+        def build_incidence_matrix(panels)
+          # incidence[volunteer_id] = array of panel indices containing this volunteer
+          incidence = Hash.new { |h, k| h[k] = [] }
+
+          panels.each_with_index do |panel, panel_idx|
+            panel.each do |volunteer_id|
+              incidence[volunteer_id] << panel_idx
+            end
+          end
+
+          incidence
+        end
+
+        # Solve LEXIMIN LP iteratively
+        #
+        # We solve a sequence of LPs:
+        # 1. Maximize π_min = min_i π_i
+        # 2. Fix π_i ≥ π_min for all i, maximize second-minimum
+        # 3. Continue until all probabilities are fixed
+        #
+        # For efficiency, we use a single LP with a max-min formulation.
+        #
+        def solve_leximin_lp(panels, incidence) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+          num_panels = panels.size
+          return [Array.new(num_panels, 1.0 / num_panels), uniform_selection_probs(panels)] if num_panels == 1
+
+          # Use a max-min LP formulation:
+          # maximize z
+          # subject to:
+          #   π_i ≥ z for all volunteers i
+          #   ∑_p λ_p = 1
+          #   λ_p ≥ 0
+          #   π_i = ∑_{p: i ∈ p} λ_p
+
+          model = Cbc::Model.new
+
+          # Variables: λ_p for each panel (probability of selecting panel p)
+          lambda_vars = (0...num_panels).map do |p|
+            model.cont_var(name: "lambda_#{p}")
+          end
+
+          # Variable: z (minimum probability to maximize)
+          z = model.cont_var(name: "z")
+
+          # Constraint: probabilities sum to 1
+          model.enforce(sum_vars(lambda_vars) == 1)
+
+          # Constraint: π_i ≥ z for each volunteer
+          @cb.volunteer_ids.each do |vid|
+            panel_indices = incidence[vid]
+            next if panel_indices.empty?
+
+            # π_i = ∑_{p: i ∈ p} λ_p
+            pi_i = sum_vars(panel_indices.map { |p| lambda_vars[p] })
+
+            # π_i ≥ z
+            model.enforce(pi_i >= z)
+          end
+
+          # Objective: maximize z (the minimum probability)
+          model.maximize(z)
+
+          # Solve
+          problem = model.to_problem
+          problem.solve
+
+          unless problem.proven_optimal?
+            # Fallback to uniform distribution
+            uniform_prob = 1.0 / num_panels
+            return [Array.new(num_panels, uniform_prob), uniform_selection_probs(panels)]
+          end
+
+          # Extract probabilities
+          probabilities = lambda_vars.map { |v| [problem.value_of(v), 0.0].max }
+
+          # Normalize to ensure they sum to 1
+          total = probabilities.sum
+          probabilities = probabilities.map { |p| p / total } if total > EPSILON
+
+          # Compute selection probabilities
+          selection_probs = {}
+          @cb.volunteer_ids.each do |vid|
+            panel_indices = incidence[vid]
+            selection_probs[vid] = panel_indices.sum { |p| probabilities[p] }
+          end
+
+          [probabilities, selection_probs]
+        end
+
+        def uniform_selection_probs(panels)
+          probs = Hash.new(0.0)
+          return probs if panels.empty?
+
+          prob_per_panel = 1.0 / panels.size
+          panels.each do |panel|
+            panel.each { |vid| probs[vid] += prob_per_panel }
+          end
+          probs
+        end
+
+        # Compute dual prices for the column generation subproblem
+        #
+        # The dual prices indicate how much each volunteer's inclusion
+        # in a new panel would improve the objective.
+        #
+        # For LEXIMIN, we use the marginal value of increasing each volunteer's
+        # selection probability.
+        #
+        def compute_dual_prices(_panels, probabilities, incidence)
+          dual_prices = {}
+
+          # Compute current selection probabilities
+          current_probs = {}
+          @cb.volunteer_ids.each do |vid|
+            panel_indices = incidence[vid]
+            current_probs[vid] = panel_indices.sum { |p| probabilities[p] }
+          end
+
+          # Find minimum probability
+          min_prob = current_probs.values.min || 0.0
+
+          # Dual price is higher for volunteers with lower selection probability
+          # This encourages new panels to include under-represented volunteers
+          @cb.volunteer_ids.each do |vid|
+            current = current_probs[vid] || 0.0
+
+            # Inverse relationship: lower probability = higher dual price
+            dual_prices[vid] = if current <= min_prob + EPSILON
+                                 # Volunteers at minimum get highest price
+                                 1.0
+                               elsif current < 1.0
+                                 # Others get price inversely proportional to their probability
+                                 (1.0 - current) / (1.0 - min_prob + EPSILON)
+                               else
+                                 0.0
+                               end
+          end
+
+          dual_prices
+        end
+
+        def sum_vars(vars)
+          return 0 if vars.empty?
+
+          vars.reduce(:+)
+        end
+      end
+    end
+  end
+end

data/app/services/decidim/stratified_sortitions/leximin/feasibility_checker.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module Leximin
+      # Validates that the LEXIMIN algorithm can run with the given data.
+      #
+      # Checks:
+      # 1. Pool has enough volunteers (n >= k)
+      # 2. Quota constraints are consistent (sum of mins <= k <= sum of maxs)
+      # 3. Each category has enough volunteers to potentially meet quota
+      # 4. Panel size is positive
+      #
+      class FeasibilityChecker
+        def initialize(constraint_builder)
+          @cb = constraint_builder
+        end
+
+        # Check if the problem is feasible
+        #
+        # @return [Hash] { feasible: Boolean, errors: Array<String> }
+        def check
+          errors = []
+
+          errors.concat(check_basic_requirements)
+          errors.concat(check_pool_size)
+          errors.concat(check_quota_consistency)
+          errors.concat(check_category_coverage)
+          errors.concat(check_cross_strata_feasibility) if errors.empty?
+
+          {
+            feasible: errors.empty?,
+            errors:,
+          }
+        end
+
+        private
+
+        def check_basic_requirements
+          errors = []
+
+          errors << I18n.t("decidim.stratified_sortitions.errors.feasibility.panel_size_positive") if @cb.panel_size.nil? || @cb.panel_size <= 0
+
+          errors << I18n.t("decidim.stratified_sortitions.errors.feasibility.no_categories") if @cb.category_ids.empty?
+
+          errors
+        end
+
+        def check_pool_size
+          errors = []
+          n = @cb.num_volunteers
+          k = @cb.panel_size
+
+          if n.zero?
+            errors << I18n.t("decidim.stratified_sortitions.errors.feasibility.no_volunteers")
+          elsif n < k
+            errors << I18n.t("decidim.stratified_sortitions.errors.feasibility.pool_too_small",
+                             volunteers_count: n,
+                             panel_size: k)
+          end
+
+          errors
+        end
+
+        def check_quota_consistency
+          errors = []
+          k = @cb.panel_size
+          return errors if k.nil? || k <= 0
+
+          # Group substrata by stratum to check per-stratum constraints
+          # For each stratum, the sum of max quotas should be >= k
+          # (at least one substratum per stratum must be selected for each member)
+
+          @cb.strata_info.each do |stratum|
+            stratum_name = extract_name(stratum[:name])
+            substrata = stratum[:substrata]
+
+            next if substrata.empty?
+
+            # Sum of max quotas for this stratum
+            total_max = substrata.sum { |s| s[:max_quota] }
+
+            if total_max < k
+              errors << I18n.t("decidim.stratified_sortitions.errors.feasibility.stratum_insufficient_quotas",
+                               stratum_name:,
+                               total_max:,
+                               panel_size: k)
+            end
+
+            # Check that percentages within a stratum don't exceed 100%
+            total_percentage = substrata.sum { |s| s[:percentage] }
+            next unless total_percentage > 100 + 0.01 # Small tolerance for floating point
+
+            errors << I18n.t("decidim.stratified_sortitions.errors.feasibility.stratum_percentages_exceed",
+                             stratum_name:,
+                             total_percentage: total_percentage.round(1))
+          end
+
+          errors
+        end
+
+        def check_category_coverage
+          errors = []
+
+          @cb.strata_info.each do |stratum|
+            stratum_name = extract_name(stratum[:name])
+
+            stratum[:substrata].each do |substratum|
+              cat_id = substratum[:id]
+              substratum_name = extract_name(substratum[:name])
+              min_quota = @cb.quotas[cat_id][:min]
+
+              next if min_quota.zero? # No minimum requirement
+
+              volunteers_count = @cb.category_volunteers[cat_id]&.size || 0
+
+              next unless volunteers_count < min_quota
+
+              errors << I18n.t("decidim.stratified_sortitions.errors.feasibility.substratum_insufficient_volunteers",
+                               substratum_name:,
+                               stratum_name:,
+                               min_quota:,
+                               volunteers_count:)
+            end
+          end
+
+          # Also check that every volunteer belongs to at least one substratum per stratum
+          volunteers_without_strata = find_volunteers_without_complete_strata
+          if volunteers_without_strata.any?
+            count = volunteers_without_strata.size
+            errors << I18n.t("decidim.stratified_sortitions.errors.feasibility.volunteers_missing_strata",
+                             count:)
+          end
+
+          errors
+        end
+
+        def find_volunteers_without_complete_strata
+          incomplete = []
+          num_strata = @cb.strata_info.size
+
+          return incomplete if num_strata.zero?
+
+          @cb.volunteer_ids.each do |vid|
+            categories = @cb.volunteer_categories[vid]
+            # Each volunteer should have exactly one substratum per stratum
+            # We can't easily verify this without more complex logic, so we just
+            # check they have at least some categories
+            incomplete << vid if categories.blank?
+          end
+
+          incomplete
+        end
+
+        # Checks that the combination of max_quota_percentage constraints across all strata
+        # can be satisfied simultaneously. For each pair of substrata from different strata,
+        # there must be enough volunteers that belong to both categories.
+        def check_cross_strata_feasibility
+          errors = []
+          k = @cb.panel_size
+          return errors if k.nil? || k <= 0
+
+          strata = @cb.strata_info
+          return errors if strata.size < 2
+
+          strata.each do |stratum|
+            errors.concat(validate_stratum_quotas(stratum))
+          end
+
+          errors
+        end
+
+        def validate_stratum_quotas(stratum)
+          errors = []
+          stratum_name = extract_name(stratum[:name])
+
+          stratum[:substrata].each do |substratum|
+            error = validate_substratum_quota(substratum, stratum_name)
+            errors << error if error.present?
+          end
+
+          errors
+        end
+
+        def validate_substratum_quota(substratum, stratum_name)
+          cat_id = substratum[:id]
+          max_quota = substratum[:max_quota]
+          percentage = substratum[:percentage]
+          volunteers_in_cat = @cb.category_volunteers[cat_id]&.size || 0
+
+          # Skip if no restriction (percentage 0 means unrestricted), no quota, or no volunteers
+          return nil if percentage.zero? || max_quota.zero? || volunteers_in_cat.zero?
+
+          # Check if this substratum's max quota exceeds available volunteers
+          return nil unless max_quota > volunteers_in_cat
+
+          substratum_name = extract_name(substratum[:name])
+
+          I18n.t(
+            "decidim.stratified_sortitions.errors.feasibility.substratum_quota_exceeds_volunteers",
+            substratum_name:,
+            stratum_name:,
+            max_quota:,
+            volunteers_count: volunteers_in_cat,
+            percentage:
+          )
+        end
+
+        def extract_name(name_field)
+          case name_field
+          when Hash
+            name_field[I18n.locale.to_s] || name_field["en"] || name_field.values.first || I18n.t("decidim.stratified_sortitions.errors.feasibility.no_name")
+          when String
+            name_field
+          else
+            I18n.t("decidim.stratified_sortitions.errors.feasibility.no_name")
+          end
+        end
+      end
+    end
+  end
+end