latticerb 0.1.0

data/lib/lattice/constraints.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+require "set"
+
+require_relative "model"
+
+module Lattice
+  class ConstraintError < StandardError; end
+
+  # Compiles model constraints into invalid-pair / requirement closures and
+  # answers feasibility questions over partial assignments. Assignments are
+  # referenced as `[parameter_index, value_index]` pairs; partial assignments
+  # are `{parameter_index => value_index}` hashes.
+  class ConstraintEngine
+    EMPTY_SET = Set.new.freeze
+
+    attr_reader :model, :forced_interactions
+
+    def initialize(model)
+      @model = model
+      @parameter_index = model.parameters.each_with_index.to_h { |parameter, index| [parameter.name, index] }
+      @value_index = {}
+      model.parameters.each_with_index do |parameter, parameter_idx|
+        parameter.values.each_with_index do |value, value_idx|
+          @value_index[[parameter_idx, value]] = value_idx
+        end
+      end
+      @invalid_pairs = {}
+      @requires = {}
+      @higher_order = []
+      @forced_interactions = []
+      @feasibility_cache = {}
+      compile_constraints
+      compute_implied_pairs
+      validate_compiled_constraints
+    end
+
+    def conflicts?(left, right)
+      invalid_pairs_for(to_ref(left)).include?(to_ref(right))
+    end
+
+    def implied_requirements(assignment)
+      requires_for(to_ref(assignment)).map { |ref| from_ref(ref) }.sort
+    end
+
+    def can_complete?(partial)
+      normalized = normalize_partial(partial.dup)
+      return false if normalized.nil?
+
+      signature = normalized.sort
+      cached = @feasibility_cache[signature]
+      return cached unless cached.nil?
+
+      result = !backtrack_complete(normalized, rng: nil, failures: Set.new).nil?
+      @feasibility_cache[signature] = result
+      result
+    end
+
+    def complete_assignment(partial, rng: nil)
+      normalized = normalize_partial(partial.dup)
+      return nil if normalized.nil?
+
+      backtrack_complete(normalized, rng:, failures: Set.new)
+    end
+
+    def complete_assignment_valid?(row)
+      partial = row.each_with_index.to_h { |value_index, parameter_index| [parameter_index, value_index] }
+      normalized = normalize_partial(partial)
+      return false if normalized.nil? || normalized.length != model.parameters.length
+
+      @higher_order.each do |antecedents, forbidden|
+        if antecedents.all? { |parameter_index, value_index| normalized[parameter_index] == value_index }
+          return false if normalized[forbidden[0]] == forbidden[1]
+        end
+      end
+      true
+    end
+
+    private
+
+    def compile_constraints
+      model.constraints.each do |constraint|
+        case constraint
+        when InvalidPairConstraint
+          add_invalid_pair(to_ref(constraint.if_assignment), to_ref(constraint.then_not))
+        when BidirectionalConstraint
+          left_ref, right_ref = constraint.pair.map { |assignment| to_ref(assignment) }
+          add_requirement(left_ref, right_ref)
+          add_requirement(right_ref, left_ref)
+          exclude_other_values(left_ref, right_ref)
+          exclude_other_values(right_ref, left_ref)
+        when ForwardDependencyConstraint
+          source_ref = to_ref(constraint.source)
+          target_ref = to_ref(constraint.target)
+          add_requirement(source_ref, target_ref)
+          exclude_other_values(source_ref, target_ref)
+        when ConditionalConstraint
+          compile_conditional(constraint)
+        when ForcedConstraint
+          @forced_interactions << constraint.assignments.map { |assignment| to_ref(assignment) }
+        when HigherOrderConstraint
+          antecedents = constraint.if_all.map { |assignment| to_ref(assignment) }
+          @higher_order << [antecedents, to_ref(constraint.then_not)]
+        end
+      end
+    end
+
+    def compile_conditional(constraint)
+      parent_index = @parameter_index.fetch(constraint.parent)
+      child_index = @parameter_index.fetch(constraint.parameter)
+      parent = model.parameters[parent_index]
+      child = model.parameters[child_index]
+      applicable_values = Set.new(constraint.applies_when)
+      na_ref = [child_index, @value_index.fetch([child_index, NA_VALUE])]
+
+      parent.values.each_with_index do |parent_value, parent_value_index|
+        parent_ref = [parent_index, parent_value_index]
+        if applicable_values.include?(parent_value)
+          add_invalid_pair(parent_ref, na_ref)
+          next
+        end
+
+        child.values.each_with_index do |child_value, child_value_index|
+          next if child_value == NA_VALUE
+
+          add_invalid_pair(parent_ref, [child_index, child_value_index])
+        end
+      end
+    end
+
+    def compute_implied_pairs
+      changed = true
+      all_assignments = all_assignment_refs
+      while changed
+        changed = false
+
+        all_assignments.each do |assignment|
+          implied = requires_for(assignment).dup
+          implied.to_a.each do |required|
+            implied.merge(requires_for(required))
+          end
+          unless (implied - requires_for(assignment)).empty?
+            (@requires[assignment] ||= Set.new).merge(implied)
+            changed = true
+          end
+        end
+
+        all_assignments.each do |assignment|
+          additions = Set.new
+          invalid_pairs_for(assignment).to_a.each do |conflicting|
+            additions.merge(requires_for(conflicting))
+          end
+          requires_for(assignment).to_a.each do |required|
+            additions.merge(invalid_pairs_for(required))
+          end
+          additions.delete(assignment)
+          additions.each do |addition|
+            unless invalid_pairs_for(assignment).include?(addition)
+              add_invalid_pair(assignment, addition)
+              changed = true
+            end
+          end
+        end
+      end
+    end
+
+    def validate_compiled_constraints
+      all_assignment_refs.each do |assignment|
+        if invalid_pairs_for(assignment).include?(assignment)
+          readable = from_ref(assignment)
+          raise ConstraintError, "Constraint closure makes `#{readable.parameter}=#{readable.value}` impossible."
+        end
+
+        requires_for(assignment).each do |required|
+          if assignment[0] == required[0] && assignment[1] != required[1]
+            left = from_ref(assignment)
+            right = from_ref(required)
+            raise ConstraintError,
+                  "Constraint closure requires incompatible values `#{left.parameter}=#{left.value}` and `#{right.parameter}=#{right.value}`."
+          end
+          if invalid_pairs_for(assignment).include?(required)
+            left = from_ref(assignment)
+            right = from_ref(required)
+            raise ConstraintError,
+                  "Constraint closure makes `#{left.parameter}=#{left.value}` conflict with its own requirement `#{right.parameter}=#{right.value}`."
+          end
+        end
+      end
+
+      @forced_interactions.each do |forced|
+        partial = forced.to_h { |parameter_index, value_index| [parameter_index, value_index] }
+        next unless complete_assignment(partial, rng: nil).nil?
+
+        assignments = forced.map do |parameter_index, value_index|
+          parameter = model.parameters[parameter_index]
+          "#{parameter.name}=#{parameter.values[value_index]}"
+        end.join(", ")
+        raise ConstraintError, "Forced interaction is not feasible: #{assignments}."
+      end
+    end
+
+    def normalize_partial(partial)
+      normalized = partial.dup
+      changed = true
+      while changed
+        changed = false
+        return nil unless partial_consistent?(normalized)
+
+        normalized.to_a.each do |parameter_index, value_index|
+          requires_for([parameter_index, value_index]).each do |required_parameter, required_value|
+            current = normalized[required_parameter]
+            if current.nil?
+              normalized[required_parameter] = required_value
+              changed = true
+            elsif current != required_value
+              return nil
+            end
+          end
+        end
+      end
+      return nil unless partial_consistent?(normalized)
+
+      normalized
+    end
+
+    def partial_consistent?(partial)
+      partial.each do |parameter_index, value_index|
+        partial.each do |other_parameter, other_value|
+          next if parameter_index == other_parameter
+
+          return false if invalid_pairs_for([parameter_index, value_index]).include?([other_parameter, other_value])
+        end
+      end
+
+      @higher_order.each do |antecedents, forbidden|
+        if antecedents.all? { |parameter_index, value_index| partial[parameter_index] == value_index }
+          return false if partial[forbidden[0]] == forbidden[1]
+        end
+      end
+      true
+    end
+
+    def backtrack_complete(partial, rng:, failures:)
+      signature = partial.sort
+      return nil if failures.include?(signature)
+
+      if partial.length == model.parameters.length
+        row = (0...model.parameters.length).map { |index| partial.fetch(index) }
+        return complete_assignment_valid?(row) ? row : nil
+      end
+
+      next_parameter, values = next_parameter_values(partial)
+      if next_parameter.nil?
+        failures.add(signature)
+        return nil
+      end
+
+      ordered_values(next_parameter, values, rng).each do |value|
+        candidate = partial.dup
+        candidate[next_parameter] = value
+        normalized = normalize_partial(candidate)
+        next if normalized.nil?
+
+        result = backtrack_complete(normalized, rng:, failures:)
+        return result unless result.nil?
+      end
+
+      failures.add(signature)
+      nil
+    end
+
+    def next_parameter_values(partial)
+      best_parameter = nil
+      best_values = []
+      best_size = nil
+
+      model.parameters.each_with_index do |parameter, parameter_index|
+        next if partial.key?(parameter_index)
+
+        feasible = []
+        (0...parameter.values.length).each do |value_index|
+          candidate = partial.dup
+          candidate[parameter_index] = value_index
+          feasible << value_index unless normalize_partial(candidate).nil?
+        end
+
+        return [nil, []] if feasible.empty?
+
+        if best_size.nil? || feasible.length < best_size
+          best_parameter = parameter_index
+          best_values = feasible
+          best_size = feasible.length
+        end
+      end
+
+      [best_parameter, best_values]
+    end
+
+    def ordered_values(parameter_index, values, rng)
+      parameter = model.parameters[parameter_index]
+      if rng.nil?
+        return values.sort_by { |value_index| [-parameter.normalized_weights[value_index], value_index] }
+      end
+
+      values
+        .map { |value_index| [rng.random / [parameter.normalized_weights[value_index], 1e-9].max, value_index] }
+        .sort
+        .map { |_, value_index| value_index }
+    end
+
+    def exclude_other_values(source, required)
+      target_parameter = model.parameters[required[0]]
+      (0...target_parameter.values.length).each do |value_index|
+        next if value_index == required[1]
+
+        add_invalid_pair(source, [required[0], value_index])
+      end
+    end
+
+    def add_invalid_pair(left, right)
+      (@invalid_pairs[left] ||= Set.new).add(right)
+      (@invalid_pairs[right] ||= Set.new).add(left)
+    end
+
+    def add_requirement(source, target)
+      (@requires[source] ||= Set.new).add(target)
+    end
+
+    def invalid_pairs_for(ref)
+      @invalid_pairs[ref] || EMPTY_SET
+    end
+
+    def requires_for(ref)
+      @requires[ref] || EMPTY_SET
+    end
+
+    def all_assignment_refs
+      refs = []
+      model.parameters.each_with_index do |parameter, parameter_index|
+        (0...parameter.values.length).each do |value_index|
+          refs << [parameter_index, value_index]
+        end
+      end
+      refs
+    end
+
+    def to_ref(assignment)
+      parameter_index = @parameter_index.fetch(assignment.parameter)
+      [parameter_index, @value_index.fetch([parameter_index, assignment.value])]
+    end
+
+    def from_ref(ref)
+      parameter = model.parameters[ref[0]]
+      Assignment.new(parameter: parameter.name, value: parameter.values[ref[1]])
+    end
+  end
+end

