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

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
1import numpy as np
2from scipy.linalg import svd
5__all__ = ['polar']
8def polar(a, side="right"):
9 """
10 Compute the polar decomposition.
12 Returns the factors of the polar decomposition [1]_ `u` and `p` such
13 that ``a = up`` (if `side` is "right") or ``a = pu`` (if `side` is
14 "left"), where `p` is positive semidefinite. Depending on the shape
15 of `a`, either the rows or columns of `u` are orthonormal. When `a`
16 is a square array, `u` is a square unitary array. When `a` is not
17 square, the "canonical polar decomposition" [2]_ is computed.
19 Parameters
20 ----------
21 a : (m, n) array_like
22 The array to be factored.
23 side : {'left', 'right'}, optional
24 Determines whether a right or left polar decomposition is computed.
25 If `side` is "right", then ``a = up``. If `side` is "left", then
26 ``a = pu``. The default is "right".
28 Returns
29 -------
30 u : (m, n) ndarray
31 If `a` is square, then `u` is unitary. If m > n, then the columns
32 of `a` are orthonormal, and if m < n, then the rows of `u` are
33 orthonormal.
34 p : ndarray
35 `p` is Hermitian positive semidefinite. If `a` is nonsingular, `p`
36 is positive definite. The shape of `p` is (n, n) or (m, m), depending
37 on whether `side` is "right" or "left", respectively.
39 References
40 ----------
41 .. [1] R. A. Horn and C. R. Johnson, "Matrix Analysis", Cambridge
42 University Press, 1985.
43 .. [2] N. J. Higham, "Functions of Matrices: Theory and Computation",
44 SIAM, 2008.
46 Examples
47 --------
48 >>> from scipy.linalg import polar
49 >>> a = np.array([[1, -1], [2, 4]])
50 >>> u, p = polar(a)
51 >>> u
52 array([[ 0.85749293, -0.51449576],
53 [ 0.51449576, 0.85749293]])
54 >>> p
55 array([[ 1.88648444, 1.2004901 ],
56 [ 1.2004901 , 3.94446746]])
58 A non-square example, with m < n:
60 >>> b = np.array([[0.5, 1, 2], [1.5, 3, 4]])
61 >>> u, p = polar(b)
62 >>> u
63 array([[-0.21196618, -0.42393237, 0.88054056],
64 [ 0.39378971, 0.78757942, 0.4739708 ]])
65 >>> p
66 array([[ 0.48470147, 0.96940295, 1.15122648],
67 [ 0.96940295, 1.9388059 , 2.30245295],
68 [ 1.15122648, 2.30245295, 3.65696431]])
69 >>> u.dot(p) # Verify the decomposition.
70 array([[ 0.5, 1. , 2. ],
71 [ 1.5, 3. , 4. ]])
72 >>> u.dot(u.T) # The rows of u are orthonormal.
73 array([[ 1.00000000e+00, -2.07353665e-17],
74 [ -2.07353665e-17, 1.00000000e+00]])
76 Another non-square example, with m > n:
78 >>> c = b.T
79 >>> u, p = polar(c)
80 >>> u
81 array([[-0.21196618, 0.39378971],
82 [-0.42393237, 0.78757942],
83 [ 0.88054056, 0.4739708 ]])
84 >>> p
85 array([[ 1.23116567, 1.93241587],
86 [ 1.93241587, 4.84930602]])
87 >>> u.dot(p) # Verify the decomposition.
88 array([[ 0.5, 1.5],
89 [ 1. , 3. ],
90 [ 2. , 4. ]])
91 >>> u.T.dot(u) # The columns of u are orthonormal.
92 array([[ 1.00000000e+00, -1.26363763e-16],
93 [ -1.26363763e-16, 1.00000000e+00]])
95 """
96 if side not in ['right', 'left']:
97 raise ValueError("`side` must be either 'right' or 'left'")
98 a = np.asarray(a)
99 if a.ndim != 2:
100 raise ValueError("`a` must be a 2-D array.")
102 w, s, vh = svd(a, full_matrices=False)
103 u = w.dot(vh)
104 if side == 'right':
105 # a = up
106 p = (vh.T.conj() * s).dot(vh)
107 else:
108 # a = pu
109 p = (w * s).dot(w.T.conj())
110 return u, p