numo-linalg-alt 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94dfd3c199541e6dc2b71968e11450af79613c6dba382c3ac0cd64541f2d8461
-  data.tar.gz: 9a7bc15d245eeb94a97c524a474f10345b78a7693ab766b0cbea3353791e22b1
+  metadata.gz: 42941b98550789f5cca4d1eb91a1dd88442a7f89574ef38b8260ec3882ec4eba
+  data.tar.gz: 15a4fa8b6147463a8fd91f9fbd16f688ebf5cc01becdf4f0589e515b7f00fd99
 SHA512:
-  metadata.gz: 2cc8b7019527b642d0827f3f1b1943e7f16889ec83af93c8ba85b6b2209f6fb17c33b457c362679ea296f48b64c6bc03811b2bb6f4ace28d9a859d18d049fcea
-  data.tar.gz: d68a26e612d144410100b56706157ef7434a6844c96d4540748cb08ebbe11843445de84667c9406e591274f3622e72f4176231f9af979a3782893b72fbd5abc7
+  metadata.gz: 85e6b6deefa0cd3fca1204cf2ccf2c337386061e79403dd420e51745869c9f4548bedd72bf9ca78b9f5506fdc9808b635810fb7a515f3e318bcbd46bd8c65e45
+  data.tar.gz: a109ac617d606e70fa8aec1f2c721ab588316b845628b912b7cc381c62bf770326a31c97e750a9308163695ba7c7d9593084060fc766e07e081db8c7559e29c7

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+## [[0.7.0](https://github.com/yoshoku/numo-linalg-alt/compare/v0.6.0...v0.7.0)] - 2025-11-11
+
+**Breaking changes**
+
+improve error handling for LAPACK functions:
+
+- add `LapackError` class under `Numo::Linalg` module.
+  - This exception class is raised when invalid arguments are passed to a LAPACK function or
+    when the algorithm does not execute successfully. In previous versions, `StandardError`
+    was raised in these cases.
+    ```ruby
+    > Numo::Linalg.inv(Numo::DFloat[[3, 1], [9, 3]])
+    /numo-linalg-alt/lib/numo/linalg.rb:418:in 'Numo::Linalg.inv': The matrix is singular, and
+    the inverse matrix could not be computed. (Numo::Linalg::LapackError)
+    ```
+- change `solve`, `lu_fact`, `ldl`, and `qz` methods to issue a warning instead of raising an
+  error when the algorithm completes but produces a result that may affect further computations,
+  such as when the resulting matrix is sigular.
+  ```ruby
+  > Numo::Linalg.solve(Numo::DFloat.zeros(2, 2), Numo::DFloat.ones(2))
+  the factorization has been completed, but the factor is singular, so the solution could not be computed.
+  =>
+  Numo::DFloat#shape=[2]
+  [1, 1]
+  ```
+- change `det` method to return zero instead of raising an error when the input matrix is singular.
+  ```ruby
+  Numo::Linalg.det(Numo::DFloat[[1, 2], [2, 4]])
+  => -0.0
+  ```
+
 ## [[0.6.0](https://github.com/yoshoku/numo-linalg-alt/compare/v0.5.0...v0.6.0)] - 2025-11-02
 
 - add `--with-blas` and `--with-lapacke` options for selecting backend libraries.

data/lib/numo/linalg/version.rb

@@ -5,6 +5,6 @@ module Numo
   # Numo::Linalg Alternative (numo-linalg-alt) is an alternative to Numo::Linalg.
   module Linalg
     # The version of numo-linalg-alt you install.
-    VERSION = '0.6.0'
+    VERSION = '0.7.0'
   end
 end

data/lib/numo/linalg.rb

@@ -8,6 +8,9 @@ require_relative 'linalg/linalg'
 module Numo
   # Numo::Linalg Alternative (numo-linalg-alt) is an alternative to Numo::Linalg.
   module Linalg # rubocop:disable Metrics/ModuleLength
+    # Exception class for errors occurred in LAPACK functions.
+    class LapackError < StandardError; end
+
     module_function
 
     # Computes the eigenvalues and eigenvectors of a symmetric / Hermitian matrix
@@ -341,7 +344,7 @@ module Numo
 
       fnc = :"#{bchr}potrs"
       x, info = Numo::Linalg::Lapack.send(fnc, a, b.dup, uplo: uplo)
-      raise "the #{-info}-th argument of potrs had illegal value" if info.negative?
+      raise LapackError, "the #{-info}-th argument of potrs had illegal value" if info.negative?
 
       x
     end
