rcas 0.2.0

data/lib/rcas/printer.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module RCAS
+  # Renders an expression tree as Ruby-flavoured infix text with the minimum
+  # number of parentheses needed to preserve the tree structure.
+  module Printer
+    ADDITIVE       = 1 # + -
+    MULTIPLICATIVE = 2 # * /
+    UNARY          = 3 # -x
+    POWER          = 4 # **
+    ATOM           = 5
+
+    module_function
+
+    def negative_number?(e) = e.is_a?(Num) && e.value.is_a?(Numeric) && e.value.real? && e.value.negative?
+
+    def print(expr)
+      case expr
+      when Var then expr.name.to_s
+      when Num then number(expr.value)
+      when Neg then "-#{wrap(expr.arg, UNARY, :inner)}"
+      when Add then negative_number?(expr.right) ? binary(Sub.new(expr.left, Num.new(-expr.right.value)), " - ") : binary(expr, " + ")
+      # a negative number on the right reads as the other sign: x - (-7/10)
+      # is x + 7/10 (fifth review, 3.3); the tree itself is unchanged
+      when Sub then negative_number?(expr.right) ? binary(Add.new(expr.left, Num.new(-expr.right.value)), " + ") : binary(expr, " - ")
+      when Mul then binary(expr, "*")
+      when Div then binary(expr, "/")
+      when Pow then "#{wrap(expr.base, POWER, :left)}**#{wrap(expr.exponent, POWER, :right)}"
+      when Const then RCAS.symbol(expr.name)
+      when RootOf then "RootOf(#{print(expr.poly.to_expr.subs(Var.new(expr.var) => Var.new(:x)))}, #{expr.index})"
+      when Fn
+        return "e" if expr.name == :exp && expr.args == [Num.new(1)]
+        if expr.name == :factorial && expr.args.size == 1
+          arg = expr.args.first
+          atom = arg.is_a?(Var) || (arg.is_a?(Num) && number_precedence(arg.value) == ATOM)
+          return atom ? "#{print(arg)}!" : "(#{print(arg)})!"
+        end
+        "#{expr.name}(#{expr.args.map { |a| print(a) }.join(', ')})"
+      when Integral then "integral(#{expr.children.map { |c| print(c) }.join(', ')})"
+      when Limit then "limit(#{print(expr.expr)}, #{print(expr.var)}, #{print(expr.point)})"
+      when Sum then "sum(#{expr.children.map { |c| print(c) }.join(', ')})"
+      when Product then "product(#{expr.children.map { |c| print(c) }.join(', ')})"
+      when Derivative then "D(#{print(expr.expr)}, #{print(expr.var)}#{expr.order == 1 ? '' : ", #{expr.order}"})"
+      when Piecewise then "piecewise(#{expr.branches.map { |cond, value| "#{condition(cond)} => #{print(value)}" }.join(', ')})"
+      else raise ArgumentError, "don't know how to print #{expr.class}"
+      end
+    end
+
+    # The condition of a piecewise branch, written so that the whole node
+    # can be typed back in: `x < 0`, `x.eq(0)`, `interval(0, 1)`, `:else`.
+    def condition(cond)
+      case cond
+      when Inequality then "#{print(cond.lhs)} #{Inequality::OPS[cond.op]} #{print(cond.rhs)}"
+      when Equation
+        # a method call binds tighter than any operator: (exp(a) - 1).eq(0)
+        lhs = print(cond.lhs)
+        bare = cond.lhs.is_a?(Var) || cond.lhs.is_a?(Fn) || cond.lhs.is_a?(Const) || (cond.lhs.is_a?(Num) && !lhs.start_with?("-"))
+        "#{bare ? lhs : "(#{lhs})"}.eq(#{print(cond.rhs)})"
+      when Interval then interval(cond)
+      when RealSet then cond.intervals.map { |i| interval(i) }.join(" | ")
+      else cond.inspect
+      end
+    end
+
+    def interval(i)
+      opens = [("left_open: true" if i.left_open), ("right_open: true" if i.right_open)].compact
+      "interval(#{print(i.low)}, #{print(i.high)}#{opens.empty? ? '' : ", #{opens.join(', ')}"})"
+    end
+
+    def precedence(expr)
+      case expr
+      when Add, Sub then ADDITIVE
+      when Mul, Div then MULTIPLICATIVE
+      when Neg      then UNARY
+      when Pow      then POWER
+      when Num      then number_precedence(expr.value)
+      else ATOM
+      end
+    end
+
+    OPERATORS = { Add => " + ", Sub => " - ", Mul => "*", Div => "/" }.freeze
+
+    # Walks the left spine of same-precedence operators iteratively so that
+    # long chains like a + b + c + ... don't recurse once per term.
+    def binary(expr, _op)
+      prec = precedence(expr)
+      spine = []
+      node = expr
+      while OPERATORS.key?(node.class) && precedence(node) == prec
+        spine << node
+        node = node.left
+      end
+      out = wrap(node, prec, :left)
+      spine.reverse_each { |n| out = "#{out}#{OPERATORS[n.class]}#{wrap(n.right, prec, :right, n)}" }
+      out
+    end
+
+    # Parenthesize +child+ when it binds looser than its parent, or when it
+    # binds equally but sits in a position where that would change meaning.
+    def wrap(child, parent_prec, position, parent = nil)
+      s = print(child)
+      child_prec = precedence(child)
+      needs_parens =
+        case position
+        when :left  then child_prec < parent_prec || (parent_prec == POWER && child_prec == POWER) || (child_prec == parent_prec && child.is_a?(Num))
+        when :right then child_prec < parent_prec || (child_prec == parent_prec && !associative_right?(parent, child)) || child.is_a?(Neg) || (child.is_a?(Num) && child_prec == UNARY)
+        when :inner then child_prec <= parent_prec
+        end
+      needs_parens ? "(#{s})" : s
+    end
+
+    # a + (b - c) and a*(b*c) read fine without parentheses; a - (b + c) and
+    # a/(b*c) do not.
+    def associative_right?(parent, child)
+      (parent.is_a?(Add) && (child.is_a?(Add) || child.is_a?(Sub))) || (parent.is_a?(Mul) && child.is_a?(Mul))
+    end
+
+    def number(value)
+      case value
+      when Rational then value.denominator == 1 ? value.numerator.to_s : "#{value.numerator}/#{value.denominator}"
+      when Complex  then complex(value)
+      else value.to_s
+      end
+    end
+
+    def complex(value)
+      re, im = value.real, value.imaginary
+      im_s =
+        case im
+        when 1 then "i"
+        when -1 then "-i"
+        else "#{number(im)}*i"
+        end
+      return im_s if re.zero?
+      sign = im.negative? ? " - " : " + "
+      "#{number(re)}#{sign}#{im_s.delete_prefix('-')}"
+    end
+
+    def number_precedence(value)
+      return value.printer_precedence if value.respond_to?(:printer_precedence)
+      if value.is_a?(Complex)
+        return ADDITIVE unless value.real.zero?
+        return value.imaginary == 1 ? ATOM : (value.imaginary == -1 ? UNARY : MULTIPLICATIVE)
+      end
+      return UNARY if value.respond_to?(:negative?) && value.negative?
+      return MULTIPLICATIVE if value.is_a?(Rational) && value.denominator != 1
+      ATOM
+    end
+  end
+end

data/lib/rcas/product.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module RCAS
+  # product(f, k, a, b): an unevaluated product, returned when no closed form is known.
+  class Product < Expression
+    attr_reader :term, :var, :from, :to
+
+    def initialize(term, var, from, to)
+      @term = term
+      @var = var
+      @from = from
+      @to = to
+      freeze
+    end
+
+    def bound_variable = var
+    def children = [term, var, from, to]
+    def rebuild(term, var, from, to) = Product.new(term, var, from, to)
+    def to_sexp = [:product, term.to_sexp, var.to_sexp, from.to_sexp, to.to_sexp]
+  end
+
+  # Symbolic products.
+  #
+  #   product(k, k, 1, n)          # => n!
+  #   product(2*k, k: 1..n)        # => 2**n*n!
+  #   product(2*k - 1, k: 1..n)    # => 2**n*gamma(1/2 + n)/pi**(1/2)
+  #   product(a**k, k: 1..n)       # => a**(n/2 + n**2/2)
+  #
+  # A term is split into factors: constants give powers, a**u(k) gives
+  # a**sum(u), and a polynomial in k that factors into linear factors over QQ
+  # gives ratios of factorials (integer shifts) or gamma values (rational
+  # shifts), since prod_{k=a}^{b} (k + r) = gamma(b + r + 1) / gamma(a + r).
+  # A linear factor whose root is a parameter gets the same ratio, under the
+  # generic assumption that the root is not inside the range.
+  # Products with integer bounds that fit no pattern are multiplied out.
+  #
+  # Sources (keys: MANUAL.md, Sources): [GKP94, §5.5] for the gamma function
+  # and rising factorials; the rest is textbook algebra.
+  module Products
+    module_function
+
+    def product(f, k, from, to)
+      f = Expression.lift(f).simplify
+      k = Expression.lift(k)
+      # -1 + 3 is the bound 2 (what subs leaves), and 5/2 is no bound at all:
+      # a product steps over integers, as a sum does (fourth review, S11)
+      from = Expression.lift(from).simplify
+      to = Expression.lift(to).simplify
+      raise ArgumentError, "product: the index must be a symbol, got #{k}" unless k.is_a?(Var)
+      [from, to].each do |b|
+        next unless b.is_a?(Num) && b.value.is_a?(Numeric) && b.value.real? && b.value != b.value.round
+        raise ArgumentError, "product: the bounds must be integers, got #{b}"
+      end
+      if (reversed = Summation.karr(from, to))
+        # Karr's convention, multiplicatively: prod_{a}^{b} = 1/prod_{b+1}^{a-1}
+        return Num.new(1) if reversed == :empty
+        return (1 / product(f, k, reversed.first, reversed.last)).simplify
+      end
+      count = (to - from + 1).simplify
+      return (f**count).simplify unless f.variables.include?(k.name)
+      # a factor with no value makes a product with none: 1/k at k = 0
+      return UNDEFINED if Summation.pole_in_range?(f, k, from, to)
+      return Product.new(f, k, from, to) if Summation.pole_past_start?(f, k, from, to)
+      return Product.new(f, k, from, to) if Limits.infinite?(to) || Limits.infinite?(from)
+
+      closed_form(f, k, from, to, count) || direct(f, k, from, to) || Product.new(f, k, from, to)
+    end
+
+    def depends?(e, k) = e.variables.include?(k.name)
+
+    def closed_form(f, k, from, to, count)
+      f = f.cancel if f.is_a?(Add) || f.is_a?(Sub) # (k + 1)/k rather than 1 + 1/k
+      coeff, factors = Simplify.factorize(f)
+      result = Num.new(coeff)**count
+      factors.each do |base, e|
+        exponent = Expression.lift(e)
+        if !depends?(base, k) && !depends?(exponent, k)
+          result *= base**(exponent * count)
+        elsif !depends?(base, k) # a**u(k) = a**sum(u)
+          s = Summation.sum(exponent, k, from, to)
+          return nil if s.is_a?(Sum)
+          result *= Simplify.power_node(base, s)
+        elsif e.is_a?(Integer) && (g = polynomial_product(base, k, from, to, count))
+          result *= g**e
+        else
+          return nil
+        end
+      end
+      result.simplify
+    end
+
+    # prod p(k) for p with linear factors over QQ, else nil.
+    def polynomial_product(base, k, from, to, count)
+      poly = begin
+        QQ[k.name].call(base)
+      rescue DomainError
+        return parametric_product(base, k, from, to, count)
+      end
+      factorization = poly.factor
+      result = factorization.unit**count
+      factorization.factors.each do |g, m|
+        return nil unless g.degree == 1
+        a = g.coeff(1).value
+        b = g.coeff(0).value
+        result *= (Num.new(a)**count)**m unless a == 1
+        ratio = gamma_ratio(Rational(b, a), from, to) or return nil
+        result *= ratio**m
+      end
+      result
+    end
+
+    # prod_{k=from}^{to} (k + r) = gamma(to + r + 1) / gamma(from + r); with factorials
+    # for integer r. Zero when a factor vanishes inside the range.
+    def gamma_ratio(r, from, to)
+      lower = (from + Num.new(r)).simplify # the first factor
+      if lower.is_a?(Num) && lower.value.is_a?(Integer) && lower.value <= 0
+        upper = (to + Num.new(r)).simplify
+        return Num.new(0) if upper.is_a?(Num) && upper.value >= 0
+        # a symbolic upper bound reaches the zero only from some n on:
+        # product(k - 3, k, 1, n) is 1, -2, 2 at n = 0, 1, 2 and was 0 for
+        # every n, and product(k - 1, k, 1, n) is the empty product 1 at
+        # n = 0 (fourth review); no single closed form says both
+        return nil unless upper.is_a?(Num)
+      end
+      if r.denominator == 1
+        RCAS.factorial((to + Num.new(r)).simplify) / RCAS.factorial((from + Num.new(r) - 1).simplify)
+      else
+        RCAS.gamma((to + Num.new(r) + 1).simplify) / RCAS.gamma(lower)
+      end
+    end
+
+    # A linear factor whose root is a parameter, a - k: the same gamma ratio.
+    # Whether the root falls inside the range cannot be decided, so this is
+    # the generic answer, as everywhere else where a symbolic quantity would
+    # have to be zero for it to be wrong.
+    def parametric_product(base, k, from, to, count)
+      coefficients = Solve.polynomial_coefficients(base.expand, k)
+      return nil unless coefficients && coefficients.size == 2
+      lead = coefficients.last
+      return nil if depends?(lead, k) || Scalar.zero?(lead)
+      r = (coefficients.first / lead).cancel
+      ((lead**count) * RCAS.gamma((to + r + 1).simplify) / RCAS.gamma((from + r).simplify)).simplify
+    rescue DomainError, NotImplementedError, RCAS::Unsupported, ZeroDivisionError
+      nil
+    end
+
+    # Integer bounds: multiply out (up to 1000 factors).
+    def direct(f, k, from, to)
+      return nil unless from.is_a?(Num) && to.is_a?(Num) && from.value.is_a?(Integer) && to.value.is_a?(Integer)
+      return Num.new(1) if to.value < from.value
+      return nil if to.value - from.value > 1000
+      (from.value..to.value).reduce(Num.new(1)) { |acc, i| (acc * f.subs(k => i)).simplify }
+    end
+  end
+end

data/lib/rcas/q_difference.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+module RCAS
+  # Linear q-difference equations,
+  #
+  #   p_0(x)*f(x) + p_1(x)*f(q*x) + ... + p_r(x)*f(q**r*x) = 0,
+  #
+  # and their q-hypergeometric solutions: Petkovsek's algorithm with the
+  # shift x -> q*x in place of n -> n + 1. A q-hypergeometric term is one
+  # whose ratio f(q*x)/f(x) is rational in x, and the same theorem holds with
+  # the same shape,
+  #
+  #   f(q*x)/f(x) = z * a(x)/b(x) * c(q*x)/c(x),
+  #
+  # with a(x) a divisor of p_0(x), b(x) a divisor of p_r(q**(r - 1)*x),
+  # gcd(a(x), b(q**h*x)) = 1 for every integer h >= 0, z free of x and c a
+  # polynomial. The polynomial c is found with a degree bound of its own: the
+  # top-degree terms give sum_j lc(Q_j)*(q**d)**j = 0, so q**d has to be a
+  # root of that polynomial in one variable and d is read off it.
+  #
+  # Solutions are reported at x = q**n, where a q-hypergeometric term is a
+  # product of q-Pochhammer symbols and powers - the form in which such
+  # answers are written and the form q-summation can use. Every candidate is
+  # verified on the ratio before it is returned.
+  #
+  # Sources (keys: MANUAL.md, Sources): [Koe14, ch. 12]; [APP98] for the
+  # q-analogue of Petkovsek's algorithm; [GR04] for the notation.
+  module QDifference
+    MAX_DIVISORS = 64
+
+    module_function
+
+    # qsolve(eq(f(q*x), (1 - a*x)*f(x)), f, x, q) => f(q**n) = C1*(a; q)_n
+    def qsolve(equation, f, x, q, n: :n)
+      name, x, q, coeffs, forcing = normalize(equation, f, x, q)
+      raise RCAS::Unsupported, "qsolve: #{forcing} makes the equation inhomogeneous" unless Scalar.zero?(forcing)
+      index = Var.new(n)
+      order = coeffs.size - 1
+      found = solutions(coeffs, x, q, index)
+      raise RCAS::Unsupported, "qsolve: no q-hypergeometric solutions (see qhyper)" if found.empty?
+      if found.size < order
+        raise RCAS::Unsupported, "qsolve: only #{found.size} of #{order} solutions are q-hypergeometric: " \
+                                   "#{found.map(&:to_s).join(', ')} (see qhyper)"
+      end
+      general = found.each_with_index.map { |t, i| Var.new(:"C#{i + 1}") * t }.reduce(:+).simplify
+      Equation.new(Fn.new(name, [(q**index).simplify]), general)
+    end
+
+    # The ratios f(q*x)/f(x) of the q-hypergeometric solutions: the honest
+    # description, free of any choice of index.
+    def qhyper(equation, f, x, q)
+      _, x, q, coeffs, forcing = normalize(equation, f, x, q)
+      raise RCAS::Unsupported, "qhyper: #{equation} is not homogeneous" unless Scalar.zero?(forcing)
+      ratios(coeffs, x, q)
+    end
+
+    # The solutions as terms in n, where x = q**n.
+    def solutions(coeffs, x, q, n)
+      ratios(coeffs, x, q).filter_map { |ratio| term(ratio, x, q, n) }
+    end
+
+    # ---- reading the equation ----------------------------------------------------
+
+    # [name, x, q, [p_0, ..., p_r], forcing]
+    def normalize(equation, f, x, q)
+      x = Expression.lift(x)
+      q = Expression.lift(q)
+      raise ArgumentError, "qsolve: the indeterminate must be a symbol, got #{x}" unless x.is_a?(Var)
+      name = Recurrence.sequence_name(f)
+      g = Solve.to_zero(equation).simplify
+      shifts = shift_table(g, name, x, q)
+      raise ArgumentError, "#{equation} contains no #{name}(q**j*#{x})" if shifts.empty?
+      low = shifts.values.min
+      unless low.zero?
+        g = g.subs(x => (q**(-low) * x).simplify).simplify
+        shifts = shift_table(g, name, x, q)
+      end
+      order = shifts.values.max
+      raise ArgumentError, "#{equation} is not a q-difference equation: only #{name}(#{x}) occurs" if order.zero?
+      ds = (0..order).map { |j| Var.new(:"_f#{j}") }
+      h = g.subs(shifts.to_h { |t, j| [t, ds[j]] })
+      raise RCAS::Unsupported, "only linear q-difference equations are supported" unless Solve.linear_in?(h, ds)
+      coeffs = ds.map { |d| Solve.polynomial_coefficients(h, d)&.[](1) || Num.new(0) }
+      forcing = Simplify.negate(h.subs(ds.to_h { |d| [d, Num.new(0)] })).simplify
+      coeffs, forcing = Recurrence.clear_denominators(coeffs, forcing, x)
+      [name, x, q, coeffs.map { |c| c.expand }, forcing]
+    end
+
+    # { f(q**j*x) node => j }
+    def shift_table(g, name, x, q)
+      g.each_node.select { |e| e.is_a?(Fn) && e.name == name }.uniq.to_h do |t|
+        raise ArgumentError, "#{t}: one argument expected" unless t.args.size == 1
+        j = power_of_q((t.args.first / x).cancel, q)
+        raise RCAS::Unsupported, "#{t}: the argument must be #{x} times a power of #{q}" if j.nil?
+        [t, j]
+      end
+    end
+
+    # ---- q-Petkovsek -------------------------------------------------------------
+
+    def ratios(coeffs, x, q)
+      r = coeffs.size - 1
+      return [] if r < 1 || Scalar.zero?(coeffs.first) || Scalar.zero?(coeffs.last)
+      ring = QQ[*([x.name, q.name] | coeffs.flat_map { |c| c.variables.to_a })]
+      first = ring.call(coeffs.first)
+      last = ring.call(coeffs.last.subs(x => (q**(r - 1) * x).simplify).expand)
+      found = []
+      divisors(first, x).each do |a|
+        divisors(last, x).each do |b|
+          next unless QSummation.dispersion(a, b, q, x).empty?
+          candidates(coeffs, a, b, x, q, r).each do |ratio|
+            found << ratio unless found.any? { |other| Scalar.zero?((other - ratio).cancel) }
+          end
+        end
+      end
+      found
+    rescue DomainError, NotImplementedError, RCAS::Unsupported, ZeroDivisionError
+      []
+    end
+
+    # For one (a, b): the possible z, and for each the polynomials c.
+    def candidates(coeffs, a, b, x, q, r)
+      base = (0..r).map do |j|
+        aj = (0...j).reduce(Num.new(1)) { |acc, i| acc * a.to_expr.subs(x => (q**i * x).simplify) }
+        bj = (j...r).reduce(Num.new(1)) { |acc, i| acc * b.to_expr.subs(x => (q**i * x).simplify) }
+        (coeffs[j] * aj * bj).expand
+      end
+      zs(base, x, r).flat_map do |z|
+        qs = base.each_with_index.map { |poly, j| (poly * z**j).expand }
+        polynomial_solutions(qs, x, q).filter_map do |c|
+          ratio = (z * a.to_expr * c.subs(x => (q * x).simplify) / (b.to_expr * c)).cancel
+          ratio if satisfies?(coeffs, ratio, x, q, r)
+        end
+      end
+    end
+
+    # The z for which the top-degree terms can cancel.
+    def zs(base, x, r)
+      degrees = base.map { |poly| Solve.polynomial_coefficients(poly, x)&.size }
+      return [] if degrees.any?(&:nil?)
+      top = degrees.each_index.select { |j| degrees[j] == degrees.max }
+      return [] if top.size < 2
+      coefficients = Array.new(r + 1) { Num.new(0) }
+      top.each { |j| coefficients[j] = Solve.polynomial_coefficients(base[j], x).last }
+      Solve.polynomial_roots(coefficients).map(&:simplify)
+           .reject { |z| Scalar.zero?(z) || z.is_a?(RootOf) }
+           .uniq { |z| z.to_s }
+    rescue NotImplementedError, RCAS::Unsupported, DomainError
+      []
+    end
+
+    # sum_j p_j(x)*ratio(x)*ratio(q*x)*...*ratio(q**(j - 1)*x) = 0?
+    def satisfies?(coeffs, ratio, x, q, r)
+      total = Num.new(0)
+      product = Num.new(1)
+      (0..r).each do |j|
+        total += coeffs[j] * product
+        product = (product * ratio.subs(x => (q**j * x).simplify)).cancel if j < r
+      end
+      Scalar.zero?(total.cancel)
+    rescue ZeroDivisionError
+      false
+    end
+
+    # ---- polynomial solutions of a q-difference equation --------------------------
+
+    # Polynomial solutions c of sum_j Q_j(x)*c(q**j*x) = 0, a basis.
+    def polynomial_solutions(coeffs, x, q)
+      bound = degree_bound(coeffs, x, q)
+      return [] if bound.nil? || bound.negative?
+      ws = (0..bound).map { |i| Var.new(:"_qc#{i}") }
+      c = ws.each_with_index.reduce(Num.new(0)) { |acc, (w, i)| acc + w * x**i }
+      residual = coeffs.each_with_index.reduce(Num.new(0)) do |acc, (poly, j)|
+        acc + poly * c.subs(x => (q**j * x).simplify)
+      end
+      conditions = Solve.polynomial_coefficients(residual.expand, x) or return []
+      solution = QSummation.linear_solve(conditions, ws) or return []
+      general = c.subs(solution)
+      free = ws - solution.keys
+      free.filter_map do |one|
+        value = general.subs(free.to_h { |w| [w, Num.new(w == one ? 1 : 0)] }).simplify
+        Scalar.zero?(value) ? nil : value
+      end
+    end
+
+    # A solution of degree d makes the top-degree terms
+    # sum_j lc(Q_j)*(q**d)**j*x**(D + d) cancel, so q**d is a root of that
+    # polynomial in one variable; d is read off the roots that are powers
+    # of q.
+    def degree_bound(coeffs, x, q)
+      degrees = coeffs.map { |poly| Solve.polynomial_coefficients(poly, x)&.size }
+      return nil if degrees.any?(&:nil?)
+      top = degrees.each_index.select { |j| degrees[j] == degrees.max }
+      return nil if top.empty?
+      return nil if top.size < 2 # a single top term cannot vanish
+      coefficients = Array.new(coeffs.size) { Num.new(0) }
+      top.each { |j| coefficients[j] = Solve.polynomial_coefficients(coeffs[j], x).last }
+      Solve.polynomial_roots(coefficients).map(&:simplify)
+           .filter_map { |z| power_of_q(z, q) }
+           .reject(&:negative?).max
+    rescue NotImplementedError, RCAS::Unsupported, DomainError
+      nil
+    end
+
+    # ---- from a ratio to a term ---------------------------------------------------
+
+    # The term u(n) = f(q**n) with f(q*x)/f(x) = ratio: every factor
+    # (1 - a*x) of the ratio contributes a q-Pochhammer symbol (a; q)_n, a
+    # factor x contributes q**(n*(n - 1)/2), and what is left of the constant
+    # contributes z**n. nil when a factor is not linear in x.
+    def term(ratio, x, q, n)
+      pair = Fraction.as_fraction(ratio, [x.name, q.name] | ratio.variables.to_a) or return nil
+      numerator, denominator = pair
+      parts = [[numerator, 1], [denominator, -1]]
+      constant = Num.new(1)
+      total = Num.new(1)
+      parts.each do |poly, sign|
+        pieces = linear_pieces(poly, x, q) or return nil
+        pieces.each do |kind, value|
+          case kind
+          when :constant then constant = sign.positive? ? constant * value : constant / value
+          when :power then total *= Simplify.power_node(q, ((n * (n - 1) / 2) * sign * value).simplify)
+          when :pochhammer
+            factor = pochhammer(value, q, n)
+            total = sign.positive? ? total * factor : total / factor
+          end
+        end
+      end
+      (Simplify.power_node(constant.simplify, n) * total).simplify
+    rescue DomainError, ZeroDivisionError, NotImplementedError, RCAS::Unsupported
+      nil
+    end
+
+    # (a; q)_n, except that (q**(-m); q)_n vanishes from n = m + 1 on: start
+    # the product past the zero instead, as Petkovsek's (n - 1)! does for
+    # u(n + 1) = n*u(n).
+    def pochhammer(a, q, n)
+      m = power_of_q(a, q)
+      return Fn.new(:qpochhammer, [a, q, n]) if m.nil? || m.positive?
+      Fn.new(:qpochhammer, [q, q, (n + m - 1).simplify])
+    end
+
+    # A polynomial in x as constants, powers of x and factors 1 - a*x.
+    def linear_pieces(poly, x, q)
+      pieces = []
+      factorization = poly.factor
+      pieces << [:constant, factorization.unit] unless Scalar.one?(factorization.unit)
+      factorization.factors.each do |factor, multiplicity|
+        degree = factor.degree(x.name)
+        case degree
+        when 0 then pieces << [:constant, Simplify.power_node(factor.to_expr, multiplicity)]
+        when 1
+          low = factor.coefficient_in(x.name, 0).to_expr
+          high = factor.coefficient_in(x.name, 1).to_expr
+          if Scalar.zero?(low) # a bare x
+            pieces << [:power, multiplicity]
+            pieces << [:constant, Simplify.power_node(high, multiplicity)]
+          else
+            multiplicity.times { pieces << [:pochhammer, Simplify.negate(high / low).cancel] }
+            pieces << [:constant, Simplify.power_node(low, multiplicity)]
+          end
+        else return nil
+        end
+      end
+      pieces
+    rescue NotImplementedError, RCAS::Unsupported, DomainError
+      nil
+    end
+
+    # ---- shared helpers ----------------------------------------------------------
+
+    # Every divisor of +poly+ that involves x, and 1.
+    def divisors(poly, x)
+      return [poly.ring.one] if poly.degree(x.name).zero?
+      list = [poly.ring.one]
+      poly.factor.factors.each do |factor, multiplicity|
+        next if factor.degree(x.name).zero? # a unit of QQ(q)[x]
+        list = list.flat_map { |d| (0..multiplicity).map { |i| d * factor**i } }
+        return [poly.ring.one] if list.size > MAX_DIVISORS
+      end
+      list.uniq { |d| d.to_expr.to_s }
+    rescue NotImplementedError, RCAS::Unsupported, DomainError
+      [poly.ring.one]
+    end
+
+    # d with value = q**d, or nil.
+    def power_of_q(value, q)
+      value = Expression.lift(value).simplify
+      return 0 if Scalar.one?(value)
+      coefficient, factors = Simplify.factorize(value)
+      return nil unless coefficient == 1 && factors.size == 1 && factors.key?(q)
+      d = factors[q]
+      d.is_a?(Integer) ? d : nil
+    end
+  end
+end