
<Chapter Label="create"><Heading>Creating semigroups and monoids</Heading> 
  In this chapter we describe the various ways that semigroups and monoids can
  be created in &Semigroups;, the options that are available at the time of
  creation, and describe some standard examples available in &Semigroups;. <P/>
  
  Any semigroup created before &Semigroups; has been loaded must
  be recreated after &Semigroups; is loaded so that the options record
  (described in Section <Ref Sect="opts"/>) is defined. Almost all of the
  functions and methods provided by &Semigroups;, including those methods for
  existing &GAP; library functions, will return an error when applied to a
  semigroup created before &Semigroups; is loaded. 

 <Section><Heading>Random semigroups</Heading> 
    <#Include Label="RandomInverseMonoid"> 
    <#Include Label="RandomTransformationMonoid"> 
    <#Include Label="RandomPartialPermMonoid"> 
    <#Include Label="RandomBinaryRelationMonoid"> 
    <#Include Label="RandomBipartitionMonoid"> 
  </Section> 

  <Section><Heading>New semigroups from old</Heading> 
    <#Include Label="ClosureInverseSemigroup">
    <#Include Label="ClosureSemigroup">
    <#Include Label="SubsemigroupByProperty">
    <#Include Label="InverseSubsemigroupByProperty">
  </Section> 
  
  <Section Label="opts"><Heading>Options when creating semigroups</Heading>
    When using any of the functions:
    <List>
      <Item><Ref Func="InverseSemigroup"  BookName="ref"/>,</Item>
      <Item><Ref Func="InverseMonoid" BookName="ref"/>,</Item>
      <Item><Ref Func="Semigroup" BookName="ref"/>,</Item>
      <Item><Ref Func="Monoid" BookName="ref"/>,</Item>
      <Item><Ref Meth="SemigroupByGenerators" BookName="ref"/>,</Item>
      <Item><Ref Meth="MonoidByGenerators" BookName="ref"/>,</Item>
      <Item><Ref Oper="ClosureInverseSemigroup"/>,</Item>
      <Item><Ref Oper="ClosureSemigroup"/>,</Item>
      <Item><Ref Func="SemigroupIdeal"/></Item>
    </List>
    a record can be given as an optional final argument. The components of this
    record specify the values of certain options for the semigroup being
    created. A list of these options and their default values is given below.
    <P/>

    Assume that <A>S</A> is the semigroup created by one of the functions given
    above and that either: <A>S</A> is generated by a collection <A>gens</A> of
    transformations, partial permutations, Rees 0-matrix semigroup elements, or
    bipartitions; or <A>S</A> is an ideal of such a semigroup.
  
    <List>
      <Mark><C>acting</C></Mark>
      <Item> 
        this component should be <K>true</K> or <K>false</K>. In order for a
        semigroup to use the methods in &Semigroups; it must satisfy
        <C>IsActingSemigroup</C>. By default any semigroup or monoid of
        transformations, partial permutations, Rees 0-matrix elements, or 
        bipartitions satisfies <C>IsActingSemigroup</C>. From time to time, it
        might be preferable to use the exhaustive algorithm in the &GAP;
        library to compute with a semigroup. If this is the case, then the
        value of this component can be set <K>false</K> when the semigroup is
        created.  Following this none of the methods in the &Semigroups;
        package will be used to compute anything about the semigroup.
      </Item>
      <Mark><C>regular</C></Mark>
      <Item>
        this component should be <K>true</K> or <K>false</K>. If it is known
        <E>a priori</E> that the semigroup <C>S</C> being created is a regular
        semigroup, then this component can be set to <K>true</K>. In this case,
        <C>S</C> knows it is a regular semigroup and can take advantage of the
        methods for regular semigroups in &Semigroups;. It is usually much more
        efficient to compute with a regular semigroup that to compute with a
        non-regular semigroup.<P/>

        If this option is set to <K>true</K> when the semigroup being defined
        is <B>not</B> regular, then the results might be unpredictable. <P/>

        The default value for this option is <K>false</K>.
      </Item>
      <Mark><C>hashlen</C></Mark>
      <Item>
        this component should be a positive integer, which roughly specifies the
        lengths of the hash tables used internally by &Semigroups;.  &Semigroups;
        uses hash tables in several fundamental methods.  The lengths of these
        tables are a compromise between performance and memory usage; larger
        tables provide better performance for large computations but use more
        memory.  Note that it is unlikely that you will need to specify this
        option unless you find that &GAP; runs out of memory unexpectedly or that
        the performance of &Semigroups; is poorer than expected. If you find that
        &GAP; runs out of memory unexpectedly, or you plan to do a large number
        of computations with relatively small semigroups (say with tens of
        thousands of elements), then you might consider setting <C>hashlen</C> to
        be less than the default value of <C>25013</C> for each of these
        semigroups.  If you find that the performance of &Semigroups; is
        unexpectedly poor, or you plan to do a computation with a very large
        semigroup (say, more than 10 million elements), then you might consider
        setting <C>hashlen</C> to be greater than the default value of
        <C>25013</C>. <P/>

        You might find it useful to set the info level of the info class
        <C>InfoOrb</C> to 2 or higher since this will indicate when hash tables
        used by &Semigroups; are being grown; see <Ref Oper="SetInfoLevel"
        BookName="ref"/>.
      </Item>
      
      <Mark><C>small</C></Mark> <Item>if this component is set to <K>true</K>,
        then &Semigroups; will compute a small subset of <A>gens</A> that
        generates <A>S</A> at the time that <A>S</A> is created. This will
        increase the amount of time required to create <A>S</A> substantially,
        but may decrease the amount of time required for subsequent
        calculations with <A>S</A>. If this component is set to <K>false</K>,
        then &Semigroups; will return the semigroup generated by <A>gens</A>
        without modifying <A>gens</A>. The default value for this component is
        <K>false</K>.<P/>

        This option is ignored when passed to <Ref Oper="ClosureSemigroup"/> or
        <Ref Oper="ClosureInverseSemigroup"/>. 
    </Item> 
