DEP: Revert a change made to solveh_banded, and add a deprecation war…

…ning so the change can eventually be made for the 0.9 release.

doc/release/0.8.0-notes.rst

@@ -61,6 +61,12 @@ Obsolete code deprecated (scipy.misc)
 The modules `helpmod`, `ppimport` and `pexec` from `scipy.misc` are deprecated.
 They will be removed from SciPy in version 0.9.
 
+Additional deprecations
+-----------------------
+* linalg: The function `solveh_banded` currently returns a tuple containing
+  the Cholesky factorization and the solution to the linear system.  In
+  SciPy 0.9, the return value will be just the solution.
+
 New features
 ============
 

scipy/linalg/basic.py

@@ -6,6 +6,8 @@
 __all__ = ['solve', 'solveh_banded', 'solve_banded',
             'inv', 'det', 'lstsq', 'pinv', 'pinv2']
 
+from warnings import warn
+
 from numpy import asarray, zeros, sum, conjugate, dot, transpose, \
         asarray_chkfinite,  single
 import numpy
@@ -165,10 +167,20 @@ def solveh_banded(ab, b, overwrite_ab=False, overwrite_b=False, lower=False):
 
     Returns
     -------
+    c : array, shape (u+1, M)
+        Cholesky factorization of a, in the same banded format as ab
     x : array, shape (M,) or (M, K)
         The solution to the system a x = b
+        
+    Notes
+    -----
+    The inclusion of `c` in the return value is deprecated.  In SciPy
+    version 0.9, the return value will be the solution `x` only.
 
     """
+    warn("In SciPy 0.9, the return value of solveh_banded will be "
+            "the solution x only.", DeprecationWarning)
+
     ab, b = map(asarray_chkfinite, (ab, b))
 
     # Validate shapes.
@@ -183,7 +195,7 @@ def solveh_banded(ab, b, overwrite_ab=False, overwrite_b=False, lower=False):
     if info < 0:
         raise ValueError('illegal value in %d-th argument of internal pbsv'
                                                                     % -info)
-    return x
+    return c, x
 
 
 # matrix inversion

scipy/linalg/tests/test_basic.py

@@ -19,6 +19,8 @@
   python tests/test_basic.py
 """
 
+import warnings
+
 from numpy import arange, array, dot, zeros, identity, conjugate, transpose, \
         float32, zeros_like
 import numpy.linalg as linalg
@@ -98,19 +100,30 @@ def test_bad_shape(self):
 
 
 class TestSolveHBanded(TestCase):
+    # solveh_banded currently has a DeprecationWarning.  When the warning
+    # is removed in scipy 0.9, the 'ignore' filters and the test for the
+    # warning can be removed.
 
     def test_01_upper(self):
+        warnings.simplefilter('ignore', category=DeprecationWarning)
         # Solve
         # [ 4 1 0]     [1]
         # [ 1 4 1] X = [4]
         # [ 0 1 4]     [1]
         # with the RHS as a 1D array.
         ab = array([[-99, 1.0, 1.0], [4.0, 4.0, 4.0]])
         b = array([1.0, 4.0, 1.0])
-        x = solveh_banded(ab, b)
+        c, x = solveh_banded(ab, b)
         assert_array_almost_equal(x, [0.0, 1.0, 0.0])
+        # Remove the following part of this test in scipy 0.9.
+        a = array([[4.0, 1.0, 0.0], [1.0, 4.0, 1.0], [0.0, 1.0, 4.0]])
+        fac = zeros_like(a)
+        fac[range(3),range(3)] = c[-1]
+        fac[(0,1),(1,2)] = c[0,1:]
+        assert_array_almost_equal(a, dot(fac.T, fac))
 
     def test_02_upper(self):
+        warnings.simplefilter('ignore', category=DeprecationWarning)
         # Solve
         # [ 4 1 0]     [1 4]
         # [ 1 4 1] X = [4 2]
@@ -121,24 +134,26 @@ def test_02_upper(self):
         b = array([[1.0, 4.0],
                    [4.0, 2.0],
                    [1.0, 4.0]])
-        x = solveh_banded(ab, b)
+        c, x = solveh_banded(ab, b)
         expected = array([[0.0, 1.0],
                           [1.0, 0.0],
                           [0.0, 1.0]])
         assert_array_almost_equal(x, expected)
 
     def test_03_upper(self):
+        warnings.simplefilter('ignore', category=DeprecationWarning)
         # Solve
         # [ 4 1 0]     [1]
         # [ 1 4 1] X = [4]
         # [ 0 1 4]     [1]
         # with the RHS as a 2D array with shape (3,1).
         ab = array([[-99, 1.0, 1.0], [4.0, 4.0, 4.0]])
         b = array([1.0, 4.0, 1.0]).reshape(-1,1)
