LieAlgebras: Add docs (#2425)

experimental/LieAlgebras/docs/doc.main

@@ -1,2 +1,7 @@
 [
+   "Lie Algebras" => [
+      "introduction.md",
+      "lie_algebras.md",
+      "modules.md",
+   ],
 ]

experimental/LieAlgebras/docs/src/introduction.md

@@ -0,0 +1,23 @@
+```@meta
+CurrentModule = Oscar
+DocTestSetup = quote
+  using Oscar
+end
+```
+
+# Introduction
+
+This project aims to provide functionality for Lie algebras and their representations.
+
+## Status
+
+This part of OSCAR is in an experimental state; please see [Adding new projects to experimental](@ref) for what this means.
+
+## Contact
+
+Please direct questions about this part of OSCAR to the following people:
+* [Lars Göttgens](https://lgoe.li/)
+
+You can ask questions in the [OSCAR Slack](https://www.oscar-system.org/community/#slack).
+
+Alternatively, you can [raise an issue on github](https://www.oscar-system.org/community/#how-to-report-issues).

experimental/LieAlgebras/docs/src/lie_algebras.md

@@ -0,0 +1,79 @@
+```@meta
+CurrentModule = Oscar
+DocTestSetup = quote
+  using Oscar
+end
+```
+
+# Lie algebras
+
+Lie algebras in OSCAR are currently always finite dimensional, and represented by two different types,
+namely `LinearLieAlgebra{C}` and `AbstractLieAlgebra{C}`, depending on whether a matrix
+representation is available or not.
+Both types are subtypes of `LieAlgebra{C}`. Similar to other types in OSCAR, each Lie algebra
+type has a corresponding element type.
+The type parameter `C` is the element type of the coefficient ring. 
+
+```@docs
+zero(::LieAlgebra{C}) where {C<:RingElement}
+iszero(::LieAlgebraElem{C}) where {C<:RingElement}
+dim(::LieAlgebra{C}) where {C<:RingElement}
+basis(::LieAlgebra{C}) where {C<:RingElement}
+basis(::LieAlgebra{C}, ::Int) where {C<:RingElement}
+coefficients(::LieAlgebraElem{C}) where {C<:RingElement}
+coeff(::LieAlgebraElem{C}, ::Int) where {C<:RingElement}
+getindex(::LieAlgebraElem{C}, ::Int) where {C<:RingElement}
+symbols(::LieAlgebra{C}) where {C<:RingElement}
+```
+
+## Special functions for `LinearLieAlgebra`s
+
+```@docs
+matrix_repr_basis(::LinearLieAlgebra{C}) where {C<:RingElement}
+matrix_repr_basis(::LinearLieAlgebra{C}, ::Int) where {C<:RingElement}
+matrix_repr(::LinearLieAlgebraElem{C}) where {C<:RingElement}
+```
+
+## Element constructors
+
+`(L::LieAlgebra{C})()` returns the zero element of the Lie algebra `L`.
+
+`(L::LieAlgebra{C})(x::LieAlgebraElem{C})` returns `x` if `x` is an element of `L`,
+and fails otherwise.
+
+`(L::LieAlgebra{C})(v)` constructs the element of `L` with coefficient vector `v`.
+`v` can be of type `Vector{C}`, `Vector{Int}`, `SRow{C}`,
+or `MatElem{C}` (of size $1 \times \dim(L)$).
+
+If `L` is a `LinearLieAlgebra` of `dim(L) > 1`, the call
+`(L::LinearLieAlgebra{C})(m::MatElem{C})` returns the Lie algebra element whose
+matrix representation corresponds to `m`.
+This requires `m` to be a square matrix of size `n > 1` (the dimension of `L`), and
+to lie in the Lie algebra `L` (i.e. to be in the span of `basis(L)`).
+The case of `m` being a $1 \times \dim(L)$ matrix still works as explained above.
+
+
+## Arithmetics
+The usual arithmetics, e.g. `+`, `-`, and `*`, are defined for `LieAlgebraElem`s.
+
+!!! warning
+    Please note that `*` refers to the Lie bracket and is thus not associative.
+
+## Lie algebra constructors
+
+```@docs
+lie_algebra
+```
+
+## Classical Lie algebras
+
+```@docs
+general_linear_lie_algebra(R::Ring, n::Int)
+special_linear_lie_algebra(R::Ring, n::Int)
+special_orthogonal_lie_algebra(R::Ring, n::Int)
+```
+
+## Relation to GAP Lie algebras
+
+Using `Oscar.iso_oscar_gap(L)`, one can get an isomorphism from the OSCAR Lie algebra `L`
+to some isomorphic GAP Lie algebra. For more details, please refer to [`iso_oscar_gap`](@ref).

experimental/LieAlgebras/docs/src/modules.md

@@ -0,0 +1,78 @@
+```@meta
+CurrentModule = Oscar
+DocTestSetup = quote
+  using Oscar
+end
+```
+
+# Lie algebra modules
+
+Lie algebra modules in OSCAR are always finite dimensional and represented by the type
+`LieAlgebraModule{C}`. Similar to other types in OSCAR, there is the corresponding
+element type `LieAlgebraModuleElem{C}`.
+The type parameter `C` is the element type of the coefficient ring.
+
+```@docs
+base_lie_algebra(V::LieAlgebraModule{C}) where {C<:RingElement}
+zero(::LieAlgebraModule{C}) where {C<:RingElement}
+iszero(::LieAlgebraModuleElem{C}) where {C<:RingElement}
+dim(::LieAlgebraModule{C}) where {C<:RingElement}
+basis(::LieAlgebraModule{C}) where {C<:RingElement}
+basis(::LieAlgebraModule{C}, ::Int) where {C<:RingElement}
+coefficients(::LieAlgebraModuleElem{C}) where {C<:RingElement}
+coeff(::LieAlgebraModuleElem{C}, ::Int) where {C<:RingElement}
+getindex(::LieAlgebraModuleElem{C}, ::Int) where {C<:RingElement}
+symbols(::LieAlgebraModule{C}) where {C<:RingElement}
+```
+
+## Element constructors
+
+`(V::LieAlgebraModule{C})()` returns the zero element of the Lie algebra module `V`.
+
+`(V::LieAlgebraModule{C})(v::LieAlgebraModuleElem{C})` returns `v` if `v` is an element of `L`. If `V` is the dual module of the parent of `v`, it returns the dual of `v`. In all other cases, it fails.
+
+`(V::LieAlgebraModule{C})(v)` constructs the element of `V` with coefficient vector `v`. `v` can be of type `Vector{C}`, `Vector{Int}`, `SRow{C}`, or `MatElem{C}` (of size $1 \times \dim(L)$).
+
+`(V::LieAlgebraModule{C})(a::Vector{T}) where {T<:LieAlgebraModuleElem{C}})`: If `V` is a direct sum, return its element, where the $i$-th component is equal to `a[i]`.
+If `V` is a tensor product, return the tensor product of the `a[i]`.
+If `V` is a exterior (symmetric, tensor) power, return the wedge product
+(product, tensor product) of the `a[i]`.
+Requires that `a` has a suitable length, and that the `a[i]` are elements of the correct modules,
+where _correct_ depends on the case above.
+
+
+## Arithmetics
+The usual arithmetics, e.g. `+`, `-`, and `*` (scalar multiplication), are defined for `LieAlgebraModuleElem`s.
+
+The module action is defined as `*`.
+```@docs
+*(x::LieAlgebraElem{C}, v::LieAlgebraModuleElem{C}) where {C<:RingElement}
+```
+
+## Module constructors
+
+```@docs
+standard_module(::LinearLieAlgebra{C}) where {C<:RingElement}
+dual(::LieAlgebraModule{C}) where {C<:RingElement}
+direct_sum(::LieAlgebraModule{C}, ::LieAlgebraModule{C}) where {C<:RingElement}
+tensor_product(::LieAlgebraModule{C}, ::LieAlgebraModule{C}) where {C<:RingElement}
+exterior_power(::LieAlgebraModule{C}, ::Int) where {C<:RingElement}
+symmetric_power(::LieAlgebraModule{C}, ::Int) where {C<:RingElement}
+tensor_power(::LieAlgebraModule{C}, ::Int) where {C<:RingElement}
+abstract_module(::LieAlgebra{C}, ::Int, ::Vector{<:MatElem{C}}, ::Vector{<:VarName}; ::Bool) where {C<:RingElement}
+abstract_module(::LieAlgebra{C}, ::Int, ::Matrix{SRow{C}}, ::Vector{<:VarName}; ::Bool) where {C<:RingElement}
+```
+
+# Type-dependent getters
+
+```@docs
+is_standard_module(::LieAlgebraModule{C}) where {C<:RingElement}
+is_dual(::LieAlgebraModule{C}) where {C<:RingElement}
+is_direct_sum(::LieAlgebraModule{C}) where {C<:RingElement}
+is_tensor_product(::LieAlgebraModule{C}) where {C<:RingElement}
+is_exterior_power(::LieAlgebraModule{C}) where {C<:RingElement}
+is_symmetric_power(::LieAlgebraModule{C}) where {C<:RingElement}
+is_tensor_power(::LieAlgebraModule{C}) where {C<:RingElement}
+base_module(::LieAlgebraModule{C}) where {C<:RingElement}
+base_modules(::LieAlgebraModule{C}) where {C<:RingElement}
+```

experimental/LieAlgebras/src/AbstractLieAlgebra.jl

@@ -114,6 +114,23 @@ end
 #
 ###############################################################################
 
+@doc raw"""
+    lie_algebra(R::Ring, struct_consts::Matrix{SRow{C}}, s::Vector{<:VarName}; cached::Bool, check::Bool) -> AbstractLieAlgebra{elem_type(R)}
+
+Construct the Lie algebra over the ring `R` with structure constants `struct_consts`
+and with basis element names `s`.
+
+The Lie bracket on the newly constructed Lie algebra `L` is determined by the structure
+constants in `struct_consts` as follows: let $x_i$ denote the $i$-th standard basis vector
+of `L`. Then the entry `struct_consts[i,j][k]` is a scalar $a_{i,j,k}$
+such that $[x_i, x_j] = \sum_k a_{i,j,k} x_k$.
+
+* `s`: A vector of basis element names. This is 
+  `[Symbol("x_$i") for i in 1:size(struct_consts, 1)]` by default.
+* `cached`: If `true`, cache the result. This is `true` by default.
+* `check`: If `true`, check that the structure constants are anti-symmetric and
+  satisfy the Jacobi identity. This is `true` by default.
+"""
 function lie_algebra(
   R::Ring,
   struct_consts::Matrix{SRow{C}},
@@ -124,6 +141,58 @@ function lie_algebra(
   return AbstractLieAlgebra{elem_type(R)}(R, struct_consts, Symbol.(s); cached, check)
 end
 
+@doc raw"""
+    lie_algebra(R::Ring, struct_consts::Array{elem_type(R),3}, s::Vector{<:VarName}; cached::Bool, check::Bool) -> AbstractLieAlgebra{elem_type(R)}
+
+Construct the Lie algebra over the ring `R` with structure constants `struct_consts`
+and with basis element names `s`.
+
+The Lie bracket on the newly constructed Lie algebra `L` is determined by the structure
+constants in `struct_consts` as follows: let $x_i$ denote the $i$-th standard basis vector
+of `L`. Then the entry `struct_consts[i,j,k]` is a scalar $a_{i,j,k}$
+such that $[x_i, x_j] = \sum_k a_{i,j,k} x_k$.
+
+* `s`: A vector of basis element names. This is
+  `[Symbol("x_$i") for i in 1:size(struct_consts, 1)]` by default.
+* `cached`: If `true`, cache the result. This is `true` by default.
+* `check`: If `true`, check that the structure constants are anti-symmetric and
+  satisfy the Jacobi identity. This is `true` by default.
+
+# Examples
+```jldoctest
+julia> struct_consts = zeros(QQ, 3, 3, 3);
+
+julia> struct_consts[1, 2, 3] = QQ(1);
+
+julia> struct_consts[2, 1, 3] = QQ(-1);
+
+julia> struct_consts[3, 1, 1] = QQ(2);
+
+julia> struct_consts[1, 3, 1] = QQ(-2);
+
+julia> struct_consts[3, 2, 2] = QQ(-2);
+
+julia> struct_consts[2, 3, 2] = QQ(2);
+
+julia> sl2 = lie_algebra(QQ, struct_consts, ["e", "f", "h"])
+AbstractLieAlgebra over Rational field
+
+julia> e, f, h = basis(sl2)
+3-element Vector{AbstractLieAlgebraElem{QQFieldElem}}:
+ e
+ f
+ h
+
+julia> e * f
+h
+
+julia> h * e
+2*e
+
+julia> h * f
+-2*f
+```
+"""
 function lie_algebra(
   R::Ring,
   struct_consts::Array{C,3},
@@ -143,8 +212,16 @@ function lie_algebra(
   return AbstractLieAlgebra{elem_type(R)}(R, struct_consts2, Symbol.(s); cached, check)
 end
 
+@doc raw"""
+    lie_algebra(R::Ring, dynkin::Tuple{Char,Int}; cached::Bool) -> AbstractLieAlgebra{elem_type(R)}
+
+Construct the simple Lie algebra over the ring `R` with Dynkin type given by `dynkin`.
+The actual construction is done in GAP.
+
+If `cached` is `true`, the constructed Lie algebra is cached.
+"""
 function lie_algebra(R::Ring, dynkin::Tuple{Char,Int}; cached::Bool=true)
-  @req is_valid_dynkin(dynkin...) "Input not allowed by GAP."
+  @req dynkin[1] in 'A':'G' "Unknown Dynkin type"
 
   coeffs_iso = inv(Oscar.iso_oscar_gap(R))
   LG = GAP.Globals.SimpleLieAlgebra(