some more docu for invariant theory

docs/src/InvariantTheory/it.md

@@ -12,38 +12,36 @@ Pages = ["it.md"]
 
 # Introduction
 
-Our basic setting in invariant theory 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$. We write $V^\ast$ for the dual vector space of $V$ and suppose that a fixed set of
-cooordinates $x = \{x_1, \dots, x_n\}\in V^*$ is chosen.
+The basic setting in this chapter 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$. Furthermore, $V^\ast$ denotes the dual vector space of $V$ and 
+$x = \{x_1, \dots, x_n\}\subset V^*$ denotes a fixed set of cooordinates.
 
+The action of $G$ on $V$ defines an action of  $G$ on the graded symmetric algebra
 
-The action of $G$ on $V$ induces an action of  $G$ on $V^\ast$: Set
+$K[x] = K[x_1, \dots, x_n] \cong K[V]:=S(V^*)=\bigoplus_{d\geq 0} S^d V^*$
 
-$(\pi f)(v)=f(\rho(\pi^{-1}) v).$
+by linear substitution: Identify $\text{GL}_n(K)\cong \text{GL}(V)$ and set
 
-This, in turn, defines an action of $G$ on the graded symmetric algebra
+$(\pi \;\!  .f) \;\! (x_1, \dots, x_n)  = f(\rho(\pi^{-1}) \cdot (x_1, \dots, x_n)^T) \text{ for all } \pi\in G.$
 
-$K[x] = K[x_1, \dots, x_n] \cong  K[V]=S(V^*)=\bigoplus_{d\geq 0} S^d V^*.$
 
 The *invariants* of $G$ are the fixed points of this action, its *ring of invariants* is the graded subalgebra
 
-$K[x]^G\cong K[V]^G=\{f\in K[V] \mid \pi f=f {\text { for any }} \pi\in G\}\subset K[V].$
+$K[x]^G = K[x_1, \dots, x_n]^G\cong  K[V]^G=\{f\in K[V] \mid \pi  \;\!  . f=f {\text { for any }} \pi\in G\}\subset K[V].$
 
-Clearly, this ring depends only on the image $\rho(G)\subset \text{GL}(V)$.
+Clearly, $K[V]^G$ depends only on the image $\rho(G)\subset \text{GL}(V)$.
 
 !!! note
-    If not mentioned otherwise, we will be in the favourable situation where $G$ is a linear reductive group which acts rationally on $V$. This has several important consequences:
-    - There exists a Reynolds operator $\mathcal R: K[V] \to K[V]$. That is, $\mathcal R$ is a $K$-linear graded map which projects $K[V]$ onto $K[V]^G$, and which is a $K[V]^G$-module homomorphism.
-    - By Hilbert's finiteness theorem, $K[V]^G$ is finitely generated as a $K$-algebra.
-    - By a result of Hochster and Roberts, $K[V]^G$ is Cohen-Macaulay. Equivalently, $K[V]^G$ is a free module (of finite rank) over any of its Noether normalizations.
+    If $K[V]^G$ is finitely generated as a $K$-algebra, then any minimal system of homogeneous generators is called a *fundamental system of invariants* of $K[V]^G$. By Nakayama's lemma, the number of elements in such a system is uniquely determined as the embedding dimension of $K[V]^G$. Similarly, the degrees of these elements are uniquely determined.
 
 !!! note
-    If $k[V]^G$ is finitely generated as a $K$-algebra, then any minimal system of homogeneous generators is called a *fundamental system of invariants* of $k[V]^G$. By Nakayama's lemma, the number of elements in such a system is uniquely determined as the embedding dimension of $K[V]^G$. Similarly, the degrees of these elements are uniquely determined.
+     If $K[V]^G$ is finitely generated as a $K$-algebra, then $K[V]^G$ admits a graded Noether normalization, that is, a Noether normalization $K[p_1, \dots, p_m] \subset K[V]^G$ with $p_1, \dots, p_m$ homogeneous. Given any such Noether normalization, $p_1, \dots, p_m$ is called a system of *primary invariants* of $K[V]^G$, and  any minimal system $s_0=1, s_1,\dots, s_l$ of homogeneous generators of $K[V]^G$ as a $K[p_1, \dots, p_m]$-module is called a system of *secondary invariants* of $K[V]^G$ with respect to $p_1, \dots, p_m$.
 
 !!! note
-    If $K[V]^G$ is finitely generated as a $K$-algebra, and $K[p_1, \dots, p_m] \subset K[V]^G$ is any Noether normalization, then $p_1, \dots, p_m$ is called a system of *primary invariants*. Given such a system $p_1, \dots, p_m$, we call any minimal system $s_0=1, s_1,\dots, s_l$ of homogeneous generators of $K[V]^G$ as a $K[p_1, \dots, p_m]$-module a system of *secondary invariants*.
-
+    In all situations considered in this chapter, theoretical results will guarantee that $K[V]^G$ is finitely generated as a $K$-algebra. In addition, if not mentioned otherwise, the following will hold:
+    - There exists a Reynolds operator $\mathcal R: K[V] \to K[V]$. That is, $\mathcal R$ is a $K$-linear graded map which projects $K[V]$ onto $K[V]^G$, and which is a $K[V]^G$-module homomorphism.
+    - The ring $K[V]^G$ is Cohen-Macaulay. Equivalently, $K[V]^G$ is a free module (of finite rank) over any of its graded Noether normalizations.
 
 The textbook
 

docs/src/InvariantTheory/it_fg.md

@@ -12,24 +12,73 @@ Pages = ["it_fg.md"]
 
 # Invariants of Finite Groups
 
-Using the notation from the introductory section, we now suppose that $\rho: G\to V$ is the representation
-of a *finite* group $G$ on $V$. Recall that we identify $K[V]\cong K[x] $ via a fixed set of cooordinates $x_1, \dots, x_n\in V^*$.
+In this section, with notation as in the introduction to this chapter, $G$ will always be a *finite* group.
 
 !!! note
-    - By Emmy Noether's finiteneness theorem, $K[V]^G$ is a finitely generated $K$-algebra of dimension $\dim K[V]^G = \dim K[V] = n$.
-    - If the group order $|G|$ is invertible in $K$, then $K[V]^G$ is Cohen-Macaulay. In fact, in this case, $G$ is a linearly reductive group with explicitly given Reynolds operator
+     - By a result of Emmy Noether, $K[V]$ is integral over $K[V]^G$. In particular,
 
-       $\mathcal R: K[V] \to K[V], f(x)\to \sum_{\pi\in G}(\pi f(x))$.
+          $\dim K[V]^G = \dim K[V] = n.$
+
+         Moreover, $K[V]^G$ is finitely generated as a $K$-algebra.
+
+    - If the group order $|G|$ is invertible in $K$, then we have the explicit Reynolds operator
+
+       $\mathcal R: K[V] \to K[V], f\to \frac{1}{|G|}\sum_{\pi\in G}(\pi \;\!  . f).$
 
 !!! note
     We speak of *non-modular* invariant theory if $|G|$ is invertible in $K$, and of *modular* invariant theory otherwise.
 
 !!! note
-    In the non-modular case, the Hilbert series of $K[V]^G$ is explicitly given as the Molien series of $G$, see [DK15](@cite) or [DJ98](@cite).
+    In the non-modular case, using  Emmy Noether's result and the Reynolds operator, it is not too difficult to show that $K[V]^G$ is a free module over any of its graded Noether normalizations. That is, $K[V]^G$ is Cohen-Macaulay.
+
+!!! note
+    In the non-modular case, the Hilbert series of $K[V]^G$ can be precomputed via Molien's theorem. See [DK15](@cite) or [DJ98](@cite) for explicit formulas.
+
+Having means to compute a $K$-basis for the invariants of each given degree, the algorithms for computing generators of invariant rings of finite groups proceed in two steps:
+
+- First, compute a system of primary invariants $p_1,\dots, p_n$.
+- Then, compute a system of secondary invariants with respect to $p_1,\dots, p_n$.
+
+In the non-modular case, the Molien series allows one to precompute the number of $K$-linearly independent invariants for each given degree,
+
+## Creating Invariant Rings
+
+The invariant theory module of OSCAR  distinguishes two ways of how  finite groups and their actions on $K[x_1, \dots, x_n]\cong K[V]$ are specified.
+
+### Matrix Groups
+
+Here, $G$ will be explicitly given as a matrix group $G\subset \text{GL}_n(K)\cong \text{GL}(V) $ by (finitely many) generating matrices, acting on $K[x_1, \dots, x_n]\cong K[V]$ by linear substitution:
+
+$(\pi \;\!  .f) \;\! (x_1, \dots, x_n)  = f(\pi^{-1} \cdot (x_1, \dots, x_n)^T) \text{ for all } \pi\in G.$
+
+
+```@docs
+invariant_ring(G::MatrixGroup)
+```
+
+### Permutation Groups
+
+
+## Basic Data Associated to Invariant Rings
+
+## The Reynolds Operator
+
+## Invariants of a Given Degree
+
+## The Molien Series
 
-The algorithms for computing generators of invariant rings of finite groups proceed in two steps. First, compute a system of primary invariants. Then, compute a corresponding system of secondary invariants.
 ## Primary Invariants
 
+```@docs
+primary_invariants(IR::InvRing)
+```
+
 ## Secondary Invariants
 
-## Invariant Rings and Fundamental Invariants
+```@docs
+secondary_invariants(IR::InvRing)
+```
+
+## Fundamental Systems of Invariants
+
+## Invariant Rings as Affine Algebras

docs/src/InvariantTheory/it_lrg.md

@@ -12,4 +12,43 @@ Pages = ["it_lrg.md"]
 
 # Invariants of Linearly Reductive Groups
 
-Omega-process, Derksen's algorithm
+In this section, with notation as in the introduction to this chapter, $G$ will always be a *linearly algebraic group* over an algebraically closed field $K$, and ``\rho: G \to \text{GL}(V)`` will be a *rational* representation of $G$. As in the previous sections, ``G`` will act on $K[x_1, \dots, x_n]\cong K[V]$ by linear substitution:
+
+$(\pi \;\!  .f) \;\! (x_1, \dots, x_n)  = f(\rho(\pi^{-1}) \cdot (x_1, \dots, x_n)^T) \text{ for all } \pi\in G.$
+
+!!! note
+
+    - By the very definition of linear reductivity, there is a Reynolds operator $\mathcal R: K[V] \to K[V]$. 
+    - By Hilbert's celebrated finiteness theorem, $K[V]^G$ is finitely generated as a $K$-algebra.
+    - By a result of Hochster and Roberts, $K[V]^G$ is Cohen-Macaulay. 
+
+## Creating Invariant Rings
+
+The invariant theory module of OSCAR handles linearly algebraic groups which are defined over an exact subfield $k$ of $K$ which is supported by OSCAR. That is:
+
+- ``G`` is  specified as an algebraic subgroup of $\text{GL}_t(K)$ by polynomial equations over $k$,  for some $t$.
+- ``\rho: G \to \text{GL}_n(K)\cong \text{GL}(V)`` is a *rational* representation of $G$ given by polynomials over $k$.
+
+!!! note
+    There are no exact means to handle algebraically closed fields on the computer. In the above setting, we do not deal with explicit elements of ``G``.
+
+
+## Basic Data Associated to Invariant Rings
+
+## The Reynolds Operator
+
+Omega-process
+
+## Generators of the Null-Cone
+
+## Generators of the Invariant Ring
+
+## Fundamental Systems of Invariants
+
+## Invariant Rings as Affine Algebras
+
+
+
+
+
+

src/InvariantTheory/invariant_rings.jl

@@ -1,3 +1,6 @@
+export invariant_ring, primary_invariants, secondary_invariants
+
+###############################################
 
 mutable struct InvRing{S, T, U, V, W, X}
    field::S
@@ -72,12 +75,48 @@ function invariant_ring(K::Field, M::Vector{<: MatrixElem})
   return invariant_ring(matrix_group([change_base_ring(K, g) for g in M]))
 end
 
+#######################################################
+
+@doc Markdown.doc"""
+    invariant_ring(G::MatrixGroup)
+
+Return the invariant ring of the finite matrix group `G`.
+
+CAVEAT: The creation of invariant rings is lazy in the sense that no explicit computations are done until specifically invoked (for example by the `primary_invariants` function).
+
+# Examples
+```jldoctest
+julia> K, a = CyclotomicField(3, "a")
+(Cyclotomic field of order 3, a)
+
+julia> M1 = matrix(K, [0 0 1; 1 0 0; 0 1 0])
+[0   0   1]
+[1   0   0]
+[0   1   0]
+
+julia> M2 = matrix(K, [1 0 0; 0 a 0; 0 0 -a-1])
+[1   0        0]
+[0   a        0]
+[0   0   -a - 1]
+
+julia> G = MatrixGroup(3, K, [ M1, M2 ])
+Matrix group of degree 3 over Cyclotomic field of order 3
+
+julia> IR = invariant_ring(G)
+Invariant ring of
+Matrix group of degree 3 over Cyclotomic field of order 3
+with generators
+AbstractAlgebra.Generic.MatSpaceElem{nf_elem}[[0 0 1; 1 0 0; 0 1 0], [1 0 0; 0 a 0; 0 0 -a-1]]
+```
+"""
 function invariant_ring(G::MatrixGroup)
   n = degree(G)
   action = mat_elem_type(typeof(G))[g.elm for g in gens(G)]
   return InvRing(base_ring(G), G, action)
 end
 
+#######################################################
+
 invariant_ring(matrices::MatrixElem{T}...) where {T} = invariant_ring(collect(matrices))
 
 function Base.show(io::IO, IR::InvRing)
@@ -124,6 +163,49 @@ function primary_invariants_via_singular(IR::InvRing)
    return IR.primary
 end
 
+#######################################################
+
+@doc Markdown.doc"""
+    primary_invariants(IR::InvRing)
+
+Return a system of primary invariants of `IR`.
+
+If a system of primary invariants of `IR` is already cached, return the cached system. 
+Otherwise, compute and cache such a system first.
+
+NOTE: The primary invariants are sorted by increasing degree.
+
+# Examples
+```jldoctest
+julia> K, a = CyclotomicField(3, "a")
+(Cyclotomic field of order 3, a)
+
+julia> M1 = matrix(K, [0 0 1; 1 0 0; 0 1 0])
+[0   0   1]
+[1   0   0]
+[0   1   0]
+
+julia> M2 = matrix(K, [1 0 0; 0 a 0; 0 0 -a-1])
+[1   0        0]
+[0   a        0]
+[0   0   -a - 1]
+
+julia> G = MatrixGroup(3, K, [ M1, M2 ])
+Matrix group of degree 3 over Cyclotomic field of order 3
+
+julia> IR = invariant_ring(G)
+Invariant ring of
+Matrix group of degree 3 over Cyclotomic field of order 3
+with generators
+AbstractAlgebra.Generic.MatSpaceElem{nf_elem}[[0 0 1; 1 0 0; 0 1 0], [1 0 0; 0 a 0; 0 0 -a-1]]
+
+julia> primary_invariants(IR)
+3-element Array{AbstractAlgebra.Generic.MPoly{nf_elem},1}:
+ x[1]*x[2]*x[3]
+ x[1]^3 + x[2]^3 + x[3]^3
+ x[1]^3*x[2]^3 + x[1]^3*x[3]^3 + x[2]^3*x[3]^3
+```
+"""    
 function primary_invariants(IR::InvRing)
    if !isdefined(IR, :primary)
       primary_invariants_via_singular(IR)
@@ -152,6 +234,49 @@ function secondary_invariants_via_singular(IR::InvRing)
    return IR.secondary
 end
 
+#######################################################
+
+@doc Markdown.doc"""
+    secondary_invariants(IR::InvRing)
+
+Return a system of secondary invariants of `IR` with respect to the currently cached system of primary invariants of `IR`
+(if no system of primary invariants of `IR` is cached, compute and cache such a system first).
+
+If a corresponding system of secondary invariants is already cached, return the cached system. 
+Otherwise, compute and cache such a system first.
+
+NOTE: The secondary invariants are sorted by increasing degree.
+
+# Examples
+```jldoctest
+julia> K, a = CyclotomicField(3, "a")
+(Cyclotomic field of order 3, a)
+
+julia> M1 = matrix(K, [0 0 1; 1 0 0; 0 1 0])
+[0   0   1]
+[1   0   0]
+[0   1   0]
+
+julia> M2 = matrix(K, [1 0 0; 0 a 0; 0 0 -a-1])
+[1   0        0]
+[0   a        0]
+[0   0   -a - 1]
+
+julia> G = MatrixGroup(3, K, [ M1, M2 ])
+Matrix group of degree 3 over Cyclotomic field of order 3
+
+julia> IR = invariant_ring(G)
+Invariant ring of
+Matrix group of degree 3 over Cyclotomic field of order 3
+with generators
+AbstractAlgebra.Generic.MatSpaceElem{nf_elem}[[0 0 1; 1 0 0; 0 1 0], [1 0 0; 0 a 0; 0 0 -a-1]]
+
+julia> secondary_invariants(IR)
+2-element Array{AbstractAlgebra.Generic.MPoly{nf_elem},1}:
+ 1
+ x[1]^6*x[3]^3 + x[1]^3*x[2]^6 + x[2]^3*x[3]^6
+```
+"""    
 function secondary_invariants(IR::InvRing)
    if !isdefined(IR, :secondary)
       secondary_invariants_via_singular(IR)