Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.9/dist-packages/scipy/linalg/lapack.py: 55%
64 statements
« prev ^ index » next coverage.py v7.3.1, created at 2023-09-23 06:43 +0000
1"""
2Low-level LAPACK functions (:mod:`scipy.linalg.lapack`)
3=======================================================
5This module contains low-level functions from the LAPACK library.
7.. versionadded:: 0.12.0
9.. note::
11 The common ``overwrite_<>`` option in many routines, allows the
12 input arrays to be overwritten to avoid extra memory allocation.
13 However this requires the array to satisfy two conditions
14 which are memory order and the data type to match exactly the
15 order and the type expected by the routine.
17 As an example, if you pass a double precision float array to any
18 ``S....`` routine which expects single precision arguments, f2py
19 will create an intermediate array to match the argument types and
20 overwriting will be performed on that intermediate array.
22 Similarly, if a C-contiguous array is passed, f2py will pass a
23 FORTRAN-contiguous array internally. Please make sure that these
24 details are satisfied. More information can be found in the f2py
25 documentation.
27.. warning::
29 These functions do little to no error checking.
30 It is possible to cause crashes by mis-using them,
31 so prefer using the higher-level routines in `scipy.linalg`.
33Finding functions
34-----------------
36.. autosummary::
37 :toctree: generated/
39 get_lapack_funcs
41All functions
42-------------
44.. autosummary::
45 :toctree: generated/
47 sgbsv
48 dgbsv
49 cgbsv
50 zgbsv
52 sgbtrf
53 dgbtrf
54 cgbtrf
55 zgbtrf
57 sgbtrs
58 dgbtrs
59 cgbtrs
60 zgbtrs
62 sgebal
63 dgebal
64 cgebal
65 zgebal
67 sgecon
68 dgecon
69 cgecon
70 zgecon
72 sgeequ
73 dgeequ
74 cgeequ
75 zgeequ
77 sgeequb
78 dgeequb
79 cgeequb
80 zgeequb
82 sgees
83 dgees
84 cgees
85 zgees
87 sgeev
88 dgeev
89 cgeev
90 zgeev
92 sgeev_lwork
93 dgeev_lwork
94 cgeev_lwork
95 zgeev_lwork
97 sgehrd
98 dgehrd
99 cgehrd
100 zgehrd
102 sgehrd_lwork
103 dgehrd_lwork
104 cgehrd_lwork
105 zgehrd_lwork
107 sgejsv
108 dgejsv
110 sgels
111 dgels
112 cgels
113 zgels
115 sgels_lwork
116 dgels_lwork
117 cgels_lwork
118 zgels_lwork
120 sgelsd
121 dgelsd
122 cgelsd
123 zgelsd
125 sgelsd_lwork
126 dgelsd_lwork
127 cgelsd_lwork
128 zgelsd_lwork
130 sgelss
131 dgelss
132 cgelss
133 zgelss
135 sgelss_lwork
136 dgelss_lwork
137 cgelss_lwork
138 zgelss_lwork
140 sgelsy
141 dgelsy
142 cgelsy
143 zgelsy
145 sgelsy_lwork
146 dgelsy_lwork
147 cgelsy_lwork
148 zgelsy_lwork
150 sgeqp3
151 dgeqp3
152 cgeqp3
153 zgeqp3
155 sgeqrf
156 dgeqrf
157 cgeqrf
158 zgeqrf
160 sgeqrf_lwork
161 dgeqrf_lwork
162 cgeqrf_lwork
163 zgeqrf_lwork
165 sgeqrfp
166 dgeqrfp
167 cgeqrfp
168 zgeqrfp
170 sgeqrfp_lwork
171 dgeqrfp_lwork
172 cgeqrfp_lwork
173 zgeqrfp_lwork
175 sgerqf
176 dgerqf
177 cgerqf
178 zgerqf
180 sgesdd
181 dgesdd
182 cgesdd
183 zgesdd
185 sgesdd_lwork
186 dgesdd_lwork
187 cgesdd_lwork
188 zgesdd_lwork
190 sgesv
191 dgesv
192 cgesv
193 zgesv
195 sgesvd
196 dgesvd
197 cgesvd
198 zgesvd
200 sgesvd_lwork
201 dgesvd_lwork
202 cgesvd_lwork
203 zgesvd_lwork
205 sgesvx
206 dgesvx
207 cgesvx
208 zgesvx
210 sgetrf
211 dgetrf
212 cgetrf
213 zgetrf
215 sgetc2
216 dgetc2
217 cgetc2
218 zgetc2
220 sgetri
221 dgetri
222 cgetri
223 zgetri
225 sgetri_lwork
226 dgetri_lwork
227 cgetri_lwork
228 zgetri_lwork
230 sgetrs
231 dgetrs
232 cgetrs
233 zgetrs
235 sgesc2
236 dgesc2
237 cgesc2
238 zgesc2
240 sgges
241 dgges
242 cgges
243 zgges
245 sggev
246 dggev
247 cggev
248 zggev
250 sgglse
251 dgglse
252 cgglse
253 zgglse
255 sgglse_lwork
256 dgglse_lwork
257 cgglse_lwork
258 zgglse_lwork
260 sgtsv
261 dgtsv
262 cgtsv
263 zgtsv
265 sgtsvx
266 dgtsvx
267 cgtsvx
268 zgtsvx
270 chbevd
271 zhbevd
273 chbevx
274 zhbevx
276 checon
277 zhecon
279 cheequb
280 zheequb
282 cheev
283 zheev
285 cheev_lwork
286 zheev_lwork
288 cheevd
289 zheevd
291 cheevd_lwork
292 zheevd_lwork
294 cheevr
295 zheevr
297 cheevr_lwork
298 zheevr_lwork
300 cheevx
301 zheevx
303 cheevx_lwork
304 zheevx_lwork
306 chegst
307 zhegst
309 chegv
310 zhegv
312 chegv_lwork
313 zhegv_lwork
315 chegvd
316 zhegvd
318 chegvx
319 zhegvx
321 chegvx_lwork
322 zhegvx_lwork
324 chesv
325 zhesv
327 chesv_lwork
328 zhesv_lwork
330 chesvx
331 zhesvx
333 chesvx_lwork
334 zhesvx_lwork
336 chetrd
337 zhetrd
339 chetrd_lwork
340 zhetrd_lwork
342 chetrf
343 zhetrf
345 chetrf_lwork
346 zhetrf_lwork
348 chfrk
349 zhfrk
351 slamch
352 dlamch
354 slange
355 dlange
356 clange
357 zlange
359 slarf
360 dlarf
361 clarf
362 zlarf
364 slarfg
365 dlarfg
366 clarfg
367 zlarfg
369 slartg
370 dlartg
371 clartg
372 zlartg
374 slasd4
375 dlasd4
377 slaswp
378 dlaswp
379 claswp
380 zlaswp
382 slauum
383 dlauum
384 clauum
385 zlauum
387 sorcsd
388 dorcsd
389 sorcsd_lwork
390 dorcsd_lwork
392 sorghr
393 dorghr
394 sorghr_lwork
395 dorghr_lwork
397 sorgqr
398 dorgqr
400 sorgrq
401 dorgrq
403 sormqr
404 dormqr
406 sormrz
407 dormrz
409 sormrz_lwork
410 dormrz_lwork
412 spbsv
413 dpbsv
414 cpbsv
415 zpbsv
417 spbtrf
418 dpbtrf
419 cpbtrf
420 zpbtrf
422 spbtrs
423 dpbtrs
424 cpbtrs
425 zpbtrs
427 spftrf
428 dpftrf
429 cpftrf
430 zpftrf
432 spftri
433 dpftri
434 cpftri
435 zpftri
437 spftrs
438 dpftrs
439 cpftrs
440 zpftrs
442 spocon
443 dpocon
444 cpocon
445 zpocon
447 spstrf
448 dpstrf
449 cpstrf
450 zpstrf
452 spstf2
453 dpstf2
454 cpstf2
455 zpstf2
457 sposv
458 dposv
459 cposv
460 zposv
462 sposvx
463 dposvx
464 cposvx
465 zposvx
467 spotrf
468 dpotrf
469 cpotrf
470 zpotrf
472 spotri
473 dpotri
474 cpotri
475 zpotri
477 spotrs
478 dpotrs
479 cpotrs
480 zpotrs
482 sppcon
483 dppcon
484 cppcon
485 zppcon
487 sppsv
488 dppsv
489 cppsv
490 zppsv
492 spptrf
493 dpptrf
494 cpptrf
495 zpptrf
497 spptri
498 dpptri
499 cpptri
500 zpptri
502 spptrs
503 dpptrs
504 cpptrs
505 zpptrs
507 sptsv
508 dptsv
509 cptsv
510 zptsv
512 sptsvx
513 dptsvx
514 cptsvx
515 zptsvx
517 spttrf
518 dpttrf
519 cpttrf
520 zpttrf
522 spttrs
523 dpttrs
524 cpttrs
525 zpttrs
527 spteqr
528 dpteqr
529 cpteqr
530 zpteqr
532 crot
533 zrot
535 ssbev
536 dsbev
538 ssbevd
539 dsbevd
541 ssbevx
542 dsbevx
544 ssfrk
545 dsfrk
547 sstebz
548 dstebz
550 sstein
551 dstein
553 sstemr
554 dstemr
556 sstemr_lwork
557 dstemr_lwork
559 ssterf
560 dsterf
562 sstev
563 dstev
565 ssycon
566 dsycon
567 csycon
568 zsycon
570 ssyconv
571 dsyconv
572 csyconv
573 zsyconv
575 ssyequb
576 dsyequb
577 csyequb
578 zsyequb
580 ssyev
581 dsyev
583 ssyev_lwork
584 dsyev_lwork
586 ssyevd
587 dsyevd
589 ssyevd_lwork
590 dsyevd_lwork
592 ssyevr
593 dsyevr
595 ssyevr_lwork
596 dsyevr_lwork
598 ssyevx
599 dsyevx
601 ssyevx_lwork
602 dsyevx_lwork
604 ssygst
605 dsygst
607 ssygv
608 dsygv
610 ssygv_lwork
611 dsygv_lwork
613 ssygvd
614 dsygvd
616 ssygvx
617 dsygvx
619 ssygvx_lwork
620 dsygvx_lwork
622 ssysv
623 dsysv
624 csysv
625 zsysv
627 ssysv_lwork
628 dsysv_lwork
629 csysv_lwork
630 zsysv_lwork
632 ssysvx
633 dsysvx
634 csysvx
635 zsysvx
637 ssysvx_lwork
638 dsysvx_lwork
639 csysvx_lwork
640 zsysvx_lwork
642 ssytf2
643 dsytf2
644 csytf2
645 zsytf2
647 ssytrd
648 dsytrd
650 ssytrd_lwork
651 dsytrd_lwork
653 ssytrf
654 dsytrf
655 csytrf
656 zsytrf
658 ssytrf_lwork
659 dsytrf_lwork
660 csytrf_lwork
661 zsytrf_lwork
663 stbtrs
664 dtbtrs
665 ctbtrs
666 ztbtrs
668 stfsm
669 dtfsm
670 ctfsm
671 ztfsm
673 stfttp
674 dtfttp
675 ctfttp
676 ztfttp
678 stfttr
679 dtfttr
680 ctfttr
681 ztfttr
683 stgexc
684 dtgexc
685 ctgexc
686 ztgexc
688 stgsen
689 dtgsen
690 ctgsen
691 ztgsen
693 stgsen_lwork
694 dtgsen_lwork
695 ctgsen_lwork
696 ztgsen_lwork
698 stgsyl
699 dtgsyl
701 stpttf
702 dtpttf
703 ctpttf
704 ztpttf
706 stpttr
707 dtpttr
708 ctpttr
709 ztpttr
711 strexc
712 dtrexc
713 ctrexc
714 ztrexc
716 strsen
717 dtrsen
718 ctrsen
719 ztrsen
721 strsen_lwork
722 dtrsen_lwork
723 ctrsen_lwork
724 ztrsen_lwork
726 strsyl
727 dtrsyl
728 ctrsyl
729 ztrsyl
731 strtri
732 dtrtri
733 ctrtri
734 ztrtri
736 strtrs
737 dtrtrs
738 ctrtrs
739 ztrtrs
741 strttf
742 dtrttf
743 ctrttf
744 ztrttf
746 strttp
747 dtrttp
748 ctrttp
749 ztrttp
751 stzrzf
752 dtzrzf
753 ctzrzf
754 ztzrzf
756 stzrzf_lwork
757 dtzrzf_lwork
758 ctzrzf_lwork
759 ztzrzf_lwork
761 cunghr
762 zunghr
764 cunghr_lwork
765 zunghr_lwork
767 cungqr
768 zungqr
770 cungrq
771 zungrq
773 cunmqr
774 zunmqr
776 sgeqrt
777 dgeqrt
778 cgeqrt
779 zgeqrt
781 sgemqrt
782 dgemqrt
783 cgemqrt
784 zgemqrt
786 sgttrf
787 dgttrf
788 cgttrf
789 zgttrf
791 sgttrs
792 dgttrs
793 cgttrs
794 zgttrs
796 stpqrt
797 dtpqrt
798 ctpqrt
799 ztpqrt
801 stpmqrt
802 dtpmqrt
803 ctpmqrt
804 ztpmqrt
806 cuncsd
807 zuncsd
809 cuncsd_lwork
810 zuncsd_lwork
812 cunmrz
813 zunmrz
815 cunmrz_lwork
816 zunmrz_lwork
818 ilaver
820"""
821#
822# Author: Pearu Peterson, March 2002
823#
825import numpy as _np
826from .blas import _get_funcs, _memoize_get_funcs
827from scipy.linalg import _flapack
828from re import compile as regex_compile
829try:
830 from scipy.linalg import _clapack
831except ImportError:
832 _clapack = None
834try:
835 from scipy.linalg import _flapack_64
836 HAS_ILP64 = True
837except ImportError:
838 HAS_ILP64 = False
839 _flapack_64 = None
842# Expose all functions (only flapack --- clapack is an implementation detail)
843empty_module = None
844from scipy.linalg._flapack import *
845del empty_module
847__all__ = ['get_lapack_funcs']
849# some convenience alias for complex functions
850_lapack_alias = {
851 'corghr': 'cunghr', 'zorghr': 'zunghr',
852 'corghr_lwork': 'cunghr_lwork', 'zorghr_lwork': 'zunghr_lwork',
853 'corgqr': 'cungqr', 'zorgqr': 'zungqr',
854 'cormqr': 'cunmqr', 'zormqr': 'zunmqr',
855 'corgrq': 'cungrq', 'zorgrq': 'zungrq',
856}
859# Place guards against docstring rendering issues with special characters
860p1 = regex_compile(r'with bounds (?P<b>.*?)( and (?P<s>.*?) storage){0,1}\n')
861p2 = regex_compile(r'Default: (?P<d>.*?)\n')
864def backtickrepl(m):
865 if m.group('s'):
866 return ('with bounds ``{}`` with ``{}`` storage\n'
867 ''.format(m.group('b'), m.group('s')))
868 else:
869 return 'with bounds ``{}``\n'.format(m.group('b'))
872for routine in [ssyevr, dsyevr, cheevr, zheevr,
873 ssyevx, dsyevx, cheevx, zheevx,
874 ssygvd, dsygvd, chegvd, zhegvd]:
875 if routine.__doc__:
876 routine.__doc__ = p1.sub(backtickrepl, routine.__doc__)
877 routine.__doc__ = p2.sub('Default ``\\1``\n', routine.__doc__)
878 else:
879 continue
881del regex_compile, p1, p2, backtickrepl
884@_memoize_get_funcs
885def get_lapack_funcs(names, arrays=(), dtype=None, ilp64=False):
886 """Return available LAPACK function objects from names.
888 Arrays are used to determine the optimal prefix of LAPACK routines.
890 Parameters
891 ----------
892 names : str or sequence of str
893 Name(s) of LAPACK functions without type prefix.
895 arrays : sequence of ndarrays, optional
896 Arrays can be given to determine optimal prefix of LAPACK
897 routines. If not given, double-precision routines will be
898 used, otherwise the most generic type in arrays will be used.
900 dtype : str or dtype, optional
901 Data-type specifier. Not used if `arrays` is non-empty.
903 ilp64 : {True, False, 'preferred'}, optional
904 Whether to return ILP64 routine variant.
905 Choosing 'preferred' returns ILP64 routine if available, and
906 otherwise the 32-bit routine. Default: False
908 Returns
909 -------
910 funcs : list
911 List containing the found function(s).
913 Notes
914 -----
915 This routine automatically chooses between Fortran/C
916 interfaces. Fortran code is used whenever possible for arrays with
917 column major order. In all other cases, C code is preferred.
919 In LAPACK, the naming convention is that all functions start with a
920 type prefix, which depends on the type of the principal
921 matrix. These can be one of {'s', 'd', 'c', 'z'} for the NumPy
922 types {float32, float64, complex64, complex128} respectively, and
923 are stored in attribute ``typecode`` of the returned functions.
925 Examples
926 --------
927 Suppose we would like to use '?lange' routine which computes the selected
928 norm of an array. We pass our array in order to get the correct 'lange'
929 flavor.
931 >>> import numpy as np
932 >>> import scipy.linalg as LA
933 >>> rng = np.random.default_rng()
935 >>> a = rng.random((3,2))
936 >>> x_lange = LA.get_lapack_funcs('lange', (a,))
937 >>> x_lange.typecode
938 'd'
939 >>> x_lange = LA.get_lapack_funcs('lange',(a*1j,))
940 >>> x_lange.typecode
941 'z'
943 Several LAPACK routines work best when its internal WORK array has
944 the optimal size (big enough for fast computation and small enough to
945 avoid waste of memory). This size is determined also by a dedicated query
946 to the function which is often wrapped as a standalone function and
947 commonly denoted as ``###_lwork``. Below is an example for ``?sysv``
949 >>> a = rng.random((1000, 1000))
950 >>> b = rng.random((1000, 1)) * 1j
951 >>> # We pick up zsysv and zsysv_lwork due to b array
952 ... xsysv, xlwork = LA.get_lapack_funcs(('sysv', 'sysv_lwork'), (a, b))
953 >>> opt_lwork, _ = xlwork(a.shape[0]) # returns a complex for 'z' prefix
954 >>> udut, ipiv, x, info = xsysv(a, b, lwork=int(opt_lwork.real))
956 """
957 if isinstance(ilp64, str):
958 if ilp64 == 'preferred':
959 ilp64 = HAS_ILP64
960 else:
961 raise ValueError("Invalid value for 'ilp64'")
963 if not ilp64:
964 return _get_funcs(names, arrays, dtype,
965 "LAPACK", _flapack, _clapack,
966 "flapack", "clapack", _lapack_alias,
967 ilp64=False)
968 else:
969 if not HAS_ILP64:
970 raise RuntimeError("LAPACK ILP64 routine requested, but Scipy "
971 "compiled only with 32-bit BLAS")
972 return _get_funcs(names, arrays, dtype,
973 "LAPACK", _flapack_64, None,
974 "flapack_64", None, _lapack_alias,
975 ilp64=True)
978_int32_max = _np.iinfo(_np.int32).max
979_int64_max = _np.iinfo(_np.int64).max
982def _compute_lwork(routine, *args, **kwargs):
983 """
984 Round floating-point lwork returned by lapack to integer.
986 Several LAPACK routines compute optimal values for LWORK, which
987 they return in a floating-point variable. However, for large
988 values of LWORK, single-precision floating point is not sufficient
989 to hold the exact value --- some LAPACK versions (<= 3.5.0 at
990 least) truncate the returned integer to single precision and in
991 some cases this can be smaller than the required value.
993 Examples
994 --------
995 >>> from scipy.linalg import lapack
996 >>> n = 5000
997 >>> s_r, s_lw = lapack.get_lapack_funcs(('sysvx', 'sysvx_lwork'))
998 >>> lwork = lapack._compute_lwork(s_lw, n)
999 >>> lwork
1000 32000
1002 """
1003 dtype = getattr(routine, 'dtype', None)
1004 int_dtype = getattr(routine, 'int_dtype', None)
1005 ret = routine(*args, **kwargs)
1006 if ret[-1] != 0:
1007 raise ValueError("Internal work array size computation failed: "
1008 "%d" % (ret[-1],))
1010 if len(ret) == 2:
1011 return _check_work_float(ret[0].real, dtype, int_dtype)
1012 else:
1013 return tuple(_check_work_float(x.real, dtype, int_dtype)
1014 for x in ret[:-1])
1017def _check_work_float(value, dtype, int_dtype):
1018 """
1019 Convert LAPACK-returned work array size float to integer,
1020 carefully for single-precision types.
1021 """
1023 if dtype == _np.float32 or dtype == _np.complex64:
1024 # Single-precision routine -- take next fp value to work
1025 # around possible truncation in LAPACK code
1026 value = _np.nextafter(value, _np.inf, dtype=_np.float32)
1028 value = int(value)
1029 if int_dtype.itemsize == 4:
1030 if value < 0 or value > _int32_max:
1031 raise ValueError("Too large work array required -- computation "
1032 "cannot be performed with standard 32-bit"
1033 " LAPACK.")
1034 elif int_dtype.itemsize == 8:
1035 if value < 0 or value > _int64_max:
1036 raise ValueError("Too large work array required -- computation"
1037 " cannot be performed with standard 64-bit"
1038 " LAPACK.")
1039 return value