Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/scipy/linalg/lapack.py: 55%
64 statements
« prev ^ index » next coverage.py v7.3.2, created at 2023-12-12 06:31 +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 stpttf
699 dtpttf
700 ctpttf
701 ztpttf
703 stpttr
704 dtpttr
705 ctpttr
706 ztpttr
708 strexc
709 dtrexc
710 ctrexc
711 ztrexc
713 strsen
714 dtrsen
715 ctrsen
716 ztrsen
718 strsen_lwork
719 dtrsen_lwork
720 ctrsen_lwork
721 ztrsen_lwork
723 strsyl
724 dtrsyl
725 ctrsyl
726 ztrsyl
728 strtri
729 dtrtri
730 ctrtri
731 ztrtri
733 strtrs
734 dtrtrs
735 ctrtrs
736 ztrtrs
738 strttf
739 dtrttf
740 ctrttf
741 ztrttf
743 strttp
744 dtrttp
745 ctrttp
746 ztrttp
748 stzrzf
749 dtzrzf
750 ctzrzf
751 ztzrzf
753 stzrzf_lwork
754 dtzrzf_lwork
755 ctzrzf_lwork
756 ztzrzf_lwork
758 cunghr
759 zunghr
761 cunghr_lwork
762 zunghr_lwork
764 cungqr
765 zungqr
767 cungrq
768 zungrq
770 cunmqr
771 zunmqr
773 sgeqrt
774 dgeqrt
775 cgeqrt
776 zgeqrt
778 sgemqrt
779 dgemqrt
780 cgemqrt
781 zgemqrt
783 sgttrf
784 dgttrf
785 cgttrf
786 zgttrf
788 sgttrs
789 dgttrs
790 cgttrs
791 zgttrs
793 stpqrt
794 dtpqrt
795 ctpqrt
796 ztpqrt
798 stpmqrt
799 dtpmqrt
800 ctpmqrt
801 ztpmqrt
803 cuncsd
804 zuncsd
806 cuncsd_lwork
807 zuncsd_lwork
809 cunmrz
810 zunmrz
812 cunmrz_lwork
813 zunmrz_lwork
815 ilaver
817"""
818#
819# Author: Pearu Peterson, March 2002
820#
822import numpy as _np
823from .blas import _get_funcs, _memoize_get_funcs
824from scipy.linalg import _flapack
825from re import compile as regex_compile
826try:
827 from scipy.linalg import _clapack
828except ImportError:
829 _clapack = None
831try:
832 from scipy.linalg import _flapack_64
833 HAS_ILP64 = True
834except ImportError:
835 HAS_ILP64 = False
836 _flapack_64 = None
839# Expose all functions (only flapack --- clapack is an implementation detail)
840empty_module = None
841from scipy.linalg._flapack import *
842del empty_module
844__all__ = ['get_lapack_funcs']
846# some convenience alias for complex functions
847_lapack_alias = {
848 'corghr': 'cunghr', 'zorghr': 'zunghr',
849 'corghr_lwork': 'cunghr_lwork', 'zorghr_lwork': 'zunghr_lwork',
850 'corgqr': 'cungqr', 'zorgqr': 'zungqr',
851 'cormqr': 'cunmqr', 'zormqr': 'zunmqr',
852 'corgrq': 'cungrq', 'zorgrq': 'zungrq',
853}
856# Place guards against docstring rendering issues with special characters
857p1 = regex_compile(r'with bounds (?P<b>.*?)( and (?P<s>.*?) storage){0,1}\n')
858p2 = regex_compile(r'Default: (?P<d>.*?)\n')
861def backtickrepl(m):
862 if m.group('s'):
863 return ('with bounds ``{}`` with ``{}`` storage\n'
864 ''.format(m.group('b'), m.group('s')))
865 else:
866 return 'with bounds ``{}``\n'.format(m.group('b'))
869for routine in [ssyevr, dsyevr, cheevr, zheevr,
870 ssyevx, dsyevx, cheevx, zheevx,
871 ssygvd, dsygvd, chegvd, zhegvd]:
872 if routine.__doc__:
873 routine.__doc__ = p1.sub(backtickrepl, routine.__doc__)
874 routine.__doc__ = p2.sub('Default ``\\1``\n', routine.__doc__)
875 else:
876 continue
878del regex_compile, p1, p2, backtickrepl
881@_memoize_get_funcs
882def get_lapack_funcs(names, arrays=(), dtype=None, ilp64=False):
883 """Return available LAPACK function objects from names.
885 Arrays are used to determine the optimal prefix of LAPACK routines.
887 Parameters
888 ----------
889 names : str or sequence of str
890 Name(s) of LAPACK functions without type prefix.
892 arrays : sequence of ndarrays, optional
893 Arrays can be given to determine optimal prefix of LAPACK
894 routines. If not given, double-precision routines will be
895 used, otherwise the most generic type in arrays will be used.
897 dtype : str or dtype, optional
898 Data-type specifier. Not used if `arrays` is non-empty.
900 ilp64 : {True, False, 'preferred'}, optional
901 Whether to return ILP64 routine variant.
902 Choosing 'preferred' returns ILP64 routine if available, and
903 otherwise the 32-bit routine. Default: False
905 Returns
906 -------
907 funcs : list
908 List containing the found function(s).
910 Notes
911 -----
912 This routine automatically chooses between Fortran/C
913 interfaces. Fortran code is used whenever possible for arrays with
914 column major order. In all other cases, C code is preferred.
916 In LAPACK, the naming convention is that all functions start with a
917 type prefix, which depends on the type of the principal
918 matrix. These can be one of {'s', 'd', 'c', 'z'} for the NumPy
919 types {float32, float64, complex64, complex128} respectively, and
920 are stored in attribute ``typecode`` of the returned functions.
922 Examples
923 --------
924 Suppose we would like to use '?lange' routine which computes the selected
925 norm of an array. We pass our array in order to get the correct 'lange'
926 flavor.
928 >>> import numpy as np
929 >>> import scipy.linalg as LA
930 >>> rng = np.random.default_rng()
932 >>> a = rng.random((3,2))
933 >>> x_lange = LA.get_lapack_funcs('lange', (a,))
934 >>> x_lange.typecode
935 'd'
936 >>> x_lange = LA.get_lapack_funcs('lange',(a*1j,))
937 >>> x_lange.typecode
938 'z'
940 Several LAPACK routines work best when its internal WORK array has
941 the optimal size (big enough for fast computation and small enough to
942 avoid waste of memory). This size is determined also by a dedicated query
943 to the function which is often wrapped as a standalone function and
944 commonly denoted as ``###_lwork``. Below is an example for ``?sysv``
946 >>> a = rng.random((1000, 1000))
947 >>> b = rng.random((1000, 1)) * 1j
948 >>> # We pick up zsysv and zsysv_lwork due to b array
949 ... xsysv, xlwork = LA.get_lapack_funcs(('sysv', 'sysv_lwork'), (a, b))
950 >>> opt_lwork, _ = xlwork(a.shape[0]) # returns a complex for 'z' prefix
951 >>> udut, ipiv, x, info = xsysv(a, b, lwork=int(opt_lwork.real))
953 """
954 if isinstance(ilp64, str):
955 if ilp64 == 'preferred':
956 ilp64 = HAS_ILP64
957 else:
958 raise ValueError("Invalid value for 'ilp64'")
960 if not ilp64:
961 return _get_funcs(names, arrays, dtype,
962 "LAPACK", _flapack, _clapack,
963 "flapack", "clapack", _lapack_alias,
964 ilp64=False)
965 else:
966 if not HAS_ILP64:
967 raise RuntimeError("LAPACK ILP64 routine requested, but Scipy "
968 "compiled only with 32-bit BLAS")
969 return _get_funcs(names, arrays, dtype,
970 "LAPACK", _flapack_64, None,
971 "flapack_64", None, _lapack_alias,
972 ilp64=True)
975_int32_max = _np.iinfo(_np.int32).max
976_int64_max = _np.iinfo(_np.int64).max
979def _compute_lwork(routine, *args, **kwargs):
980 """
981 Round floating-point lwork returned by lapack to integer.
983 Several LAPACK routines compute optimal values for LWORK, which
984 they return in a floating-point variable. However, for large
985 values of LWORK, single-precision floating point is not sufficient
986 to hold the exact value --- some LAPACK versions (<= 3.5.0 at
987 least) truncate the returned integer to single precision and in
988 some cases this can be smaller than the required value.
990 Examples
991 --------
992 >>> from scipy.linalg import lapack
993 >>> n = 5000
994 >>> s_r, s_lw = lapack.get_lapack_funcs(('sysvx', 'sysvx_lwork'))
995 >>> lwork = lapack._compute_lwork(s_lw, n)
996 >>> lwork
997 32000
999 """
1000 dtype = getattr(routine, 'dtype', None)
1001 int_dtype = getattr(routine, 'int_dtype', None)
1002 ret = routine(*args, **kwargs)
1003 if ret[-1] != 0:
1004 raise ValueError("Internal work array size computation failed: "
1005 "%d" % (ret[-1],))
1007 if len(ret) == 2:
1008 return _check_work_float(ret[0].real, dtype, int_dtype)
1009 else:
1010 return tuple(_check_work_float(x.real, dtype, int_dtype)
1011 for x in ret[:-1])
1014def _check_work_float(value, dtype, int_dtype):
1015 """
1016 Convert LAPACK-returned work array size float to integer,
1017 carefully for single-precision types.
1018 """
1020 if dtype == _np.float32 or dtype == _np.complex64:
1021 # Single-precision routine -- take next fp value to work
1022 # around possible truncation in LAPACK code
1023 value = _np.nextafter(value, _np.inf, dtype=_np.float32)
1025 value = int(value)
1026 if int_dtype.itemsize == 4:
1027 if value < 0 or value > _int32_max:
1028 raise ValueError("Too large work array required -- computation "
1029 "cannot be performed with standard 32-bit"
1030 " LAPACK.")
1031 elif int_dtype.itemsize == 8:
1032 if value < 0 or value > _int64_max:
1033 raise ValueError("Too large work array required -- computation"
1034 " cannot be performed with standard 64-bit"
1035 " LAPACK.")
1036 return value