games_dice 0.4.2 → 0.6.0

data/lib/games_dice/complex_die_helpers.rb

@@ -3,125 +3,32 @@
 module GamesDice
   class ComplexDie
     # @!visibility private
-    # Private extension methods for GamesDice::ComplexDie probability calculations
+    # Private cache handling for bounded probability calculations.
     module ProbabilityHelpers
       private
 
-      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
-
-      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
-
-      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
-
-      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 probabilities_for_budget(limit)
+        refresh_recipe
+        return cached_probabilities if valid_probability_cache?(limit)
 
-      def conintue_recursing?(stack, rule_idx)
-        if stack.depth >= 20 || stack.prior_probability < 1.0e-16
-          @probabilities_complete = false
-          return false
+        with_recipe do
+          cache_calculation(ProbabilityCalculation.new(self, limit))
         end
-
-        !rule_idx.nil?
+      rescue StandardError
+        @probabilities_complete = nil
+        raise
       end
 
-      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)
+      def cached_probabilities
+        @probabilities_complete = @probability_error.zero?
+        @probabilities
       end
 
-      def end_recursion_store_probs(stack, result_so_far)
-        t = result_so_far.total
-        stack.probabilities[t] ||= 0.0
-        stack.probabilities[t] += stack.prior_probability
-      end
-
-      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
-
-        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]
+      def cache_calculation(calculation)
+        distribution = calculation.calculate
+        @probability_error = calculation.error
+        @probabilities_complete = @probability_error.zero?
+        @probabilities = distribution
       end
     end
 
@@ -130,21 +37,21 @@ module GamesDice
     module RollHelpers
       private
 
-      def roll_apply_rerolls
-        return unless @rerolls
+      def roll_apply_rerolls(rules)
+        return unless rules
 
         subtracting = false
-        rerolls_remaining = @rerolls.map(&:limit)
+        rerolls_remaining = rules.map(&:limit)
 
-        rerolls_loop(subtracting, rerolls_remaining)
+        rerolls_loop(subtracting, rerolls_remaining, rules)
       end
 
-      def rerolls_loop(subtracting, rerolls_remaining)
+      def rerolls_loop(subtracting, rerolls_remaining, rules)
         loop do
-          rule_idx = find_matching_reroll_rule(@basic_die.result, @result.rolls.length, rerolls_remaining)
+          rule_idx = find_matching_reroll_rule(@basic_die.result, @result.rolls.length, rerolls_remaining, nil, rules)
           break unless rule_idx
 
-          rule = @rerolls[rule_idx]
+          rule = rules[rule_idx]
           rerolls_remaining[rule_idx] -= 1
           subtracting = true if rule.type == :reroll_subtract
           roll_apply_reroll_rule rule, subtracting
@@ -161,32 +68,36 @@ module GamesDice
       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
+      def find_matching_reroll_rule(check_value, num_rolls, rerolls_remaining, budget = nil, rules = @rerolls)
+        return unless rules
+
+        rules.each_with_index do |rule, index|
+          next unless available_reroll?(rule, num_rolls, rerolls_remaining[index])
 
-          remaining.positive? && rule.applies?(check_value)
+          budget&.predicate
+          return index if rule.applies?(check_value)
         end
+        nil
+      end
+
+      def available_reroll?(rule, num_rolls, remaining)
+        remaining.positive? && !(rule.type == :reroll_subtract && num_rolls > 1)
       end
 
-      def roll_apply_maps
-        return unless @maps
+      def roll_apply_maps(maps)
+        return unless maps
 
-        m, n = calc_maps(@result.value)
-        @result.apply_map(m, n)
+        m, n = calc_maps(@result.value, nil, maps)
+        @result.apply_map(m, n.dup)
       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
+      def calc_maps(original_value, budget = nil, maps = @maps)
+        maps.each do |rule|
+          budget&.predicate
+          mapped = rule.map_from(original_value)
+          return [mapped, rule.mapped_name] if mapped
         end