</List>

    <Example>
gap> S:=Semigroup(Transformation( [ 1, 2, 3, 3 ] ), 
> rec(hashlen:=100003, small:=false));
&lt;commutative transformation semigroup on 4 pts with 1 generator></Example>

      The default values of the options described above are stored in a global
      variable named <Ref Var="SemigroupsOptionsRec"/>. If you want to change
      the default values of these options for a single &GAP; session, then you
      can simply redefine the value in &GAP;. For example, to change the option
      <C>small</C> from the default value of <A>false</A> use:

    <Log>gap> SemigroupsOptionsRec.small:=true;
true</Log>

    If you want to change the default values of the options stored in <Ref
      Var="SemigroupsOptionsRec"/> for all &GAP; sessions, then you can
    edit these values in the file <C>semigroups/gap/options.g</C>. <P/>


    <#Include Label="SemigroupsOptionsRec">

   </Section>
    
  <Section><Heading>Changing the representation of a semigroup</Heading>
    In addition, to the library functions
    <List>
      <Item><Ref Oper="IsomorphismReesMatrixSemigroup" BookName="ref"/>,</Item>
      <Item><Ref Oper="AntiIsomorphismTransformationSemigroup" BookName="ref"/>,
      </Item>
      <Item><Ref Oper="IsomorphismTransformationSemigroup" BookName="ref"/>,
      </Item>
      <Item><Ref Oper="IsomorphismPartialPermSemigroup" BookName="ref"/>,</Item>
    </List>
      there are several methods for changing the representation of a semigroup
      in &Semigroups;. There are also methods for the operations given above for
      the types of semigroups defined in &Semigroups; which are not mentioned in
      the reference manual. 
      <#Include Label="AsTransformationSemigroup">
      <#Include Label="IsomorphismPermGroup">
      <#Include Label="IsomorphismBipartitionSemigroup">
      <#Include Label="IsomorphismBlockBijectionSemigroup">
  </Section>
  
  <Section Label="Examples"><Heading>Standard examples</Heading>
    In this section, we describe the operations in &Semigroups; that can be
    used to creating semigroups belonging to several standard classes of
    example. See Chapter <Ref Chap="bipartition"/> for more information about
    semigroups of bipartitions. 
    <#Include Label="EndomorphismsPartition"> 
    <#Include Label="PartitionMonoid"> 
    <#Include Label="BrauerMonoid"> 
    <#Include Label="JonesMonoid"> 
    <#Include Label="FactorisableDualSymmetricInverseSemigroup">
    <#Include Label="DualSymmetricInverseSemigroup">
    <#Include Label="PartialTransformationSemigroup"> 
    <#Include Label="FullMatrixSemigroup">
    <#Include Label="IsFullMatrixSemigroup">
    <#Include Label="MunnSemigroup">
    <#Include Label="OPOIPOPI">
    <#Include Label="SingularTransformationSemigroup">
    <#Include Label="RegularBinaryRelationSemigroup">
    <#Include Label="MonogenicSemigroup">
    <#Include Label="RectangularBand">
    <#Include Label="ZeroSemigroup">
  </Section>

</Chapter>

