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.

[fingolfin]

I think @JohnAAbbott resolved this; I'll have a look to verify that my "complaints" in this issue were addressed and will close it

[fingolfin]

@HereAround points out that some examples for this would be a good addition to the linear algebra tutorial. I'll see if I can provide some.

[fingolfin]

This issue is resolved from my POV, thanks.

@HereAround I think the examples I give above would be a good basis for the tutorial,
maybe enriched with some interspersed text:

---

Consider the following two matrices over the
integers resp. rationals.

julia> mQ = matrix(QQ, [1//2 0; 0 2])
[1//2   0]
[   0   2]

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

We can ask for the eigenvalues. A first attempt might look like this:

julia> eigenvalues(mQ)
2-element Vector{QQFieldElem}:
 2
 1//2

julia> eigenvalues(mZ)
ZZRingElem[]

The second list is empty because by default eigenvalues are searched only in the
base_ring of the matrix, and the matrix has no integer eigenvalues.

We can also ask for eigenvalues in a larger ring,
e.g. in the algebraic closure of the rationals:

julia> K = algebraic_closure(QQ)
Algebraic closure of rational field

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

Next we may wish to compute eigenspaces.
Again we can first try a single argument version:

julia> eigenspaces(mQ)
Dict{QQFieldElem, QQMatrix} with 2 entries:
  1//2 => [1 0]
  2    => [0 1]

julia> eigenspaces(mZ)
ERROR: ArgumentError: Please specify the field over which to compute (since matrix is not over a field)

The second command run into an error because OSCAR currently only
supports eigenspaces which are vector spaces, so over a field.
But as before, if we specify nothing else it performs computations
over the base ring of the matrix, which here is the ring of
integers.

Once again we can resolve this by specifying a field over which to compute
the eigenspaces, e.g. again the algebraic closure of the rationals:

julia> eigenspaces(K, mZ)
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]

Of course we can also ask for a specific eigenspace corresponding to a given
eigenvalue. Here we don't need to specify a field if the eigenvalue is already
a field element

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

julia> eigenspace(mQ, 2)
[0   1]

[JohnAAbbott]

I would like to add that the result of eigenspace is a matrix whose rows are a basis for the eigenspace (not sure if the basis is orthogonal). Similarly eigenspaces returns a Dict associating to each eigenvalue a matrix whose rows form a basis.
Not surprisingly we get the following when the given value is not an eigenvalue:

julia> eigenspace(mQ, 3)
0 by 2 empty matrix