data/lib/lattice/formatters.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "csv"
+require "json"
+
+require_relative "ipog"
+require_relative "model"
+
+module Lattice
+  # Output rendering. Table, JSON, CSV, and summary formats are byte-identical
+  # to the Python implementation's output for the same model and result.
+  module Formatters
+    extend self
+
+    def render_output(model, result, output_format:, seed:)
+      case output_format
+      when "table" then format_table(model, result)
+      when "json" then format_json(model, result, seed:)
+      when "csv" then format_csv(model, result)
+      when "summary" then format_summary(model, result)
+      else
+        raise ArgumentError, "Unknown format `#{output_format}`."
+      end
+    end
+
+    def format_table(model, result)
+      rows = named_rows(model, result)
+      headers = ["#"] + model.parameter_names
+      body = rows.each_with_index.map do |row, index|
+        [(index + 1).to_s] + model.parameter_names.map { |name| row[name] }
+      end
+      widths = headers.each_index.map do |column|
+        ([headers[column].length] + body.map { |record| record[column].length }).max
+      end
+
+      lines = [headline(model, result), ""]
+      lines.concat(milestone_lines(result))
+      lines << ""
+      lines << headers.each_index.map do |column|
+        column.zero? ? headers[column].rjust(widths[column]) : headers[column].ljust(widths[column])
+      end.join(" | ")
+      lines << widths.map { |width| "-" * width }.join("-|-")
+
+      body.each do |record|
+        lines << record.each_index.map do |column|
+          column.zero? ? record[column].rjust(widths[column]) : record[column].ljust(widths[column])
+        end.join(" | ")
+      end
+      lines.join("\n")
+    end
+
+    def format_summary(model, result)
+      lines = [headline(model, result), ""]
+      lines.concat(milestone_lines(result))
+      lines.join("\n")
+    end
+
+    def format_json(model, result, seed:)
+      last_point = result.coverage_curve.last
+      payload = {
+        "meta" => {
+          "model_name" => model.model_name,
+          "strength" => model.strength,
+          "test_count" => result.rows.length,
+          "exhaustive_count" => model.exhaustive_count,
+          "reduction" => reduction_label(model.exhaustive_count, result.rows.length),
+          "coverage" => last_point ? format("%.1f%%", last_point.cumulative_pct) : "0.0%",
+          "seed" => seed
+        },
+        "coverage_curve" => result.coverage_curve.map do |point|
+          { "scenario" => point.scenario, "cumulative_pct" => point.cumulative_pct }
+        end,
+        "scenarios" => named_rows(model, result).each_with_index.map do |row, index|
+          {
+            "id" => index + 1,
+            "values" => model.parameter_names.to_h { |name| [name, row[name]] }
+          }
+        end
+      }
+      JSON.pretty_generate(payload, ascii_only: true)
+    end
+
+    def format_csv(model, result)
+      CSV.generate(row_sep: "\r\n") do |csv|
+        csv << model.parameter_names
+        named_rows(model, result).each do |row|
+          csv << model.parameter_names.map { |name| row[name] }
+        end
+      end.strip
+    end
+
+    def headline(model, result)
+      "Lattice — #{result.rows.length} scenarios (from #{thousands(model.exhaustive_count)} possible)"
+    end
+
+    def milestone_lines(result)
+      [50.0, 75.0, 90.0, 100.0].filter_map do |threshold|
+        point = result.coverage_curve.find { |candidate| candidate.cumulative_pct >= threshold }
+        "  #{threshold.to_i}% coverage at scenario ##{point.scenario}" if point
+      end
+    end
+
+    def named_rows(model, result)
+      result.rows.map do |row|
+        model.parameters.each_with_index.to_h do |parameter, index|
+          [parameter.name, parameter.values[row[index]]]
+        end
+      end
+    end
+
+    def reduction_label(exhaustive_count, scenario_count)
+      return "inf" if scenario_count.zero?
+
+      reduction = exhaustive_count.to_f / scenario_count
+      if (reduction - reduction.round).abs < 1e-9
+        "#{reduction.round(half: :even)}x"
+      else
+        format("%.1fx", reduction)
+      end
+    end
+
+    def thousands(count)
+      count.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\1,').reverse
+    end
+  end
+end

