numo-linalg-alt 0.4.0 → 0.5.0

data/lib/numo/linalg.rb

@@ -740,6 +740,63 @@ module Numo
       [b, v, sdim]
     end
 
+    # Computes the Hessenberg decomposition of a square matrix.
+    # The Hessenberg decomposition is given by `A = Q * H * Q^H`,
+    # where `A` is the input matrix, `Q` is a unitary matrix,
+    # and `H` is an upper Hessenberg matrix.
+    #
+    # @example
+    #   require 'numo/linalg'
+    #
+    #   a = Numo::DFloat[[1, 2, 3], [4, 5, 6], [7, 8, 9]] * 0.5
+    #   h, q = Numo::Linalg.hessenberg(a, calc_q: true)
+    #
+    #   pp h
+    #   # => Numo::DFloat#shape=[3,3]
+    #   # [[0.5, -1.7985, -0.124035],
+    #   #  [-4.03113, 7.02308, 1.41538],
+    #   #  [0, 0.415385, -0.0230769]]
+    #   pp q
+    #   # => Numo::DFloat#shape=[3,3]
+    #   # [[1, 0, 0],
+    #   #  [0, -0.496139, -0.868243],
+    #   #  [0, -0.868243, 0.496139]]
+    #   pp (a - q.dot(h).dot(q.transpose)).abs.max
+    #   # => 1.7763568394002505e-15
+    #
+    # @param a [Numo::NArray] The n-by-n square matrix.
+    # @param calc_q [Boolean] The flag indicating whether to calculate the unitary matrix `Q`.
+    # @return [Numo::NArray] if calc_q=false, the Hessenberg form `H`.
+    # @return [Array<Numo::NArray, Numo::NArray>] if calc_q=true,
+    #   the Hessenberg form `H` and the unitary matrix `Q`.
+    def hessenberg(a, calc_q: false)
+      raise Numo::NArray::ShapeError, 'input array a must be 2-dimensional' if a.ndim != 2
+      raise Numo::NArray::ShapeError, 'input array a must be square' if a.shape[0] != a.shape[1]
+
+      bchr = blas_char(a)
+      raise ArgumentError, "invalid array type: #{a.class}" if bchr == 'n'
+
+      func = :"#{bchr}gebal"
+      b, ilo, ihi, _, info = Numo::Linalg::Lapack.send(func, a.dup)
+
+      raise "the #{-info}-th argument of #{func} had illegal value" if info.negative?
+
+      func = :"#{bchr}gehrd"
+      hq, tau, info = Numo::Linalg::Lapack.send(func, b, ilo: ilo, ihi: ihi)
+
+      raise "the #{-info}-th argument of #{func} had illegal value" if info.negative?
+
+      h = hq.triu(-1)
+      return h unless calc_q
+
+      func = %w[d s].include?(bchr) ? :"#{bchr}orghr" : :"#{bchr}unghr"
+      q, info = Numo::Linalg::Lapack.send(func, hq, tau, ilo: ilo, ihi: ihi)
+
+      raise "the #{-info}-th argument of #{func} had illegal value" if info.negative?
+
+      [h, q]
+    end
+
     # Solves linear equation `A * x = b` or `A * X = B` for `x` from square matrix `A`.
     #
     # @example
@@ -1189,6 +1246,102 @@ module Numo
       [r, scale]
     end
 
