Deprecate cholesky_decomposition() in favor of cholesky()

[rbeezer]

cholesky_decomposition() is needlessly verbose, and the existing spaghetti code with _cholesky_decomposition() is too convoluted to unwind. Dependencies install the new cholesky() alongside.

The old cholesky_decomposition() is so broken that nobody should be using it anyway, thus it should be no problem to obsolete it.

Depends: #12966, #13018, #11274, #13035

Apply:

1. trac_13045-deprecate-cholesky-decomposition-v1.patch​
2. trac_13045-deprecate-cholesky-decomposition-update.patch​

[rbeezer]

Importing the deprecation machinery seemed to set off some Python deprecation warnings about messages on exceptions, so those have been modernized.

[ddrake]

One note: string formatting when raising an exception is, in many cases, a really bad idea, since generating the string may take a really long time. This mostly happens when trying to represent a very large number or other Sage object, and can dramatically slow down some algorithms which try things, catch exceptions, and then try other things without looking at the error message.

I think the string formatting here is fine, since it should just be mixing in another simple error message, but it seems wise to leave a warning here.

[ddrake]

In the warning, you should link to the new cholesky function: :meth:`cholesky`.

[ddrake]

More seriously, the caching means that this broken, crappy function can infect the new, correct function:

sage: r = matrix(CDF, 2, 2, [ 1, -2*I, 2*I, 0 ]); r
[   1.0 -2.0*I]
[ 2.0*I    0.0]
sage: r[0,0] = 0
sage: r.cholesky_decomposition()
[        0.0         0.0]
[NaN + NaN*I NaN + NaN*I]
sage: r.cholesky()
[        0.0         0.0]
[NaN + NaN*I NaN + NaN*I]

The documentation makes it clear that cholesky_decomposition can return bad answers, but the new function shouldn't be infected by that.

[rbeezer]

Update patch addresses reviewer comments: cholesky is linked in warning, cache strings are separated, and a doctest for that is added.

Apply new patch on top of old.

[ddrake]

Separating the caches does show us that the new routine is much faster:

sage: A= random_matrix(CDF, 200); M = A*A.conjugate_transpose()
sage: %time M.cholesky()
CPU times: user 0.01 s, sys: 0.00 s, total: 0.01 s
Wall time: 0.03 s
200 x 200 dense matrix over Complex Double Field
sage: %time M.cholesky_decomposition()
/home/drake/s/sage-5.1.beta0/local/lib/python2.7/site-packages/IPython/Magic.py:1981: DeprecationWarning: (Since Sage Version 5.1) cholesky_decomposition() is deprecated; please use cholesky() instead.
  out = eval(code,glob)
CPU times: user 23.33 s, sys: 0.01 s, total: 23.34 s
Wall time: 23.42 s
200 x 200 dense matrix over Complex Double Field

About three orders of magnitude. Nice.

[ddrake]

The second patch is good. Positive review to all.

Apply trac_13045-deprecate-cholesky-decomposition-v1.patch and trac_13045-deprecate-cholesky-decomposition-update.patch