New API name conventions

[lopezm94]

Due to the coming of the new API, the names of some methods and keyword arguments are going to change, these are all preliminary so feel free to share alternatives. Here are some of the changes:

Method names:

• eigvals_power => powm
• eigvals_ii => invpowm
• eigvals_rqi => rqi
• gauss_seidel => gs
• eigvals_lanczos => eiglancz

  Keyword arguments:

In the new API all the optional positional arguments are now going to be keyword arguments. Some of the new keyword names:

• shift: For inverse iteration and rayleigh
• nsv: For number of singular values requested in svdl
• The rest have the same name but are now keywords

  Dictionary keys:

It is also worth discussing the name conventions in ConvergenceHistory since it will most likely have an inner dictionary for tolerances and the rest of the information. So some names for tolerances could be reltol, abstol and so on instead of atol, btol, ctol or other non-explicit naming, it goes the same for norms (resnorm, Anorm, etc). If two of them repeat then it will have a number as suffix.

@lruthotto @dpo

[ChrisRackauckas]

I highly prefer more descriptive names to shortened names which require knowing package details to understand. I.e. eigvals_lanczos >> eiglancz, though eig_lanczos would suffice. eiglancz would be a ?? if I didn't already know what it was, and I couldn't even just google the method really quickly. Same with nsv. If I see that in code, I don't necessarily know what that is, but num_singular_val is readable. I fear that some of this is a little too far on the terse side.

[lopezm94]

What I tried to do was put short names on every keyword and solve any misunderstanding in the docs. There you can check anything you want. Is it too messy?

For example:

svdl(A)

  Compute some singular values (and optionally vectors) using
  Golub-Kahan-Lanczos bidiagonalization cite{Golub1965} with thick restarting
  cite{Wu2000}.

  If log is set to true is given, method will output a tuple X, L, ch. Where
  ch is a ConvergenceHistory object. Otherwise it will only return X, L.

  The plot attribute can only be used when log is set version.

  Arguents

    •    A : The matrix or matrix-like object whose singular values are
        desired.

  Keywords

    •    nsv::Int = 6: number of singular values requested.

    •    v0 = random unit vector: starting guess vector in the domain of A.

  The length of q should be the number of columns in A.

    •    k::Int = 2nsv: maximum number of Lanczos vectors to compute before
        restarting.

    •    j::Int = nsv: number of vectors to keep at the end of the restart.

  We don't recommend j < nsv.

    •    maxiter::Int = minimum(size(A)): maximum number of iterations to
        run.

    •    verbose::Bool = false: print information at each iteration.

    •    tol::Real = √eps(): maximum absolute error in each desired
        singular value.

    •    reltol::Real=√eps(): maximum error in each desired singular value
        relative to the

  estimated norm of the input matrix.

    •    method::Symbol=:ritz: restarting algorithm to use. Valid choices
        are:

          •    :ritz: Thick restart with Ritz values [Wu2000].

          •    :harmonic: Restart with harmonic Ritz values
              [Baglama2005].

    •    vecs::Symbol = :none: singular vectors to return.

          •    :both: Both left and right singular vectors are
              returned.

          •    :left: Only the left singular vectors are returned.

          •    :right: Only the right singular vectors are returned.

          •    :none: No singular vectors are returned.

    •    dolock::Bool=false: If true, locks converged Ritz values, removing
        them

  from the Krylov subspace being searched in the next macroiteration.

    •    log::Bool = false: output an extra element of type
        ConvergenceHistory

  containing extra information of the method execution.

    •    plot::Bool = false: plot data. (Only when log is set)

  Output

  log is false:

    •    Σ: list of the desired singular values if vecs == :none (the
        default), otherwise returns an SVD object with the desired
        singular vectors filled in.

    •    L: computed partial factorizations of A.

  log is true:

    •    Σ: list of the desired singular values if vecs == :none (the
        default), otherwise returns an SVD object with the desired
        singular vectors filled in.

    •    L: computed partial factorizations of A.

    •    ch::ConvergenceHistory: convergence history.

  ConvergenceHistory keys

    •    :betas => betas: The history of the computed betas.

    •    :Bs => Bs: The history of the computed projected matrices.

    •    :ritz => ritzvalhist: Ritz values computed at each iteration.

    •    :conv => convhist: Convergence data.

[ChrisRackauckas]

I also notice that a lot of this doesn't match conventions in other parts of the package ecosystem. Large swaths of Base, JuliaOpt, JuliaDiffEq, etc. all tend to name things similarly (as compiled by JuliaPraxis), but IterativeSolvers.jl doesn't match these conventions. For example:

• tol instead of abstol
• maxiter instead of maxiters

I think these should be double-triple checked to make sure it matches other places.

[lopezm94]

Agreed. I'll be posting any recent changes I make here. If you can let me know of anything that violates convention it will be extremely helpful.