rcas 0.2.0

data/lib/rcas/lattice.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module RCAS
+  # Lattice basis reduction: the LLL algorithm, exactly.
+  #
+  #   lll(matrix([[1, 1, 1], [-1, 0, 2], [3, 5, 6]]))   # rows (0, 1, 0), (1, 0, 1), (-1, 0, 2)
+  #   b, u = lll(m, transform: true)                    # u*m == b, u unimodular
+  #   m.lll(delta: 99/100r)
+  #
+  # A lattice is every integer combination of some linearly independent
+  # vectors, its basis; many bases give the same lattice, and most of them
+  # are long and nearly parallel. A reduced basis is short and nearly
+  # orthogonal. Its first vector is at most 2**((n - 1)/2) times as long as
+  # the shortest non-zero vector of the lattice (for delta = 3/4), which is
+  # what makes the algorithm useful far beyond lattices: integer relations
+  # between real numbers, minimal polynomials from a decimal expansion,
+  # simultaneous approximation, knapsacks.
+  #
+  # The vectors are the rows, as in the literature. The arithmetic is exact
+  # (Rational), so the Gram-Schmidt coefficients are kept and updated rather
+  # than recomputed, as in Cohen's formulation: size reduction touches one
+  # row of mu, and a swap changes two rows and two columns of it. The price
+  # of exactness is the size of those rationals; the integral version
+  # [Coh93, Algorithm 2.6.7] keeps them as integers, and floating-point
+  # variants trade exactness for speed, neither of which rcas needs at the
+  # sizes a student reduces.
+  #
+  # Sources (keys: MANUAL.md, Sources): the algorithm and its bound
+  # [LLL82]; the formulation with the incremental Gram-Schmidt update
+  # [Coh93, §2.6, Algorithm 2.6.3]; [vzGG13, ch. 16] for the analysis.
+  module Lattice
+    DELTA = Rational(3, 4)
+
+    module_function
+
+    # The reduced basis in the shape it came in: a Matrix for a Matrix, an
+    # Array of vectors otherwise; with transform: true also the unimodular
+    # matrix U with U*B equal to the result.
+    def lll(basis, delta: DELTA, transform: false)
+      rows, shape = rows_of(basis)
+      delta = rational(delta) { "lll: delta must be a rational number, got #{delta.inspect}" }
+      raise ArgumentError, "lll: delta must lie in (1/4, 1], got #{delta}" unless delta > Rational(1, 4) && delta <= 1
+      reduced, u = reduce(rows, delta)
+      out = shape.call(reduced)
+      transform ? [out, RCAS.matrix(u)] : out
+    end
+
+    # Cohen's Algorithm 2.6.3. mu[i][j] (j < i) are the Gram-Schmidt
+    # coefficients and bb[i] the squared lengths of the orthogonalised
+    # vectors; k is the first vector not yet known to be reduced against
+    # the ones before it.
+    def reduce(rows, delta)
+      b = rows.map(&:dup)
+      n = b.size
+      u = Array.new(n) { |i| Array.new(n) { |j| i == j ? 1 : 0 } }
+      mu, bb = gram_schmidt(b)
+      if (i = bb.index(&:zero?))
+        raise ArgumentError, "lll: the vectors are linearly dependent (vector #{i + 1} lies in the span of the ones before it); LLL reduces a basis"
+      end
+      k = 1
+      while k < n
+        size_reduce(b, u, mu, k, k - 1)
+        # Lovasz's condition: the orthogonalised k-th vector is not much
+        # shorter than the one before it
+        if bb[k] >= (delta - mu[k][k - 1]**2) * bb[k - 1]
+          (k - 2).downto(0) { |l| size_reduce(b, u, mu, k, l) }
+          k += 1
+        else
+          swap(b, u, mu, bb, k)
+          k = [k - 1, 1].max
+        end
+      end
+      [b, u]
+    end
+
+    # b_k -= q*b_l with q the integer nearest mu[k][l], which leaves
+    # |mu[k][l]| <= 1/2; mu[k][j] for j < l changes with it.
+    def size_reduce(b, u, mu, k, l)
+      q = mu[k][l].round
+      return if q.zero?
+      b[k] = b[k].zip(b[l]).map { |x, y| x - q * y }
+      u[k] = u[k].zip(u[l]).map { |x, y| x - q * y }
+      mu[k][l] -= q
+      (0...l).each { |j| mu[k][j] -= q * mu[l][j] }
+    end
+
+    # Exchange b_(k-1) and b_k and update the Gram-Schmidt data in place
+    # [Coh93, Algorithm 2.6.3, step 3]: only the two orthogonalised vectors
+    # involved change, and with them rows k-1, k and columns k-1, k of mu.
+    def swap(b, u, mu, bb, k)
+      b[k], b[k - 1] = b[k - 1], b[k]
+      u[k], u[k - 1] = u[k - 1], u[k]
+      (0...k - 1).each { |j| mu[k][j], mu[k - 1][j] = mu[k - 1][j], mu[k][j] }
+      m = mu[k][k - 1]
+      big = bb[k] + m * m * bb[k - 1]
+      mu[k][k - 1] = m * bb[k - 1] / big
+      bb[k] = bb[k - 1] * bb[k] / big
+      bb[k - 1] = big
+      (k + 1...b.size).each do |i|
+        t = mu[i][k]
+        mu[i][k] = mu[i][k - 1] - m * t
+        mu[i][k - 1] = t + mu[k][k - 1] * mu[i][k]
+      end
+    end
+
+    # The Gram-Schmidt coefficients and squared lengths, exactly.
+    def gram_schmidt(b)
+      n = b.size
+      mu = Array.new(n) { Array.new(n, 0r) }
+      bb = Array.new(n, 0r)
+      star = []
+      b.each_with_index do |v, i|
+        w = v.dup
+        (0...i).each do |j|
+          next if bb[j].zero?
+          mu[i][j] = dot(v, star[j]) / bb[j]
+          w = w.zip(star[j]).map { |x, y| x - mu[i][j] * y }
+        end
+        star << w
+        bb[i] = dot(w, w)
+      end
+      [mu, bb]
+    end
+
+    # Whether the rows are LLL-reduced: size-reduced (|mu| <= 1/2) and
+    # Lovasz's condition between neighbours. The tests ask this of every
+    # answer.
+    def reduced?(rows, delta: DELTA)
+      rows = rows_of(rows).first
+      mu, bb = gram_schmidt(rows)
+      size = (1...rows.size).all? { |i| (0...i).all? { |j| mu[i][j].abs <= Rational(1, 2) } }
+      size && (1...rows.size).all? { |k| bb[k] >= (Rational(delta) - mu[k][k - 1]**2) * bb[k - 1] }
+    end
+
+    def dot(v, w) = v.zip(w).sum { |x, y| x * y }
+
+    # [rows as Arrays of Rationals, a lambda giving the answer its shape]
+    def rows_of(basis)
+      rows, shape =
+        case basis
+        when Matrix then [basis.to_a, ->(r) { RCAS.matrix(numbers(r)) }]
+        when Array
+          vectors = basis.map { |v| v.is_a?(Vector) ? v.entries : v }
+          raise ArgumentError, "lll: expected a matrix or a list of vectors, got #{basis.inspect}" unless vectors.all?(Array)
+          [vectors, ->(r) { numbers(r).map { |row| RCAS.vector(*row) } }]
+        else raise ArgumentError, "lll: expected a matrix or a list of vectors, got #{basis.inspect}"
+        end
+      raise ArgumentError, "lll: no vectors to reduce" if rows.empty?
+      raise ArgumentError, "lll: the vectors have different lengths" unless rows.map(&:size).uniq.size == 1
+      entries = rows.map do |row|
+        row.map do |e|
+          rational(e) { "lll: the entries must be rational numbers, got #{e}; scale and round a real lattice first" }
+        end
+      end
+      [entries, shape]
+    end
+
+    def rational(e)
+      e = e.value if e.is_a?(Num)
+      e = Expression.lift(e).simplify.then { |s| s.is_a?(Num) ? s.value : s } if e.is_a?(Expression)
+      return e.to_r if e.is_a?(Integer) || e.is_a?(Rational)
+      raise ArgumentError, yield
+    end
+
+    def numbers(rows) = rows.map { |row| row.map { |x| Simplify.normalize_number(x) } }
+  end
+
+  class Matrix
+    # The LLL-reduced basis of the lattice spanned by the rows; see Lattice.
+    def lll(delta: Lattice::DELTA, transform: false) = Lattice.lll(self, delta: delta, transform: transform)
+  end
+end

