#############################################################################
##
#W primitiv.gd GAP group library Heiko Theißen
#W Alexander Hulpke
#W Colva Roney-Dougal
##
##
##
##
## <#GAPDoc Label="[1]{primitiv}">
## &GAP; contains a library of primitive permutation groups which includes,
## up to permutation isomorphism (i.e., up to conjugacy in the corresponding
## symmetric group),
## all primitive permutation groups of degree <M>< 4096</M>,
## calculated in <Cite Key="RoneyDougal05"/> and <Cite Key="CRDQ11"/>,
## in particular,
## <List>
## <Item>
## the primitive permutation groups up to degree 50,
## calculated by C. Sims,
## </Item>
## <Item>
## the primitive groups with insoluble socles of degree
## <M>< 1000</M> as calculated in <Cite Key="DixonMortimer88"/>,
## </Item>
## <Item>
## the solvable (hence affine) primitive permutation groups of degree
## <M>< 256</M> as calculated by M. Short <Cite Key="Sho92"/>,
## </Item>
## <Item>
## some insolvable affine primitive permutation groups of degree
## <M>< 256</M> as calculated in <Cite Key="Theissen97"/>.
## </Item>
## <Item>
## The solvable primitive groups of degree up to <M>999</M> as calculated
## in <Cite Key="EickHoefling02"/>.
## </Item>
## <Item>
## The primitive groups of affine type of degree up to <M>999</M> as
## calculated in <Cite Key="RoneyDougal02"/>.
## </Item>
## </List>
## <P/>
## Not all groups are named, those which do have names use ATLAS notation.
## Not all names are necessarily unique!
## <P/>
## The list given in <Cite Key="RoneyDougal05"/> is believed to be complete,
## correcting various omissions in <Cite Key="DixonMortimer88"/>,
## <Cite Key="Sho92"/> and <Cite Key="Theissen97"/>.
## <P/>
## In detail, we guarantee the following properties for this and further
## versions (but <E>not</E> versions which came before &GAP; 4.2)
## of the library:
## <P/>
## <List>
## <Item>
## All groups in the library are primitive permutation groups
## of the indicated degree.
## </Item>
## <Item>
## The positions of the groups in the library are stable.
## That is <C>PrimitiveGroup(<A>n</A>,<A>nr</A>)</C> will always give you
## a permutation isomorphic group.
## Note however that we do not guarantee to keep the chosen
## <M>S_n</M>-representative, the generating set or the name for eternity.
## </Item>
## <Item>
## Different groups in the library are not conjugate in <M>S_n</M>.
## </Item>
## <Item>
## If a group in the library has a primitive subgroup with the same socle,
## this group is in the library as well.
## </Item>
## </List>
## <P/>
## (Note that the arrangement of groups is not guaranteed to be in
## increasing size, though it holds for many degrees.)
## <#/GAPDoc>
#############################################################################
##
#F PrimitiveGroup(<deg>,<nr>)
##
## <#GAPDoc Label="PrimitiveGroup">
## <ManSection>
## <Func Name="PrimitiveGroup" Arg='deg,nr'/>
##
## <Description>
## returns the primitive permutation group of degree <A>deg</A> with number <A>nr</A>
## from the list.
## <P/>
## The arrangement of the groups of degrees not greater than 50
## differs from the arrangement of primitive
## groups in the list of C. Sims, which was used in &GAP; 3. See
## <Ref Func="SimsNo"/>.
## </Description>
## </ManSection>
## <#/GAPDoc>
##
UNBIND_GLOBAL("PrimitiveGroup");
DeclareGlobalFunction( "PrimitiveGroup" );
#############################################################################
##
#F PrimitiveGroupsAvailable(<deg>)
##
## <#GAPDoc Label="PrimitiveGroupsAvailable">
## <ManSection>
## <Func Name="PrimitiveGroupsAvailable" Arg='deg'/>
##
## <Description>
## To offer a clearer interface to the primitive groups library, this
## function checks whether the primitive groups of degree <A>deg</A> are
## available.
## </Description>
## </ManSection>
## <#/GAPDoc>
##
if IsBoundGlobal("PrimitiveGroupsAvailable") then
# redefine the dummy function from the library
MakeReadWriteGlobal("PrimitiveGroupsAvailable");
Unbind(PrimitiveGroupsAvailable);
fi;
DeclareGlobalFunction("PrimitiveGroupsAvailable");
#############################################################################
##
#F NrPrimitiveGroups(<deg>)
##
## <#GAPDoc Label="NrPrimitiveGroups">
## <ManSection>
## <Func Name="NrPrimitiveGroups" Arg='deg'/>
##
## <Description>
## returns the number of primitive permutation groups of degree <A>deg</A> in the
## library.
## <Example><![CDATA[
## gap> NrPrimitiveGroups(25);
## 28
## gap> PrimitiveGroup(25,19);
## 5^2:((Q(8):3)'4)
## gap> PrimitiveGroup(25,20);
## ASL(2, 5)
## gap> PrimitiveGroup(25,22);
## AGL(2, 5)
## gap> PrimitiveGroup(25,23);
## (A(5) x A(5)):2
## ]]></Example>
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareGlobalFunction( "NrPrimitiveGroups" );
## <#GAPDoc Label="[2]{primitiv}">
## The selection functions (see <Ref BookName="ref" Sect="Selection Functions"/>) for
## the primitive groups library are <C>AllPrimitiveGroups</C> and
## <C>OnePrimitiveGroup</C>.
## They obtain the following properties from the database without having to
## compute them anew:
## <P/>
## <Ref BookName="ref" Attr="NrMovedPoints" Label="for a list or collection of permutations
"/>,
## <Ref BookName="ref" Attr="Size"/>,
## <Ref BookName="ref" Attr="Transitivity" Label="for a group and an action domain"/>,
## <Ref BookName="ref" Attr="ONanScottType"/>,
## <Ref BookName="ref" Prop="IsSimpleGroup"/>,
## <Ref BookName="ref" Prop="IsSolvableGroup"/>,
## and <Ref BookName="ref" Attr="SocleTypePrimitiveGroup"/>.
## <P/>
## (Note, that for groups of degree up to 2499, O'Nan-Scott types 4a, 4b and
## 5 cannot occur.)
## <#/GAPDoc>
#############################################################################
##
#F PrimitiveGroupsIterator(<attr1>,<val1>,<attr2>,<val2>,...)
##
## <#GAPDoc Label="PrimitiveGroupsIterator">
## <ManSection>
## <Func Name="PrimitiveGroupsIterator" Arg='attr1,val1,attr2,val2,...'/>
##
## <Description>
## returns an iterator through
## <C>AllPrimitiveGroups(<A>attr1</A>,<A>val1</A>,<A>attr2</A>,<A>val2</A>,...)</C> without creating
## all these groups at the same time.
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareGlobalFunction( "PrimitiveGroupsIterator" );
#############################################################################
##
#F AllPrimitiveGroups(<attr1>,<val1>,<attr2>,<val2>,...)
##
## <#GAPDoc Label="AllPrimitiveGroups">
## <ManSection>
## <Func Name="AllPrimitiveGroups" Arg='attr1,val1,attr2,val2,...'/>
##
## <Description>
## This is a selection function which permits to select all groups
## from the Primitive Group Library that have a given set of properties.
## It accepts arguments as specified in Section
## <Ref BookName="ref" Sect="Selection Functions"/> of the &GAP; reference manual.
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareGlobalFunction( "AllPrimitiveGroups" );
#############################################################################
##
#F OnePrimitiveGroup(<attr1>,<val1>,<attr2>,<val2>,...)
##
## <#GAPDoc Label="OnePrimitiveGroup">
## <ManSection>
## <Func Name="OnePrimitiveGroup" Arg='attr1,val1,attr2,val2,...'/>
##
## <Description>
## This is a selection function which permits to select at most one group
## from the Primitive Group Library that have a given set of properties.
## It accepts arguments as specified in Section
## <Ref BookName="ref" Sect="Selection Functions"/> of the &GAP; reference manual.
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareGlobalFunction( "OnePrimitiveGroup" );
#############################################################################
##
#A SimsNo(<G>)
##
## <#GAPDoc Label="SimsNo">
## <ManSection>
## <Attr Name="SimsNo" Arg='G'/>
##
## <Description>
## If <A>G</A> is a primitive group of degree not greater than 50,
## obtained by <Ref Func="PrimitiveGroup"/>
## (respectively one of the selection functions), then this attribute contains
## the number of the isomorphic group in the original list of C. Sims.
## (This is the arrangement as it was used in &GAP; 3.)
## <P/>
## <Example><![CDATA[
## gap> g:=PrimitiveGroup(25,2);
## 5^2:S(3)
## gap> SimsNo(g);
## 3
## ]]></Example>
## <P/>
## As mentioned in the previous section, the index numbers of primitive
## groups in &GAP; are guaranteed to remain stable. (Thus, missing groups
## will be added to the library at the end of each degree.)
## In particular, it is safe to refer to a primitive group of type
## <A>deg</A>, <A>nr</A> in the &GAP; library.
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareAttribute( "SimsNo", IsPermGroup );
#############################################################################
##
#V PrimitiveIndexIrreducibleSolvableGroup
##
## <#GAPDoc Label="PrimitiveIndexIrreducibleSolvableGroup">
## <ManSection>
## <Var Name="PrimitiveIndexIrreducibleSolvableGroup"/>
##
## <Description>
## This variable provides a way to get from irreducible solvable groups to
## primitive groups and vice versa. For the group
## <M>G</M> = <C>IrreducibleSolvableGroup( <A>n</A>, <A>p</A>, <A>k</A> )</C>
## and <M>d = p^n</M>, the entry
## <C>PrimitiveIndexIrreducibleSolvableGroup[d][i]</C> gives the index
## number of the semidirect product <M>p^n:G</M> in the library of primitive
## groups.
## <P/>
## Searching for an index in this list with
## <Ref BookName="ref" Func="Position"/> gives the
## translation in the other direction.
## </Description>
## </ManSection>
## <#/GAPDoc>
##
#DeclareGlobalVariable("PrimitiveIndexIrreducibleSolvableGroup");
#############################################################################
##
#A PrimitiveIdentification( <G> )
##
## <#GAPDoc Label="PrimitiveIdentification">
## <ManSection>
## <Attr Name="PrimitiveIdentification" Arg='G'/>
##
## <Description>
## For a primitive permutation group for which an <M>S_n</M>-conjugate exists in
## the library of primitive permutation groups
## (see <Ref Sect="Primitive Permutation Groups"/>),
## this attribute returns the index position. That is <A>G</A> is
## conjugate to
## <C>PrimitiveGroup(NrMovedPoints(<A>G</A>),PrimitiveIdentification(<A>G</A>))</C>.
## <P/>
## Methods only exist if the primitive groups library is installed.
## <P/>
## Note: As this function uses the primitive groups library, the result is
## only guaranteed to the same extent as this library. If it is incomplete,
## <C>PrimitiveIdentification</C> might return an existing index number for a
## group not in the library.
## <Example><![CDATA[
## gap> PrimitiveIdentification(Group((1,2),(1,2,3)));
## 2
## ]]></Example>
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareAttribute( "PrimitiveIdentification", IsPermGroup );
