Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/scipy/linalg/_interpolative_backend.py: 20%
285 statements
« prev ^ index » next coverage.py v7.3.2, created at 2023-12-12 06:31 +0000
1#******************************************************************************
2# Copyright (C) 2013 Kenneth L. Ho
3#
4# Redistribution and use in source and binary forms, with or without
5# modification, are permitted provided that the following conditions are met:
6#
7# Redistributions of source code must retain the above copyright notice, this
8# list of conditions and the following disclaimer. Redistributions in binary
9# form must reproduce the above copyright notice, this list of conditions and
10# the following disclaimer in the documentation and/or other materials
11# provided with the distribution.
12#
13# None of the names of the copyright holders may be used to endorse or
14# promote products derived from this software without specific prior written
15# permission.
16#
17# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
18# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
21# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27# POSSIBILITY OF SUCH DAMAGE.
28#******************************************************************************
30"""
31Direct wrappers for Fortran `id_dist` backend.
32"""
34import scipy.linalg._interpolative as _id
35import numpy as np
37_RETCODE_ERROR = RuntimeError("nonzero return code")
40def _asfortranarray_copy(A):
41 """
42 Same as np.asfortranarray, but ensure a copy
43 """
44 A = np.asarray(A)
45 if A.flags.f_contiguous:
46 A = A.copy(order="F")
47 else:
48 A = np.asfortranarray(A)
49 return A
52#------------------------------------------------------------------------------
53# id_rand.f
54#------------------------------------------------------------------------------
56def id_srand(n):
57 """
58 Generate standard uniform pseudorandom numbers via a very efficient lagged
59 Fibonacci method.
61 :param n:
62 Number of pseudorandom numbers to generate.
63 :type n: int
65 :return:
66 Pseudorandom numbers.
67 :rtype: :class:`numpy.ndarray`
68 """
69 return _id.id_srand(n)
72def id_srandi(t):
73 """
74 Initialize seed values for :func:`id_srand` (any appropriately random
75 numbers will do).
77 :param t:
78 Array of 55 seed values.
79 :type t: :class:`numpy.ndarray`
80 """
81 t = np.asfortranarray(t)
82 _id.id_srandi(t)
85def id_srando():
86 """
87 Reset seed values to their original values.
88 """
89 _id.id_srando()
92#------------------------------------------------------------------------------
93# idd_frm.f
94#------------------------------------------------------------------------------
96def idd_frm(n, w, x):
97 """
98 Transform real vector via a composition of Rokhlin's random transform,
99 random subselection, and an FFT.
101 In contrast to :func:`idd_sfrm`, this routine works best when the length of
102 the transformed vector is the power-of-two integer output by
103 :func:`idd_frmi`, or when the length is not specified but instead
104 determined a posteriori from the output. The returned transformed vector is
105 randomly permuted.
107 :param n:
108 Greatest power-of-two integer satisfying `n <= x.size` as obtained from
109 :func:`idd_frmi`; `n` is also the length of the output vector.
110 :type n: int
111 :param w:
112 Initialization array constructed by :func:`idd_frmi`.
113 :type w: :class:`numpy.ndarray`
114 :param x:
115 Vector to be transformed.
116 :type x: :class:`numpy.ndarray`
118 :return:
119 Transformed vector.
120 :rtype: :class:`numpy.ndarray`
121 """
122 return _id.idd_frm(n, w, x)
125def idd_sfrm(l, n, w, x):
126 """
127 Transform real vector via a composition of Rokhlin's random transform,
128 random subselection, and an FFT.
130 In contrast to :func:`idd_frm`, this routine works best when the length of
131 the transformed vector is known a priori.
133 :param l:
134 Length of transformed vector, satisfying `l <= n`.
135 :type l: int
136 :param n:
137 Greatest power-of-two integer satisfying `n <= x.size` as obtained from
138 :func:`idd_sfrmi`.
139 :type n: int
140 :param w:
141 Initialization array constructed by :func:`idd_sfrmi`.
142 :type w: :class:`numpy.ndarray`
143 :param x:
144 Vector to be transformed.
145 :type x: :class:`numpy.ndarray`
147 :return:
148 Transformed vector.
149 :rtype: :class:`numpy.ndarray`
150 """
151 return _id.idd_sfrm(l, n, w, x)
154def idd_frmi(m):
155 """
156 Initialize data for :func:`idd_frm`.
158 :param m:
159 Length of vector to be transformed.
160 :type m: int
162 :return:
163 Greatest power-of-two integer `n` satisfying `n <= m`.
164 :rtype: int
165 :return:
166 Initialization array to be used by :func:`idd_frm`.
167 :rtype: :class:`numpy.ndarray`
168 """
169 return _id.idd_frmi(m)
172def idd_sfrmi(l, m):
173 """
174 Initialize data for :func:`idd_sfrm`.
176 :param l:
177 Length of output transformed vector.
178 :type l: int
179 :param m:
180 Length of the vector to be transformed.
181 :type m: int
183 :return:
184 Greatest power-of-two integer `n` satisfying `n <= m`.
185 :rtype: int
186 :return:
187 Initialization array to be used by :func:`idd_sfrm`.
188 :rtype: :class:`numpy.ndarray`
189 """
190 return _id.idd_sfrmi(l, m)
193#------------------------------------------------------------------------------
194# idd_id.f
195#------------------------------------------------------------------------------
197def iddp_id(eps, A):
198 """
199 Compute ID of a real matrix to a specified relative precision.
201 :param eps:
202 Relative precision.
203 :type eps: float
204 :param A:
205 Matrix.
206 :type A: :class:`numpy.ndarray`
208 :return:
209 Rank of ID.
210 :rtype: int
211 :return:
212 Column index array.
213 :rtype: :class:`numpy.ndarray`
214 :return:
215 Interpolation coefficients.
216 :rtype: :class:`numpy.ndarray`
217 """
218 A = _asfortranarray_copy(A)
219 k, idx, rnorms = _id.iddp_id(eps, A)
220 n = A.shape[1]
221 proj = A.T.ravel()[:k*(n-k)].reshape((k, n-k), order='F')
222 return k, idx, proj
225def iddr_id(A, k):
226 """
227 Compute ID of a real matrix to a specified rank.
229 :param A:
230 Matrix.
231 :type A: :class:`numpy.ndarray`
232 :param k:
233 Rank of ID.
234 :type k: int
236 :return:
237 Column index array.
238 :rtype: :class:`numpy.ndarray`
239 :return:
240 Interpolation coefficients.
241 :rtype: :class:`numpy.ndarray`
242 """
243 A = _asfortranarray_copy(A)
244 idx, rnorms = _id.iddr_id(A, k)
245 n = A.shape[1]
246 proj = A.T.ravel()[:k*(n-k)].reshape((k, n-k), order='F')
247 return idx, proj
250def idd_reconid(B, idx, proj):
251 """
252 Reconstruct matrix from real ID.
254 :param B:
255 Skeleton matrix.
256 :type B: :class:`numpy.ndarray`
257 :param idx:
258 Column index array.
259 :type idx: :class:`numpy.ndarray`
260 :param proj:
261 Interpolation coefficients.
262 :type proj: :class:`numpy.ndarray`
264 :return:
265 Reconstructed matrix.
266 :rtype: :class:`numpy.ndarray`
267 """
268 B = np.asfortranarray(B)
269 if proj.size > 0:
270 return _id.idd_reconid(B, idx, proj)
271 else:
272 return B[:, np.argsort(idx)]
275def idd_reconint(idx, proj):
276 """
277 Reconstruct interpolation matrix from real ID.
279 :param idx:
280 Column index array.
281 :type idx: :class:`numpy.ndarray`
282 :param proj:
283 Interpolation coefficients.
284 :type proj: :class:`numpy.ndarray`
286 :return:
287 Interpolation matrix.
288 :rtype: :class:`numpy.ndarray`
289 """
290 return _id.idd_reconint(idx, proj)
293def idd_copycols(A, k, idx):
294 """
295 Reconstruct skeleton matrix from real ID.
297 :param A:
298 Original matrix.
299 :type A: :class:`numpy.ndarray`
300 :param k:
301 Rank of ID.
302 :type k: int
303 :param idx:
304 Column index array.
305 :type idx: :class:`numpy.ndarray`
307 :return:
308 Skeleton matrix.
309 :rtype: :class:`numpy.ndarray`
310 """
311 A = np.asfortranarray(A)
312 return _id.idd_copycols(A, k, idx)
315#------------------------------------------------------------------------------
316# idd_id2svd.f
317#------------------------------------------------------------------------------
319def idd_id2svd(B, idx, proj):
320 """
321 Convert real ID to SVD.
323 :param B:
324 Skeleton matrix.
325 :type B: :class:`numpy.ndarray`
326 :param idx:
327 Column index array.
328 :type idx: :class:`numpy.ndarray`
329 :param proj:
330 Interpolation coefficients.
331 :type proj: :class:`numpy.ndarray`
333 :return:
334 Left singular vectors.
335 :rtype: :class:`numpy.ndarray`
336 :return:
337 Right singular vectors.
338 :rtype: :class:`numpy.ndarray`
339 :return:
340 Singular values.
341 :rtype: :class:`numpy.ndarray`
342 """
343 B = np.asfortranarray(B)
344 U, V, S, ier = _id.idd_id2svd(B, idx, proj)
345 if ier:
346 raise _RETCODE_ERROR
347 return U, V, S
350#------------------------------------------------------------------------------
351# idd_snorm.f
352#------------------------------------------------------------------------------
354def idd_snorm(m, n, matvect, matvec, its=20):
355 """
356 Estimate spectral norm of a real matrix by the randomized power method.
358 :param m:
359 Matrix row dimension.
360 :type m: int
361 :param n:
362 Matrix column dimension.
363 :type n: int
364 :param matvect:
365 Function to apply the matrix transpose to a vector, with call signature
366 `y = matvect(x)`, where `x` and `y` are the input and output vectors,
367 respectively.
368 :type matvect: function
369 :param matvec:
370 Function to apply the matrix to a vector, with call signature
371 `y = matvec(x)`, where `x` and `y` are the input and output vectors,
372 respectively.
373 :type matvec: function
374 :param its:
375 Number of power method iterations.
376 :type its: int
378 :return:
379 Spectral norm estimate.
380 :rtype: float
381 """
382 snorm, v = _id.idd_snorm(m, n, matvect, matvec, its)
383 return snorm
386def idd_diffsnorm(m, n, matvect, matvect2, matvec, matvec2, its=20):
387 """
388 Estimate spectral norm of the difference of two real matrices by the
389 randomized power method.
391 :param m:
392 Matrix row dimension.
393 :type m: int
394 :param n:
395 Matrix column dimension.
396 :type n: int
397 :param matvect:
398 Function to apply the transpose of the first matrix to a vector, with
399 call signature `y = matvect(x)`, where `x` and `y` are the input and
400 output vectors, respectively.
401 :type matvect: function
402 :param matvect2:
403 Function to apply the transpose of the second matrix to a vector, with
404 call signature `y = matvect2(x)`, where `x` and `y` are the input and
405 output vectors, respectively.
406 :type matvect2: function
407 :param matvec:
408 Function to apply the first matrix to a vector, with call signature
409 `y = matvec(x)`, where `x` and `y` are the input and output vectors,
410 respectively.
411 :type matvec: function
412 :param matvec2:
413 Function to apply the second matrix to a vector, with call signature
414 `y = matvec2(x)`, where `x` and `y` are the input and output vectors,
415 respectively.
416 :type matvec2: function
417 :param its:
418 Number of power method iterations.
419 :type its: int
421 :return:
422 Spectral norm estimate of matrix difference.
423 :rtype: float
424 """
425 return _id.idd_diffsnorm(m, n, matvect, matvect2, matvec, matvec2, its)
428#------------------------------------------------------------------------------
429# idd_svd.f
430#------------------------------------------------------------------------------
432def iddr_svd(A, k):
433 """
434 Compute SVD of a real matrix to a specified rank.
436 :param A:
437 Matrix.
438 :type A: :class:`numpy.ndarray`
439 :param k:
440 Rank of SVD.
441 :type k: int
443 :return:
444 Left singular vectors.
445 :rtype: :class:`numpy.ndarray`
446 :return:
447 Right singular vectors.
448 :rtype: :class:`numpy.ndarray`
449 :return:
450 Singular values.
451 :rtype: :class:`numpy.ndarray`
452 """
453 A = np.asfortranarray(A)
454 U, V, S, ier = _id.iddr_svd(A, k)
455 if ier:
456 raise _RETCODE_ERROR
457 return U, V, S
460def iddp_svd(eps, A):
461 """
462 Compute SVD of a real matrix to a specified relative precision.
464 :param eps:
465 Relative precision.
466 :type eps: float
467 :param A:
468 Matrix.
469 :type A: :class:`numpy.ndarray`
471 :return:
472 Left singular vectors.
473 :rtype: :class:`numpy.ndarray`
474 :return:
475 Right singular vectors.
476 :rtype: :class:`numpy.ndarray`
477 :return:
478 Singular values.
479 :rtype: :class:`numpy.ndarray`
480 """
481 A = np.asfortranarray(A)
482 m, n = A.shape
483 k, iU, iV, iS, w, ier = _id.iddp_svd(eps, A)
484 if ier:
485 raise _RETCODE_ERROR
486 U = w[iU-1:iU+m*k-1].reshape((m, k), order='F')
487 V = w[iV-1:iV+n*k-1].reshape((n, k), order='F')
488 S = w[iS-1:iS+k-1]
489 return U, V, S
492#------------------------------------------------------------------------------
493# iddp_aid.f
494#------------------------------------------------------------------------------
496def iddp_aid(eps, A):
497 """
498 Compute ID of a real matrix to a specified relative precision using random
499 sampling.
501 :param eps:
502 Relative precision.
503 :type eps: float
504 :param A:
505 Matrix.
506 :type A: :class:`numpy.ndarray`
508 :return:
509 Rank of ID.
510 :rtype: int
511 :return:
512 Column index array.
513 :rtype: :class:`numpy.ndarray`
514 :return:
515 Interpolation coefficients.
516 :rtype: :class:`numpy.ndarray`
517 """
518 A = np.asfortranarray(A)
519 m, n = A.shape
520 n2, w = idd_frmi(m)
521 proj = np.empty(n*(2*n2 + 1) + n2 + 1, order='F')
522 k, idx, proj = _id.iddp_aid(eps, A, w, proj)
523 proj = proj[:k*(n-k)].reshape((k, n-k), order='F')
524 return k, idx, proj
527def idd_estrank(eps, A):
528 """
529 Estimate rank of a real matrix to a specified relative precision using
530 random sampling.
532 The output rank is typically about 8 higher than the actual rank.
534 :param eps:
535 Relative precision.
536 :type eps: float
537 :param A:
538 Matrix.
539 :type A: :class:`numpy.ndarray`
541 :return:
542 Rank estimate.
543 :rtype: int
544 """
545 A = np.asfortranarray(A)
546 m, n = A.shape
547 n2, w = idd_frmi(m)
548 ra = np.empty(n*n2 + (n + 1)*(n2 + 1), order='F')
549 k, ra = _id.idd_estrank(eps, A, w, ra)
550 return k
553#------------------------------------------------------------------------------
554# iddp_asvd.f
555#------------------------------------------------------------------------------
557def iddp_asvd(eps, A):
558 """
559 Compute SVD of a real matrix to a specified relative precision using random
560 sampling.
562 :param eps:
563 Relative precision.
564 :type eps: float
565 :param A:
566 Matrix.
567 :type A: :class:`numpy.ndarray`
569 :return:
570 Left singular vectors.
571 :rtype: :class:`numpy.ndarray`
572 :return:
573 Right singular vectors.
574 :rtype: :class:`numpy.ndarray`
575 :return:
576 Singular values.
577 :rtype: :class:`numpy.ndarray`
578 """
579 A = np.asfortranarray(A)
580 m, n = A.shape
581 n2, winit = _id.idd_frmi(m)
582 w = np.empty(
583 max((min(m, n) + 1)*(3*m + 5*n + 1) + 25*min(m, n)**2,
584 (2*n + 1)*(n2 + 1)),
585 order='F')
586 k, iU, iV, iS, w, ier = _id.iddp_asvd(eps, A, winit, w)
587 if ier:
588 raise _RETCODE_ERROR
589 U = w[iU-1:iU+m*k-1].reshape((m, k), order='F')
590 V = w[iV-1:iV+n*k-1].reshape((n, k), order='F')
591 S = w[iS-1:iS+k-1]
592 return U, V, S
595#------------------------------------------------------------------------------
596# iddp_rid.f
597#------------------------------------------------------------------------------
599def iddp_rid(eps, m, n, matvect):
600 """
601 Compute ID of a real matrix to a specified relative precision using random
602 matrix-vector multiplication.
604 :param eps:
605 Relative precision.
606 :type eps: float
607 :param m:
608 Matrix row dimension.
609 :type m: int
610 :param n:
611 Matrix column dimension.
612 :type n: int
613 :param matvect:
614 Function to apply the matrix transpose to a vector, with call signature
615 `y = matvect(x)`, where `x` and `y` are the input and output vectors,
616 respectively.
617 :type matvect: function
619 :return:
620 Rank of ID.
621 :rtype: int
622 :return:
623 Column index array.
624 :rtype: :class:`numpy.ndarray`
625 :return:
626 Interpolation coefficients.
627 :rtype: :class:`numpy.ndarray`
628 """
629 proj = np.empty(m + 1 + 2*n*(min(m, n) + 1), order='F')
630 k, idx, proj, ier = _id.iddp_rid(eps, m, n, matvect, proj)
631 if ier != 0:
632 raise _RETCODE_ERROR
633 proj = proj[:k*(n-k)].reshape((k, n-k), order='F')
634 return k, idx, proj
637def idd_findrank(eps, m, n, matvect):
638 """
639 Estimate rank of a real matrix to a specified relative precision using
640 random matrix-vector multiplication.
642 :param eps:
643 Relative precision.
644 :type eps: float
645 :param m:
646 Matrix row dimension.
647 :type m: int
648 :param n:
649 Matrix column dimension.
650 :type n: int
651 :param matvect:
652 Function to apply the matrix transpose to a vector, with call signature
653 `y = matvect(x)`, where `x` and `y` are the input and output vectors,
654 respectively.
655 :type matvect: function
657 :return:
658 Rank estimate.
659 :rtype: int
660 """
661 k, ra, ier = _id.idd_findrank(eps, m, n, matvect)
662 if ier:
663 raise _RETCODE_ERROR
664 return k
667#------------------------------------------------------------------------------
668# iddp_rsvd.f
669#------------------------------------------------------------------------------
671def iddp_rsvd(eps, m, n, matvect, matvec):
672 """
673 Compute SVD of a real matrix to a specified relative precision using random
674 matrix-vector multiplication.
676 :param eps:
677 Relative precision.
678 :type eps: float
679 :param m:
680 Matrix row dimension.
681 :type m: int
682 :param n:
683 Matrix column dimension.
684 :type n: int
685 :param matvect:
686 Function to apply the matrix transpose to a vector, with call signature
687 `y = matvect(x)`, where `x` and `y` are the input and output vectors,
688 respectively.
689 :type matvect: function
690 :param matvec:
691 Function to apply the matrix to a vector, with call signature
692 `y = matvec(x)`, where `x` and `y` are the input and output vectors,
693 respectively.
694 :type matvec: function
696 :return:
697 Left singular vectors.
698 :rtype: :class:`numpy.ndarray`
699 :return:
700 Right singular vectors.
701 :rtype: :class:`numpy.ndarray`
702 :return:
703 Singular values.
704 :rtype: :class:`numpy.ndarray`
705 """
706 k, iU, iV, iS, w, ier = _id.iddp_rsvd(eps, m, n, matvect, matvec)
707 if ier:
708 raise _RETCODE_ERROR
709 U = w[iU-1:iU+m*k-1].reshape((m, k), order='F')
710 V = w[iV-1:iV+n*k-1].reshape((n, k), order='F')
711 S = w[iS-1:iS+k-1]
712 return U, V, S
715#------------------------------------------------------------------------------
716# iddr_aid.f
717#------------------------------------------------------------------------------
719def iddr_aid(A, k):
720 """
721 Compute ID of a real matrix to a specified rank using random sampling.
723 :param A:
724 Matrix.
725 :type A: :class:`numpy.ndarray`
726 :param k:
727 Rank of ID.
728 :type k: int
730 :return:
731 Column index array.
732 :rtype: :class:`numpy.ndarray`
733 :return:
734 Interpolation coefficients.
735 :rtype: :class:`numpy.ndarray`
736 """
737 A = np.asfortranarray(A)
738 m, n = A.shape
739 w = iddr_aidi(m, n, k)
740 idx, proj = _id.iddr_aid(A, k, w)
741 if k == n:
742 proj = np.empty((k, n-k), dtype='float64', order='F')
743 else:
744 proj = proj.reshape((k, n-k), order='F')
745 return idx, proj
748def iddr_aidi(m, n, k):
749 """
750 Initialize array for :func:`iddr_aid`.
752 :param m:
753 Matrix row dimension.
754 :type m: int
755 :param n:
756 Matrix column dimension.
757 :type n: int
758 :param k:
759 Rank of ID.
760 :type k: int
762 :return:
763 Initialization array to be used by :func:`iddr_aid`.
764 :rtype: :class:`numpy.ndarray`
765 """
766 return _id.iddr_aidi(m, n, k)
769#------------------------------------------------------------------------------
770# iddr_asvd.f
771#------------------------------------------------------------------------------
773def iddr_asvd(A, k):
774 """
775 Compute SVD of a real matrix to a specified rank using random sampling.
777 :param A:
778 Matrix.
779 :type A: :class:`numpy.ndarray`
780 :param k:
781 Rank of SVD.
782 :type k: int
784 :return:
785 Left singular vectors.
786 :rtype: :class:`numpy.ndarray`
787 :return:
788 Right singular vectors.
789 :rtype: :class:`numpy.ndarray`
790 :return:
791 Singular values.
792 :rtype: :class:`numpy.ndarray`
793 """
794 A = np.asfortranarray(A)
795 m, n = A.shape
796 w = np.empty((2*k + 28)*m + (6*k + 21)*n + 25*k**2 + 100, order='F')
797 w_ = iddr_aidi(m, n, k)
798 w[:w_.size] = w_
799 U, V, S, ier = _id.iddr_asvd(A, k, w)
800 if ier != 0:
801 raise _RETCODE_ERROR
802 return U, V, S
805#------------------------------------------------------------------------------
806# iddr_rid.f
807#------------------------------------------------------------------------------
809def iddr_rid(m, n, matvect, k):
810 """
811 Compute ID of a real matrix to a specified rank using random matrix-vector
812 multiplication.
814 :param m:
815 Matrix row dimension.
816 :type m: int
817 :param n:
818 Matrix column dimension.
819 :type n: int
820 :param matvect:
821 Function to apply the matrix transpose to a vector, with call signature
822 `y = matvect(x)`, where `x` and `y` are the input and output vectors,
823 respectively.
824 :type matvect: function
825 :param k:
826 Rank of ID.
827 :type k: int
829 :return:
830 Column index array.
831 :rtype: :class:`numpy.ndarray`
832 :return:
833 Interpolation coefficients.
834 :rtype: :class:`numpy.ndarray`
835 """
836 idx, proj = _id.iddr_rid(m, n, matvect, k)
837 proj = proj[:k*(n-k)].reshape((k, n-k), order='F')
838 return idx, proj
841#------------------------------------------------------------------------------
842# iddr_rsvd.f
843#------------------------------------------------------------------------------
845def iddr_rsvd(m, n, matvect, matvec, k):
846 """
847 Compute SVD of a real matrix to a specified rank using random matrix-vector
848 multiplication.
850 :param m:
851 Matrix row dimension.
852 :type m: int
853 :param n:
854 Matrix column dimension.
855 :type n: int
856 :param matvect:
857 Function to apply the matrix transpose to a vector, with call signature
858 `y = matvect(x)`, where `x` and `y` are the input and output vectors,
859 respectively.
860 :type matvect: function
861 :param matvec:
862 Function to apply the matrix to a vector, with call signature
863 `y = matvec(x)`, where `x` and `y` are the input and output vectors,
864 respectively.
865 :type matvec: function
866 :param k:
867 Rank of SVD.
868 :type k: int
870 :return:
871 Left singular vectors.
872 :rtype: :class:`numpy.ndarray`
873 :return:
874 Right singular vectors.
875 :rtype: :class:`numpy.ndarray`
876 :return:
877 Singular values.
878 :rtype: :class:`numpy.ndarray`
879 """
880 U, V, S, ier = _id.iddr_rsvd(m, n, matvect, matvec, k)
881 if ier != 0:
882 raise _RETCODE_ERROR
883 return U, V, S
886#------------------------------------------------------------------------------
887# idz_frm.f
888#------------------------------------------------------------------------------
890def idz_frm(n, w, x):
891 """
892 Transform complex vector via a composition of Rokhlin's random transform,
893 random subselection, and an FFT.
895 In contrast to :func:`idz_sfrm`, this routine works best when the length of
896 the transformed vector is the power-of-two integer output by
897 :func:`idz_frmi`, or when the length is not specified but instead
898 determined a posteriori from the output. The returned transformed vector is
899 randomly permuted.
901 :param n:
902 Greatest power-of-two integer satisfying `n <= x.size` as obtained from
903 :func:`idz_frmi`; `n` is also the length of the output vector.
904 :type n: int
905 :param w:
906 Initialization array constructed by :func:`idz_frmi`.
907 :type w: :class:`numpy.ndarray`
908 :param x:
909 Vector to be transformed.
910 :type x: :class:`numpy.ndarray`
912 :return:
913 Transformed vector.
914 :rtype: :class:`numpy.ndarray`
915 """
916 return _id.idz_frm(n, w, x)
919def idz_sfrm(l, n, w, x):
920 """
921 Transform complex vector via a composition of Rokhlin's random transform,
922 random subselection, and an FFT.
924 In contrast to :func:`idz_frm`, this routine works best when the length of
925 the transformed vector is known a priori.
927 :param l:
928 Length of transformed vector, satisfying `l <= n`.
929 :type l: int
930 :param n:
931 Greatest power-of-two integer satisfying `n <= x.size` as obtained from
932 :func:`idz_sfrmi`.
933 :type n: int
934 :param w:
935 Initialization array constructed by :func:`idd_sfrmi`.
936 :type w: :class:`numpy.ndarray`
937 :param x:
938 Vector to be transformed.
939 :type x: :class:`numpy.ndarray`
941 :return:
942 Transformed vector.
943 :rtype: :class:`numpy.ndarray`
944 """
945 return _id.idz_sfrm(l, n, w, x)
948def idz_frmi(m):
949 """
950 Initialize data for :func:`idz_frm`.
952 :param m:
953 Length of vector to be transformed.
954 :type m: int
956 :return:
957 Greatest power-of-two integer `n` satisfying `n <= m`.
958 :rtype: int
959 :return:
960 Initialization array to be used by :func:`idz_frm`.
961 :rtype: :class:`numpy.ndarray`
962 """
963 return _id.idz_frmi(m)
966def idz_sfrmi(l, m):
967 """
968 Initialize data for :func:`idz_sfrm`.
970 :param l:
971 Length of output transformed vector.
972 :type l: int
973 :param m:
974 Length of the vector to be transformed.
975 :type m: int
977 :return:
978 Greatest power-of-two integer `n` satisfying `n <= m`.
979 :rtype: int
980 :return:
981 Initialization array to be used by :func:`idz_sfrm`.
982 :rtype: :class:`numpy.ndarray`
983 """
984 return _id.idz_sfrmi(l, m)
987#------------------------------------------------------------------------------
988# idz_id.f
989#------------------------------------------------------------------------------
991def idzp_id(eps, A):
992 """
993 Compute ID of a complex matrix to a specified relative precision.
995 :param eps:
996 Relative precision.
997 :type eps: float
998 :param A:
999 Matrix.
1000 :type A: :class:`numpy.ndarray`
1002 :return:
1003 Rank of ID.
1004 :rtype: int
1005 :return:
1006 Column index array.
1007 :rtype: :class:`numpy.ndarray`
1008 :return:
1009 Interpolation coefficients.
1010 :rtype: :class:`numpy.ndarray`
1011 """
1012 A = _asfortranarray_copy(A)
1013 k, idx, rnorms = _id.idzp_id(eps, A)
1014 n = A.shape[1]
1015 proj = A.T.ravel()[:k*(n-k)].reshape((k, n-k), order='F')
1016 return k, idx, proj
1019def idzr_id(A, k):
1020 """
1021 Compute ID of a complex matrix to a specified rank.
1023 :param A:
1024 Matrix.
1025 :type A: :class:`numpy.ndarray`
1026 :param k:
1027 Rank of ID.
1028 :type k: int
1030 :return:
1031 Column index array.
1032 :rtype: :class:`numpy.ndarray`
1033 :return:
1034 Interpolation coefficients.
1035 :rtype: :class:`numpy.ndarray`
1036 """
1037 A = _asfortranarray_copy(A)
1038 idx, rnorms = _id.idzr_id(A, k)
1039 n = A.shape[1]
1040 proj = A.T.ravel()[:k*(n-k)].reshape((k, n-k), order='F')
1041 return idx, proj
1044def idz_reconid(B, idx, proj):
1045 """
1046 Reconstruct matrix from complex ID.
1048 :param B:
1049 Skeleton matrix.
1050 :type B: :class:`numpy.ndarray`
1051 :param idx:
1052 Column index array.
1053 :type idx: :class:`numpy.ndarray`
1054 :param proj:
1055 Interpolation coefficients.
1056 :type proj: :class:`numpy.ndarray`
1058 :return:
1059 Reconstructed matrix.
1060 :rtype: :class:`numpy.ndarray`
1061 """
1062 B = np.asfortranarray(B)
1063 if proj.size > 0:
1064 return _id.idz_reconid(B, idx, proj)
1065 else:
1066 return B[:, np.argsort(idx)]
1069def idz_reconint(idx, proj):
1070 """
1071 Reconstruct interpolation matrix from complex ID.
1073 :param idx:
1074 Column index array.
1075 :type idx: :class:`numpy.ndarray`
1076 :param proj:
1077 Interpolation coefficients.
1078 :type proj: :class:`numpy.ndarray`
1080 :return:
1081 Interpolation matrix.
1082 :rtype: :class:`numpy.ndarray`
1083 """
1084 return _id.idz_reconint(idx, proj)
1087def idz_copycols(A, k, idx):
1088 """
1089 Reconstruct skeleton matrix from complex ID.
1091 :param A:
1092 Original matrix.
1093 :type A: :class:`numpy.ndarray`
1094 :param k:
1095 Rank of ID.
1096 :type k: int
1097 :param idx:
1098 Column index array.
1099 :type idx: :class:`numpy.ndarray`
1101 :return:
1102 Skeleton matrix.
1103 :rtype: :class:`numpy.ndarray`
1104 """
1105 A = np.asfortranarray(A)
1106 return _id.idz_copycols(A, k, idx)
1109#------------------------------------------------------------------------------
1110# idz_id2svd.f
1111#------------------------------------------------------------------------------
1113def idz_id2svd(B, idx, proj):
1114 """
1115 Convert complex ID to SVD.
1117 :param B:
1118 Skeleton matrix.
1119 :type B: :class:`numpy.ndarray`
1120 :param idx:
1121 Column index array.
1122 :type idx: :class:`numpy.ndarray`
1123 :param proj:
1124 Interpolation coefficients.
1125 :type proj: :class:`numpy.ndarray`
1127 :return:
1128 Left singular vectors.
1129 :rtype: :class:`numpy.ndarray`
1130 :return:
1131 Right singular vectors.
1132 :rtype: :class:`numpy.ndarray`
1133 :return:
1134 Singular values.
1135 :rtype: :class:`numpy.ndarray`
1136 """
1137 B = np.asfortranarray(B)
1138 U, V, S, ier = _id.idz_id2svd(B, idx, proj)
1139 if ier:
1140 raise _RETCODE_ERROR
1141 return U, V, S
1144#------------------------------------------------------------------------------
1145# idz_snorm.f
1146#------------------------------------------------------------------------------
1148def idz_snorm(m, n, matveca, matvec, its=20):
1149 """
1150 Estimate spectral norm of a complex matrix by the randomized power method.
1152 :param m:
1153 Matrix row dimension.
1154 :type m: int
1155 :param n:
1156 Matrix column dimension.
1157 :type n: int
1158 :param matveca:
1159 Function to apply the matrix adjoint to a vector, with call signature
1160 `y = matveca(x)`, where `x` and `y` are the input and output vectors,
1161 respectively.
1162 :type matveca: function
1163 :param matvec:
1164 Function to apply the matrix to a vector, with call signature
1165 `y = matvec(x)`, where `x` and `y` are the input and output vectors,
1166 respectively.
1167 :type matvec: function
1168 :param its:
1169 Number of power method iterations.
1170 :type its: int
1172 :return:
1173 Spectral norm estimate.
1174 :rtype: float
1175 """
1176 snorm, v = _id.idz_snorm(m, n, matveca, matvec, its)
1177 return snorm
1180def idz_diffsnorm(m, n, matveca, matveca2, matvec, matvec2, its=20):
1181 """
1182 Estimate spectral norm of the difference of two complex matrices by the
1183 randomized power method.
1185 :param m:
1186 Matrix row dimension.
1187 :type m: int
1188 :param n:
1189 Matrix column dimension.
1190 :type n: int
1191 :param matveca:
1192 Function to apply the adjoint of the first matrix to a vector, with
1193 call signature `y = matveca(x)`, where `x` and `y` are the input and
1194 output vectors, respectively.
1195 :type matveca: function
1196 :param matveca2:
1197 Function to apply the adjoint of the second matrix to a vector, with
1198 call signature `y = matveca2(x)`, where `x` and `y` are the input and
1199 output vectors, respectively.
1200 :type matveca2: function
1201 :param matvec:
1202 Function to apply the first matrix to a vector, with call signature
1203 `y = matvec(x)`, where `x` and `y` are the input and output vectors,
1204 respectively.
1205 :type matvec: function
1206 :param matvec2:
1207 Function to apply the second matrix to a vector, with call signature
1208 `y = matvec2(x)`, where `x` and `y` are the input and output vectors,
1209 respectively.
1210 :type matvec2: function
1211 :param its:
1212 Number of power method iterations.
1213 :type its: int
1215 :return:
1216 Spectral norm estimate of matrix difference.
1217 :rtype: float
1218 """
1219 return _id.idz_diffsnorm(m, n, matveca, matveca2, matvec, matvec2, its)
1222#------------------------------------------------------------------------------
1223# idz_svd.f
1224#------------------------------------------------------------------------------
1226def idzr_svd(A, k):
1227 """
1228 Compute SVD of a complex matrix to a specified rank.
1230 :param A:
1231 Matrix.
1232 :type A: :class:`numpy.ndarray`
1233 :param k:
1234 Rank of SVD.
1235 :type k: int
1237 :return:
1238 Left singular vectors.
1239 :rtype: :class:`numpy.ndarray`
1240 :return:
1241 Right singular vectors.
1242 :rtype: :class:`numpy.ndarray`
1243 :return:
1244 Singular values.
1245 :rtype: :class:`numpy.ndarray`
1246 """
1247 A = np.asfortranarray(A)
1248 U, V, S, ier = _id.idzr_svd(A, k)
1249 if ier:
1250 raise _RETCODE_ERROR
1251 return U, V, S
1254def idzp_svd(eps, A):
1255 """
1256 Compute SVD of a complex matrix to a specified relative precision.
1258 :param eps:
1259 Relative precision.
1260 :type eps: float
1261 :param A:
1262 Matrix.
1263 :type A: :class:`numpy.ndarray`
1265 :return:
1266 Left singular vectors.
1267 :rtype: :class:`numpy.ndarray`
1268 :return:
1269 Right singular vectors.
1270 :rtype: :class:`numpy.ndarray`
1271 :return:
1272 Singular values.
1273 :rtype: :class:`numpy.ndarray`
1274 """
1275 A = np.asfortranarray(A)
1276 m, n = A.shape
1277 k, iU, iV, iS, w, ier = _id.idzp_svd(eps, A)
1278 if ier:
1279 raise _RETCODE_ERROR
1280 U = w[iU-1:iU+m*k-1].reshape((m, k), order='F')
1281 V = w[iV-1:iV+n*k-1].reshape((n, k), order='F')
1282 S = w[iS-1:iS+k-1]
1283 return U, V, S
1286#------------------------------------------------------------------------------
1287# idzp_aid.f
1288#------------------------------------------------------------------------------
1290def idzp_aid(eps, A):
1291 """
1292 Compute ID of a complex matrix to a specified relative precision using
1293 random sampling.
1295 :param eps:
1296 Relative precision.
1297 :type eps: float
1298 :param A:
1299 Matrix.
1300 :type A: :class:`numpy.ndarray`
1302 :return:
1303 Rank of ID.
1304 :rtype: int
1305 :return:
1306 Column index array.
1307 :rtype: :class:`numpy.ndarray`
1308 :return:
1309 Interpolation coefficients.
1310 :rtype: :class:`numpy.ndarray`
1311 """
1312 A = np.asfortranarray(A)
1313 m, n = A.shape
1314 n2, w = idz_frmi(m)
1315 proj = np.empty(n*(2*n2 + 1) + n2 + 1, dtype='complex128', order='F')
1316 k, idx, proj = _id.idzp_aid(eps, A, w, proj)
1317 proj = proj[:k*(n-k)].reshape((k, n-k), order='F')
1318 return k, idx, proj
1321def idz_estrank(eps, A):
1322 """
1323 Estimate rank of a complex matrix to a specified relative precision using
1324 random sampling.
1326 The output rank is typically about 8 higher than the actual rank.
1328 :param eps:
1329 Relative precision.
1330 :type eps: float
1331 :param A:
1332 Matrix.
1333 :type A: :class:`numpy.ndarray`
1335 :return:
1336 Rank estimate.
1337 :rtype: int
1338 """
1339 A = np.asfortranarray(A)
1340 m, n = A.shape
1341 n2, w = idz_frmi(m)
1342 ra = np.empty(n*n2 + (n + 1)*(n2 + 1), dtype='complex128', order='F')
1343 k, ra = _id.idz_estrank(eps, A, w, ra)
1344 return k
1347#------------------------------------------------------------------------------
1348# idzp_asvd.f
1349#------------------------------------------------------------------------------
1351def idzp_asvd(eps, A):
1352 """
1353 Compute SVD of a complex matrix to a specified relative precision using
1354 random sampling.
1356 :param eps:
1357 Relative precision.
1358 :type eps: float
1359 :param A:
1360 Matrix.
1361 :type A: :class:`numpy.ndarray`
1363 :return:
1364 Left singular vectors.
1365 :rtype: :class:`numpy.ndarray`
1366 :return:
1367 Right singular vectors.
1368 :rtype: :class:`numpy.ndarray`
1369 :return:
1370 Singular values.
1371 :rtype: :class:`numpy.ndarray`
1372 """
1373 A = np.asfortranarray(A)
1374 m, n = A.shape
1375 n2, winit = _id.idz_frmi(m)
1376 w = np.empty(
1377 max((min(m, n) + 1)*(3*m + 5*n + 11) + 8*min(m, n)**2,
1378 (2*n + 1)*(n2 + 1)),
1379 dtype=np.complex128, order='F')
1380 k, iU, iV, iS, w, ier = _id.idzp_asvd(eps, A, winit, w)
1381 if ier:
1382 raise _RETCODE_ERROR
1383 U = w[iU-1:iU+m*k-1].reshape((m, k), order='F')
1384 V = w[iV-1:iV+n*k-1].reshape((n, k), order='F')
1385 S = w[iS-1:iS+k-1]
1386 return U, V, S
1389#------------------------------------------------------------------------------
1390# idzp_rid.f
1391#------------------------------------------------------------------------------
1393def idzp_rid(eps, m, n, matveca):
1394 """
1395 Compute ID of a complex matrix to a specified relative precision using
1396 random matrix-vector multiplication.
1398 :param eps:
1399 Relative precision.
1400 :type eps: float
1401 :param m:
1402 Matrix row dimension.
1403 :type m: int
1404 :param n:
1405 Matrix column dimension.
1406 :type n: int
1407 :param matveca:
1408 Function to apply the matrix adjoint to a vector, with call signature
1409 `y = matveca(x)`, where `x` and `y` are the input and output vectors,
1410 respectively.
1411 :type matveca: function
1413 :return:
1414 Rank of ID.
1415 :rtype: int
1416 :return:
1417 Column index array.
1418 :rtype: :class:`numpy.ndarray`
1419 :return:
1420 Interpolation coefficients.
1421 :rtype: :class:`numpy.ndarray`
1422 """
1423 proj = np.empty(
1424 m + 1 + 2*n*(min(m, n) + 1),
1425 dtype=np.complex128, order='F')
1426 k, idx, proj, ier = _id.idzp_rid(eps, m, n, matveca, proj)
1427 if ier:
1428 raise _RETCODE_ERROR
1429 proj = proj[:k*(n-k)].reshape((k, n-k), order='F')
1430 return k, idx, proj
1433def idz_findrank(eps, m, n, matveca):
1434 """
1435 Estimate rank of a complex matrix to a specified relative precision using
1436 random matrix-vector multiplication.
1438 :param eps:
1439 Relative precision.
1440 :type eps: float
1441 :param m:
1442 Matrix row dimension.
1443 :type m: int
1444 :param n:
1445 Matrix column dimension.
1446 :type n: int
1447 :param matveca:
1448 Function to apply the matrix adjoint to a vector, with call signature
1449 `y = matveca(x)`, where `x` and `y` are the input and output vectors,
1450 respectively.
1451 :type matveca: function
1453 :return:
1454 Rank estimate.
1455 :rtype: int
1456 """
1457 k, ra, ier = _id.idz_findrank(eps, m, n, matveca)
1458 if ier:
1459 raise _RETCODE_ERROR
1460 return k
1463#------------------------------------------------------------------------------
1464# idzp_rsvd.f
1465#------------------------------------------------------------------------------
1467def idzp_rsvd(eps, m, n, matveca, matvec):
1468 """
1469 Compute SVD of a complex matrix to a specified relative precision using
1470 random matrix-vector multiplication.
1472 :param eps:
1473 Relative precision.
1474 :type eps: float
1475 :param m:
1476 Matrix row dimension.
1477 :type m: int
1478 :param n:
1479 Matrix column dimension.
1480 :type n: int
1481 :param matveca:
1482 Function to apply the matrix adjoint to a vector, with call signature
1483 `y = matveca(x)`, where `x` and `y` are the input and output vectors,
1484 respectively.
1485 :type matveca: function
1486 :param matvec:
1487 Function to apply the matrix to a vector, with call signature
1488 `y = matvec(x)`, where `x` and `y` are the input and output vectors,
1489 respectively.
1490 :type matvec: function
1492 :return:
1493 Left singular vectors.
1494 :rtype: :class:`numpy.ndarray`
1495 :return:
1496 Right singular vectors.
1497 :rtype: :class:`numpy.ndarray`
1498 :return:
1499 Singular values.
1500 :rtype: :class:`numpy.ndarray`
1501 """
1502 k, iU, iV, iS, w, ier = _id.idzp_rsvd(eps, m, n, matveca, matvec)
1503 if ier:
1504 raise _RETCODE_ERROR
1505 U = w[iU-1:iU+m*k-1].reshape((m, k), order='F')
1506 V = w[iV-1:iV+n*k-1].reshape((n, k), order='F')
1507 S = w[iS-1:iS+k-1]
1508 return U, V, S
1511#------------------------------------------------------------------------------
1512# idzr_aid.f
1513#------------------------------------------------------------------------------
1515def idzr_aid(A, k):
1516 """
1517 Compute ID of a complex matrix to a specified rank using random sampling.
1519 :param A:
1520 Matrix.
1521 :type A: :class:`numpy.ndarray`
1522 :param k:
1523 Rank of ID.
1524 :type k: int
1526 :return:
1527 Column index array.
1528 :rtype: :class:`numpy.ndarray`
1529 :return:
1530 Interpolation coefficients.
1531 :rtype: :class:`numpy.ndarray`
1532 """
1533 A = np.asfortranarray(A)
1534 m, n = A.shape
1535 w = idzr_aidi(m, n, k)
1536 idx, proj = _id.idzr_aid(A, k, w)
1537 if k == n:
1538 proj = np.empty((k, n-k), dtype='complex128', order='F')
1539 else:
1540 proj = proj.reshape((k, n-k), order='F')
1541 return idx, proj
1544def idzr_aidi(m, n, k):
1545 """
1546 Initialize array for :func:`idzr_aid`.
1548 :param m:
1549 Matrix row dimension.
1550 :type m: int
1551 :param n:
1552 Matrix column dimension.
1553 :type n: int
1554 :param k:
1555 Rank of ID.
1556 :type k: int
1558 :return:
1559 Initialization array to be used by :func:`idzr_aid`.
1560 :rtype: :class:`numpy.ndarray`
1561 """
1562 return _id.idzr_aidi(m, n, k)
1565#------------------------------------------------------------------------------
1566# idzr_asvd.f
1567#------------------------------------------------------------------------------
1569def idzr_asvd(A, k):
1570 """
1571 Compute SVD of a complex matrix to a specified rank using random sampling.
1573 :param A:
1574 Matrix.
1575 :type A: :class:`numpy.ndarray`
1576 :param k:
1577 Rank of SVD.
1578 :type k: int
1580 :return:
1581 Left singular vectors.
1582 :rtype: :class:`numpy.ndarray`
1583 :return:
1584 Right singular vectors.
1585 :rtype: :class:`numpy.ndarray`
1586 :return:
1587 Singular values.
1588 :rtype: :class:`numpy.ndarray`
1589 """
1590 A = np.asfortranarray(A)
1591 m, n = A.shape
1592 w = np.empty(
1593 (2*k + 22)*m + (6*k + 21)*n + 8*k**2 + 10*k + 90,
1594 dtype='complex128', order='F')
1595 w_ = idzr_aidi(m, n, k)
1596 w[:w_.size] = w_
1597 U, V, S, ier = _id.idzr_asvd(A, k, w)
1598 if ier:
1599 raise _RETCODE_ERROR
1600 return U, V, S
1603#------------------------------------------------------------------------------
1604# idzr_rid.f
1605#------------------------------------------------------------------------------
1607def idzr_rid(m, n, matveca, k):
1608 """
1609 Compute ID of a complex matrix to a specified rank using random
1610 matrix-vector multiplication.
1612 :param m:
1613 Matrix row dimension.
1614 :type m: int
1615 :param n:
1616 Matrix column dimension.
1617 :type n: int
1618 :param matveca:
1619 Function to apply the matrix adjoint to a vector, with call signature
1620 `y = matveca(x)`, where `x` and `y` are the input and output vectors,
1621 respectively.
1622 :type matveca: function
1623 :param k:
1624 Rank of ID.
1625 :type k: int
1627 :return:
1628 Column index array.
1629 :rtype: :class:`numpy.ndarray`
1630 :return:
1631 Interpolation coefficients.
1632 :rtype: :class:`numpy.ndarray`
1633 """
1634 idx, proj = _id.idzr_rid(m, n, matveca, k)
1635 proj = proj[:k*(n-k)].reshape((k, n-k), order='F')
1636 return idx, proj
1639#------------------------------------------------------------------------------
1640# idzr_rsvd.f
1641#------------------------------------------------------------------------------
1643def idzr_rsvd(m, n, matveca, matvec, k):
1644 """
1645 Compute SVD of a complex matrix to a specified rank using random
1646 matrix-vector multiplication.
1648 :param m:
1649 Matrix row dimension.
1650 :type m: int
1651 :param n:
1652 Matrix column dimension.
1653 :type n: int
1654 :param matveca:
1655 Function to apply the matrix adjoint to a vector, with call signature
1656 `y = matveca(x)`, where `x` and `y` are the input and output vectors,
1657 respectively.
1658 :type matveca: function
1659 :param matvec:
1660 Function to apply the matrix to a vector, with call signature
1661 `y = matvec(x)`, where `x` and `y` are the input and output vectors,
1662 respectively.
1663 :type matvec: function
1664 :param k:
1665 Rank of SVD.
1666 :type k: int
1668 :return:
1669 Left singular vectors.
1670 :rtype: :class:`numpy.ndarray`
1671 :return:
1672 Right singular vectors.
1673 :rtype: :class:`numpy.ndarray`
1674 :return:
1675 Singular values.
1676 :rtype: :class:`numpy.ndarray`
1677 """
1678 U, V, S, ier = _id.idzr_rsvd(m, n, matveca, matvec, k)
1679 if ier:
1680 raise _RETCODE_ERROR
1681 return U, V, S