-        x = solveh_banded(ab, b)
+        c, x = solveh_banded(ab, b)
         assert_array_almost_equal(x, array([0.0, 1.0, 0.0]).reshape(-1,1))
 
     def test_01_lower(self):
+        warnings.simplefilter('ignore', category=DeprecationWarning)
         # Solve
         # [ 4 1 0]     [1]
         # [ 1 4 1] X = [4]
@@ -147,10 +162,11 @@ def test_01_lower(self):
         ab = array([[4.0, 4.0, 4.0],
                     [1.0, 1.0, -99]])
         b = array([1.0, 4.0, 1.0])
-        x = solveh_banded(ab, b, lower=True)
+        c, x = solveh_banded(ab, b, lower=True)
         assert_array_almost_equal(x, [0.0, 1.0, 0.0])
 
     def test_02_lower(self):
+        warnings.simplefilter('ignore', category=DeprecationWarning)
         # Solve
         # [ 4 1 0]     [1 4]
         # [ 1 4 1] X = [4 2]
@@ -161,24 +177,26 @@ def test_02_lower(self):
         b = array([[1.0, 4.0],
                    [4.0, 2.0],
                    [1.0, 4.0]])
-        x = solveh_banded(ab, b, lower=True)
+        c, x = solveh_banded(ab, b, lower=True)
         expected = array([[0.0, 1.0],
                           [1.0, 0.0],
                           [0.0, 1.0]])
         assert_array_almost_equal(x, expected)
 
     def test_01_float32(self):
+        warnings.simplefilter('ignore', category=DeprecationWarning)
         # Solve
         # [ 4 1 0]     [1]
         # [ 1 4 1] X = [4]
         # [ 0 1 4]     [1]
         #
         ab = array([[-99, 1.0, 1.0], [4.0, 4.0, 4.0]], dtype=float32)
         b = array([1.0, 4.0, 1.0], dtype=float32)
-        x = solveh_banded(ab, b)
+        c, x = solveh_banded(ab, b)
         assert_array_almost_equal(x, [0.0, 1.0, 0.0])
 
     def test_02_float32(self):
+        warnings.simplefilter('ignore', category=DeprecationWarning)
         # Solve
         # [ 4 1 0]     [1 4]
         # [ 1 4 1] X = [4 2]
@@ -189,24 +207,26 @@ def test_02_float32(self):
         b = array([[1.0, 4.0],
                    [4.0, 2.0],
                    [1.0, 4.0]], dtype=float32)
-        x = solveh_banded(ab, b)
+        c, x = solveh_banded(ab, b)
         expected = array([[0.0, 1.0],
                           [1.0, 0.0],
                           [0.0, 1.0]])
         assert_array_almost_equal(x, expected)
 
     def test_01_complex(self):
+        warnings.simplefilter('ignore', category=DeprecationWarning)
         # Solve
         # [ 4 -j 0]     [ -j]
         # [ j 4 -j] X = [4-j]
         # [ 0 j  4]     [4+j]
         #
         ab = array([[-99, -1.0j, -1.0j], [4.0, 4.0, 4.0]])
         b = array([-1.0j, 4.0-1j, 4+1j])
-        x = solveh_banded(ab, b)
+        c, x = solveh_banded(ab, b)
         assert_array_almost_equal(x, [0.0, 1.0, 1.0])
 
     def test_02_complex(self):
+        warnings.simplefilter('ignore', category=DeprecationWarning)
         # Solve
         # [ 4 -j 0]     [ -j    4j]
         # [ j 4 -j] X = [4-j  -1-j]
@@ -217,13 +237,15 @@ def test_02_complex(self):
         b = array([[   -1j,    4.0j],
                    [4.0-1j, -1.0-1j],
                    [4.0+1j,     4.0]])
-        x = solveh_banded(ab, b)
+        c, x = solveh_banded(ab, b)
         expected = array([[0.0, 1.0j],
                           [1.0,  0.0],
                           [1.0,  1.0]])
         assert_array_almost_equal(x, expected)
 
     def test_bad_shapes(self):
+        warnings.simplefilter('ignore', category=DeprecationWarning)
+
         ab = array([[-99, 1.0, 1.0],
                     [4.0, 4.0, 4.0]])
         b = array([[1.0, 4.0],
@@ -232,6 +254,12 @@ def test_bad_shapes(self):
         assert_raises(ValueError, solveh_banded, ab, [1.0, 2.0])
         assert_raises(ValueError, solveh_banded, ab, [1.0])
 
+    def test_00_deprecation_warning(self):
+        warnings.simplefilter('error', category=DeprecationWarning)
+        ab = array([[-99, 1.0, 1.0], [4.0, 4.0, 4.0]])
+        b = array([1.0, 4.0, 1.0])
+        assert_raises(DeprecationWarning, solveh_banded, ab, b)
+        #warnings.simplefilter('ignore', category=DeprecationWarning)
 
 class TestSolve(TestCase):