Add documentation

experimental/LieAlgebras/docs/doc.main

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

experimental/LieAlgebras/docs/src/ideals_and_subalgebras.md

@@ -0,0 +1,65 @@
+```@meta
+CurrentModule = Oscar
+DocTestSetup = quote
+  using Oscar
+end
+```
+
+# Ideals and Lie subalgebras
+
+Ideals and Lie subalgebras are represented by the types `LieAlgebraIdeal` and
+`LieSubalgebra` respectively.
+They are used similarly in most cases.
+
+## Functions
+
+### Ideals
+
+```@docs
+dim(::LieAlgebraIdeal)
+basis(::LieAlgebraIdeal)
+basis(::LieAlgebraIdeal, ::Int)
+Base.in(::LieAlgebraElem, ::LieAlgebraIdeal)
+bracket(::LieAlgebraIdeal{C,LieT}, ::LieAlgebraIdeal{C,LieT}) where {C<:RingElement,LieT<:LieAlgebraElem{C}}
+normalizer(::LieAlgebra, ::LieAlgebraIdeal)
+centralizer(::LieAlgebra, ::LieAlgebraIdeal)
+```
+
+### Lie subalgebras
+
+```@docs
+dim(::LieSubalgebra)
+basis(::LieSubalgebra)
+basis(::LieSubalgebra, ::Int)
+Base.in(::LieAlgebraElem, ::LieSubalgebra)
+bracket(::LieSubalgebra{C,LieT}, ::LieSubalgebra{C,LieT}) where {C<:RingElement,LieT<:LieAlgebraElem{C}}
+normalizer(::LieAlgebra, ::LieSubalgebra)
+centralizer(::LieAlgebra, ::LieSubalgebra)
+is_self_normalizing(S::LieSubalgebra)
+```
+
+## Constructors
+
+### Ideals
+
+```@docs
+ideal(::LieAlgebra, ::Vector; is_basis::Bool=false)
+ideal(::LieAlgebra{C}, ::LieAlgebraElem{C}) where {C<:RingElement}
+ideal(::LieAlgebra)
+```
+
+### Lie subalgebras
+
+```@docs
+sub(::LieAlgebra, ::Vector; is_basis::Bool=false)
+sub(::LieAlgebra{C}, ::LieAlgebraElem{C}) where {C<:RingElement}
+sub(::LieAlgebra)
+```
+
+## Conversions
+
+```@docs
+lie_algebra(::LieSubalgebra)
+lie_algebra(::LieAlgebraIdeal)
+sub(::LieAlgebra{C}, ::LieAlgebraIdeal{C}) where {C<:RingElement}
+```

experimental/LieAlgebras/docs/src/lie_algebras.md

@@ -59,6 +59,22 @@ 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.
 