data/lib/lattice/ipog.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "set"
+
+require_relative "constraints"
+require_relative "mersenne_twister"
+
+module Lattice
+  CoveragePoint = Data.define(:scenario, :cumulative_pct)
+  GenerationResult = Data.define(:rows, :coverage_curve, :total_valid_tuples)
+  GenerationProgress = Data.define(:event, :scenario, :covered, :total, :cumulative_pct, :uncovered)
+
+  # Greedy covering-array generation (IPOG-style): enumerate every valid
+  # t-way interaction, then repeatedly extend the lowest uncovered tuple into
+  # the highest-scoring full row from a seeded candidate pool. Deterministic
+  # for a given seed, and row-for-row identical to the Python implementation.
+  module IPOG
+    extend self
+
+    def generate_covering_array(
+      model,
+      strength: nil,
+      seed: 42,
+      pool_size: 50,
+      progress: nil,
+      max_rows: nil,
+      stop_after_coverage: nil
+    )
+      actual_strength = strength || model.strength
+      raise ArgumentError, "`pool_size` must be at least 1." if pool_size < 1
+      raise ArgumentError, "`max_rows` must be at least 1." if !max_rows.nil? && max_rows < 1
+
+      coverage_target = coverage_target_for(stop_after_coverage)
+
+      engine = ConstraintEngine.new(model)
+      raise ArgumentError, "Model has no valid full assignments." unless engine.can_complete?({})
+
+      valid_tuples = enumerate_valid_tuples(model, engine, actual_strength, progress:)
+      uncovered = Set.new(valid_tuples)
+      rows = []
+      coverage_points = []
+      rng = MersenneTwister.new(seed)
+      limit_reached = false
+      progress&.call(
+        GenerationProgress.new(
+          event: "enumerated",
+          scenario: 0,
+          covered: 0,
+          total: valid_tuples.length,
+          cumulative_pct: coverage_pct(0, valid_tuples.length),
+          uncovered: uncovered.length
+        )
+      )
+
+      record_row = lambda do |row|
+        newly_covered = covered_tuples(row, actual_strength, uncovered)
+        rows << row
+        uncovered.subtract(newly_covered)
+        covered = valid_tuples.length - uncovered.length
+        cumulative_pct = coverage_pct(covered, valid_tuples.length)
+        coverage_points << CoveragePoint.new(scenario: rows.length, cumulative_pct:)
+        progress&.call(
+          GenerationProgress.new(
+            event: "scenario",
+            scenario: rows.length,
+            covered:,
+            total: valid_tuples.length,
+            cumulative_pct:,
+            uncovered: uncovered.length
+          )
+        )
+        if should_stop?(rows.length, cumulative_pct, max_rows, coverage_target)
+          progress&.call(
+            GenerationProgress.new(
+              event: "stopped",
+              scenario: rows.length,
+              covered:,
+              total: valid_tuples.length,
+              cumulative_pct:,
+              uncovered: uncovered.length
+            )
+          )
+          true
+        else
+          false
+        end
+      end
+
+      engine.forced_interactions.each do |forced|
+        partial = forced.to_h { |parameter_index, value_index| [parameter_index, value_index] }
+        row = best_candidate_row(model, engine, partial, uncovered, actual_strength, pool_size, rng)
+        next if row.nil? || rows.include?(row)
+
+        if record_row.call(row)
+          limit_reached = true
+          break
+        end
+      end
+
+      while !uncovered.empty? && !limit_reached
+        seed_tuple = uncovered.min
+        partial = seed_tuple.to_h { |parameter_index, value_index| [parameter_index, value_index] }
+        row = best_candidate_row(model, engine, partial, uncovered, actual_strength, pool_size, rng)
+        raise "Unable to complete uncovered tuple: #{seed_tuple.inspect}" if row.nil?
+
+        if record_row.call(row)
+          limit_reached = true
+          break
+        end
+      end
+
+      GenerationResult.new(
+        rows: rows.freeze,
+        coverage_curve: coverage_points.freeze,
+        total_valid_tuples: valid_tuples.length
+      )
+    end
+
+    def enumerate_valid_tuples(model, engine, strength, progress: nil)
+      tuples = []
+      total_candidates = candidate_tuple_count(model, strength)
+      checked = 0
+      report = lambda do
+        progress&.call(
+          GenerationProgress.new(
+            event: "enumerating",
+            scenario: 0,
+            covered: checked,
+            total: total_candidates,
+            cumulative_pct: coverage_pct(checked, total_candidates),
+            uncovered: [0, total_candidates - checked].max
+          )
+        )
+      end
+
+      (0...model.parameters.length).to_a.combination(strength) do |parameter_combo|
+        domains = parameter_combo.map { |parameter_index| (0...model.parameters[parameter_index].values.length).to_a }
+        domains[0].product(*domains[1..]) do |value_combo|
+          checked += 1
+          partial = parameter_combo.each_with_index.to_h { |parameter_index, offset| [parameter_index, value_combo[offset]] }
+          tuples << parameter_combo.zip(value_combo) if engine.can_complete?(partial)
+          report.call if progress && (checked % 1000).zero?
+        end
+      end
+      report.call if progress
+      tuples
+    end
+
+    def candidate_tuple_count(model, strength)
+      total = 0
+      (0...model.parameters.length).to_a.combination(strength) do |parameter_combo|
+        total += parameter_combo.inject(1) { |count, parameter_index| count * model.parameters[parameter_index].values.length }
+      end
+      total
+    end
+
+    def coverage_target_for(stop_after_coverage)
+      return nil if stop_after_coverage.nil?
+
+      unless stop_after_coverage.positive? && stop_after_coverage <= 100
+        raise ArgumentError, "`stop_after_coverage` must be in the range (0, 100]."
+      end
+      return nil if stop_after_coverage >= 100
+
+      stop_after_coverage
+    end
+
+    def should_stop?(row_count, cumulative_pct, max_rows, coverage_target)
+      return true if !max_rows.nil? && row_count >= max_rows
+      return true if !coverage_target.nil? && cumulative_pct >= coverage_target
+
+      false
+    end
+
+    def best_candidate_row(model, engine, partial, uncovered, strength, pool_size, rng)
+      candidates = {}
+      deterministic = engine.complete_assignment(partial, rng: nil)
+      candidates[deterministic] = score_row(model, deterministic, uncovered, strength) unless deterministic.nil?
+
+      (pool_size - 1).times do
+        attempt_rng = MersenneTwister.new(rng.getrandbits(64))
+        candidate = engine.complete_assignment(partial, rng: attempt_rng)
+        next if candidate.nil?
+
+        score = score_row(model, candidate, uncovered, strength)
+        previous = candidates[candidate]
+        candidates[candidate] = score if previous.nil? || (score <=> previous).positive?
+      end
+
+      return nil if candidates.empty?
+
+      candidates.max_by { |row, score| [score[0], score[1], reverse_lex(row)] }[0]
+    end
+
+    def score_row(model, row, uncovered, strength)
+      newly_covered = covered_tuples(row, strength, uncovered).length
+      weight_score = row.each_with_index.inject(0.0) do |acc, (value_index, parameter_index)|
+        acc + model.parameters[parameter_index].normalized_weights[value_index]
+      end
+      [newly_covered, weight_score]
+    end
+
+    def covered_tuples(row, strength, candidate_tuples)
+      covered = Set.new
+      (0...row.length).to_a.combination(strength) do |parameter_combo|
+        tuple_key = parameter_combo.map { |parameter_index| [parameter_index, row[parameter_index]] }
+        covered.add(tuple_key) if candidate_tuples.include?(tuple_key)
+      end
+      covered
+    end
+
+    def coverage_pct(covered_count, total_count)
+      return 100.0 if total_count.zero?
+
+      ((covered_count.to_f / total_count) * 100).round(1, half: :even)
+    end
+
+    def reverse_lex(row)
+      row.map(&:-@)
+    end
+  end
+end