rcas 0.2.0

data/lib/rcas/decompositions.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module RCAS
+  # Matrix factorizations, exact: LU with row swaps, QR by Gram-Schmidt,
+  # Cholesky, diagonalization and the Jordan normal form.
+  #
+  #   l, u, p = matrix([[0, 1], [2, 3]]).lu     # p*a == l*u
+  #   q, r = a.qr                               # a == q*r, q orthogonal
+  #   l = a.cholesky                            # a == l*l.transpose
+  #   pm, d = a.diagonalize                     # a == pm*d*pm.inverse
+  #   pm, j = a.jordan                          # a == pm*j*pm.inverse
+  #
+  # The arithmetic is the exact Scalar arithmetic the rest of the matrix
+  # code uses, so pivots are swapped only when they are zero (there is no
+  # rounding to steer away from): a symbolic pivot that is not identically
+  # zero is taken to be non-zero, the generic case, as everywhere else.
+  #
+  # Sources (keys: MANUAL.md, Sources): LU, QR and Cholesky as in
+  # [Str16, ch. 2, 4, 6]; the Jordan form built from chains of generalized
+  # eigenvectors as in [HK71, ch. 7].
+  module Decompositions
+    module_function
+
+    # P*A = L*U with L unit lower triangular, U upper triangular and P a
+    # permutation. Rows are swapped only to get away from a zero pivot.
+    def lu(matrix)
+      square!(matrix, "lu")
+      n = matrix.rows
+      u = matrix.to_a
+      l = identity_rows(n)
+      p = identity_rows(n)
+      (0...n).each do |k|
+        pivot = (k...n).find { |i| !Scalar.zero?(u[i][k]) }
+        next if pivot.nil?
+        if pivot != k
+          u[k], u[pivot] = u[pivot], u[k]
+          p[k], p[pivot] = p[pivot], p[k]
+          (0...k).each { |j| l[k][j], l[pivot][j] = l[pivot][j], l[k][j] }
+        end
+        ((k + 1)...n).each do |i|
+          factor = Scalar.div(u[i][k], u[k][k])
+          l[i][k] = factor
+          (k...n).each { |j| u[i][j] = Scalar.sub(u[i][j], Scalar.mul(factor, u[k][j])).simplify }
+        end
+      end
+      [field_matrix(matrix, l), field_matrix(matrix, u), field_matrix(matrix, p)]
+    end
+
+    # A = Q*R with the columns of Q orthonormal and R upper triangular.
+    # Exact, so the entries of Q carry square roots.
+    def qr(matrix)
+      basis = LinearAlgebra.gram_schmidt(matrix.column_vectors, normalize: true)
+      raise ArgumentError, "qr: the columns of the matrix are not independent" unless basis.size == matrix.cols
+      q = field_matrix(matrix, basis.map(&:entries).transpose, matrix.rows, matrix.cols)
+      # Q^H A: the conjugate transpose, which is the transpose for real Q
+      adjoint = field_matrix(matrix, q.transpose.to_a.map { |row| row.map { |e| LinearAlgebra.conjugate(e) } }, matrix.cols, matrix.rows)
+      r = (adjoint * matrix).simplify
+      [q, r]
+    end
+
+    # A = L*L' for a symmetric positive definite A.
+    def cholesky(matrix)
+      square!(matrix, "cholesky")
+      raise ArgumentError, "cholesky: the matrix is not symmetric" unless matrix.symmetric?
+      n = matrix.rows
+      l = Array.new(n) { Array.new(n, Num.new(0)) }
+      (0...n).each do |i|
+        (0..i).each do |j|
+          rest = (0...j).reduce(matrix[i, j]) { |acc, k| Scalar.sub(acc, Scalar.mul(l[i][k], l[j][k])) }.simplify
+          l[i][j] =
+            if i == j
+              raise ArgumentError, "cholesky: the matrix is not positive definite" if nonpositive?(rest)
+              Pow.new(rest, Num.new(Rational(1, 2))).simplify
+            else
+              Scalar.div(rest, l[j][j]).simplify
+            end
+        end
+      end
+      field_matrix(matrix, l)
+    end
+
+    # A = P*D*P**-1 with D diagonal: the eigenvectors as the columns of P.
+    def diagonalize(matrix)
+      square!(matrix, "diagonalize")
+      pairs = matrix.eigenvectors.flat_map { |value, _, vectors| vectors.map { |v| [value, v] } }
+      unless pairs.size == matrix.rows
+        raise ArgumentError, "diagonalize: #{pairs.size} independent eigenvectors for #{matrix.rows} dimensions; " \
+                             "the matrix is not diagonalizable - jordan gives its Jordan form"
+      end
+      [basis_matrix(matrix, pairs.map { |_, v| v.entries }), diagonal(matrix, pairs.map(&:first))]
+    end
+
+    # A = P*J*P**-1 with J in Jordan normal form: one block per chain of
+    # generalized eigenvectors.
+    def jordan(matrix)
+      square!(matrix, "jordan")
+      n = matrix.rows
+      columns = []
+      blocks = []
+      Solve.dedupe(matrix.eigenvalues).each do |value|
+        chains = chains_for(matrix, value)
+        chains.each do |chain|
+          columns.concat(chain)
+          blocks << [value, chain.size]
+        end
+      end
+      unless columns.size == n
+        raise RCAS::Unsupported, "jordan: only #{columns.size} of #{n} basis vectors were found; " \
+                                   "the eigenvalues have to be exact for the chains to be built"
+      end
+      [basis_matrix(matrix, columns), jordan_matrix(matrix, blocks)]
+    end
+
+    # ---- the Jordan chains ---------------------------------------------------
+
+    # The chains for one eigenvalue, longest first. A chain is
+    # [N**(k-1) u, ..., N u, u] with N = A - lambda and u in ker(N**k) but
+    # not in ker(N**(k-1)), so that N maps each vector to the one before it
+    # and the first one is an eigenvector.
+    def chains_for(matrix, value)
+      shifted = matrix - matrix.space.identity.scale(value)
+      kernels = nested_kernels(shifted)
+      chains = []
+      taken = []
+      kernels.size.downto(1) do |k|
+        candidates(kernels, k).each do |u|
+          chain = build_chain(shifted, u, k)
+          next if chain.nil? || !independent?(taken + chain.flatten(0), matrix)
+          chains << chain
+          taken.concat(chain)
+        end
+      end
+      chains
+    end
+
+    # [basis of ker(N), basis of ker(N**2), ...] up to the point where the
+    # kernel stops growing.
+    def nested_kernels(shifted)
+      out = []
+      power = shifted
+      loop do
+        basis = power.kernel.map { |v| v.entries.map { |e| Expression.lift(e).simplify } }
+        break if !out.empty? && basis.size <= out.last.size
+        out << basis
+        break if basis.size >= shifted.rows
+        power = (power * shifted).simplify
+      end
+      out
+    end
+
+    # Vectors of ker(N**k) that are not already in ker(N**(k-1)).
+    def candidates(kernels, k)
+      return [] if kernels[k - 1].nil?
+      lower = k >= 2 ? kernels[k - 2] : []
+      kernels[k - 1].reject { |v| in_span?(lower, v) }
+    end
+
+    def build_chain(shifted, top, length)
+      chain = [top]
+      (length - 1).times do
+        previous = apply(shifted, chain.first)
+        return nil if previous.all? { |e| Scalar.zero?(e) }
+        chain.unshift(previous)
+      end
+      chain
+    end
+
+    def apply(matrix, vector)
+      (0...matrix.rows).map do |i|
+        (0...matrix.cols).reduce(Num.new(0)) { |acc, j| Scalar.add(acc, Scalar.mul(matrix[i, j], vector[j])) }.simplify
+      end
+    end
+
+    def in_span?(vectors, v)
+      return false if vectors.empty?
+      rank_of(vectors) == rank_of(vectors + [v])
+    end
+
+    def independent?(vectors, _matrix) = rank_of(vectors) == vectors.size
+
+    def rank_of(vectors)
+      return 0 if vectors.empty?
+      Elimination.rref(vectors.map { |v| v.map { |e| Expression.lift(e) } }).last.size
+    end
+
+    # ---- building matrices ---------------------------------------------------
+
+    def square!(matrix, name)
+      raise ArgumentError, "#{name}: the matrix must be square" unless matrix.square?
+    end
+
+    def identity_rows(n) = Array.new(n) { |i| Array.new(n) { |j| Num.new(i == j ? 1 : 0) } }
+
+    def field_matrix(matrix, rows, r = nil, c = nil)
+      space = MatrixSpace.new(matrix.base.fraction_field, r || rows.size, c || rows.first.size)
+      space.unchecked(rows)
+    end
+
+    # The vectors as the columns of one matrix.
+    def basis_matrix(matrix, vectors) = field_matrix(matrix, vectors.map { |v| v.map { |e| Expression.lift(e).simplify } }.transpose)
+
+    def diagonal(matrix, values)
+      n = values.size
+      field_matrix(matrix, Array.new(n) { |i| Array.new(n) { |j| i == j ? Expression.lift(values[i]) : Num.new(0) } })
+    end
+
+    # One Jordan block per [eigenvalue, size], on the diagonal.
+    def jordan_matrix(matrix, blocks)
+      n = blocks.sum(&:last)
+      rows = Array.new(n) { Array.new(n, Num.new(0)) }
+      offset = 0
+      blocks.each do |value, size|
+        (0...size).each do |i|
+          rows[offset + i][offset + i] = Expression.lift(value)
+          rows[offset + i][offset + i + 1] = Num.new(1) if i + 1 < size
+        end
+        offset += size
+      end
+      field_matrix(matrix, rows)
+    end
+
+    def nonpositive?(entry)
+      return true if Scalar.zero?(entry)
+      value = Expression.lift(entry).evalf
+      value.is_a?(Numeric) && value.real? && value.negative?
+    end
+  end
+
+  class Matrix
+    # P*A = L*U: l, u, p = a.lu
+    def lu = Decompositions.lu(self)
+    # A = Q*R with Q orthogonal: q, r = a.qr
+    def qr = Decompositions.qr(self)
+    # A = L*L' for a symmetric positive definite matrix
+    def cholesky = Decompositions.cholesky(self)
+    # A = P*D*P**-1 with D diagonal: p, d = a.diagonalize
+    def diagonalize = Decompositions.diagonalize(self)
+    # A = P*J*P**-1 with J in Jordan normal form: p, j = a.jordan
+    def jordan = Decompositions.jordan(self)
+  end
+end