+## Properties
+
+```@docs
+is_abelian(L::LieAlgebra)
+is_simple(L::LieAlgebra)
+```
+
+## More functions
+
+```@docs
+derived_algebra(L::LieAlgebra)
+center(L::LieAlgebra)
+centralizer(L::LieAlgebra, xs::AbstractVector{<:LieAlgebraElem})
+centralizer(L::LieAlgebra, x::LieAlgebraElem)
+```
+
 ## Lie algebra constructors
 
 ```@docs

experimental/LieAlgebras/src/LieAlgebra.jl

@@ -274,11 +274,21 @@ end
 #
 ###############################################################################
 
+@doc raw"""
+    derived_algebra(L::LieAlgebra) -> LieAlgebraIdeal
+
+Return the derived algebra of `L`, i.e. $[L, L]$.
+"""
 function derived_algebra(L::LieAlgebra)
   L_ideal = ideal(L)
   return bracket(L_ideal, L_ideal)
 end
 
+@doc raw"""
+    center(L::LieAlgebra) -> LieAlgebraIdeal
+
+Return the center of `L`, i.e. $\{x \in L \mid [x, L] = 0\}$
+"""
 function center(L::LieAlgebra)
   dim(L) == 0 && return ideal(L, [])
 
@@ -293,6 +303,11 @@ function center(L::LieAlgebra)
   return ideal(L, [L(c_basis[i, :]) for i in 1:c_dim]; is_basis=true)
 end
 
+@doc raw"""
+    centralizer(L::LieAlgebra, xs::AbstractVector{<:LieAlgebraElem}) -> LieSubalgebra
+
+Return the centralizer of `xs` in `L`, i.e. $\{y \in L \mid [x, y] = 0 \forall x \in xs\}$.
+"""
 function centralizer(L::LieAlgebra, xs::AbstractVector{<:LieAlgebraElem})
   @req all(x -> parent(x) == L, xs) "Incompatible Lie algebras."
 
@@ -307,6 +322,11 @@ function centralizer(L::LieAlgebra, xs::AbstractVector{<:LieAlgebraElem})
   return sub(L, [L(c_basis[i, :]) for i in 1:c_dim]; is_basis=true)
 end
 
+@doc raw"""
+    centralizer(L::LieAlgebra, x::LieAlgebraElem) -> LieSubalgebra
+
+Return the centralizer of `x` in `L`, i.e. $\{y \in L \mid [x, y] = 0\}$.
+"""
 function centralizer(L::LieAlgebra, x::LieAlgebraElem)
   return centralizer(L, [x])
 end
@@ -317,10 +337,23 @@ end
 #
 ###############################################################################
 
+@doc raw"""
+    is_abelian(L::LieAlgebra) -> Bool
+
+Return `true` if `L` is abelian, i.e. $[L, L] = 0$.
+"""
 function is_abelian(L::LieAlgebra)
   return all(iszero, x * y for (x, y) in combinations(basis(L), 2))
 end
 
+@doc raw"""
+    is_simple(L::LieAlgebra) -> Bool
+
+Return `true` if `L` is simple, i.e. `L` is not abelian and has no non-trivial ideals.
+
+!!! warning
+    This function is not implemented yet.
+"""
 function is_simple(L::LieAlgebra)
   is_abelian(L) && return false
   error("Not implemented.") # TODO
@@ -332,6 +365,11 @@ end
 #
 ###############################################################################
 
+@doc raw"""
+    universal_enveloping_algebra(L::LieAlgebra; ordering::Symbol=:lex) -> PBEAlgRing, Map
+
+Return the universal enveloping algebra of `L` with the given monomial ordering.
+"""
 function universal_enveloping_algebra(L::LieAlgebra; ordering::Symbol=:lex)
   R, gensR = polynomial_ring(coefficient_ring(L), symbols(L))
   n = dim(L)
@@ -345,9 +383,11 @@ function universal_enveloping_algebra(L::LieAlgebra; ordering::Symbol=:lex)
   ])
   U, gensU = pbw_algebra(R, rel, monomial_ordering(R, ordering); check=true)
 
-  L_to_U = function (x::LieAlgebraElem)
-    sum(c * g for (c, g) in zip(coefficients(x), gensU); init=zero(U))
-  end
+  L_to_U = MapFromFunc(
+    L, U, function (x::LieAlgebraElem)
+      sum(c * g for (c, g) in zip(coefficients(x), gensU); init=zero(U))
+    end
+  )
   return U, L_to_U
 end
 

experimental/LieAlgebras/src/LieAlgebraIdeal.jl

@@ -56,6 +56,10 @@ function gens(I::LieAlgebraIdeal)
   return I.gens
 end
 
+function gen(I::LieAlgebraIdeal, i::Int)
+  return I.gens[i]
+end
+
 function ngens(I::LieAlgebraIdeal)
   return length(gens(I))
 end
@@ -66,10 +70,29 @@ function basis_matrix(
   return I.basis_matrix::dense_matrix_type(C)
 end
 
+@doc raw"""
+    basis(I::LieAlgebraIdeal) -> Vector{LieAlgebraElem}
+
+Return the basis of the ideal `I`.
+"""
 function basis(I::LieAlgebraIdeal)
   return I.basis_elems
 end
 
+@doc raw"""
+    basis(I::LieAlgebraIdeal, i::Int) -> LieAlgebraElem
+
+Return the `i`-th basis element of the ideal `I`.
+"""
+function basis(I::LieAlgebraIdeal, i::Int)
+  return I.basis_elems[i]
+end
+
+@doc raw"""
+    dim(I::LieAlgebraIdeal) -> Int
+
+Return the dimension of the ideal `I`.
+"""
 dim(I::LieAlgebraIdeal) = length(basis(I))
 
 ###############################################################################
@@ -134,6 +157,11 @@ end
 #
 ###############################################################################
 
+@doc raw"""
+    in(x::LieAlgebraElem, I::LieAlgebraIdeal) -> Bool
+
+Return `true` if `x` is in the ideal `I`, `false` otherwise.
+"""
 function Base.in(x::LieAlgebraElem, I::LieAlgebraIdeal)
   return can_solve(basis_matrix(I), _matrix(x); side=:left)
 end
@@ -151,6 +179,11 @@ function Base.:+(
   return ideal(base_lie_algebra(I1), [gens(I1); gens(I2)])
 end
 
+@doc raw"""
+    bracket(I1::LieAlgebraIdeal, I2::LieAlgebraIdeal) -> LieAlgebraIdeal
+
+Return $[I_1,I_2]$.
+"""
 function bracket(
   I1::LieAlgebraIdeal{C,LieT}, I2::LieAlgebraIdeal{C,LieT}
 ) where {C<:RingElement,LieT<:LieAlgebraElem{C}}
@@ -164,11 +197,20 @@ end
 #
 ###############################################################################
 
+@doc raw"""
+    normalizer(L::LieAlgebra, I::LieAlgebraIdeal) -> LieSubalgebra
+
+Return the normalizer of `I` in `L`, i.e. $\{x \in L \mid [x, I] \subseteq I\} = L$.
+"""
 function normalizer(L::LieAlgebra, I::LieAlgebraIdeal)
-  @req parent(I) == L "Incompatible Lie algebras."
-  return normalizer(L, sub(L, I))
+  return sub(L)
 end
 
+@doc raw"""
+    centralizer(L::LieAlgebra, I::LieAlgebraIdeal) -> LieSubalgebra
+  
+Return the centralizer of `I` in `L`, i.e. $\{x \in L \mid [x, I] = 0\}$.
+"""
 function centralizer(L::LieAlgebra, I::LieAlgebraIdeal)
   return centralizer(L, basis(I))
 end
@@ -179,12 +221,20 @@ end
 #
 ###############################################################################
 
-function lie_algebra(
-  I::LieAlgebraIdeal{C,LieT}
-) where {C<:RingElement,LieT<:LieAlgebraElem{C}}
+@doc raw"""
+    lie_algebra(I::LieAlgebraIdeal) -> LieAlgebra
+
+Return `I` as a Lie algebra.
+"""
+function lie_algebra(I::LieAlgebraIdeal)
   return lie_algebra(basis(I))
 end
 
+@doc raw"""
+    sub(L::LieAlgebra, I::LieAlgebraIdeal) -> LieSubalgebra
+
+Return `I` as a subalgebra of `L`.
+"""
 function sub(L::LieAlgebra{C}, I::LieAlgebraIdeal{C}) where {C<:RingElement}
   @req base_lie_algebra(I) === L "Incompatible Lie algebras."
   return sub(L, basis(I); is_basis=true)
@@ -196,14 +246,30 @@ end
 #
 ###############################################################################
 
+@doc raw"""
+    ideal(L::LieAlgebra, gens::Vector{LieAlgebraElem}; is_basis::Bool=false) -> LieAlgebraIdeal
+
+Return the smallest ideal of `L` containing `gens`.
+If `is_basis` is `true`, then `gens` is assumed to be a basis of the ideal.
+"""
 function ideal(L::LieAlgebra, gens::Vector; is_basis::Bool=false)
   return LieAlgebraIdeal{elem_type(coefficient_ring(L)),elem_type(L)}(L, gens; is_basis)
 end
 
+@doc raw"""
+    ideal(L::LieAlgebra, gen::LieAlgebraElem) -> LieAlgebraIdeal
+
+Return the smallest ideal of `L` containing `gen`.
+"""
 function ideal(L::LieAlgebra{C}, gen::LieAlgebraElem{C}) where {C<:RingElement}
   return ideal(L, [gen])
 end
 
+@doc raw"""
+    ideal(L::LieAlgebra) -> LieAlgebraIdeal
+
+Return `L` as an ideal of itself.
+"""
 function ideal(L::LieAlgebra)
   return ideal(L, basis(L); is_basis=true)
 end