support user-specified permutation in CHOLMOD factorizations

[stevengj]

This changes the cholfact and ldltfact sparse factorizations (via CHOLMOD) to accept a perm argument specifying a user-defined permutation instead of the default AMD permutation. It also changes the (undocumented) optional β argument to a (documented) shift keyword argument. Some of the code is consolidated a bit, and I switched to using the new-style Ref{Complex128} instead of Ptr{Cdouble} (which seems easy to misuse by passing only a single real number when CHOLMOD sometimes expects two) for a couple of ccalls.

I included a couple of other keywords args for cholmod options I was experimenting with, but was unsure whether to document them. Passing perm and setting userperm_only=false causes CHOLMOD to try both the user-specified permutation and AMD and pick the better of the two, and passing postorder=false omits a post-ordering pass in CHOLMOD (that doesn't affect nnz but supposedly effects supernodal efficiency).

cc @andreasnoack, who helped track down the relevant functionality (I needed it for teaching, in order to show the effect of different orderings).

[andreasnoack]

👍

[stevengj]

See also this IJulia notebook from my class.

[vtjnash]

Ptr{Cdouble} (which seems easy to misuse by passing only a single real number when CHOLMOD sometimes expects two) for a couple of ccalls.

at no point should it have been valid to pass Ptr{Cdouble},& where a Ptr{Complex128},& was intended. the result should have been incorrect answers and corruption of the program. was that what was being done here previous?

[ViralBShah]

👍

[andreasnoack]

@vtjnash I think the old version was wrong. The signature for the C function is double alpha [2] and I think I simply missed the [2] part. It might be that only real arguments are tested for this function, but it is also a bit tricky because it seems that the it has to be a genuinely complex argument to cause trouble, e.g.

julia> SparseMatrix.CHOLMOD.sdmult!(AS, false, complex(1.0), complex(0.0), bS, cS)

works, but

julia> SparseMatrix.CHOLMOD.sdmult!(AS, false, complex(1.0, 1.0), complex(0.0), bS, cS)
ERROR: InexactError()
 in ptr_arg_cconvert at base.jl:58
 in sdmult! at sparse/cholmod.jl:578

Anyway, @stevengj has fixed the problem.

[stevengj]

@vtjnash, in at least some cases, CHOLMOD was only reading beta[0] even though the argument was declared as double beta[2].

[stevengj]

We might want a backport of the complex-arg fix, but I don't think the API changes should be backported.