-        [y, n]
+        [0, '']
       end
     end
 
@@ -196,12 +107,66 @@ module GamesDice
       private
 
       def calc_minmax
-        @min_result = probabilities.min
-        @max_result = probabilities.max
-        return if @probabilities_complete
+        cheap = cheap_minmax
+        if cheap
+          @min_result, @max_result = cheap
+        else
+          calculate_minmax
+        end
+      end
+
+      def calculate_minmax
+        distribution = probabilities
+        if @probabilities_complete
+          @min_result = distribution.min
+          @max_result = distribution.max
+        else
+          @min_result, @max_result = logical_minmax
+        end
+      rescue ProbabilityLimitError
+        @min_result, @max_result = safe_minmax
+      end
+
+      def cheap_minmax
+        return if @maps
+        return [1, sides] if !@rerolls || @rerolls.empty?
+        return unless @rerolls.one?
+
+        rule = @rerolls.first
+        return unless rule.instance_of?(RerollRule) && ProbabilityShortcuts.boolean_rule?(rule)
+
+        cheap_rule_minmax(rule)
+      end
+
+      def cheap_rule_minmax(rule)
+        return [1, sides] if rule.type == :reroll_replace
+        return unless sides == 1 && rule.type == :reroll_add
 
-        logical_min, logical_max = logical_minmax
-        @min_result, @max_result = [@min_result, @max_result, logical_min, logical_max].minmax
+        value = 1 + (rule.applies?(1) ? [rule.limit, 0].max : 0)
+        [value, value]
+      end
+
+      def safe_minmax
+        return safe_mapped_minmax if @maps
+
+        adds = positive_rule_limits(:reroll_add)
+        subtracts = positive_rule_limits(:reroll_subtract)
+        return [1, sides * (1 + adds)] if subtracts.zero?
+
+        maximum = sides * (1 + adds + subtracts)
+        [-maximum, maximum]
+      end
+
+      def safe_mapped_minmax
+        unless @maps.all? { |rule| rule.instance_of?(MapRule) && ProbabilityShortcuts.boolean_rule?(rule) }
+          raise ProbabilityLimitError, 'Cannot establish finite dice bounds within calculation limits'
+        end
+
+        [0, *@maps.map(&:mapped_value)].minmax
+      end
+
+      def positive_rule_limits(type)
+        (@rerolls || []).sum { |rule| rule.type == type ? [rule.limit, 0].max : 0 }
       end
 
       def minmax_mappings(possible_values)
@@ -216,15 +181,28 @@ module GamesDice
       # 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
+        return safe_minmax unless inexpensive_bounds?
 
         min_result, max_result = logical_rerolls_minmax
-        return minmax_mappings(min_result..max_result) if @maps
+        if @maps
+          return safe_minmax if (max_result - min_result + 1) * @maps.length > ProbabilityBudget::MAX_PREDICATES
+
+          return minmax_mappings(min_result..max_result)
+        end
 
         [min_result, max_result]
       end
 
+      def inexpensive_bounds?
+        rules = [*(@rerolls || []), *(@maps || [])]
+        rules.all? { |rule| ordinary_boolean_rule?(rule) } &&
+          sides * rules.length <= ProbabilityBudget::MAX_FACES
+      end
+
+      def ordinary_boolean_rule?(rule)
+        (rule.instance_of?(RerollRule) || rule.instance_of?(MapRule)) && ProbabilityShortcuts.boolean_rule?(rule)
+      end
+
       def logical_rerolls_minmax
         min_result = @basic_die.min
         max_result = @basic_die.max
@@ -251,7 +229,7 @@ module GamesDice
           max_reroll = @basic_die.all_values.select { |v| rule.applies?(v) }.max
           next unless max_reroll
 
-          total_add += max_reroll * rule.limit
+          total_add += max_reroll * [rule.limit, 0].max
         end
         total_add
       end

data/lib/games_dice/dice.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'games_dice/dice_helpers'
+
 module GamesDice
   # This class models a combination of GamesDice::Bunch objects plus a fixed offset.
   #
