Add (dense) Cholesky up- and downdates

[andreasnoack]

As discussed in #2929. Cholmod also provides this functionality in the sparse case so it should be easy to add that.

Only issue is that update! in the CHOLMOD is used as method name for reusing a symbolic factorization. The update! methods in the CHOLMOD module are not exported so we can rename them and I think we should. I'll propose to just overload cholfact and ldlfact with methods taking both a factorization and a matrix.

[tkelman]

cholfact! with separate destination (reused factorization) and source maybe?

[tkelman]

update is a very generic name to be exporting from base, but this is a very specific linear algebra operation so I'm not sure it's worth claiming the namespace for yet. Maybe leave this as LinAlg.update at first?

[ViralBShah]

How about calling it updatefactor?

[andreasnoack]

@ViralBShah Which of them?

@tkelman One method of a generic function has to be the first. It's clear from the signature that is is a linear algebra method and it won't collide with any use outside linear algebra. However, it will probably not be the most widely used linear algebra function, so I'd be okay with removing the entries in exports.jl.

[tkelman]

If any packages are currently exporting something named update wouldn't adding the export to base cause issues?

[andreasnoack]

I think it would only be a problem if they exported a function with the exact same signature, but did something different. Otherwise they could just import update from Base. In JuliaStats we decided to define and export many names in StatsBase because that could be the most upstream package for most other statistics packages. Then two downstream packages that don't have a dependency on eachother can both import that name from StatsBase.

[StefanKarpinski]

No way – Base cannot export such a generic name used in such a non-general way. Extending the function with unrelated functionality that happens to have the same name is also not ok. In order to have something like this exported from Base you have to be able to write some general description of what update means. This documentation is entirely specific to Cholesky, which is really not acceptable.

[jiahao]

"Update" and "downdate" refer to fixed-rank additive or subtractive modifications of matrix factorizations - in principle applicable to any matrix factorization, not just Cholesky, and not necessarily rank 1. So it would be possible to treat "update" in the matrix factorization sense as "the" way to update! a matrix factorization object.

Maybe it's best to call them LinAlg.update! and LinAlg.downdate!.

[andreasnoack]

@StefanKarpinski I'm fine with not exporting it from Base or renaming it to rankUpdate or updateRank, but to avoid misunderstadings: updates like these are not specific to Cholesky. It's basically a rank update of the underlying matrix. As pointed out by @jiahao: eventually, we should also have rank update methods for non-factorized matrices, QR and eigen factorizations. It just happened that the Cholesky came first.

Lately, I've been splitting up method documentation entries instead of having the larger entries covering several methods. I think it makes them more precise and easier to maintain. Is that the wrong direction?

[tkelman]

No indent at the start of the line.

Please, please, add line breaks to docstrings. Please.

[tkelman]

Come on. https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md#general-formatting-guidelines-for-julia-code-contributions

[andreasnoack]

We have discussed this before and you know we don't agree. It's not to annoy you, but I think it is wrong to use hard line break in prose. The section you link to was added because of long code lines and didn't consider doc strings.

Using soft-wrapping in prose is in line with how md files are handled now. It doesn't work for our doc strings and it doesn't on the phones, as you pointed out last time, so I've send a request to GitHub for a fix.

[tkelman]

It's inline documentation in source code. Not the same thing as prose. Unreadable and a pain to review and edit. Not just on github, plenty of local editors as well. You may think hard line breaks are wrong (would it actively harm anything other than your personal taste to add them?), but I'd guess that as many or more contributors think not adding them is wrong for readability. Aesthetic disagreements like this just cause everyone additional work and hassle, so we need to agree on a convention and stick to it. I'll shut up if we make that decision universally, but it's going to need more opinions than just yours behind it.