Docu invariants tori (#3428)

* Add test example to PR #3412 as requested by @thofma

* docu invariants tori

* readd algebraic.md

* typo

* Update docs/doc.main

* add one more functions and corrections

* correction

* correction

* addressing review

* forgot to add corrected file

---------

Co-authored-by: Lars Göttgens <[email protected]>

docs/doc.main

@@ -57,7 +57,7 @@
         "Nemo/qadic.md",
      ],
      "Nemo/finitefield.md",
-     "Nemo/algebraic.md", 
+     "Nemo/algebraic.md",
      "Fields/algebraic_closure_fp.md",
   ],
 
@@ -153,6 +153,7 @@
   "Invariant Theory" => [
      "InvariantTheory/intro.md",
      "InvariantTheory/finite_groups.md",
+     "InvariantTheory/tori.md",
      "InvariantTheory/reductive_groups.md",
   ],
 

docs/src/InvariantTheory/finite_groups.md

@@ -41,7 +41,7 @@ We discuss the relevant OSCAR functionality below.
 
 ## Creating Invariant Rings
 
-### How Groups are Given
+### How Finite Groups are Given
 
 The invariant theory part of OSCAR  distinguishes two ways of how  finite groups and their actions on $K[x_1, \dots, x_n]\cong K[V]$ are specified:
 

docs/src/InvariantTheory/intro.md

@@ -9,11 +9,11 @@ of group actions, focusing on finite and linearly reductive groups, respectively
 
 The basic setting in this context consists of a group $G$, a field $K$, a vector space
 $V$ over $K$ of finite dimension $n,$ and  a representation $\rho: G \to \text{GL}(V)$ of $G$ on $V$.
-The induced action on the dual vector space $V^\ast$,
+The induced right action on the dual vector space $V^\ast$,
 
 $V^\ast  \times G \to V^\ast, (f, \pi)\mapsto f \;\!   . \;\! \pi  := f\circ \rho(\pi),$
 
-extends to an action of $G$ on the graded symmetric algebra
+extends to a right action of $G$ on the graded symmetric algebra
 
 $K[V]:=S(V^*)=\bigoplus_{d\geq 0} S^d V^*$
 
@@ -23,12 +23,11 @@ The *invariants* of $G$ are the fixed points of this action, its *invariant ring
 
 $K[V]^G:=\{f\in K[V] \mid f \;\!   . \;\! \pi =f {\text { for any }} \pi\in G\} \subset K[V].$
 
-Explicitly, the choice of a basis of $V$ and its dual basis, say, $\{x_1, \dots, x_n\}$ of $V^*$
-gives rise to isomorphisms $\text{GL}(V) \cong \text{GL}_n(K)$ and $K[V]\cong  K[x_1, \dots, x_n]$.
-After identifying $\text{GL}(V)$ with $\text{GL}_n(K)$ and $K[V]$ with $K[x_1, \dots, x_n]$ by means of
-these isomorphisms, the action of $G$ on $K[V]$ is given as follows:
+Explicitly, fixing a basis of $V$ and its dual basis, say, $\{x_1, \dots, x_n\}$ of $V^*$,
+we may identify $\GL(V) \cong \GL_n(K)$ and $K[V]\cong  K[x_1, \dots, x_n]$.
+Then the action of an element $\pi \in G$ with $\rho(\pi) = (a_{i, j})$ on a polynomial $f\in K[x_1,\dots, x_n]$ is given as follows:
 
-$(f \;\!   . \;\! \pi)  (x_1, \dots, x_n)  = f((x_1, \dots, x_n) \cdot \rho(\pi)).$
+$(f \;\!   . \;\! \pi)  (x_1, \dots, x_n) = f\bigl(\sum_j a_{1, j}x_j, \dots, \sum_j a_{n, j}x_j\bigr).$
 
 Accordingly, $K[V]^G$ may be regarded as a graded subalgebra of $K[x_1, \dots, x_n]$:
 

docs/src/InvariantTheory/tori.md

@@ -0,0 +1,52 @@
+```@meta
+CurrentModule = Oscar
+```
+
+# Invariants of Tori
+In this section, with notation as in the introduction to this chapter, $T =(K^{\ast})^m$ will be a torus of rank $m$
+over a field $K$. To compute invariants of diagonal torus actions, OSCAR makes use of Algorithm 4.3.1  in [DK15](@cite) which,
+in particular, relies on algorithmic means from polyhedral geometry.
+
+## Creating Invariant Rings
+
+### How Tori  and Their Representations are Given
+
+```@docs
+ torus_group(F::Field, n::Int)
+```
+
+```@docs
+rank(T::TorusGroup)
+```
+
+```@docs
+field(T::TorusGroup)
+```
+
+```@docs
+representation_from_weights(T::TorusGroup, W::Union{ZZMatrix, Matrix{<:Integer}, Vector{<:Int}})
+```
+
+```@docs
+group(r::RepresentationTorusGroup)
+```
+
+### Constructor for Invariant Rings
+
+```@docs
+invariant_ring(r::RepresentationTorusGroup)
+```
+
+
+## Fundamental Systems of Invariants
+
+```@docs
+fundamental_invariants(RT::TorGrpInvRing)
+```
+
+
+## Invariant Rings as Affine Algebras
+
+```@docs
+affine_algebra(RT::TorGrpInvRing)
+```