games_dice 0.4.0 → 0.4.2

data/lib/games_dice/complex_die_helpers.rb

@@ -1,68 +1,260 @@
 # frozen_string_literal: true
 
-# @!visibility private
 module GamesDice
-  # Private extension methods for GamesDice::ComplexDie
-  module ComplexDieHelpers
-    private
+  class ComplexDie
+    # @!visibility private
+    # Private extension methods for GamesDice::ComplexDie probability calculations
+    module ProbabilityHelpers
+      private
 
-    def recursive_probabilities(probabilities = {}, prior_probability = 1.0, depth = 0, prior_result = nil, rerolls_left = nil, roll_reason = :basic, subtracting = false)
-      each_probability = prior_probability / @basic_die.sides
-      depth += 1
-      if depth >= 20 || each_probability < 1.0e-16
-        @probabilities_complete = false
-        stop_recursing = true
+      def calculate_probabilities
+        if @rerolls && @maps
+          GamesDice::Probabilities.from_h(prob_hash_with_rerolls_and_maps)
+        elsif @rerolls
+          GamesDice::Probabilities.from_h(recursive_probabilities)
+        elsif @maps
+          GamesDice::Probabilities.from_h(prob_hash_with_just_maps)
+        else
+          @basic_die.probabilities
+        end
       end
 
-      @basic_die.each_value do |v|
-        recurse_probs_for_value(v, roll_reason, probabilities, each_probability, depth, prior_result, rerolls_left,
-                                subtracting, stop_recursing)
+      def prob_hash_with_rerolls_and_maps
+        prob_hash = {}
+        reroll_probs = recursive_probabilities
+        reroll_probs.each do |v, p|
+          add_mapped_to_prob_hash(prob_hash, v, p)
+        end
+        prob_hash
       end
-      probabilities
-    end
 
-    def recurse_probs_for_value(v, roll_reason, probabilities, each_probability, depth, prior_result, rerolls_left, subtracting, stop_recursing)
-      # calculate value, recurse if there is a reroll
-      result_so_far, rerolls_remaining = calc_result_so_far(prior_result, rerolls_left, v, roll_reason)
+      def prob_hash_with_just_maps
+        prob_hash = {}
+        @basic_die.probabilities.each do |v, p|
+          add_mapped_to_prob_hash(prob_hash, v, p)
+        end
+        prob_hash
+      end
 
-      # Find which rule, if any, is being triggered
-      rule_idx = find_matching_reroll_rule(v, result_so_far.rolls.length, rerolls_remaining)
+      def add_mapped_to_prob_hash(prob_hash, orig_val, prob)
+        mapped_val, = calc_maps(orig_val)
+        prob_hash[mapped_val] ||= 0.0
+        prob_hash[mapped_val] += prob
+      end
+
+      RecurseStack = Struct.new(:depth, :roll_reason, :subtracting, :probabilities, :prior_probability, :prior_result,
+                                :rerolls_left) do
+        def initialize
+          self.depth = 0
+          self.roll_reason = :basic
+          self.subtracting = false
+          self.probabilities = {}
+          self.prior_probability = 1.0
+        end
+      end
+      private_constant :RecurseStack
+
+      def recursive_probabilities(stack = RecurseStack.new)
+        stack.prior_probability = stack.prior_probability / @basic_die.sides
+        stack.depth += 1
+
+        @basic_die.each_value do |die_val|
+          recurse_probs_for_value(die_val, stack)
+        end
+        stack.probabilities
+      end
+
+      def recurse_probs_for_value(die_val, stack)
+        result_so_far, rerolls_remaining = calc_result_so_far(die_val, stack)
+        rule_idx = find_matching_reroll_rule(die_val, result_so_far.rolls.length, rerolls_remaining)
+
+        if conintue_recursing?(stack, rule_idx)
+          continue_recursion(stack, result_so_far, rerolls_remaining, rule_idx)
+        else
+          end_recursion_store_probs(stack, result_so_far)
+        end
+      end
+
+      def conintue_recursing?(stack, rule_idx)
+        if stack.depth >= 20 || stack.prior_probability < 1.0e-16
+          @probabilities_complete = false
+          return false
+        end
+
+        !rule_idx.nil?
+      end
 
