-*
   Copyright 2020, Luigi Ferraro, Federico Galetto,
   Francesca Gandini, Hang Huang, Matthew Mastroeni, Xianglong Ni.

   You may redistribute this file under the terms of the GNU General Public
   License as published by the Free Software Foundation, either version 2 of
   the License, or any later version.
*-


document {
	Key => {finiteAction, 
	    (finiteAction, List, PolynomialRing),
	    (finiteAction, Matrix, PolynomialRing),
	    },
	
	Headline => "the group action generated by a list of matrices",
	
	Usage => "finiteAction(L, R), finiteAction(M, R)",
	Inputs => {
	    	"L" => List => {"of matrices representing the generators of a finite group"},
		"M" => Matrix => {"generating a finite cyclic group of matrices"},
		"R" => PolynomialRing => {"on which the group elements 
		    act by linear changes of coordinates"}
		},
	Outputs => {
		FiniteGroupAction => {"the action of the (finite) matrix group generated by 
		    the input matrices on the given polynomial ring"}
		},
	
	"This function is provided by the package ", TO InvariantRing,".",
	
	PARA {
	    "The following example defines the permutation action of
	    a symmetric group on three elements."
	    },
	
	EXAMPLE {
	    	"R = QQ[x_1..x_3]",
		"L = apply(2, i -> permutationMatrix(3, [i + 1, i + 2] ) )",
		"S3 = finiteAction(L, R)",
		},
	
	PARA {
	    "On the other hand, the action below corresponds to a cyclic permutation 
	    of the variables."
	    },
	
	EXAMPLE {
		"P = permutationMatrix toString 231",
		"C3 = finiteAction(P, R)",
		},    
	    }

document {
	Key => {FiniteGroupAction},
	
	Headline => "the class of all finite group actions",
	
	"This class is provided by the package ", TO InvariantRing,".",
	
	PARA {
	    	TT "FiniteGroupAction", " is the class of all finite
		matrix group actions on polynomial rings for the
		purpose of computing invariants.
		It is created using ", TO "finiteAction", ". ",
		"Note that diagonal actions of finite abelian
		groups can be created with the class ",
		TO "DiagonalAction", " which implements more
		efficient methods for computing invariants."
	    },
	}

document {
	Key => {(generators, FiniteGroupAction)},
	Headline => "generators of a finite group",
	Usage => "generators G",
	Inputs => {
	    	"G" => FiniteGroupAction =>
		{"the action of a finite group"},
		},
	Outputs => {
		List => {"a list of generators of the group"}
		},
	"This function is provided by the package ", TO InvariantRing,". ",

    	PARA {
	    "Use this function to get the user-defined
	    generators of a group action."
	},
    
    	PARA { "The following example defines the permutation action
	    of a symmetric group on three elements using three
	    transpositions."  },
	
	EXAMPLE {
	    "R = QQ[x_1..x_3]",
	    "L = {matrix {{0,1,0},{1,0,0},{0,0,1}}, matrix {{0,0,1},{0,1,0},{1,0,0}}, matrix {{1,0,0},{0,0,1},{0,1,0}} }",
	    "G = finiteAction(L, R)",
	    "generators G"
	    },
	    
	    }

document {
	Key => {group, (group, FiniteGroupAction)},
	
	Headline => "list all elements of the group of a finite group action",
	
	Usage => "group G",
	Inputs => {
	    	"G" => FiniteGroupAction
		},
	Outputs => {
		List => {"of all elements in the finite matrix group associated to
		    the given group action"}
		},
	
	"This function is provided by the package ", TO InvariantRing,".",
	
	PARA {
	    "The following example defines the permutation action of
	    a symmetric group on three elements."
	    },
	
	EXAMPLE {
	    	"R = QQ[x_1..x_3]",
		"L = apply(2, i -> permutationMatrix(3, [i + 1, i + 2] ) )",
		"S3 = finiteAction(L, R)",
		"group S3"
		},
	PARA {
	    "The computation of all elements in the group is actually performed by the method ", 
	    TO schreierGraph, " since the process of computing the Schreier graph of the group
	    yields other useful information about the group besides just its elements."
	    },
	
	SeeAlso => {schreierGraph, words}
	    }

document {
	Key => {isAbelian, (isAbelian, FiniteGroupAction)},

	Headline => "check whether a finite matrix group is Abelian",
	
	Usage => "isAbelian G",
	
	Inputs => {
	    	"G" => FiniteGroupAction
		},
	    
	Outputs => {
		Boolean => "whether the group associated to the action is Abelian"
		},
	    
	"This function is provided by the package ", TO InvariantRing,". ",

	PARA {
	    "The following example defines the action of
	    a symmetric group permuting the three variables generating
	    a polynomial ring."
	    },
    	
	EXAMPLE {
	    "R = QQ[x_1..x_4]",
	    "P = apply(3, i -> permutationMatrix(4, [i + 1, i + 2] ) )",
	    "S4 = finiteAction(P, R)",
	    "isAbelian S4",
	    },
	    	    
	PARA {
	    "The following example defines the action of
	    the product of two cyclic groups. One group has order 3
	    and cyclically permutes the three variables generating
	    a polynomial ring. The other group has order 2 and
	    multiplies the variables by -1."
	    },
	
	EXAMPLE {
	    	"R = QQ[x_1..x_3]",
		"L = {matrix {{0,0,1},{0,1,0},{1,0,0}}, matrix {{-1,0,0},{0,-1,0},{0,0,-1}} }",
		"G = finiteAction(L, R)",
		"isAbelian G"
		},
	    }

document {
	Key => {(numgens, FiniteGroupAction)},
	Headline => "number of generators of a finite group",
	Usage => "numgens G",
	Inputs => {
	    	"G" => FiniteGroupAction =>
		{"the action of a finite group"},
		},
	Outputs => {
		ZZ => {"the number of generators of the group"}
		},
	"This function is provided by the package ", TO InvariantRing,". ",

    	PARA {
	    "Use this function to get the number of user-defined
	    generators of a group action."
	},
    
    	PARA { "The following example defines the permutation action
	    of a symmetric group on three elements using three
	    transpositions."  },
	
	EXAMPLE {
	    "R = QQ[x_1..x_3]",
	    "L = {matrix {{0,1,0},{1,0,0},{0,0,1}}, matrix {{0,0,1},{0,1,0},{1,0,0}}, matrix {{1,0,0},{0,0,1},{0,1,0}} }",
	    "G = finiteAction(L, R)",
	    "numgens G"
	    },
	
	Caveat => {"The integer returned by this function is not
	    necessarily the minimal number of generators of the
	    group, rather it is the cardinality of the generating
	    set defined by the user."}
	    
	    }

document {
	Key => {schreierGraph, (schreierGraph, FiniteGroupAction)},
	
	Headline => "Schreier graph of a finite group",
	
	Usage => "schreierGraph G",
	Inputs => {
	    	"G" => FiniteGroupAction => {"a finite group action"},
		},
	Outputs => {
		HashTable => {"representing the Schreier graph of the group"}
		},
	
	"This function is provided by the package ", TO InvariantRing,".",
	
	PARA {
	    "For a finite group action, we form a ", TO "HashTable",
	    " whose keys are the generators provided
	    by the user. The value corresponding to a generator ",
	    TT "g", " is a ", TO "HashTable", " containing all pairs ",
	    TT "a => b", " such that ", TT "a*g == b",
	    ". This represents the Schreier graph of the group
	    relative to the generating set provided by the user."
	    },
	
	PARA {
	    "The following example defines the permutation action of
	    a symmetric group on three elements using only two
	    generators, a transposition and a 3-cycle."
	    },
	
	EXAMPLE {
	    	"R = QQ[x_1..x_3]",
		"L = {matrix {{0,1,0},{1,0,0},{0,0,1}}, matrix {{0,0,1},{0,1,0},{1,0,0}} }",
		"G = finiteAction(L, R)",
		"schreierGraph G"
		},
	    }

document {
	Key => {words, (words, FiniteGroupAction)},
	
	Headline => "associate a word in the generators of a group to each element",
	
	Usage => "words G",
	Inputs => {
	    	"G" => FiniteGroupAction
		},
	Outputs => {
		HashTable => {"associating to each element in the group of the action
		    a word of minimal length in (the indices of) the generators of the group"}
		},
	
	"This function is provided by the package ", TO InvariantRing,".",
	
	PARA {
	    "The following example computes, for each permutation in the symmetric group
	    on three elements, a word of minimal length in the Coxeter generators."
	    },
	
	EXAMPLE {
	    	"R = QQ[x_1..x_3]",
		"L = apply(2, i -> permutationMatrix(3, [i + 1, i + 2] ) )",
		"S3 = finiteAction(L, R)",
		"words S3"
		},
	PARA {
	    "The computation of the words addressing each element in the group is actually 
	    performed by the method ", TO schreierGraph, " since the process of computing 
	    the Schreier graph of the group yields other useful information about the group."
	    },
	
	SeeAlso => {group, schreierGraph}
	    }
	
	
document {
	Key => {permutationMatrix, 
	    (permutationMatrix, String),
	    (permutationMatrix, ZZ, Array),
	    (permutationMatrix, ZZ, List),
	    (permutationMatrix, Array),
	    (permutationMatrix, List)
	    },
	
	Headline => "convert a one-line notation or cyclic notation of a permutation to a matrix representation",
	
	Usage => "permutationMatrix s, permutationMatrix(n , c)",
	Inputs => {
	    	"s" => String =>  {"an array or a list of arrays giving a one-line notation or cyclic notation of a permutation"},
		"n" => ZZ => {"giving the number of integers getting permuted"},
		"c" => List => {"of arrays giving a cyclic notation of a permutation"}
		},
	Outputs => {
		Matrix => {"the matrix representation of the permutation"}
		},
	
	"This function is provided by the package ", TO InvariantRing,".",
	
	PARA {
	    "The following example converts the one-line notation of a transposition into a matrix representation. "
	    },
	
	EXAMPLE {
		"M = permutationMatrix toString 213",
		},
	
	PARA {
	    "The following example converts the cyclic notation of the same transposition into a matrix representation. Without ",TT "n"," the function assumes ",TT "n"," is the largest integer that appears in your array or list of arrays."
	    },
	
	EXAMPLE {
		"M = permutationMatrix(3,[1,2])",
		"M = permutationMatrix [1,2]",
		},
	PARA {
	    "The following example converts the cyclic notation of a permutation of 4 into a matrix representation."
	    },    
	EXAMPLE {
	    	"M = permutationMatrix(4,{[1,2],[3,4]})",
		"M = permutationMatrix {[1,2],[3,4]}",
	    },
	    }
document {
	Key => {(relations, FiniteGroupAction)},
	Headline => "relations of a finite group",
	Usage => "relations G",
	Inputs => {
	    	"G" => FiniteGroupAction =>
		{"the action of a finite group"},
		},
	Outputs => {
		List => {"a list of relations of the group"}
		},
	"This function is provided by the package ", TO InvariantRing,". ",

    	PARA {
	    "Use this function to get the relations among elements of a group. Each element is represented by a word of minimal length in the Coxeter generators. And each relation is represented by a list of two words that equates the group element represented by those two words."
	},
    
    	PARA { "The following example defines the permutation action
	    of a symmetric group on three elements using three
	    transpositions."  },
	
	EXAMPLE {
	    "R = QQ[x_1..x_3]",
	    "L = {matrix {{0,1,0},{1,0,0},{0,0,1}}, matrix {{0,0,1},{0,1,0},{1,0,0}}, matrix {{1,0,0},{0,0,1},{0,1,0}} }",
	    "G = finiteAction(L, R)",
	    "relations G"
	    },
	
	SeeAlso => {group, schreierGraph, words}
	    
	    }