@@ -366,8 +369,12 @@ module Numo
 
       getrf = :"#{bchr}getrf"
       lu, piv, info = Numo::Linalg::Lapack.send(getrf, a.dup)
-      raise "the #{-info}-th argument of getrf had illegal value" if info.negative?
-      raise 'the factor U is singular, and the inverse matrix could not be computed.' if info.positive?
+      raise LapackError, "the #{-info}-th argument of getrf had illegal value" if info.negative?
+
+      # info > 0 means the factor U has a zero diagonal element and is singular.
+      # In this case, the determinant is zero. The method should simply return 0.0.
+      # Therefore, the error is not raised here.
+      # raise 'the factor U is singular, ...' if info.positive?
 
       det_l = 1
       det_u = lu.diagonal.prod
@@ -405,12 +412,11 @@ module Numo
       getri = :"#{bchr}getri"
 
       lu, piv, info = Numo::Linalg::Lapack.send(getrf, a.dup)
-      raise "the #{-info}-th argument of getrf had illegal value" if info.negative?
-      raise 'the factor U is singular, and the inverse matrix could not be computed.' if info.positive?
+      raise LapackError, "the #{-info}-th argument of getrf had illegal value" if info.negative?
 
       a_inv, info = Numo::Linalg::Lapack.send(getri, lu, piv)
-      raise "the #{-info}-th argument of getrf had illegal value" if info.negative?
-      raise 'the factor U is singular, and the inverse matrix could not be computed.' if info.positive?
+      raise LapackError, "the #{-info}-th argument of getrf had illegal value" if info.negative?
+      raise LapackError, 'The matrix is singular, and the inverse matrix could not be computed.' if info.positive?
 
       a_inv
     end
@@ -611,7 +617,7 @@ module Numo
 
       fnc = :"#{bchr}gerqf"
       rq, tau, info = Numo::Linalg::Lapack.send(fnc, a.dup)
-      raise "the #{-info}-th argument of #{fnc} had illegal value" if info.negative?
+      raise LapackError, "the #{-info}-th argument of #{fnc} had illegal value" if info.negative?
 
       m, n = rq.shape
       r = rq.triu(n - m).dup
@@ -629,7 +635,7 @@ module Numo
             end
 
       q, info = Numo::Linalg::Lapack.send(fnc, tmp, tau)
-      raise "the #{-info}-th argument of #{fnc} had illegal value" if info.negative?
+      raise LapackError, "the #{-info}-th argument of #{fnc} had illegal value" if info.negative?
 
       [r, q]
     end
@@ -674,8 +680,21 @@ module Numo
         aa, bb, _alpha, _beta, q, z, _sdim, info = Numo::Linalg::Lapack.send(fnc, a.dup, b.dup)
       end
 
-      raise "the #{-info}-th argument of #{fnc} had illegal value" if info.negative?
-      raise 'the QZ algorithm failed.' if info.positive?
+      n = a.shape[0]
+      raise LapackError, "the #{-info}-th argument of #{fnc} had illegal value" if info.negative?
+      raise LapackError, 'something other than QZ iteration failed.' if info == n + 1
+      raise LapackError, "reordering failed in #{bchr}tgsen" if info == n + 3
+
+      if info == n + 2
+        raise LapackError, 'after reordering, roundoff changed values of some eigenvalues ' \
+                           'so that leading eigenvalues in the Generalized Schur form no ' \
+                           'longer satisfy the sorting condition.'
+      end
+
+      if info.positive? && info <= n
+        warn('the QZ iteration failed. (a, b) are not in Schur form, ' \
+             "but alpha[i] and beta[i] for i = #{info},...,n are correct.")
+      end
 
       [aa, bb, q, z]
     end
@@ -731,10 +750,15 @@ module Numo
       end
 
       n = a.shape[0]
-      raise "the #{-info}-th argument of #{fnc} had illegal value" if info.negative?
-      raise 'the QR algorithm failed to compute all the eigenvalues.' if info.positive? && info <= n
-      raise 'the eigenvalues could not be reordered.' if info == n + 1
-      raise 'after reordering, roundoff changed values of some complex eigenvalues.' if info == n + 2
+      raise LapackError, "the #{-info}-th argument of #{fnc} had illegal value" if info.negative?
+      raise LapackError, 'the QR algorithm failed to compute all the eigenvalues.' if info.positive? && info <= n
+      raise LapackError, 'the eigenvalues could not be reordered.' if info == n + 1
+
+      if info == n + 2
+        raise LapackError, 'after reordering, roundoff changed values of some eigenvalues ' \
+                           'so that leading eigenvalues in the Schur form no longer satisfy ' \
+                           'the sorting condition.'
+      end
 
       [b, v, sdim]
     end