-      if rule_idx && !stop_recursing
-        recurse_probs_with_rule(probabilities, each_probability, depth, result_so_far, rerolls_remaining, rule_idx,
-                                subtracting)
-      else
+      def continue_recursion(stack, result_so_far, rerolls_remaining, rule_idx)
+        rule = @rerolls[rule_idx]
+        rerolls_remaining[rule_idx] -= 1
+        recurse_probs_with_rule(stack, result_so_far, rerolls_remaining, rule)
+      end
+
+      def end_recursion_store_probs(stack, result_so_far)
         t = result_so_far.total
-        probabilities[t] ||= 0.0
-        probabilities[t] += each_probability
+        stack.probabilities[t] ||= 0.0
+        stack.probabilities[t] += stack.prior_probability
       end
-    end
 
-    def recurse_probs_with_rule(probabilities, each_probability, depth, result_so_far, rerolls_remaining, rule_idx, subtracting)
-      rule = @rerolls[rule_idx]
-      rerolls_remaining[rule_idx] -= 1
-      is_subtracting = true if subtracting || rule.type == :reroll_subtract
+      def recurse_probs_with_rule(stack, result_so_far, rerolls_remaining, rule)
+        next_stack = stack.clone
+        next_stack.prior_result = result_so_far
+        next_stack.rerolls_left = rerolls_remaining
+        next_stack.subtracting = true if stack.subtracting || rule.type == :reroll_subtract
+
+        # Apply the rule (note reversal for additions, after a subtract)
+        next_stack.roll_reason = if stack.subtracting && rule.type == :reroll_add
+                                   :reroll_subtract
+                                 else
+                                   rule.type
+                                 end
 
-      # Apply the rule (note reversal for additions, after a subtract)
-      if subtracting && rule.type == :reroll_add
-        recursive_probabilities probabilities, each_probability, depth, result_so_far, rerolls_remaining,
-                                :reroll_subtract, is_subtracting
-      else
-        recursive_probabilities probabilities, each_probability, depth, result_so_far, rerolls_remaining, rule.type,
-                                is_subtracting
+        recursive_probabilities next_stack
+      end
+
+      def calc_result_so_far(die_val, stack)
+        if stack.prior_result
+          result_so_far = stack.prior_result.clone
+          rerolls_remaining = stack.rerolls_left.clone
+          result_so_far.add_roll(die_val, stack.roll_reason)
+        else
+          rerolls_remaining = @rerolls.map(&:limit)
+          result_so_far = GamesDice::DieResult.new(die_val, stack.roll_reason)
+        end
+        [result_so_far, rerolls_remaining]
       end
     end
 
-    def calc_result_so_far(prior_result, rerolls_left, v, roll_reason)
-      if prior_result
-        result_so_far = prior_result.clone
-        result_so_far.add_roll(v, roll_reason)
-        rerolls_remaining = rerolls_left.clone
-      else
-        result_so_far = GamesDice::DieResult.new(v, roll_reason)
+    # @!visibility private
+    # Private extension methods for GamesDice::ComplexDie simulating rolls
+    module RollHelpers
+      private
+
+      def roll_apply_rerolls
+        return unless @rerolls
+
+        subtracting = false
         rerolls_remaining = @rerolls.map(&:limit)
