LieAlgebras: Add docs

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,20 @@
+```@meta
+CurrentModule = Oscar
+```
+
+# 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,69 @@
+```@meta
+CurrentModule = Oscar
+```
+
+# Lie algebras
+
+Lie algebras in OSCAR are 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}
+(::LinearLieAlgebra{C})(::MatElem{C}) where {C<:RingElement}
+```
+
+## Element constructors
+
+```@docs
+(::LieAlgebra{C})() where {C<:RingElement}
+(::LieAlgebra{C})(::Vector{C}) where {C<:RingElement}
+(::LieAlgebra{C})(::Vector{Int}) where {C<:RingElement}
+(::LieAlgebra{C})(::MatElem{C}) where {C<:RingElement}
+(::LieAlgebra{C})(::SRow{C}) where {C<:RingElement}
+(::LieAlgebra{C})(::LieAlgebraElem{C}) where {C<:RingElement}
+```
+
+## 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,71 @@
+```@meta
+CurrentModule = Oscar
+```
+
+# 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
+
+```@docs
+(::LieAlgebraModule{C})() where {C<:RingElement}
+(::LieAlgebraModule{C})(::Vector{C}) where {C<:RingElement}
+(::LieAlgebraModule{C})(::Vector{Int}) where {C<:RingElement}
+(::LieAlgebraModule{C})(::MatElem{C}) where {C<:RingElement}
+(::LieAlgebraModule{C})(::SRow{C}) where {C<:RingElement}
+(::LieAlgebraModule{C})(::LieAlgebraModuleElem{C}) where {C<:RingElement}
+(::LieAlgebraModule{C})(::Vector{T}) where {T<:LieAlgebraModuleElem{C}} where {C<:RingElement}
+```
+
+## 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,20 @@ 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 given by
+`struct_consts` and with basis element names `s`.
+
+* `struct_consts`: The entry with indices `[i,j][k]` is the 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 +138,55 @@ 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 given by
+`struct_consts` and with basis element names `s`.
+
+* `struct_consts`: The entry with indices `[i,j,k]` is the 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 +206,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 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(