Hide keyboard shortcuts

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======================================================= 

4 

5This module contains low-level functions from the LAPACK library. 

6 

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. 

10 

11.. versionadded:: 0.12.0 

12 

13.. note:: 

14 

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. 

20 

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. 

25 

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. 

30 

31.. warning:: 

32 

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`. 

36 

37Finding functions 

38----------------- 

39 

40.. autosummary:: 

41 :toctree: generated/ 

42 

43 get_lapack_funcs 

44 

45All functions 

46------------- 

47 

48.. autosummary:: 

49 :toctree: generated/ 

50 

51 sgbsv 

52 dgbsv 

53 cgbsv 

54 zgbsv 

55 

56 sgbtrf 

57 dgbtrf 

58 cgbtrf 

59 zgbtrf 

60 

61 sgbtrs 

62 dgbtrs 

63 cgbtrs 

64 zgbtrs 

65 

66 sgebal 

67 dgebal 

68 cgebal 

69 zgebal 

70 

71 sgecon 

72 dgecon 

73 cgecon 

74 zgecon 

75 

76 sgeequ 

77 dgeequ 

78 cgeequ 

79 zgeequ 

80 

81 sgeequb 

82 dgeequb 

83 cgeequb 

84 zgeequb 

85 

86 sgees 

87 dgees 

88 cgees 

89 zgees 

90 

91 sgeev 

92 dgeev 

93 cgeev 

94 zgeev 

95 

96 sgeev_lwork 

97 dgeev_lwork 

98 cgeev_lwork 

99 zgeev_lwork 

100 

101 sgegv 

102 dgegv 

103 cgegv 

104 zgegv 

105 

106 sgehrd 

107 dgehrd 

108 cgehrd 

109 zgehrd 

110 

111 sgehrd_lwork 

112 dgehrd_lwork 

113 cgehrd_lwork 

114 zgehrd_lwork 

115 

116 sgejsv 

117 dgejsv 

118 

119 sgels 

120 dgels 

121 cgels 

122 zgels 

123 

124 sgels_lwork 

125 dgels_lwork 

126 cgels_lwork 

127 zgels_lwork 

128 

129 sgelsd 

130 dgelsd 

131 cgelsd 

132 zgelsd 

133 

134 sgelsd_lwork 

135 dgelsd_lwork 

136 cgelsd_lwork 

137 zgelsd_lwork 

138 

139 sgelss 

140 dgelss 

141 cgelss 

142 zgelss 

143 

144 sgelss_lwork 

145 dgelss_lwork 

146 cgelss_lwork 

147 zgelss_lwork 

148 

149 sgelsy 

150 dgelsy 

151 cgelsy 

152 zgelsy 

153 

154 sgelsy_lwork 

155 dgelsy_lwork 

156 cgelsy_lwork 

157 zgelsy_lwork 

158 

159 sgeqp3 

160 dgeqp3 

161 cgeqp3 

162 zgeqp3 

163 

164 sgeqrf 

165 dgeqrf 

166 cgeqrf 

167 zgeqrf 

168 

169 sgeqrf_lwork 

170 dgeqrf_lwork 

171 cgeqrf_lwork 

172 zgeqrf_lwork 

173 

174 sgeqrfp 

175 dgeqrfp 

176 cgeqrfp 

177 zgeqrfp 

178 

179 sgeqrfp_lwork 

180 dgeqrfp_lwork 

181 cgeqrfp_lwork 

182 zgeqrfp_lwork 

183 

184 sgerqf 

185 dgerqf 

186 cgerqf 

187 zgerqf 

188 

189 sgesdd 

190 dgesdd 

191 cgesdd 

192 zgesdd 

193 

194 sgesdd_lwork 

195 dgesdd_lwork 

196 cgesdd_lwork 

197 zgesdd_lwork 

198 

199 sgesv 

200 dgesv 

201 cgesv 

202 zgesv 

203 

204 sgesvd 

205 dgesvd 

206 cgesvd 

207 zgesvd 

208 

209 sgesvd_lwork 

210 dgesvd_lwork 

211 cgesvd_lwork 

212 zgesvd_lwork 

213 

214 sgesvx 

215 dgesvx 

216 cgesvx 

217 zgesvx 

218 

219 sgetrf 

220 dgetrf 

221 cgetrf 

222 zgetrf 

223 

224 sgetc2 

225 dgetc2 

226 cgetc2 

227 zgetc2 

228 

229 sgetri 

230 dgetri 

231 cgetri 

232 zgetri 

233 

234 sgetri_lwork 

235 dgetri_lwork 

236 cgetri_lwork 

237 zgetri_lwork 

238 

239 sgetrs 

240 dgetrs 

241 cgetrs 

242 zgetrs 

243 

244 sgesc2 

245 dgesc2 

246 cgesc2 

247 zgesc2 

248 

249 sgges 

250 dgges 

251 cgges 

252 zgges 

253 

254 sggev 

255 dggev 

256 cggev 

257 zggev 

258 

259 sgglse 

260 dgglse 

261 cgglse 

262 zgglse 

263 

264 sgglse_lwork 

265 dgglse_lwork 

266 cgglse_lwork 

267 zgglse_lwork 

268 

269 sgtsv 

270 dgtsv 

271 cgtsv 

272 zgtsv 

273 

274 sgtsvx 

275 dgtsvx 

276 cgtsvx 

277 zgtsvx 

278 

279 chbevd 

280 zhbevd 

281 

282 chbevx 

283 zhbevx 

284 

285 checon 

286 zhecon 

287 

288 cheequb 

289 zheequb 

290 

291 cheev 

292 zheev 

293 

294 cheev_lwork 

295 zheev_lwork 

296 

297 cheevd 

298 zheevd 

299 

300 cheevd_lwork 

301 zheevd_lwork 

302 

303 cheevr 

304 zheevr 

305 

306 cheevr_lwork 

307 zheevr_lwork 

308 

309 cheevx 

310 zheevx 

311 

312 cheevx_lwork 

313 zheevx_lwork 

314 

315 chegst 

316 zhegst 

317 

318 chegv 

319 zhegv 

320 

321 chegv_lwork 

322 zhegv_lwork 

323 

324 chegvd 

325 zhegvd 

326 

327 chegvx 

328 zhegvx 

329 

330 chegvx_lwork 

331 zhegvx_lwork 

332 

333 chesv 

334 zhesv 

335 

336 chesv_lwork 

337 zhesv_lwork 

338 

339 chesvx 

340 zhesvx 

341 

342 chesvx_lwork 

343 zhesvx_lwork 

344 

345 chetrd 

346 zhetrd 

347 

348 chetrd_lwork 

349 zhetrd_lwork 

350 

351 chetrf 

352 zhetrf 

353 

354 chetrf_lwork 

355 zhetrf_lwork 

356 

357 chfrk 

358 zhfrk 

359 

360 slamch 

361 dlamch 

362 

363 slange 

364 dlange 

365 clange 

366 zlange 

367 

368 slarf 

369 dlarf 

370 clarf 

371 zlarf 

372 

373 slarfg 

374 dlarfg 

375 clarfg 

376 zlarfg 

377 

378 slartg 

379 dlartg 

380 clartg 

381 zlartg 

382 

383 slasd4 

384 dlasd4 

385 

386 slaswp 

387 dlaswp 

388 claswp 

389 zlaswp 

390 

391 slauum 

392 dlauum 

393 clauum 

394 zlauum 

395 

396 sorcsd 

397 dorcsd 

398 sorcsd_lwork 

399 dorcsd_lwork 

400 

401 sorghr 

402 dorghr 

403 sorghr_lwork 

404 dorghr_lwork 

405 

406 sorgqr 

407 dorgqr 

408 

409 sorgrq 

410 dorgrq 

411 

412 sormqr 

413 dormqr 

414 

415 sormrz 

416 dormrz 

417 

418 sormrz_lwork 

419 dormrz_lwork 

420 

421 spbsv 

422 dpbsv 

423 cpbsv 

424 zpbsv 

425 

426 spbtrf 

427 dpbtrf 

428 cpbtrf 

429 zpbtrf 

430 

431 spbtrs 

432 dpbtrs 

433 cpbtrs 

434 zpbtrs 

435 

436 spftrf 

437 dpftrf 

438 cpftrf 

439 zpftrf 

440 

441 spftri 

442 dpftri 

443 cpftri 

444 zpftri 

445 

446 spftrs 

447 dpftrs 

448 cpftrs 

449 zpftrs 

450 

451 spocon 

452 dpocon 

453 cpocon 

454 zpocon 

455 

456 spstrf 

457 dpstrf 

458 cpstrf 

459 zpstrf 

460 

461 spstf2 

462 dpstf2 

463 cpstf2 

464 zpstf2 

465 

466 sposv 

467 dposv 

468 cposv 

469 zposv 

470 

471 sposvx 

472 dposvx 

473 cposvx 

474 zposvx 

475 

476 spotrf 

477 dpotrf 

478 cpotrf 

479 zpotrf 

480 

481 spotri 

482 dpotri 

483 cpotri 

484 zpotri 

485 

486 spotrs 

487 dpotrs 

488 cpotrs 

489 zpotrs 

490 

491 sptsv 

492 dptsv 

493 cptsv 

494 zptsv 

495 

496 sptsvx 

497 dptsvx 

498 cptsvx 

499 zptsvx 

500 

501 spttrf 

502 dpttrf 

503 cpttrf 

504 zpttrf 

505 

506 spttrs 

507 dpttrs 

508 cpttrs 

509 zpttrs 

510 

511 spteqr 

512 dpteqr 

513 cpteqr 

514 zpteqr 

515 

516 crot 

517 zrot 

518 

519 ssbev 

520 dsbev 

521 

522 ssbevd 

523 dsbevd 

524 

525 ssbevx 

526 dsbevx 

527 

528 ssfrk 

529 dsfrk 

530 

531 sstebz 

532 dstebz 

533 

534 sstein 

535 dstein 

536 

537 sstemr 

538 dstemr 

539 

540 sstemr_lwork 

541 dstemr_lwork 

542 

543 ssterf 

544 dsterf 

545 

546 sstev 

547 dstev 

548 

549 ssycon 

550 dsycon 

551 csycon 

552 zsycon 

553 

554 ssyconv 

555 dsyconv 

556 csyconv 

557 zsyconv 

558 

559 ssyequb 

560 dsyequb 

561 csyequb 

562 zsyequb 

563 

564 ssyev 

565 dsyev 

566 

567 ssyev_lwork 

568 dsyev_lwork 

569 

570 ssyevd 

571 dsyevd 

572 

573 ssyevd_lwork 

574 dsyevd_lwork 

575 

576 ssyevr 

577 dsyevr 

578 

579 ssyevr_lwork 

580 dsyevr_lwork 

581 

582 ssyevx 

583 dsyevx 

584 

585 ssyevx_lwork 

586 dsyevx_lwork 

587 

588 ssygst 

589 dsygst 

590 

591 ssygv 

592 dsygv 

593 

594 ssygv_lwork 

595 dsygv_lwork 

596 

597 ssygvd 

598 dsygvd 

599 

600 ssygvx 

601 dsygvx 

602 

603 ssygvx_lwork 

604 dsygvx_lwork 

605 

606 ssysv 

607 dsysv 

608 csysv 

609 zsysv 

610 

611 ssysv_lwork 

612 dsysv_lwork 

613 csysv_lwork 

614 zsysv_lwork 

615 

616 ssysvx 

617 dsysvx 

618 csysvx 

619 zsysvx 

620 

621 ssysvx_lwork 

622 dsysvx_lwork 

623 csysvx_lwork 

624 zsysvx_lwork 

625 

626 ssytf2 

627 dsytf2 

628 csytf2 

629 zsytf2 

630 

631 ssytrd 

632 dsytrd 

633 

634 ssytrd_lwork 

635 dsytrd_lwork 

636 

637 ssytrf 

638 dsytrf 

639 csytrf 

640 zsytrf 

641 

642 ssytrf_lwork 

643 dsytrf_lwork 

644 csytrf_lwork 

645 zsytrf_lwork 

646 

647 stbtrs 

648 dtbtrs 

649 ctbtrs 

650 ztbtrs 

651 

652 stfsm 

653 dtfsm 

654 ctfsm 

655 ztfsm 

656 

657 stfttp 

658 dtfttp 

659 ctfttp 

660 ztfttp 

661 

662 stfttr 

663 dtfttr 

664 ctfttr 

665 ztfttr 

666 

667 stgsen 

668 dtgsen 

669 ctgsen 

670 ztgsen 

671 

672 stpttf 

673 dtpttf 

674 ctpttf 

675 ztpttf 

676 

677 stpttr 

678 dtpttr 

679 ctpttr 

680 ztpttr 

681 

682 strsyl 

683 dtrsyl 

684 ctrsyl 

685 ztrsyl 

686 

687 strtri 

688 dtrtri 

689 ctrtri 

690 ztrtri 

691 

692 strtrs 

693 dtrtrs 

694 ctrtrs 

695 ztrtrs 

696 

697 strttf 

698 dtrttf 

699 ctrttf 

700 ztrttf 

701 

702 strttp 

703 dtrttp 

704 ctrttp 

705 ztrttp 

706 

707 stzrzf 

708 dtzrzf 

709 ctzrzf 

710 ztzrzf 

711 

712 stzrzf_lwork 

713 dtzrzf_lwork 

714 ctzrzf_lwork 

715 ztzrzf_lwork 

716 

717 cunghr 

718 zunghr 

719 

720 cunghr_lwork 

721 zunghr_lwork 

722 

723 cungqr 

724 zungqr 

725 

726 cungrq 

727 zungrq 

728 

729 cunmqr 

730 zunmqr 

731 

732 sgeqrt 

733 dgeqrt 

734 cgeqrt 

735 zgeqrt 

736 

737 sgemqrt 

738 dgemqrt 

739 cgemqrt 

740 zgemqrt 

741 

742 sgttrf 

743 dgttrf 

744 cgttrf 

745 zgttrf 

746 

747 sgttrs 

748 dgttrs 

749 cgttrs 

750 zgttrs 

751 

752 stpqrt 

753 dtpqrt 

754 ctpqrt 

755 ztpqrt 

756 

757 stpmqrt 

758 dtpmqrt 

759 ctpmqrt 

760 ztpmqrt 

761 

762 cuncsd 

763 zuncsd 

764 

765 cuncsd_lwork 

766 zuncsd_lwork 

767 

768 cunmrz 

769 zunmrz 

770 

771 cunmrz_lwork 

772 zunmrz_lwork 

773 

774 ilaver 

775 

776""" 

777# 

778# Author: Pearu Peterson, March 2002 

779# 

780 

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 

789 

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") 

794 

795# Expose all functions (only flapack --- clapack is an implementation detail) 

796empty_module = None 

797from scipy.linalg._flapack import * 

798del empty_module 

799 

800__all__ = ['get_lapack_funcs'] 

801 

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.""" 

806 

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) 

811 

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 

818 

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} 

827 

828 

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') 

832 

833 

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')) 

840 

841 

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 

850 

851del regex_compile, p1, p2, backtickrepl 

852 

853 

854@_memoize_get_funcs 

855def get_lapack_funcs(names, arrays=(), dtype=None): 

856 """Return available LAPACK function objects from names. 

857 

858 Arrays are used to determine the optimal prefix of LAPACK routines. 

859 

860 Parameters 

861 ---------- 

862 names : str or sequence of str 

863 Name(s) of LAPACK functions without type prefix. 

864 

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. 

869 

870 dtype : str or dtype, optional 

871 Data-type specifier. Not used if `arrays` is non-empty. 

872 

873 Returns 

874 ------- 

875 funcs : list 

876 List containing the found function(s). 

877 

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. 

883 

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. 

889 

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. 

895 

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' 

904 

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`` 

910 

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)) 

918 

919 """ 

920 return _get_funcs(names, arrays, dtype, 

921 "LAPACK", _flapack, _clapack, 

922 "flapack", "clapack", _lapack_alias) 

923 

924 

925_int32_max = _np.iinfo(_np.int32).max 

926 

927 

928def _compute_lwork(routine, *args, **kwargs): 

929 """ 

930 Round floating-point lwork returned by lapack to integer. 

931 

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. 

938 

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 

947 

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],)) 

954 

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]) 

959 

960 

961def _check_work_float(value, dtype): 

962 """ 

963 Convert LAPACK-returned work array size float to integer, 

964 carefully for single-precision types. 

965 """ 

966 

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) 

971 

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