Wishlist for `eigenspace` and `eigenspaces`

[fingolfin]

Some wishes:

• searching for eigenspace or eigenspaces on https://docs.oscar-system.org/stable/ should yield more than 0 hits
  - I think this is because Nemo defines and exports these function, including docstrings, but they are not put into the manual
  - so someone should add it to the Nemo manual and/or the Oscar manual
• generalize these rings from matrices over fields to matrices over rings
  - the kernel function they use may not always be available then, but that's no reason to not support this for e.g. Z ?
• there should be a variant for eigenspaces which takes a coefficient ring and a matrix (example below)
• there should be a variant for eigenspace which takes a matrix and an eigenvalue of a different type (e.g.: matrix over Z, eigenvalue in QQBar)

For the last two points, this currently works:

julia> m = matrix(ZZ, [0 1; -1 0])
[ 0   1]
[-1   0]

julia> eigenvalues(m)
ZZRingElem[]

julia> K = algebraic_closure(QQ)
Field of algebraic numbers

julia> lambda1, lambda2 = eigenvalues(K, m)
2-element Vector{QQBarFieldElem}:
 Root 1.00000*im of x^2 + 1
 Root -1.00000*im of x^2 + 1

But there is no direct way to get eigenspaces. I need to convert the matrices first:

julia> m2 = matrix(K, m)
[           Root 0 of x   Root 1.00000 of x - 1]
[Root -1.00000 of x + 1             Root 0 of x]

julia> eigenspaces(m2)
Dict{QQBarFieldElem, AbstractAlgebra.Generic.MatSpaceElem{QQBarFieldElem}} with 2 entries:
  Root 1.00000*im of x^2 + 1  => [Root 1.00000*im of x^2 + 1 Root 1.00000 of x - 1]
  Root -1.00000*im of x^2 + 1 => [Root -1.00000*im of x^2 + 1 Root 1.00000 of x - 1]

julia> eigenspace(m2, lambda1)
[Root 1.00000*im of x^2 + 1   Root 1.00000 of x - 1]

I'd like to be able to do these (all currently produce an error):

julia> eigenspaces(m)
Dict{ZZRingElem, ZZMatrix}()

julia> eigenspaces(K, m)
Dict{QQBarFieldElem, AbstractAlgebra.Generic.MatSpaceElem{QQBarFieldElem}} with 2 entries:
  Root 1.00000*im of x^2 + 1  => [Root 1.00000*im of x^2 + 1 Root 1.00000 of x - 1]
  Root -1.00000*im of x^2 + 1 => [Root -1.00000*im of x^2 + 1 Root 1.00000 of x - 1]

julia> eigenspace(m, lambda1)
[Root 1.00000*im of x^2 + 1   Root 1.00000 of x - 1]

Perhaps @JohnAAbbott can take a look at this?

[fingolfin]

@JohnAAbbott did you make any progress on this?

[fingolfin]

Just had a discussion with John and realized that one of my requests was misleading at best but more likely just nonsense: for the ZZMatrix I suggested m

julia> eigenspaces(m)
Dict{ZZRingElem, ZZMatrix}()

but that suggests that for other matrices there could be a non-empty result, which leads to the question what an "integral eigenspace of an integer matrix" is. I am not even sure that's a well-defined notion, but even if it is, it's certainly not one that is commonly taught or understood.

But this is not what I had in mind at all when I wrote the above: where I was coming from was the real world experience of a first time user trying to figure out how to do things and struggling: they defined a square integer matrix (because for other stuff they did with the matrix, it was square). And then they tried to get the eigenspaces (with the usual mathematician approach of implicitly treating it as a rational matrix), and got a scary error.

So this was meant to gently lead them down a path leading to asking the right question. But what I suggested probably isn't that. Instead, we could either...

1. ignore this and keep throwing the same error,
2. throw a somewhat nicer error: "eigenspaces can only be computed over fields, see ?eigenspaces to information on how to do that"
3. implicitly assume the quotient field is meant and use that, so QQ in my example (at least for integral domains -- if the input isn't an integral domain resp. if it's type isn't a is_domain_type type, I'd be happy to see an error).

[thofma]

I am happy with 1) or 2), but would be against 3).

[JohnAAbbott]

I have revised the implementation to align with @fingolfin last comment about.
This is a breaking change: previously it was possible to compute eigenvalues(::ZZMatrix), but this now produces an error. Instead one has two options: eigenvalues(QQ,M) or eigenvalues(change_base_ring(QQ,M)). Also the result has changed: it is now Vector{QQFieldElem} whereas previously is was Vector{ZZRingElem}. Analogous comments apply to eigenspaces.