@@ -20,6 +22,9 @@ module GamesDice
   #  d.explain_result # => "2d20: 4, 16. Keep: 16. 16 + 5 = 21"
   #
   class Dice
+    include RecipeQueries
+    include ProbabilityHelpers
+
     # The first parameter is an array of values that are passed to GamesDice::Bunch constructors.
     # @param [Array<Hash>] bunches Array of options for creating bunches
     # @param [Integer] offset Total offset
@@ -43,6 +48,7 @@ module GamesDice
       @bunches = bunches.map { |b| GamesDice::Bunch.new(b) }
       @bunch_multipliers = bunches.map { |b| b[:multiplier] || 1 }
       @result = nil
+      initialize_recipe
     end
 
     # Name to help identify dice
@@ -64,26 +70,35 @@ module GamesDice
 
     # Result of most-recent roll, or nil if no roll made yet.
     # @return [Integer,nil]
-    attr_reader :result
+    def result
+      refresh_recipe
+      @result
+    end
 
     # Simulates rolling dice
     # @return [Integer] Sum of all rolled dice
     def roll
-      @result = @offset + bunches_weighted_sum(:roll)
+      with_recipe { @result = @offset + bunches_weighted_sum(:roll) }
     end
 
     # @!attribute [r] min
-    # Minimum possible result from a call to #roll
+    # Lower bound on the value returned by #roll. No roll will be below this value.
+    # For some complex dice, this may be lower than any value that can actually
+    # be rolled, because calculating the exact minimum would take too much work.
     # @return [Integer]
     def min
-      @min ||= @offset + bunches_weighted_sum(:min)
+      refresh_recipe
+      @min ||= with_recipe { @offset + weighted_bound(:min, :max) }
     end
 
     # @!attribute [r] max
-    # Maximum possible result from a call to #roll
+    # Upper bound on the value returned by #roll. No roll will exceed this value.
+    # For some complex dice, this may be higher than any value that can actually
+    # be rolled, because calculating the exact maximum would take too much work.
     # @return [Integer]
     def max
-      @max ||= @offset + bunches_weighted_sum(:max)
+      refresh_recipe
+      @max ||= with_recipe { @offset + weighted_bound(:max, :min) }
     end
 
     # @!attribute [r] minmax
@@ -93,22 +108,27 @@ module GamesDice
       [min, max]
     end
 
-    # Calculates the probability distribution for the dice. When the dice include components with
-    # open-ended re-roll rules, there are some arbitrary limits imposed to prevent large amounts of
-    # recursion.
-    # @return [GamesDice::Probabilities] Probability distribution of dice.
+    # Calculates the probability distribution for the combined dice result.
+    #
+    # Very unlikely sequences of rerolls may be left out to keep calculation
+    # time reasonable. This changes the probability of any combined result by
+    # at most 1e-10 (one in ten billion), in addition to normal floating-point
+    # rounding. This limit covers all the bunches together.
+    #
+    # Raises ProbabilityLimitError if this accuracy cannot be achieved within
+    # the calculation's work limits.
+    # @return [GamesDice::Probabilities] Probability distribution of the dice.
     def probabilities
-      return @probabilities if @probabilities
+      refresh_recipe
+      return @probabilities if valid_probability_cache?(ProbabilityBudget::LIMIT)
 
-      @bunch_multipliers.zip(@bunches).inject(GamesDice::Probabilities.new([1.0], @offset)) do |probs, mb|
-        m, b = mb
-        GamesDice::Probabilities.add_distributions_mult(1, probs, m, b.probabilities)
-      end
+      @probabilities = with_recipe { combined_probabilities }
     end
 
     # @!attribute [r] explain_result
     # @return [String,nil] Explanation of result, or nil if no call to #roll yet.
     def explain_result
+      refresh_recipe
       return nil unless @result
 
       explanations = @bunches.map { |bunch| "#{bunch.label}: #{bunch.explain_result}" }