@@ -778,12 +802,12 @@ module Numo
       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?
+      raise LapackError, "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?
+      raise LapackError, "the #{-info}-th argument of #{func} had illegal value" if info.negative?
 
       h = hq.triu(-1)
       return h unless calc_q
@@ -791,7 +815,7 @@ module Numo
       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?
+      raise LapackError, "the #{-info}-th argument of #{func} had illegal value" if info.negative?
 
       [h, q]
     end
@@ -830,8 +854,12 @@ module Numo
 
       gesv = :"#{bchr}gesv"
       _lu, x, _ipiv, info = Numo::Linalg::Lapack.send(gesv, a.dup, b.dup)
-      raise "the #{-info}-th argument of getrf had illegal value" if info.negative?
-      raise 'the factor U is singular, and the solution could not be computed.' if info.positive?
+      raise LapackError, "the #{-info}-th argument of getrf had illegal value" if info.negative?
+
+      if info.positive?
+        warn('the factorization has been completed, but the factor is singular, ' \
+             'so the solution could not be computed.')
+      end
 
       x
     end
@@ -870,7 +898,7 @@ module Numo
       trtrs = :"#{bchr}trtrs"
       uplo = lower ? 'L' : 'U'
       x, info = Numo::Linalg::Lapack.send(trtrs, a, b.dup, uplo: uplo)
-      raise "wrong value is given to the #{info}-th argument of #{trtrs} used internally" if info.negative?
+      raise LapackError, "wrong value is given to the #{info}-th argument of #{trtrs} used internally" if info.negative?
 
       x
     end
@@ -926,9 +954,9 @@ module Numo
         raise ArgumentError, "invalid driver: #{driver}"
       end
 
-      raise "the #{info.abs}-th argument had illegal value" if info.negative?
-      raise 'input array has a NAN entry' if info == -4
-      raise 'svd did not converge' if info.positive?
+      raise LapackError, "the #{info.abs}-th argument had illegal value" if info.negative?
+      raise LapackError, 'the input array has a NAN entry' if info == -4
+      raise LapackError, 'the did not converge' if info.positive?
 
       [s, u, vt]
     end
@@ -1015,9 +1043,9 @@ module Numo
         raise ArgumentError, "invalid driver: #{driver}"
       end
 
-      raise "the #{info.abs}-th argument had illegal value" if info.negative?
-      raise 'input array has a NAN entry' if info == -4
-      raise 'svd did not converge' if info.positive?
+      raise LapackError, "the #{info.abs}-th argument had illegal value" if info.negative?
+      raise LapackError, 'the input array has a NAN entry' if info == -4
+      raise LapackError, 'the decomposition did not converge' if info.positive?
 
       s
     end
@@ -1143,8 +1171,12 @@ module Numo
       getrf = :"#{bchr}getrf"
       lu, piv, info = Numo::Linalg::Lapack.send(getrf, a.dup)
 
-      raise "the #{info.abs}-th argument of getrf had illegal value" if info.negative?
-      raise "the U(#{info}, #{info}) is exactly zero. The factorization has been completed." if info.positive?
+      raise LapackError, "the #{info.abs}-th argument of getrf had illegal value" if info.negative?
+
+      if info.positive?
+        warn("the factorization has been completed, but the factor U[#{info - 1}, #{info - 1}] is " \
+             'exactly zero, indicating that the matrix is singular.')
+      end
 
       [lu, piv]
     end
@@ -1182,7 +1214,7 @@ module Numo
       getrs = :"#{bchr}getrs"
       x, info = Numo::Linalg::Lapack.send(getrs, lu, ipiv, b.dup)
 
-      raise "the #{info.abs}-th argument of getrs had illegal value" if info.negative?
+      raise LapackError, "the #{info.abs}-th argument of getrs had illegal value" if info.negative?
 
       x
     end
@@ -1203,8 +1235,12 @@ module Numo
       fnc = :"#{bchr}potrf"
       c, info = Numo::Linalg::Lapack.send(fnc, a.dup, uplo: uplo)
 
-      raise "the #{info}-th leading minor of the array is not positive definite, and the factorization could not be completed." if info.positive?
-      raise "the #{-info}-th argument of #{fnc} had illegal value" if info.negative?
+      raise LapackError, "the #{-info}-th argument of #{fnc} had illegal value" if info.negative?
+
+      if info.positive?
+        raise LapackError, "the leading principal minor of order #{info} is not positive, " \
+                           'and the factorization could not be completed.'
+      end
 
       c
     end