+
+        rerolls_loop(subtracting, rerolls_remaining)
+      end
+
+      def rerolls_loop(subtracting, rerolls_remaining)
+        loop do
+          rule_idx = find_matching_reroll_rule(@basic_die.result, @result.rolls.length, rerolls_remaining)
+          break unless rule_idx
+
+          rule = @rerolls[rule_idx]
+          rerolls_remaining[rule_idx] -= 1
+          subtracting = true if rule.type == :reroll_subtract
+          roll_apply_reroll_rule rule, subtracting
+        end
+      end
+
+      def roll_apply_reroll_rule(rule, is_subtracting)
+        # Apply the rule (note reversal for additions, after a subtract)
+        if is_subtracting && rule.type == :reroll_add
+          @result.add_roll(@basic_die.roll, :reroll_subtract)
+        else
+          @result.add_roll(@basic_die.roll, rule.type)
+        end
+      end
+
+      # Find which rule, if any, is being triggered
+      def find_matching_reroll_rule(check_value, num_rolls, rerolls_remaining)
+        @rerolls.zip(rerolls_remaining).find_index do |rule, remaining|
+          next if rule.type == :reroll_subtract && num_rolls > 1
+
+          remaining.positive? && rule.applies?(check_value)
+        end
+      end
+
+      def roll_apply_maps
+        return unless @maps
+
+        m, n = calc_maps(@result.value)
+        @result.apply_map(m, n)
+      end
+
+      def calc_maps(original_value)
+        y = 0
+        n = ''
+        @maps.find do |rule|
+          if (maybe_y = rule.map_from(original_value))
+            y = maybe_y
+            n = rule.mapped_name
+          end
+          maybe_y
+        end
+        [y, n]
+      end
+    end
+
+    # @!visibility private
+    # Private extension methods for GamesDice::ComplexDie calculating min and max (which is surprisingly complex)
+    module MinMaxHelpers
+      private
+
+      def calc_minmax
+        @min_result = probabilities.min
+        @max_result = probabilities.max
+        return if @probabilities_complete
+
+        logical_min, logical_max = logical_minmax
+        @min_result, @max_result = [@min_result, @max_result, logical_min, logical_max].minmax
+      end
+
+      def minmax_mappings(possible_values)
+        possible_values.map do |x|
+          map_val, = calc_maps(x)
+          map_val
+        end.minmax
+      end
+
+      # This isn't 100% accurate, but does cover most "normal" scenarios, and we're only falling back to it when we
+      # have to. The inaccuracy is that min_result..max_result may contain 'holes' which have extreme map values that
+      # cannot actually occur. In practice it is likely a non-issue unless someone went out of their way to invent a
+      # dice schem that broke it.
+      def logical_minmax
+        return @basic_die.minmax unless @rerolls || @maps
+        return minmax_mappings(@basic_die.all_values) unless @rerolls
+
+        min_result, max_result = logical_rerolls_minmax
+        return minmax_mappings(min_result..max_result) if @maps
+
+        [min_result, max_result]
+      end
+
+      def logical_rerolls_minmax
+        min_result = @basic_die.min
+        max_result = @basic_die.max
+        min_subtract = find_minimum_possible_subtract
+        max_add = find_maximum_possible_adds
+        min_result = [min_subtract - max_add, min_subtract - max_result].min if min_subtract
+        [min_result, max_add + max_result]
+      end
+
+      def find_minimum_possible_subtract
+        min_subtract = nil
+        @rerolls.select { |r| r.type == :reroll_subtract }.each do |rule|
+          min_reroll = @basic_die.all_values.select { |v| rule.applies?(v) }.min
+          next unless min_reroll
+
+          min_subtract = [min_reroll, min_subtract].compact.min
+        end
+        min_subtract
+      end
+
+      def find_maximum_possible_adds
+        total_add = 0
+        @rerolls.select { |r| r.type == :reroll_add }.each do |rule|
+          max_reroll = @basic_die.all_values.select { |v| rule.applies?(v) }.max
+          next unless max_reroll
+
+          total_add += max_reroll * rule.limit
+        end
+        total_add
       end
-      [result_so_far, rerolls_remaining]
     end
   end
 end

data/lib/games_dice/dice.rb

@@ -28,11 +28,14 @@ module GamesDice
     # @option bunches [Integer] :sides Number of sides on a single die in the bunch, *mandatory*
     # @option bunches [String] :name Optional name for the bunch
     # @option bunches [Array<GamesDice::RerollRule,Array>] :rerolls Optional rules that cause the die to roll again
-    # @option bunches [Array<GamesDice::MapRule,Array>] :maps Optional rules to convert a value into a final result for the die
-    # @option bunches [#rand] :prng Optional alternative source of randomness to Ruby's built-in #rand, passed to GamesDice::Die's constructor
+    # @option bunches [Array<GamesDice::MapRule,Array>] :maps Optional rules to convert a value into a final result
+    #   for the die
+    # @option bunches [#rand] :prng Optional alternative source of randomness to Ruby's built-in #rand, passed to
+    #   GamesDice::Die's constructor
     # @option bunches [Symbol] :keep_mode Optional, either *:keep_best* or *:keep_worst*
     # @option bunches [Integer] :keep_number Optional number of dice to keep when :keep_mode is not nil
-    # @option bunches [Integer] :multiplier Optional, defaults to 1, and typically 1 or -1 to describe whether the Bunch total is to be added or subtracted
+    # @option bunches [Integer] :multiplier Optional, defaults to 1, and typically 1 or -1 to describe whether the
+    #   Bunch total is to be added or subtracted
     # @return [GamesDice::Dice]
     def initialize(bunches, offset = 0, name = '')
       @name = name
@@ -110,14 +113,11 @@ module GamesDice
 
       explanations = @bunches.map { |bunch| "#{bunch.label}: #{bunch.explain_result}" }
 
-      return @offset.to_s if explanations.count.zero?
+      return @offset.to_s if explanations.none?
 
-      return simple_explanation(explanations.first) if explanations.count == 1
+      return simple_explanation(explanations.first) if explanations.one?
 
-      bunch_values = @bunch_multipliers.zip(@bunches).map { |m, b| m * b.result }
-      bunch_values << @offset if @offset != 0
-      explanations << array_to_sum(bunch_values)
-      explanations.join('. ')
+      multi_explanations(explanations)
     end
 
     private
@@ -128,8 +128,15 @@ module GamesDice
       "#{explanation}. #{array_to_sum([@bunches[0].result, @offset])}"
     end
 
+    def multi_explanations(explanations)
+      bunch_values = @bunch_multipliers.zip(@bunches).map { |m, b| m * b.result }
+      bunch_values << @offset if @offset != 0
+      explanations << array_to_sum(bunch_values)
+      explanations.join('. ')
+    end
+
     def array_to_sum(array)
-      (numbers_to_strings(array) + ['=', array.inject(:+)]).join(' ')
+      (numbers_to_strings(array) + ['=', array.sum]).join(' ')
     end
 
     def numbers_to_strings(array)

data/lib/games_dice/die.rb

@@ -74,8 +74,8 @@ module GamesDice
     # Iterates through all possible results on die.
     # @yieldparam [Integer] result A potential result from the die
     # @return [GamesDice::Die] this object
-    def each_value(&block)
-      (1..@sides).each(&block)
+    def each_value(&)
+      (1..@sides).each(&)
       self
     end
 

data/lib/games_dice/die_result.rb

@@ -1,6 +1,35 @@
 # frozen_string_literal: true
 
 module GamesDice
+  # Module supports using DieResults directly in calculations
+  # @!visibility private
+  module ExpressionHelpers
+    # all coercions simply use #value (i.e. nil or a Integer)
+    def coerce(thing)
+      @value.coerce(thing)
+    end
+
+    # addition uses #value
+    def +(other)
+      @value + other
+    end
+
+    # subtraction uses #value
+    def -(other)
+      @value - other
+    end
+
+    # multiplication uses #value
+    def *(other)
+      @value * other
+    end
+
+    # comparison <=> uses #value
+    def <=>(other)
+      value <=> other
+    end
+  end
+
   # This class models the output of GamesDice::ComplexDie.
   #
   # An object of the class represents the results of a roll of a ComplexDie, including any re-rolls and
@@ -29,6 +58,7 @@ module GamesDice
   #
   class DieResult
     include Comparable
+    include ExpressionHelpers
 
     # Creates new instance of GamesDice::DieResult. The object can be initialised "empty" or with a first result.
     # @param [Integer,nil] first_roll_result Value for first roll of the die.
@@ -40,13 +70,9 @@ module GamesDice
       end
 
       if first_roll_result
-        @rolls = [Integer(first_roll_result)]
-        @roll_reasons = [first_roll_reason]
-        @total = @rolls[0]
+        init_with_result(first_roll_result, first_roll_reason)
       else
-        @rolls = []
-        @roll_reasons = []
-        @total = nil
+        init_empty
       end
       @mapped = false
       @value = @total
@@ -78,32 +104,13 @@ module GamesDice
     # @param [Symbol] roll_reason Reason for rolling the die.
     # @return [Integer] Total so far
     def add_roll(roll_result, roll_reason = :basic)
-      unless GamesDice::REROLL_TYPES.key?(roll_reason)
-        raise ArgumentError, "Unrecognised reason for roll #{roll_reason}"
-      end
+      raise ArgumentError, "Unrecognised roll reason #{roll_reason}" unless GamesDice::REROLL_TYPES.key?(roll_reason)
 
       @rolls << Integer(roll_result)
       @roll_reasons << roll_reason
       @total = 0 if @rolls.length == 1
 
-      case roll_reason
-      when :basic
-        @total = roll_result
-      when :reroll_add
-        @total += roll_result
-      when :reroll_subtract
-        @total -= roll_result
-      when :reroll_new_die
-        @total = roll_result
-      when :reroll_new_keeper
-        @total = roll_result
-      when :reroll_replace
-        @total = roll_result
-      when :reroll_use_best
-        @total = [@value, roll_result].max
-      when :reroll_use_worst
-        @total = [@value, roll_result].min
-      end
+      apply_roll_to_total(roll_reason, roll_result)
 
       @mapped = false
       @value = @total
@@ -125,17 +132,12 @@ module GamesDice
     # map description, but does not include the mapped value.
     # @return [String] Explanation of #value.
     def explain_value
-      text = ''
-      if @rolls.length < 2
-        text = @total.to_s
-      else
-        text = "[#{@rolls[0]}"
-        text = (1..@rolls.length - 1).inject(text) do |so_far, i|
-          so_far + GamesDice::REROLL_TYPES[@roll_reasons[i]] + @rolls[i].to_s
-        end
-        text += "] #{@total}"
-      end
-      text += " #{@map_description}" if @mapped && @map_description && @map_description.length.positive?
+      text = if @rolls.length < 2
+               @total.to_s
+             else
+               explain_value_multiple_rolls
+             end
+      text += " #{@map_description}" if @mapped && @map_description&.length&.positive?
       text
     end
 
@@ -143,51 +145,62 @@ module GamesDice
     # This is mis-named, it doesn't explain the total at all! It is used to generate summaries of keeper dice.
     def explain_total
       text = @total.to_s
-      text += " #{@map_description}" if @mapped && @map_description && @map_description.length.positive?
+      text += " #{@map_description}" if @mapped && @map_description&.length&.positive?
       text
     end
 
-    # @!visibility private
-    # all coercions simply use #value (i.e. nil or a Integer)
-    def coerce(thing)
-      @value.coerce(thing)
+    # This is a deep clone, all attributes are also cloned.
+    # @return [GamesDice::DieResult]
+    def clone
+      cloned = GamesDice::DieResult.new
+      cloned.instance_variable_set(:@rolls, @rolls.clone)
+      cloned.instance_variable_set(:@roll_reasons, @roll_reasons.clone)
+      cloned.instance_variable_set(:@total, @total)
+      cloned.instance_variable_set(:@value, @value)
+      cloned.instance_variable_set(:@mapped, @mapped)
+      cloned.instance_variable_set(:@map_description, @map_description)
+      cloned
     end
 
