Unify eigenvalue methods

[joschmitt]

Somebody is probably well aware of this, but just to write it down somewhere...
At least the following methods to compute eigenvalues exist:

spectrum(M::MatElem{T}) where T <: FieldElem -> Dict{T, Int}

  Returns the spectrum of a matrix, i.e. the set of eigenvalues of M with
  multiplicities.

and

eigenvalues(A::ZZMatrix, R::CalciumQQBarField)

  Return all the eigenvalues of the matrix A in the field of algebraic numbers R. The
  output array is sorted in the default sort order for algebraic numbers. Eigenvalues
  of multiplicity higher than one are repeated according to their multiplicity.

  ────────────────────────────────────────────────────────────────────────────────────

  eigenvalues(A::QQMatrix, R::CalciumQQBarField)

  Return all the eigenvalues of the matrix A in the field of algebraic numbers R. The
  output array is sorted in the default sort order for algebraic numbers. Eigenvalues
  of multiplicity higher than one are repeated according to their multiplicity.

Can we unify this interface in terms of the name and the returned type? Especially, when a user does ?eigenvalue they will think that we can only do eigenvalues in QQBar...

[fieker]

different things in different context. To me:

• eigenvalues, by default, will only return those in the field of definition
• spectrum implicitly works over C (or QQbar), there should be versino that also allows to specify the target field
• eigenvalues should also have an option to specify the target field...not quite sure what all the options should be here
• a link in the docs should be there

[joschmitt]

As far as I can tell, spectrum only computes the eigenvalues contained in the field of definition; one can supply a 'bigger' field as second argument. eigenvalues works over QQbar.
So I have the impression that the names are exactly opposite to your expectation?

[fieker]

yep - but I haven't spend a lot of time thinking about it. spectrum I mainly encountered in functional analysis, hence I'd be inclinded to use C (or R for symmetric ones)

[joschmitt]

I just noticed that there is also

  eigvals(A::acb_mat)

  Returns the eigenvalues of A as a vector of tuples (acb, Int). Each tuple (z, k)
  corresponds to a cluster of k eigenvalues of A.

  This function is experimental.

  ────────────────────────────────────────────────────────────────────────────────────

  eigvals(A::ComplexMat)

  Returns the eigenvalues of A as a vector of tuples (ComplexFieldElem, Int). Each
  tuple (z, k) corresponds to a cluster of k eigenvalues of A.

  This function is experimental.

which has yet another name and return type. The name eigvals would also be the name for the Julia/LinearAlgebra method, but they don't return multiplicities.

[thofma]

Let's keep the discussion here @joschmitt @lgoettgens.

Regarding the name and the return type. Maybe eigenvalues (just the roots of the characteristic polynomial) and eigenvalues_with_multiplicity for both?

Also not sure about the dictionary (anymore). For the Fac, the point of having a dedicated object is to handle the unit. Here it could just be a list of 2-tuples instead?

We can also discuss this in person tomorrow.

[joschmitt]

Regarding the name and the return type. Maybe eigenvalues (just the roots of the characteristic polynomial) and eigenvalues_with_multiplicity for both?

Then eigenvalues would agree with LinearAlgebra.eigvals. Sounds good.

Also not sure about the dictionary (anymore). For the Fac, the point of having a dedicated object is to handle the unit. Here it could just be a list of 2-tuples instead?

I was also thinking of factor for ideals which returns a dictionary. But I can't say I have a strong opinion.

We can also discuss this in person tomorrow.

Sure.

[lgoettgens]

Conclusion from the discussion with @thofma and @joschmitt:

• eigenvalues returns a list of unique eigenvalues (alias of LinearAlgebra.eigvals)
• eigenvalues_with_multiplicities returns a list of 2-tuples of unique eigenvalues with the corresponding algebraic multiplicity.
• Optionally, one can provide a field as first argument.
• spectrum gets removed.
• As a first step, we move everything to Nemo (everything is up to discussion).

[joschmitt]

Closed via #3231 . 🎉