@@ -1300,7 +1336,7 @@ module Numo
       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?
+      raise LapackError, "the #{info.abs}-th argument of #{fnc} had illegal value" if info.negative?
 
       # convert from Fortran style index to Ruby style index.
       lo -= 1
@@ -1377,8 +1413,8 @@ module Numo
         wr, wi, vl, vr, info = Numo::Linalg::Lapack.send(fnc, a.dup, jobvl: jobvl, jobvr: jobvr)
       end
 
-      raise "the #{info.abs}-th argument of #{fnc} had illegal value" if info.negative?
-      raise 'the QR algorithm failed to compute all the eigenvalues.' if info.positive?
+      raise LapackError, "the #{info.abs}-th argument of #{fnc} had illegal value" if info.negative?
+      raise LapackError, 'the QR algorithm failed to compute all the eigenvalues.' if info.positive?
 
       if %w[d s].include?(bchr)
         w = wr + (wi * 1.0i)
@@ -1422,8 +1458,8 @@ module Numo
         w = wr + (wi * 1.0i)
       end
 
-      raise "the #{info.abs}-th argument of #{fnc} had illegal value" if info.negative?
-      raise 'the QR algorithm failed to compute all the eigenvalues.' if info.positive?
+      raise LapackError, "the #{info.abs}-th argument of #{fnc} had illegal value" if info.negative?
+      raise LapackError, 'the QR algorithm failed to compute all the eigenvalues.' if info.positive?
 
       w
     end
@@ -1473,8 +1509,12 @@ module Numo
       lud = a.dup
       ipiv, info = Numo::Linalg::Lapack.send(fnc, lud, uplo: uplo)
 
-      raise "the #{info.abs}-th argument of #{fnc} had illegal value" if info.negative?
-      raise 'the factorization has been completed' if info.positive?
+      raise LapackError, "the #{info.abs}-th argument of #{fnc} had illegal value" if info.negative?
+
+      if info.positive?
+        warn("the factorization has been completed, but the D[#{info - 1}, #{info - 1}] is " \
+             'exactly zero, indicating that the block diagonal matrix is singular.')
+      end
 
       _lud_permutation(lud, ipiv, uplo: uplo, hermitian: hermitian)
     end
@@ -1562,8 +1602,8 @@ module Numo
       fnc = :"#{bchr}gelsd"
       s, rank, info = Numo::Linalg::Lapack.send(fnc, a.dup, x, rcond: rcond)
 
-      raise "the #{info.abs}-th argument of #{fnc} had illegal value" if info.negative?
-      raise 'the algorithm for computing the SVD failed to converge' if info.positive?
+      raise LapackError, "the #{info.abs}-th argument of #{fnc} had illegal value" if info.negative?
+      raise LapackError, 'the algorithm for computing the SVD failed to converge' if info.positive?
 
       resids = x.class[]
       if m > n
@@ -1765,8 +1805,8 @@ module Numo
       fnc = :"#{bchr}getri"
       inv, info = Numo::Linalg::Lapack.send(fnc, lu.dup, ipiv)
 
-      raise "the #{info.abs}-th argument of #{fnc} had illegal value" if info.negative?
-      raise 'the matrix is singular and its inverse could not be computed' if info.positive?
+      raise LapackError, "the #{info.abs}-th argument of #{fnc} had illegal value" if info.negative?
+      raise LapackError, 'the matrix is singular and its inverse could not be computed' if info.positive?
 
       inv
     end
@@ -1796,8 +1836,12 @@ module Numo
       fnc = :"#{bchr}potri"
       inv, info = Numo::Linalg::Lapack.send(fnc, a.dup, uplo: uplo)
 
-      raise "the #{info.abs}-th argument of #{fnc} had illegal value" if info.negative?
-      raise "the (#{info}, #info)-th element of the factor U or L is zero, and the inverse could not be computed." if info.positive?
+      raise LapackError, "the #{info.abs}-th argument of #{fnc} had illegal value" if info.negative?
+
+      if info.positive?
+        raise LapackError, "the (#{info - 1}, #{info - 1})-th element of the factor U or L is zero, " \
+                           'and the inverse could not be computed.'
+      end
 
       inv
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: numo-linalg-alt
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - yoshoku
@@ -145,7 +145,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.6.0/
+  documentation_uri: https://gemdocs.org/gems/numo-linalg-alt/0.7.0/
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -161,7 +161,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Numo::Linalg Alternative (numo-linalg-alt) is an alternative to Numo::Linalg.
 test_files: []