Coverage for /home/martinb/.local/share/virtualenvs/camcops/lib/python3.6/site-packages/scipy/linalg/lapack.py : 73%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2Low-level LAPACK functions (:mod:`scipy.linalg.lapack`)
3=======================================================
5This module contains low-level functions from the LAPACK library.
7The `*gegv` family of routines have been removed from LAPACK 3.6.0
8and have been deprecated in SciPy 0.17.0. They will be removed in
9a future release.
11.. versionadded:: 0.12.0
13.. note::
15 The common ``overwrite_<>`` option in many routines, allows the
16 input arrays to be overwritten to avoid extra memory allocation.
17 However this requires the array to satisfy two conditions
18 which are memory order and the data type to match exactly the
19 order and the type expected by the routine.
21 As an example, if you pass a double precision float array to any
22 ``S....`` routine which expects single precision arguments, f2py
23 will create an intermediate array to match the argument types and
24 overwriting will be performed on that intermediate array.
26 Similarly, if a C-contiguous array is passed, f2py will pass a
27 FORTRAN-contiguous array internally. Please make sure that these
28 details are satisfied. More information can be found in the f2py
29 documentation.
31.. warning::
33 These functions do little to no error checking.
34 It is possible to cause crashes by mis-using them,
35 so prefer using the higher-level routines in `scipy.linalg`.
37Finding functions
38-----------------
40.. autosummary::
41 :toctree: generated/
43 get_lapack_funcs
45All functions
46-------------
48.. autosummary::
49 :toctree: generated/
51 sgbsv
52 dgbsv
53 cgbsv
54 zgbsv
56 sgbtrf
57 dgbtrf
58 cgbtrf
59 zgbtrf
61 sgbtrs
62 dgbtrs
63 cgbtrs
64 zgbtrs
66 sgebal
67 dgebal
68 cgebal
69 zgebal
71 sgecon
72 dgecon
73 cgecon
74 zgecon
76 sgeequ
77 dgeequ
78 cgeequ
79 zgeequ
81 sgeequb
82 dgeequb
83 cgeequb
84 zgeequb
86 sgees
87 dgees
88 cgees
89 zgees
91 sgeev
92 dgeev
93 cgeev
94 zgeev
96 sgeev_lwork
97 dgeev_lwork
98 cgeev_lwork
99 zgeev_lwork
101 sgegv
102 dgegv
103 cgegv
104 zgegv
106 sgehrd
107 dgehrd
108 cgehrd
109 zgehrd
111 sgehrd_lwork
112 dgehrd_lwork
113 cgehrd_lwork
114 zgehrd_lwork
116 sgejsv
117 dgejsv
119 sgels
120 dgels
121 cgels
122 zgels
124 sgels_lwork
125 dgels_lwork
126 cgels_lwork
127 zgels_lwork
129 sgelsd
130 dgelsd
131 cgelsd
132 zgelsd
134 sgelsd_lwork
135 dgelsd_lwork
136 cgelsd_lwork
137 zgelsd_lwork
139 sgelss
140 dgelss
141 cgelss
142 zgelss
144 sgelss_lwork
145 dgelss_lwork
146 cgelss_lwork
147 zgelss_lwork
149 sgelsy
150 dgelsy
151 cgelsy
152 zgelsy
154 sgelsy_lwork
155 dgelsy_lwork
156 cgelsy_lwork
157 zgelsy_lwork
159 sgeqp3
160 dgeqp3
161 cgeqp3
162 zgeqp3
164 sgeqrf
165 dgeqrf
166 cgeqrf
167 zgeqrf
169 sgeqrf_lwork
170 dgeqrf_lwork
171 cgeqrf_lwork
172 zgeqrf_lwork
174 sgeqrfp
175 dgeqrfp
176 cgeqrfp
177 zgeqrfp
179 sgeqrfp_lwork
180 dgeqrfp_lwork
181 cgeqrfp_lwork
182 zgeqrfp_lwork
184 sgerqf
185 dgerqf
186 cgerqf
187 zgerqf
189 sgesdd
190 dgesdd
191 cgesdd
192 zgesdd
194 sgesdd_lwork
195 dgesdd_lwork
196 cgesdd_lwork
197 zgesdd_lwork
199 sgesv
200 dgesv
201 cgesv
202 zgesv
204 sgesvd
205 dgesvd
206 cgesvd
207 zgesvd
209 sgesvd_lwork
210 dgesvd_lwork
211 cgesvd_lwork
212 zgesvd_lwork
214 sgesvx
215 dgesvx
216 cgesvx
217 zgesvx
219 sgetrf
220 dgetrf
221 cgetrf
222 zgetrf
224 sgetc2
225 dgetc2
226 cgetc2
227 zgetc2
229 sgetri
230 dgetri
231 cgetri
232 zgetri
234 sgetri_lwork
235 dgetri_lwork
236 cgetri_lwork
237 zgetri_lwork
239 sgetrs
240 dgetrs
241 cgetrs
242 zgetrs
244 sgesc2
245 dgesc2
246 cgesc2
247 zgesc2
249 sgges
250 dgges
251 cgges
252 zgges
254 sggev
255 dggev
256 cggev
257 zggev
259 sgglse
260 dgglse
261 cgglse
262 zgglse
264 sgglse_lwork
265 dgglse_lwork
266 cgglse_lwork
267 zgglse_lwork
269 sgtsv
270 dgtsv
271 cgtsv
272 zgtsv
274 sgtsvx
275 dgtsvx
276 cgtsvx
277 zgtsvx
279 chbevd
280 zhbevd
282 chbevx
283 zhbevx
285 checon
286 zhecon
288 cheequb
289 zheequb
291 cheev
292 zheev
294 cheev_lwork
295 zheev_lwork
297 cheevd
298 zheevd
300 cheevd_lwork
301 zheevd_lwork
303 cheevr
304 zheevr
306 cheevr_lwork
307 zheevr_lwork
309 cheevx
310 zheevx
312 cheevx_lwork
313 zheevx_lwork
315 chegst
316 zhegst
318 chegv
319 zhegv
321 chegv_lwork
322 zhegv_lwork
324 chegvd
325 zhegvd
327 chegvx
328 zhegvx
330 chegvx_lwork
331 zhegvx_lwork
333 chesv
334 zhesv
336 chesv_lwork
337 zhesv_lwork
339 chesvx
340 zhesvx
342 chesvx_lwork
343 zhesvx_lwork
345 chetrd
346 zhetrd
348 chetrd_lwork
349 zhetrd_lwork
351 chetrf
352 zhetrf
354 chetrf_lwork
355 zhetrf_lwork
357 chfrk
358 zhfrk
360 slamch
361 dlamch
363 slange
364 dlange
365 clange
366 zlange
368 slarf
369 dlarf
370 clarf
371 zlarf
373 slarfg
374 dlarfg
375 clarfg
376 zlarfg
378 slartg
379 dlartg
380 clartg
381 zlartg
383 slasd4
384 dlasd4
386 slaswp
387 dlaswp
388 claswp
389 zlaswp
391 slauum
392 dlauum
393 clauum
394 zlauum
396 sorcsd
397 dorcsd
398 sorcsd_lwork
399 dorcsd_lwork
401 sorghr
402 dorghr
403 sorghr_lwork
404 dorghr_lwork
406 sorgqr
407 dorgqr
409 sorgrq
410 dorgrq
412 sormqr
413 dormqr
415 sormrz
416 dormrz
418 sormrz_lwork
419 dormrz_lwork
421 spbsv
422 dpbsv
423 cpbsv
424 zpbsv
426 spbtrf
427 dpbtrf
428 cpbtrf
429 zpbtrf
431 spbtrs
432 dpbtrs
433 cpbtrs
434 zpbtrs
436 spftrf
437 dpftrf
438 cpftrf
439 zpftrf
441 spftri
442 dpftri
443 cpftri
444 zpftri
446 spftrs
447 dpftrs
448 cpftrs
449 zpftrs
451 spocon
452 dpocon
453 cpocon
454 zpocon
456 spstrf
457 dpstrf
458 cpstrf
459 zpstrf
461 spstf2
462 dpstf2
463 cpstf2
464 zpstf2
466 sposv
467 dposv
468 cposv
469 zposv
471 sposvx
472 dposvx
473 cposvx
474 zposvx
476 spotrf
477 dpotrf
478 cpotrf
479 zpotrf
481 spotri
482 dpotri
483 cpotri
484 zpotri
486 spotrs
487 dpotrs
488 cpotrs
489 zpotrs
491 sptsv
492 dptsv
493 cptsv
494 zptsv
496 sptsvx
497 dptsvx
498 cptsvx
499 zptsvx
501 spttrf
502 dpttrf
503 cpttrf
504 zpttrf
506 spttrs
507 dpttrs
508 cpttrs
509 zpttrs
511 spteqr
512 dpteqr
513 cpteqr
514 zpteqr
516 crot
517 zrot
519 ssbev
520 dsbev
522 ssbevd
523 dsbevd
525 ssbevx
526 dsbevx
528 ssfrk
529 dsfrk
531 sstebz
532 dstebz
534 sstein
535 dstein
537 sstemr
538 dstemr
540 sstemr_lwork
541 dstemr_lwork
543 ssterf
544 dsterf
546 sstev
547 dstev
549 ssycon
550 dsycon
551 csycon
552 zsycon
554 ssyconv
555 dsyconv
556 csyconv
557 zsyconv
559 ssyequb
560 dsyequb
561 csyequb
562 zsyequb
564 ssyev
565 dsyev
567 ssyev_lwork
568 dsyev_lwork
570 ssyevd
571 dsyevd
573 ssyevd_lwork
574 dsyevd_lwork
576 ssyevr
577 dsyevr
579 ssyevr_lwork
580 dsyevr_lwork
582 ssyevx
583 dsyevx
585 ssyevx_lwork
586 dsyevx_lwork
588 ssygst
589 dsygst
591 ssygv
592 dsygv
594 ssygv_lwork
595 dsygv_lwork
597 ssygvd
598 dsygvd
600 ssygvx
601 dsygvx
603 ssygvx_lwork
604 dsygvx_lwork
606 ssysv
607 dsysv
608 csysv
609 zsysv
611 ssysv_lwork
612 dsysv_lwork
613 csysv_lwork
614 zsysv_lwork
616 ssysvx
617 dsysvx
618 csysvx
619 zsysvx
621 ssysvx_lwork
622 dsysvx_lwork
623 csysvx_lwork
624 zsysvx_lwork
626 ssytf2
627 dsytf2
628 csytf2
629 zsytf2
631 ssytrd
632 dsytrd
634 ssytrd_lwork
635 dsytrd_lwork
637 ssytrf
638 dsytrf
639 csytrf
640 zsytrf
642 ssytrf_lwork
643 dsytrf_lwork
644 csytrf_lwork
645 zsytrf_lwork
647 stbtrs
648 dtbtrs
649 ctbtrs
650 ztbtrs
652 stfsm
653 dtfsm
654 ctfsm
655 ztfsm
657 stfttp
658 dtfttp
659 ctfttp
660 ztfttp
662 stfttr
663 dtfttr
664 ctfttr
665 ztfttr
667 stgsen
668 dtgsen
669 ctgsen
670 ztgsen
672 stpttf
673 dtpttf
674 ctpttf
675 ztpttf
677 stpttr
678 dtpttr
679 ctpttr
680 ztpttr
682 strsyl
683 dtrsyl
684 ctrsyl
685 ztrsyl
687 strtri
688 dtrtri
689 ctrtri
690 ztrtri
692 strtrs
693 dtrtrs
694 ctrtrs
695 ztrtrs
697 strttf
698 dtrttf
699 ctrttf
700 ztrttf
702 strttp
703 dtrttp
704 ctrttp
705 ztrttp
707 stzrzf
708 dtzrzf
709 ctzrzf
710 ztzrzf
712 stzrzf_lwork
713 dtzrzf_lwork
714 ctzrzf_lwork
715 ztzrzf_lwork
717 cunghr
718 zunghr
720 cunghr_lwork
721 zunghr_lwork
723 cungqr
724 zungqr
726 cungrq
727 zungrq
729 cunmqr
730 zunmqr
732 sgeqrt
733 dgeqrt
734 cgeqrt
735 zgeqrt
737 sgemqrt
738 dgemqrt
739 cgemqrt
740 zgemqrt
742 sgttrf
743 dgttrf
744 cgttrf
745 zgttrf
747 sgttrs
748 dgttrs
749 cgttrs
750 zgttrs
752 stpqrt
753 dtpqrt
754 ctpqrt
755 ztpqrt
757 stpmqrt
758 dtpmqrt
759 ctpmqrt
760 ztpmqrt
762 cuncsd
763 zuncsd
765 cuncsd_lwork
766 zuncsd_lwork
768 cunmrz
769 zunmrz
771 cunmrz_lwork
772 zunmrz_lwork
774 ilaver
776"""
777#
778# Author: Pearu Peterson, March 2002
779#
781import numpy as _np
782from .blas import _get_funcs, _memoize_get_funcs
783from scipy.linalg import _flapack
784from re import compile as regex_compile
785try:
786 from scipy.linalg import _clapack
787except ImportError:
788 _clapack = None
790# Backward compatibility
791from scipy._lib._util import DeprecatedImport as _DeprecatedImport
792clapack = _DeprecatedImport("scipy.linalg.blas.clapack", "scipy.linalg.lapack")
793flapack = _DeprecatedImport("scipy.linalg.blas.flapack", "scipy.linalg.lapack")
795# Expose all functions (only flapack --- clapack is an implementation detail)
796empty_module = None
797from scipy.linalg._flapack import *
798del empty_module
800__all__ = ['get_lapack_funcs']
802_dep_message = """The `*gegv` family of routines has been deprecated in
803LAPACK 3.6.0 in favor of the `*ggev` family of routines.
804The corresponding wrappers will be removed from SciPy in
805a future release."""
807cgegv = _np.deprecate(cgegv, old_name='cgegv', message=_dep_message)
808dgegv = _np.deprecate(dgegv, old_name='dgegv', message=_dep_message)
809sgegv = _np.deprecate(sgegv, old_name='sgegv', message=_dep_message)
810zgegv = _np.deprecate(zgegv, old_name='zgegv', message=_dep_message)
812# Modify _flapack in this scope so the deprecation warnings apply to
813# functions returned by get_lapack_funcs.
814_flapack.cgegv = cgegv
815_flapack.dgegv = dgegv
816_flapack.sgegv = sgegv
817_flapack.zgegv = zgegv
819# some convenience alias for complex functions
820_lapack_alias = {
821 'corghr': 'cunghr', 'zorghr': 'zunghr',
822 'corghr_lwork': 'cunghr_lwork', 'zorghr_lwork': 'zunghr_lwork',
823 'corgqr': 'cungqr', 'zorgqr': 'zungqr',
824 'cormqr': 'cunmqr', 'zormqr': 'zunmqr',
825 'corgrq': 'cungrq', 'zorgrq': 'zungrq',
826}
829# Place guards against docstring rendering issues with special characters
830p1 = regex_compile(r'with bounds (?P<b>.*?)( and (?P<s>.*?) storage){0,1}\n')
831p2 = regex_compile(r'Default: (?P<d>.*?)\n')
834def backtickrepl(m):
835 if m.group('s'):
836 return ('with bounds ``{}`` with ``{}`` storage\n'
837 ''.format(m.group('b'), m.group('s')))
838 else:
839 return 'with bounds ``{}``\n'.format(m.group('b'))
842for routine in [ssyevr, dsyevr, cheevr, zheevr,
843 ssyevx, dsyevx, cheevx, zheevx,
844 ssygvd, dsygvd, chegvd, zhegvd]:
845 if routine.__doc__:
846 routine.__doc__ = p1.sub(backtickrepl, routine.__doc__)
847 routine.__doc__ = p2.sub('Default ``\\1``\n', routine.__doc__)
848 else:
849 continue
851del regex_compile, p1, p2, backtickrepl
854@_memoize_get_funcs
855def get_lapack_funcs(names, arrays=(), dtype=None):
856 """Return available LAPACK function objects from names.
858 Arrays are used to determine the optimal prefix of LAPACK routines.
860 Parameters
861 ----------
862 names : str or sequence of str
863 Name(s) of LAPACK functions without type prefix.
865 arrays : sequence of ndarrays, optional
866 Arrays can be given to determine optimal prefix of LAPACK
867 routines. If not given, double-precision routines will be
868 used, otherwise the most generic type in arrays will be used.
870 dtype : str or dtype, optional
871 Data-type specifier. Not used if `arrays` is non-empty.
873 Returns
874 -------
875 funcs : list
876 List containing the found function(s).
878 Notes
879 -----
880 This routine automatically chooses between Fortran/C
881 interfaces. Fortran code is used whenever possible for arrays with
882 column major order. In all other cases, C code is preferred.
884 In LAPACK, the naming convention is that all functions start with a
885 type prefix, which depends on the type of the principal
886 matrix. These can be one of {'s', 'd', 'c', 'z'} for the NumPy
887 types {float32, float64, complex64, complex128} respectively, and
888 are stored in attribute ``typecode`` of the returned functions.
890 Examples
891 --------
892 Suppose we would like to use '?lange' routine which computes the selected
893 norm of an array. We pass our array in order to get the correct 'lange'
894 flavor.
896 >>> import scipy.linalg as LA
897 >>> a = np.random.rand(3,2)
898 >>> x_lange = LA.get_lapack_funcs('lange', (a,))
899 >>> x_lange.typecode
900 'd'
901 >>> x_lange = LA.get_lapack_funcs('lange',(a*1j,))
902 >>> x_lange.typecode
903 'z'
905 Several LAPACK routines work best when its internal WORK array has
906 the optimal size (big enough for fast computation and small enough to
907 avoid waste of memory). This size is determined also by a dedicated query
908 to the function which is often wrapped as a standalone function and
909 commonly denoted as ``###_lwork``. Below is an example for ``?sysv``
911 >>> import scipy.linalg as LA
912 >>> a = np.random.rand(1000,1000)
913 >>> b = np.random.rand(1000,1)*1j
914 >>> # We pick up zsysv and zsysv_lwork due to b array
915 ... xsysv, xlwork = LA.get_lapack_funcs(('sysv', 'sysv_lwork'), (a, b))
916 >>> opt_lwork, _ = xlwork(a.shape[0]) # returns a complex for 'z' prefix
917 >>> udut, ipiv, x, info = xsysv(a, b, lwork=int(opt_lwork.real))
919 """
920 return _get_funcs(names, arrays, dtype,
921 "LAPACK", _flapack, _clapack,
922 "flapack", "clapack", _lapack_alias)
925_int32_max = _np.iinfo(_np.int32).max
928def _compute_lwork(routine, *args, **kwargs):
929 """
930 Round floating-point lwork returned by lapack to integer.
932 Several LAPACK routines compute optimal values for LWORK, which
933 they return in a floating-point variable. However, for large
934 values of LWORK, single-precision floating point is not sufficient
935 to hold the exact value --- some LAPACK versions (<= 3.5.0 at
936 least) truncate the returned integer to single precision and in
937 some cases this can be smaller than the required value.
939 Examples
940 --------
941 >>> from scipy.linalg import lapack
942 >>> n = 5000
943 >>> s_r, s_lw = lapack.get_lapack_funcs(('sysvx', 'sysvx_lwork'))
944 >>> lwork = lapack._compute_lwork(s_lw, n)
945 >>> lwork
946 32000
948 """
949 dtype = getattr(routine, 'dtype', None)
950 ret = routine(*args, **kwargs)
951 if ret[-1] != 0:
952 raise ValueError("Internal work array size computation failed: "
953 "%d" % (ret[-1],))
955 if len(ret) == 2:
956 return _check_work_float(ret[0].real, dtype)
957 else:
958 return tuple(_check_work_float(x.real, dtype) for x in ret[:-1])
961def _check_work_float(value, dtype):
962 """
963 Convert LAPACK-returned work array size float to integer,
964 carefully for single-precision types.
965 """
967 if dtype == _np.float32 or dtype == _np.complex64:
968 # Single-precision routine -- take next fp value to work
969 # around possible truncation in LAPACK code
970 value = _np.nextafter(value, _np.inf, dtype=_np.float32)
972 value = int(value)
973 if value < 0 or value > _int32_max:
974 raise ValueError("Too large work array required -- computation cannot "
975 "be performed with standard 32-bit LAPACK.")
976 return value