data/lib/rcas/linear_algebra.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module RCAS
+  # The second course in linear algebra: orthogonality and least squares.
+  #
+  #   gram_schmidt([vector(1, 1, 0), vector(1, 0, 1)])      # orthogonal basis
+  #   gram_schmidt(vs, normalize: true)                     # orthonormal
+  #   least_squares(matrix([[1, 1], [1, 2], [1, 3]]), vector(1, 2, 4))
+  #   project(vector(1, 2), onto: vector(1, 0))
+  #
+  # Exact throughout, so an orthonormal basis keeps its square roots.
+  #
+  # Sources (keys: MANUAL.md, Sources): Gram-Schmidt and the normal equations
+  # as in [Str16, ch. 4]; the numerically stabler QR route is not used because
+  # the arithmetic here is exact.
+  module LinearAlgebra
+    module_function
+
+    # The inner product, Hermitian where an entry carries an explicit
+    # complex number: (1, i).(1, i) is 1 + i*i = 0 bilinearly, and |(1, i)|
+    # is sqrt(2), not 0 (third review, L12). Symbolic entries are taken as
+    # they stand, so the real case is unchanged.
+    def dot(u, v)
+      same_length!(u, v, "dot")
+      u.entries.zip(v.entries).map { |a, b| Scalar.mul(a, conjugate(b)) }.reduce { |x, y| Scalar.add(x, y) }.simplify
+    end
+
+    # zip drops the extra coordinates of the longer vector, which made
+    # project((1, 2), onto: (1, 0, 3)) a plausible (1/10, 0) (a review,
+    # 23 Sept 2026): vectors of two different spaces have no inner product.
+    def same_length!(u, v, name)
+      return if u.entries.size == v.entries.size
+      raise ArgumentError, "#{name}: the vectors have #{u.entries.size} and #{v.entries.size} entries; they must lie in the same space"
+    end
+
+    def conjugate(e)
+      e = Expression.lift(e)
+      return e unless e.each_node.any? { |n| n.is_a?(Num) && n.value.is_a?(Complex) }
+      ComplexParts.conj(e)
+    end
+
+    def norm(v) = RCAS.sqrt(dot(v, v)).simplify
+
+    def scale(v, factor) = v.space.unchecked(v.entries.map { |e| (e * factor).simplify })
+
+    def subtract(u, v)
+      same_length!(u, v, "subtract")
+      u.space.unchecked(u.entries.zip(v.entries).map { |a, b| (a - b).simplify })
+    end
+
+    # The projection of v onto a vector or onto the span of several.
+    #
+    # The sum of the single projections is the projection onto the span only
+    # when the targets are pairwise orthogonal; a slanted pair has to be
+    # orthogonalised first. project(e1, onto: [e1, e1 + e2]) is e1 - those
+    # two span the plane, so the projection onto it is the identity - and
+    # was (3/2, 1/2) before (22 Sept 2026, from a review). Dependent
+    # generators drop out on the way, as they do in gram_schmidt.
+    def project(v, onto:)
+      targets = onto.is_a?(Array) ? onto : [onto]
+      targets.each do |u|
+        raise ArgumentError, "project: cannot project onto the zero vector" if Scalar.zero?(dot(u, u))
+      end
+      targets = gram_schmidt(targets) unless orthogonal_family?(targets)
+      onto_orthogonal(v, targets)
+    end
+
+    def orthogonal_family?(targets) = targets.combination(2).all? { |u, w| orthogonal?(u, w) }
+
+    # The sum of the single projections, which is the projection itself once
+    # the targets are known to be pairwise orthogonal. gram_schmidt builds
+    # such a family as it goes and calls this directly, so that project does
+    # not orthogonalise what it has just orthogonalised.
+    def onto_orthogonal(v, targets)
+      targets.reduce(v.space.unchecked(Array.new(v.entries.size, Num.new(0)))) do |sum, u|
+        add(sum, scale(u, (dot(v, u) / dot(u, u)).simplify))
+      end
+    end
+
+    def add(u, v)
+      same_length!(u, v, "add")
+      u.space.unchecked(u.entries.zip(v.entries).map { |a, b| (a + b).simplify })
+    end
+
+    # An orthogonal (or orthonormal) basis of the same span; dependent
+    # vectors drop out rather than appearing as zeros.
+    def gram_schmidt(vectors, normalize: false)
+      basis = []
+      Array(vectors).each do |v|
+        w = basis.empty? ? v : subtract(v, onto_orthogonal(v, basis))
+        next if w.entries.all? { |e| Scalar.zero?(e) }
+        basis << w
+      end
+      return basis unless normalize
+      basis.map { |w| scale(w, (1 / norm(w)).simplify) }
+    end
+
+    # The x minimising |A x - b|, from the normal equations A* A x = A* b
+    # with A* the conjugate transpose. The plain transpose is right only for
+    # real entries: for A = (1, 2i)' it gave -1/3 where the minimiser of
+    # |z - 1|**2 + |2iz|**2 is 1/5, and (1, i)' had "dependent columns"
+    # (a review, 23 Sept 2026). `conjugate` leaves a symbolic entry alone,
+    # as `dot` does, so the real case is unchanged.
+    def least_squares(matrix, target)
+      unless target.entries.size == matrix.rows
+        raise ArgumentError, "least_squares: the matrix has #{matrix.rows} rows and the vector #{target.entries.size} entries"
+      end
+      adjoint = RCAS.matrix(matrix.transpose.to_a.map { |row| row.map { |e| conjugate(e) } })
+      normal = adjoint * matrix
+      right = adjoint * target
+      raise ArgumentError, "least_squares: the columns are dependent, so the solution is not unique" if Scalar.zero?(normal.det)
+      normal.solve(right.entries)
+    end
+
+    def orthogonal?(u, v) = Scalar.zero?(dot(u, v))
+  end
+end