Add a linear algebra tutorial

[fingolfin]

Due to recent questions by people interested in using OSCAR but coming from e.g. OSCAR, we noticed that we could really use a good Linear Algebra tutorial on our website.

Teaching things like

• how to create matrices (via matrix(R, [1 2 ;3 4]) or via special constructors like identity_matrix)
• how to solve linear systems of equations
• how to find eigenvalues, eigenspaces
• how to find various normal forms
• acting with matrices on "vectors" (how to even get a "vector")
• probably more...

[HereAround]

@fingolfin A first version of this tutorial is now available at https://www.oscar-system.org/tutorials/LinearAlgebra/.

[JohnAAbbott]

I have sent a long email to @HereAround @aaruni96 and @fingolfin with some feedback including aspects requiring discussion. If desired, I can paste a copy of the email into this issue.

[HereAround]

@JohnAAbbott and I just discussed this tutorial and made improvements to it.

Here are some points that might be good to discuss in triage tomorrow @fingolfin :

• Do we want a redundant matrix constructor, like matrix(ZZ, 2,3, [[1,2,3], [4,5,6]])?
• Where is the documentation of base_ring for matrices?
• characteristic_polynomial(M) = characteristic_polynomial(M) returns fail due to mismatch in parents. Those parent rings can be provided as optional first argument. Is this behavior desired? How to discuss this in the tutorial (if at all)?
• Give an example for diagonalization for which the eigenvalues are not elements of the base ring of the given matrix. (Up to anyone interested.)
• Should snf and hnf work for base rings different than the integers? Currently, they allow for instance also QQ, whilst @JohnAAbbott expected an error whenever the ring is different from ZZ.

Out of curiosity:
Given a matrix over a ring R, its eigenvalues are elements of the algebraic closure of R, and OSCAR returns them as such. Assume that the eigenvalues are actually elements of R. Can one convert the OSCAR computed eigenvalues (returned as elements of the algebraic closure) to elements of R? If so, how?

[thofma]

Here are some points that might be good to discuss in triage tomorrow @fingolfin :

Maybe we can already answer some of them.

• Do we want a redundant matrix constructor, like matrix(ZZ, 2,3, [[1,2,3], [4,5,6]])?

Why redundant? One takes a two-dimensional array and the other a list of one-dimensional arrays.

• Where is the documentation of base_ring for matrices?

Does not exist.

• characteristic_polynomial(M) = characteristic_polynomial(M) returns fail due to mismatch in parents. Those parent rings can be provided as optional first argument. Is this behavior desired? How to discuss this in the tutorial (if at all)?

I think people would be open to changing it, see #3619 (comment).

• Give an example for diagonalization for which the eigenvalues are not elements of the base ring of the given matrix. (Up to anyone interested.)

julia> D, = jordan_normal_form(change_base_ring(algebraic_closure(QQ), QQ[0 2; 1 0])); D

but the output is not pretty.

• Should snf and hnf work for base rings different than the integers? Currently, they allow for instance also QQ, whilst @JohnAAbbott expected an error whenever the ring is different from ZZ.

Yes, this is working as expected.

Out of curiosity: Given a matrix over a ring R, its eigenvalues are elements of the algebraic closure of R, and OSCAR returns them as such. Assume that the eigenvalues are actually elements of R. Can one convert the OSCAR computed eigenvalues (returned as elements of the algebraic closure) to elements of R? If so, how?

For which matrices is this happening? The eigenvalues are elements of the base ring for the examples I tried:

julia> eigenvalues(QQ[2 0; 0 1])
2-element Vector{QQFieldElem}:
 2
 1

julia> eigenvalues(GF(3)[2 0; 0 1])
2-element Vector{FqFieldElem}:
 1
 2

[HereAround]

Here are some points that might be good to discuss in triage tomorrow @fingolfin :

Maybe we can already answer some of them.

Indeed!

• Do we want a redundant matrix constructor, like matrix(ZZ, 2,3, [[1,2,3], [4,5,6]])?

Why redundant? One takes a two-dimensional array and the other a list of one-dimensional arrays.

Because the two middle arguments (2,3) specify the dimensions of the matrix, which could be inferred from the list of rows (last argument: [[1,2,3], [4,5,6]]).

@JohnAAbbott told me earlier that such a constructor exists for the build-in julia matrices. This raised the question if we should mimic this constructor in OSCAR.

I just skimmed over the julia documentation, but could not find such a constructor for the build-in julia matrices. @JohnAAbbott , could you give an example?

• Where is the documentation of base_ring for matrices?

Does not exist.

I understand that we do not want to document every method base_ring, dim, gens etc. Still, a sentence like "You can apply base_ring to a matrix to obtain the ring over which this matrix is defined" in the documentation might help? Maybe it is in our documentation and I olverlooked it. Otherwise, we could add this.

Either way, it should help that this is covered in the tutorial.

• characteristic_polynomial(M) = characteristic_polynomial(M) returns fail due to mismatch in parents. Those parent rings can be provided as optional first argument. Is this behavior desired? How to discuss this in the tutorial (if at all)?

I think people would be open to changing it, see #3619 (comment).

Ok. Thx for the pointer!

• Give an example for diagonalization for which the eigenvalues are not elements of the base ring of the given matrix. (Up to anyone interested.)

julia> D, = jordan_normal_form(change_base_ring(algebraic_closure(QQ), QQ[0 2; 1 0])); D

but the output is not pretty.

Thx!

• Should snf and hnf work for base rings different than the integers? Currently, they allow for instance also QQ, whilst @JohnAAbbott expected an error whenever the ring is different from ZZ.

Yes, this is working as expected.

Thx for confirming!

Out of curiosity: Given a matrix over a ring R, its eigenvalues are elements of the algebraic closure of R, and OSCAR returns them as such. Assume that the eigenvalues are actually elements of R. Can one convert the OSCAR computed eigenvalues (returned as elements of the algebraic closure) to elements of R? If so, how?

For which matrices is this happening? The eigenvalues are elements of the base ring for the examples I tried:

julia> eigenvalues(QQ[2 0; 0 1])
2-element Vector{QQFieldElem}:
 2
 1

julia> eigenvalues(GF(3)[2 0; 0 1])
2-element Vector{FqFieldElem}:
 1
 2

Nvm my last question - I confused myself: "The problem was sitting in front of the computer". ;)

[thofma]

• Do we want a redundant matrix constructor, like matrix(ZZ, 2,3, [[1,2,3], [4,5,6]])?

Why redundant? One takes a two-dimensional array and the other a list of one-dimensional arrays.

Because the two middle arguments (2,3) specify the dimensions of the matrix, which could be inferred from the list of rows (last argument: [[1,2,3], [4,5,6]]).

In some form this came up recently in #4380, but the same argument applies. It helps to quickly see the dimensions for large matrices or for matrices with complex expressions as entries. One could probably add both versions to the tutorial.

Does not exist.

I understand that we do not want to document every method base_ring, dim, gens etc. Still, a sentence like "You can apply base_ring to a matrix to obtain the ring over which this matrix is defined" in the documentation might help? Maybe it is in our documentation and I olverlooked it. Otherwise, we could add this.

Either way, it should help that this is covered in the tutorial.

I agree that this should be added (I also did not find it in the documentation).

[JohnAAbbott]

I have just made PR #1976 in AbstractAlgebra so that charpoly(M) == charpoly(M) works as expected.