data/lib/rcas/differentiate.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module RCAS
+  # Symbolic differentiation. Produces an unsimplified tree; Expression#diff
+  # simplifies the result.
+  module Differentiate
+    module_function
+
+    def diff(expr, var)
+      # an expression without var (free) is a constant in it: sqrt(y - y)
+      # has derivative 0, and the chain rule divided by sqrt(0) on the way
+      # (third review, C11)
+      return Num.new(0) if expr.is_a?(Expression) && !expr.is_a?(Derivative) && !expr.variables.include?(var.name) &&
+                           !(expr.is_a?(Const) && expr.name == :undefined)
+      case expr
+      when Const then expr.name == :undefined ? expr : Num.new(0)
+      when Num, RootOf then Num.new(0)
+      when Var then Num.new(expr == var ? 1 : 0)
+      when Neg then Neg.new(diff(expr.arg, var))
+      when Add then Add.new(diff(expr.left, var), diff(expr.right, var))
+      when Sub then Sub.new(diff(expr.left, var), diff(expr.right, var))
+      when Mul then Add.new(Mul.new(diff(expr.left, var), expr.right), Mul.new(expr.left, diff(expr.right, var)))
+      when Div then quotient(expr, var)
+      when Pow then power(expr, var)
+      when Fn
+        if %i[re im conj].include?(expr.name) then Fn.new(expr.name, [diff(expr.args.first, var)])
+        elsif expr.name == :surd && expr.args.size == 2 then surd(expr, var)
+        else chain(expr, var)
+        end
+      when Integral then integral(expr, var)
+      when Derivative then derivative(expr, var)
+      when Piecewise then Piecewise.new(expr.branches.map { |cond, value| [cond, diff(value, var)] })
+      else raise ArgumentError, "can't differentiate #{expr.class}"
+      end
+    end
+
+    # A derivative with respect to another variable. D(y, x) of an unknown
+    # function y stands for y(x), which depends on x alone, so its
+    # derivative in anything else is 0. An explicit expression is another
+    # matter: D(x*y, x) is y, and its y-derivative is 1, not the 0 this
+    # returned for every other variable (a review, 23 Sept 2026). It is
+    # taken first and differentiated again; one that cannot be taken stays
+    # a formal mixed derivative rather than becoming 0.
+    def derivative(d, var)
+      return Derivative.new(d.expr, d.var, d.order + 1) if d.var == var
+      return Num.new(0) if d.expr.is_a?(Var) || !d.expr.variables.include?(var.name)
+      taken = begin
+        d.evaluate
+      rescue ArgumentError => e
+        raise unless e.message.start_with?(Integrate::NO_DERIVATIVE) # floor(x*y)
+        d
+      end
+      return diff(taken, var) unless taken.each_node.any? { |n| n.is_a?(Derivative) }
+      Derivative.new(d, var)
+    end
+
+    # A definite integral is a number, but a number that still depends on
+    # the parameters of its integrand: d/dx integral(x*t, t, 0, 1) is 1/2,
+    # not 0. Only the *integration* variable is bound, and looking at the
+    # bounds alone answered every such derivative with zero (22 Sept 2026,
+    # from a review). Bounds that move add Leibniz's two boundary terms.
+    #
+    # The rule is applied, not checked: differentiating under the integral
+    # sign needs the integrand and its parameter derivative continuous on
+    # the rectangle (and, over an infinite range, the differentiated
+    # integral uniformly convergent) - [DLMF, 1.5(iv)]. rcas does not verify
+    # that, which is why the answer is another integral rather than a value:
+    # what comes out is the derivative wherever the rule applies, and the
+    # caller keeps the hypotheses.
+    def integral(expr, var)
+      unless expr.definite?
+        return expr.var == var ? expr.integrand : Integral.new(differentiated(expr, var), expr.var)
+      end
+      moving = [expr.from, expr.to].any? { |c| c.variables.include?(var.name) }
+      # A name bound by the integral is not the free one outside it, even
+      # where the two are spelled alike: integral(sin(x), x, 0, x) is the
+      # integral(sin(t), t, 0, x) that renaming the bound variable gives, so
+      # the integrand contributes nothing and only the bound moves. Refusing
+      # it as ambiguous was wrong (22 Sept 2026, the second review).
+      bound = expr.var == var
+      inside = !bound && expr.integrand.variables.include?(var.name) ? Integral.new(differentiated(expr, var), expr.var, expr.from, expr.to) : Num.new(0)
+      return inside unless moving
+      at = ->(edge) { Mul.new(expr.integrand.subs(expr.var => edge), diff(edge, var)) }
+      Add.new(inside, Sub.new(at[expr.to], at[expr.from]))
+    end
+
+    # The new integrand is simplified on the way in: an Integral is an atom
+    # to Simplify, so nothing would tidy it afterwards.
+    def differentiated(expr, var) = diff(expr.integrand, var).simplify
+
+    def quotient(expr, var)
+      u, v = expr.left, expr.right
+      Div.new(Sub.new(Mul.new(diff(u, var), v), Mul.new(u, diff(v, var))), Pow.new(v, Num.new(2)))
+    end
+
+    def power(expr, var)
+      u, n = expr.base, expr.exponent
+      if !n.variables.include?(var.name)
+        # d(u**n) = n * u**(n-1) * u' - and 0 when u does not move: sqrt(x - x)
+        # is the zero function, and 0**(-1/2)*0 divided by zero (fourth review)
+        du = diff(u, var)
+        flat = du.is_a?(Num) ? du : du.simplify
+        return Num.new(0) if flat.is_a?(Num) && flat.value.is_a?(Numeric) && flat.value.zero?
+        Mul.new(Mul.new(n, Pow.new(u, Sub.new(n, Num.new(1)))), du)
+      elsif !u.variables.include?(var.name)
+        # d(a**v) = a**v * log(a) * v'
+        Mul.new(Mul.new(expr, Fn.new(:log, [u])), diff(n, var))
+      else
+        # general case: u**v * (v' * log(u) + v * u' / u)
+        Mul.new(expr, Add.new(Mul.new(diff(n, var), Fn.new(:log, [u])), Div.new(Mul.new(n, diff(u, var)), u)))
+      end
+    end
+
+    # surd(u, n)**n = u, so surd(u, n)' = u'/(n*surd(u, n)**(n - 1)) where u != 0
+    def surd(expr, var)
+      u, n = expr.args
+      Div.new(diff(u, var), Mul.new(n, Pow.new(expr, Sub.new(n, Num.new(1)))))
+    end
+
+    def chain(expr, var)
+      raise ArgumentError, "#{expr.name} takes one argument" unless expr.args.size == 1
+      u = expr.args.first
+      outer =
+        case expr.name
+        when :sin then Fn.new(:cos, [u])
+        when :cos then Neg.new(Fn.new(:sin, [u]))
+        when :tan then Add.new(Num.new(1), Pow.new(Fn.new(:tan, [u]), Num.new(2)))
+        when :exp then expr
+        when :log then Div.new(Num.new(1), u)
+        when :atan then Div.new(Num.new(1), Add.new(Num.new(1), Pow.new(u, Num.new(2))))
+        when :abs then Fn.new(:sign, [u])
+        when :sign then Num.new(0)
+        when :asin then Pow.new(Sub.new(Num.new(1), Pow.new(u, Num.new(2))), Num.new(Rational(-1, 2)))
+        when :acos then Neg.new(Pow.new(Sub.new(Num.new(1), Pow.new(u, Num.new(2))), Num.new(Rational(-1, 2))))
+        when :sinh then Fn.new(:cosh, [u])
+        when :cosh then Fn.new(:sinh, [u])
+        when :erf then Div.new(Mul.new(Num.new(2), Fn.new(:exp, [Neg.new(Pow.new(u, Num.new(2)))])), Pow.new(PI, Num.new(Rational(1, 2))))
+        when :erfc then Neg.new(Div.new(Mul.new(Num.new(2), Fn.new(:exp, [Neg.new(Pow.new(u, Num.new(2)))])), Pow.new(PI, Num.new(Rational(1, 2)))))
+        else IntegralFunctions.derivative(expr.name, u) || raise(ArgumentError, "don't know the derivative of #{expr.name}")
+        end
+      Mul.new(outer, diff(u, var))
+    end
+  end
+end