+    # Computes a diagonal similarity transformation that balances a square matrix.
+    #
+    # @example
+    #   require 'numo/linalg'
+    #
+    #   a = Numo::DFloat[[1, 0, 0], [1, 2, 0], [1, 2, 3]]
+    #   b, h = Numo::Linalg.matrix_balance(a)
+    #   pp b
+    #   # =>
+    #   # Numo::DFloat#shape=[3,3]
+    #   # [[3, 2, 1],
+    #   #  [0, 2, 1],
+    #   #  [0, 0, 1]]
+    #   pp h
+    #   # =>
+    #   # Numo::DFloat#shape=[3,3]
+    #   # [[0, 0, 1],
+    #   #  [0, 1, 0],
+    #   #  [1, 0, 0]]
+    #   pp (Numo::Linalg.inv(h).dot(a).dot(h) - b).abs.max
+    #   # => 0.0
+    #
+    # @param a [Numo::NArray] The n-by-n square matrix.
+    # @param permute [Boolean] The flag indicating whether to permute the matrix.
+    # @param scale [Boolean] The flag indicating whether to scale the matrix.
+    # @param separate [Boolean] The flag indicating whether to return scaling factors and permutation indices
+    #   separately.
+    # @return [Array<Numo::NArray, Numo::NArray>] if `separate` is `false`, the balanced matrix and the
+    #   similarity transformation matrix `H` ([b, h]). if `separate` is `true`, the balanced matrix, the
+    #   scaling factors, and the permutation indices ([b, scaler, perm]).
+    def matrix_balance(a, permute: true, scale: true, separate: false) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      raise Numo::NArray::ShapeError, 'input array a must be 2-dimensional' if a.ndim != 2
+
+      n = a.shape[0]
+      raise ArgumentError, 'input array a must be square' if a.shape[1] != n
+
+      bchr = blas_char(a)
+      raise ArgumentError, "invalid array type: #{a.class}" if bchr == 'n'
+
+      job = if permute && scale
+              'B'
+            elsif permute && !scale
+              'P'
+            elsif !permute && scale
+              'S'
+            else
+              'N'
+            end
+      fnc = :"#{bchr}gebal"
+      b, lo, hi, prm_scl, info = Numo::Linalg::Lapack.send(fnc, a.dup, job: job)
+
+      raise "the #{info.abs}-th argument of #{fnc} had illegal value" if info.negative?
+
+      # convert from Fortran style index to Ruby style index.
+      lo -= 1
+      hi -= 1
+      iprm_scl = Numo::Int32.cast(prm_scl) - 1
+
+      # extract scaling factors
+      scaler = prm_scl.class.ones(n)
+      scaler[lo...(hi + 1)] = prm_scl[lo...(hi + 1)]
+
+      # extract permutation indices
+      perm = Numo::Int32.new(n).seq
+      if hi < n - 1
+        iprm_scl[(hi + 1)...n].to_a.reverse.each.with_index(1) do |s, i|
+          j = n - i
+          next if s == j
+
+          tmp_ls, tmp_lj = perm[[s, j]].to_a
+          tmp_rj, tmp_rs = perm[[j, s]].to_a
+          perm[[s, j]] = [tmp_rj, tmp_rs]
+          perm[[j, s]] = [tmp_ls, tmp_lj]
+        end
+      end
+      if lo > 0 # rubocop:disable Style/NumericPredicate
+        iprm_scl[0...lo].to_a.each_with_index do |s, j|
+          next if s == j
+
+          tmp_ls, tmp_lj = perm[[s, j]].to_a
+          tmp_rj, tmp_rs = perm[[j, s]].to_a
+          perm[[s, j]] = [tmp_rj, tmp_rs]
+          perm[[j, s]] = [tmp_ls, tmp_lj]
+        end
+      end
+
+      return [b, scaler, perm] if separate
+
+      # construct inverse permutation matrix
+      inv_perm = Numo::Int32.zeros(n)
+      inv_perm[perm] = Numo::Int32.new(n).seq
+      h = scaler.diag[inv_perm, true].dup
+
+      [b, h]
+    end
+
     # Computes the eigenvalues and right and/or left eigenvectors of a general square matrix.
     #
     # @example
@@ -1517,6 +1670,41 @@ module Numo
       a_sin.dot(Numo::Linalg.inv(a_cos))
     end
 