-    # @!visibility private
-    # addition uses #value
-    def +(other)
-      @value + other
-    end
+    private
 
-    # @!visibility private
-    # subtraction uses #value
-    def -(other)
-      @value - other
+    # Splitting this method up further, or flattening it will not make it read better. If
+    # we had a few more reroll reasons, they could maybe be grouped and method split up.
+    # rubocop:disable Metrics/MethodLength
+    def apply_roll_to_total(roll_reason, roll_result)
+      case roll_reason
+      when :basic, :reroll_new_die, :reroll_new_keeper, :reroll_replace
+        @total = roll_result
+      when :reroll_add
+        @total += roll_result
+      when :reroll_subtract
+        @total -= roll_result
+      when :reroll_use_best
+        @total = [@value, roll_result].max
+      when :reroll_use_worst
+        @total = [@value, roll_result].min
+      end
     end
+    # rubocop:enable Metrics/MethodLength
 
-    # @!visibility private
-    # multiplication uses #value
-    def *(other)
-      @value * other
+    def init_with_result(first_roll_result, first_roll_reason)
+      @rolls = [Integer(first_roll_result)]
+      @roll_reasons = [first_roll_reason]
+      @total = @rolls[0]
     end
 
-    # @!visibility private
-    # comparison <=> uses #value
-    def <=>(other)
-      value <=> other
+    def init_empty
+      @rolls = []
+      @roll_reasons = []
+      @total = nil
     end
 
-    # This is a deep clone, all attributes are cloned.
-    # @return [GamesDice::DieResult]
-    def clone
-      cloned = GamesDice::DieResult.new
-      cloned.instance_variable_set('@rolls', @rolls.clone)
-      cloned.instance_variable_set('@roll_reasons', @roll_reasons.clone)
-      cloned.instance_variable_set('@total', @total)
-      cloned.instance_variable_set('@value', @value)
-      cloned.instance_variable_set('@mapped', @mapped)
-      cloned.instance_variable_set('@map_description', @map_description)
-      cloned
+    def explain_value_multiple_rolls
+      text = "[#{@rolls[0]}"
+      text = (1..(@rolls.length - 1)).inject(text) do |so_far, i|
+        so_far + GamesDice::REROLL_TYPES[@roll_reasons[i]] + @rolls[i].to_s
+      end
+      text + "] #{@total}"
     end
   end
 end

data/lib/games_dice/marshal.rb

@@ -1,17 +1,40 @@
 # frozen_string_literal: true
 
 module GamesDice
-  # Probability calculations
+  # This class models probability distributions for dice systems.
+  #
+  # An object of this class represents a single distribution, which might be the result of a complex
+  # combination of dice.
+  #
+  # @example Distribution for a six-sided die
+  #  probs = GamesDice::Probabilities.for_fair_die( 6 )
+  #  probs.min # => 1
+  #  probs.max # => 6
+  #  probs.expected # => 3.5
+  #  probs.p_ge( 4 ) # => 0.5
+  #
+  # @example Adding two distributions
+  #  pd6 = GamesDice::Probabilities.for_fair_die( 6 )
+  #  probs = GamesDice::Probabilities.add_distributions( pd6, pd6 )
+  #  probs.min # => 2
+  #  probs.max # => 12
+  #  probs.expected # => 7.0
+  #  probs.p_ge( 10 ) # => 0.16666666666666669
+  #
   class Probabilities
     # @!visibility private
     # Adds support for Marshal, via to_h and from_h methods
-    def _dump(*_ignored)
-      Marshal.dump to_h
+    def marshal_dump
+      to_h
     end
 
     # @!visibility private
     def self._load(buf)
+      # Use of Marshal for general-purpose object serialisation is discouraged. However, this class does support
+      # it for backwards-compatibility.
+      # rubocop:disable Security/MarshalLoad
       h = Marshal.load buf
+      # rubocop:enable Security/MarshalLoad
       from_h h
     end
   end