@@ -122,10 +142,34 @@ module GamesDice
 
     private
 
+    def recipe_sources
+      [[@bunches, Bunch], [@bunch_multipliers, Numeric]]
+    end
+
+    def recipe_labels
+      [@name]
+    end
+
+    def validate_recipe
+      return if @bunches.length == @bunch_multipliers.length
+
+      raise ArgumentError, 'bunches and bunch_multipliers must have the same length'
+    end
+
+    def weighted_bound(positive, negative)
+      @bunches.zip(@bunch_multipliers).sum do |bunch, multiplier|
+        next 0 if multiplier.zero?
+
+        multiplier * bunch.public_send(multiplier.negative? ? negative : positive)
+      end
+    end
+
     def simple_explanation(explanation)
-      return explanation if @offset.zero?
+      return explanation if @offset.zero? && @bunch_multipliers[0] == 1
 
-      "#{explanation}. #{array_to_sum([@bunches[0].result, @offset])}"
+      values = [@bunch_multipliers[0] * @bunches[0].result]
+      values << @offset unless @offset.zero?
+      "#{explanation}. #{array_to_sum(values)}"
     end
 
     def multi_explanations(explanations)

data/lib/games_dice/dice_helpers.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module GamesDice
+  class Dice
+    # @!visibility private
+    # Private combination helpers sharing one truncation budget across bunches.
+    module ProbabilityHelpers
+      Combination = Struct.new(:distribution, :error)
+      private_constant :Combination
+
+      private
+
+      def combined_probabilities
+        per_die = ProbabilityBudget.share(ProbabilityBudget::LIMIT, [probability_dice_count, 1].max)
+        result = Combination.new(Probabilities.new([1.0], @offset), 0.0)
+        @bunches.zip(@bunch_multipliers).each do |bunch, multiplier|
+          next if multiplier.zero?
+
+          component = component_probabilities(bunch, per_die, result)
+          result.distribution = Probabilities.add_distributions_mult(1, result.distribution, multiplier, component)
+        end
+        @probability_error = ProbabilityBudget.check(result.error, ProbabilityBudget::LIMIT)
+        result.distribution
+      end
+
+      def probability_dice_count
+        @bunches.each_with_index.sum { |bunch, index| @bunch_multipliers[index].zero? ? 0 : bunch.ndice }
+      end
+
+      def component_probabilities(bunch, per_die, result)
+        component = bunch.__send__(:probabilities_for_budget, (per_die * bunch.ndice).prev_float)
+        result.error = ProbabilityBudget.add(result.error, bunch.instance_variable_get(:@probability_error))
+        component
+      end
+    end
+  end
+end

data/lib/games_dice/die_result.rb

@@ -164,9 +164,6 @@ module GamesDice
 
     private
 
-    # 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
@@ -175,13 +172,14 @@ module GamesDice
         @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
+      when :reroll_use_best, :reroll_use_worst
+        @total = select_roll(roll_reason, roll_result)
       end
     end
-    # rubocop:enable Metrics/MethodLength
+
+    def select_roll(roll_reason, roll_result)
+      roll_reason == :reroll_use_best ? [@value, roll_result].max : [@value, roll_result].min
+    end
 
     def init_with_result(first_roll_result, first_roll_reason)
       @rolls = [Integer(first_roll_result)]

data/lib/games_dice/marshal.rb

@@ -29,13 +29,8 @@ module GamesDice
     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
+    def marshal_load(distribution)
+      initialize_copy(self.class.from_h(distribution))
     end
   end
 end

data/lib/games_dice/parser.rb

@@ -92,6 +92,9 @@ module GamesDice
     # @!visibility private
     class ParseTreeProcessor
       class << self
+        # Collects dice terms into constructor options, leaving constant terms for {collect_offset}.
+        # @param [Hash] dice_expressions Parsed expression tree.
+        # @return [Array<Hash>] Options for each GamesDice::Bunch.
         def collect_bunches(dice_expressions)
           dice_expressions[:bunches].select { |h| h[:ndice] }.map do |in_hash|
             out_hash = {}