+    # Computes the matrix hyperbolic sine using the matrix exponential.
+    #
+    # @param a [Numo::NArray] The n-by-n square matrix.
+    # @return [Numo::NArray] The matrix hyperbolic sine of `a`.
+    def sinhm(a)
+      raise Numo::NArray::ShapeError, 'input array a must be 2-dimensional' if a.ndim != 2
+      raise Numo::NArray::ShapeError, 'input array a must be square' if a.shape[0] != a.shape[1]
+
+      0.5 * (expm(a) - expm(-a))
+    end
+
+    # Computes the matrix hyperbolic cosine using the matrix exponential.
+    #
+    # @param a [Numo::NArray] The n-by-n square matrix.
+    # @return [Numo::NArray] The matrix hyperbolic cosine of `a`.
+    def coshm(a)
+      raise Numo::NArray::ShapeError, 'input array a must be 2-dimensional' if a.ndim != 2
+      raise Numo::NArray::ShapeError, 'input array a must be square' if a.shape[0] != a.shape[1]
+
+      0.5 * (expm(a) + expm(-a))
+    end
+
+    # Computes the matrix hyperbolic tangent.
+    #
+    # @param a [Numo::NArray] The n-by-n square matrix.
+    # @return [Numo::NArray] The matrix hyperbolic tangent of `a`.
+    def tanhm(a)
+      raise Numo::NArray::ShapeError, 'input array a must be 2-dimensional' if a.ndim != 2
+      raise Numo::NArray::ShapeError, 'input array a must be square' if a.shape[0] != a.shape[1]
+
+      a_sinh = sinhm(a)
+      a_cosh = coshm(a)
+      a_sinh.dot(Numo::Linalg.inv(a_cosh))
+    end
+
     # Computes the inverse of a matrix using its LU decomposition.
     #
     # @param lu [Numo::NArray] The LU decomposition of the n-by-n matrix `A`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: numo-linalg-alt
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - yoshoku
@@ -50,10 +50,14 @@ files:
 - ext/numo/linalg/converter.c
 - ext/numo/linalg/converter.h
 - ext/numo/linalg/extconf.rb
+- ext/numo/linalg/lapack/gebal.c
+- ext/numo/linalg/lapack/gebal.h
 - ext/numo/linalg/lapack/gees.c
 - ext/numo/linalg/lapack/gees.h
 - ext/numo/linalg/lapack/geev.c
 - ext/numo/linalg/lapack/geev.h
+- ext/numo/linalg/lapack/gehrd.c
+- ext/numo/linalg/lapack/gehrd.h
 - ext/numo/linalg/lapack/gelsd.c
 - ext/numo/linalg/lapack/gelsd.h
 - ext/numo/linalg/lapack/geqrf.c
@@ -90,6 +94,8 @@ files:
 - ext/numo/linalg/lapack/hetrf.h
 - ext/numo/linalg/lapack/lange.c
 - ext/numo/linalg/lapack/lange.h
+- ext/numo/linalg/lapack/orghr.c
+- ext/numo/linalg/lapack/orghr.h
 - ext/numo/linalg/lapack/orgqr.c
 - ext/numo/linalg/lapack/orgqr.h
 - ext/numo/linalg/lapack/orgrq.c
@@ -116,6 +122,8 @@ files:
 - ext/numo/linalg/lapack/sytrf.h
 - ext/numo/linalg/lapack/trtrs.c
 - ext/numo/linalg/lapack/trtrs.h
+- ext/numo/linalg/lapack/unghr.c
+- ext/numo/linalg/lapack/unghr.h
 - ext/numo/linalg/lapack/ungqr.c
 - ext/numo/linalg/lapack/ungqr.h
 - ext/numo/linalg/lapack/ungrq.c
@@ -134,7 +142,7 @@ metadata:
   homepage_uri: https://github.com/yoshoku/numo-linalg-alt
   source_code_uri: https://github.com/yoshoku/numo-linalg-alt
   changelog_uri: https://github.com/yoshoku/numo-linalg-alt/blob/main/CHANGELOG.md
-  documentation_uri: https://gemdocs.org/gems/numo-linalg-alt/0.4.0/
+  documentation_uri: https://gemdocs.org/gems/numo-linalg-alt/0.5.0/
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: