Starting manual for groups

Project.toml

@@ -11,6 +11,7 @@ version = "0.3.0"
 
 [deps]
 AbstractAlgebra = "c3fe647b-3220-5bb0-a1ea-a7954cac585d"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 GAP = "c863536a-3901-11e9-33e7-d5cd0df7b904"
 Hecke = "3e1990a7-5d81-5526-99ce-9ba3ff248f21"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"

docs/src/Groups/groups.md

@@ -13,7 +13,7 @@ Pages = ["groups.md"]
 # Groups
 
 
-Julia supports the following types of groups:
+Oscar supports the following types of groups:
 
 * `PermGroup` = groups of permutations
 * `MatrixGroup` = groups of matrices
@@ -22,6 +22,96 @@ Julia supports the following types of groups:
 * `DirectProductOfGroups` = direct product of two groups
 * `AutomorphismGroup` = group of automorphisms over a group
 
-## Permutations groups
 
-In Julia, permutations are displayed as products of disjoint cycles, as in GAP.
+## Subgroups
+
+The subgroup of a group `G` generated by the elements `x,y,...` are defined by the following instruction:
+
+* `sub(G, [x,y,...])` ;
+* `sub(x,y,...)`.
+
+This function returns two objects: a group `H`, that is the subgroup of `G` generated by the elements `x,y,...`, and the embedding homomorphism of `H` into `G`. The object `H` has the same type of `G`, and it has no memory of the "parent" group `G`: it is an independent group.
+```@repl oscar
+G = symmetric_group(4);
+H = sub(G,[cperm([1,2,3]),cperm([2,3,4])]);
+H[1] == alternating_group(4)
+```
+
+
+## Permutation groups
+
+Permutation groups can be defined as symmetric groups, alternating groups or their subgroups.
+```@repl oscar
+degree(symmetric_group(4))
+```
+
+```@repl oscar
+symmetric_group(4)
+alternating_group(4)
+```
+
+Every permutation group `G` is identified by a degree, that corresponds ideally to the size of the set on which `G` is acting.
+
+!!! note
+    The degree of a group of permutations is not necessarily the highest moved point of the group `G`. For example, if `G` is defined as a   subgroup of `Sym(n)`, its degree is `n` even if every element of `G` fixes `n`.
+
+### Permutations
+
+Permutations in Oscar are displayed as products of disjoint cycles, as in GAP. A permutation can be defined in different ways.
+
+* `perm(L)`: here, `L` is a vector ``[a_1, ... , a_n]`` containing one time each number from ``1`` to ``n`` for a certain positive integer ``n``. The output is the permutation over the set ``\{1, ... , n\}`` sending ``i`` into ``a_i`` for every ``i``. Example:
+```@repl oscar
+perm([2,4,6,1,3,5])
+```
+
+
+* `cperm(L1,L2,...)`: here, the `L1`, `L2`, etc. are vectors of integers. Each vector is read as a cycle (e.g. the vector ``[1,2,3]`` corresponds to the cycle ``(1,2,3)``) and the output is the product of all the cycles. Each of these vectors need to contain all different numbers, but at the moment they are not required to be disjoint. Example:
+```@repl oscar
+cperm([1,2,3],[4,5,6])
+cperm([1,2],[2,3])
+```
+
+Every permutation has always a permutation group as a parent. If a permutation is defined as above, the default parent is `Sym(n)`, where `n` is the highest moved point. It is possible to set another parent group for `perm` and `cperm` by adding the group at the begin of the list of arguments.
+```@repl oscar
+G = symmetric_group(5);
+x = cperm([1,2]);
+y = cperm(G,[1,2]);
+parent(x)
+parent(y)
+```
+Here, `x` and `y` belongs to different groups, although they are displayed in the same way.
+
+Of course, the function `cperm(G,L)` returns an error if the degree of the group `G` is lower than the highest moved point of `L`.
+
+If `G` is a group and `x` is a permutation, it is possible to set `G` as parent of `x` simply typing `G(x)`. This returns the permutation `x` as element of `G` (or ERROR if `x` does not embed into `G`).
+```@repl oscar
+G=symmetric_group(5);
+x=cperm([1,2,3]);
+y=G(x);
+parent(x)
+parent(y)
+```
+
+The function `listperm` works in the opposite way with respect to `perm`: given a permutation `x`, it returns the vector `[x(1), ... , x(n)]`, where `n` is the degree of `parent(x)`. In the example above, we would get
+```@repl oscar
+(x,y) = (cperm([1,2,3]), cperm(symmetric_group(5),[1,2,3])) # hide
+listperm(x)
+listperm(y)
+```
+
+
+#### Permutations as functions
+A permutation can be viewed as a function on the set `{1,...,n}`, hence it can be evaluated on integers.
+```@repl oscar
+x = cperm([1,2,3,4,5]);
+x(2)
+```
+This works also if the argument is not in the range `1:n`; in such a case, the output coincides with the input.
+
+!!! note
+    The multiplication between permutations works from the left to the right. So, if `x` and `y` are permutations and `n` is an integer, then `(x*y)(n) = (y(x(n))`, NOT `x(y(n))`.
+
+
+
+
+