@@ -106,6 +109,10 @@ module GamesDice
           end
         end
 
+        # Copies the parsed number of dice and sides into constructor options as integers.
+        # @param [Hash] in_hash Parsed dice term.
+        # @param [Hash] out_hash Constructor options to update.
+        # @return [Array<Symbol>] The processed field names.
         def collect_bunch_basics(in_hash, out_hash)
           %i[ndice sides].each do |s|
             next unless in_hash[s]
@@ -114,6 +121,10 @@ module GamesDice
           end
         end
 
+        # Converts a term's sign to its numeric multiplier.
+        # @param [Hash] in_hash Parsed dice term with an :op entry.
+        # @param [Hash] out_hash Constructor options to update.
+        # @return [Integer,nil] Multiplier, or nil for an unknown operator.
         def collect_bunch_multiplier(in_hash, out_hash)
           optype = in_hash[:op].to_s
           out_hash[:multiplier] = case optype
@@ -122,6 +133,10 @@ module GamesDice
                                   end
         end
 
+        # Dispatches a parsed modifier to its alias, keeper, map, or reroll collector.
+        # @param [Hash] mod Parsed modifier.
+        # @param [Hash] out_hash Constructor options to update.
+        # @return [Object] Result of the selected collector, or nil for an unknown modifier.
         def collect_bunch_modifier(mod, out_hash)
           if mod[:alias]
             ParseTreeBunchModifier.collect_alias_modifier mod, out_hash
@@ -134,6 +149,9 @@ module GamesDice
           end
         end
 
+        # Sums signed constant terms separately from dice terms.
+        # @param [Hash] dice_expressions Parsed expression tree.
+        # @return [Integer] Fixed offset for GamesDice::Dice.
         def collect_offset(dice_expressions)
           dice_expressions[:bunches].select { |h| h[:constant] }.inject(0) do |total, in_hash|
             c = in_hash[:constant].to_i
@@ -173,6 +191,11 @@ module GamesDice
           collect_complex_reroll_rule(reroll_mod, out_hash)
         end
 
+        # Appends a reroll rule, reversing the comparison and preserving an explicit limit.
+        # Omitted types default to replacement; an omitted limit uses RerollRule's default.
+        # @param [Hash] reroll_mod Parsed long-form reroll modifier.
+        # @param [Hash] out_hash Constructor options with an initialized :rerolls array.
+        # @return [Array<Array>] Updated reroll rules.
         def collect_complex_reroll_rule(reroll_mod, out_hash)
           # Typical reroll_mod: {:reroll=>"r"@5, :condition=>{:compare_num=>"10"@7}, :type=>"add"@10}
           op = get_op_symbol(reroll_mod[:condition][:comparison] || '==')
@@ -212,6 +235,10 @@ module GamesDice
           collect_complex_map_rule(map_mod, out_hash)
         end
 
+        # Appends a map rule, defaulting to a threshold comparison and a mapped value of one.
+        # @param [Hash] map_mod Parsed long-form map modifier, optionally including a label.
+        # @param [Hash] out_hash Constructor options with an initialized :maps array.
+        # @return [Array<Array>] Updated map rules.
         def collect_complex_map_rule(map_mod, out_hash)
           # Typical map_mod: {:map=>"m"@4, :condition=>{:compare_num=>"5"@6}, :num=>"2"@8, :output=>"Qwerty"@10}
           op = get_op_symbol(map_mod[:condition][:comparison] || '>=')
@@ -236,6 +263,9 @@ module GamesDice
           '<=' => :>=
         }.freeze
 
+        # Reverses a notation comparison for rules that send the operator to the trigger value.
+        # @param [#to_s] parsed_op_string Comparison from the parse tree.
+        # @return [Symbol,nil] Reversed operator, or nil for an unknown comparison.
         def get_op_symbol(parsed_op_string)
           OP_CONVERSION[parsed_op_string.to_s]
         end