#############################################################################
##
#W  semimaxplus.xml
#Y  Copyright (C) 2016                                  Stuart A. Burrell
##
##  Licensing information can be found in the README file of this package.
##
#############################################################################
##

<#GAPDoc Label="IsXMatrixSemigroup">
  <ManSection Label = "IsXMatrixSemigroup">
  <Heading>Matrix semigroup filters</Heading>
    <Filt Name = "IsMatrixOverSemiringSemigroup"      Arg = "obj" Type = "Category"/>
    <Filt Name = "IsBooleanMatSemigroup"              Arg = "obj" Type = "Category"/>
    <Filt Name = "IsMatrixOverFiniteFieldSemigroup"   Arg = "obj" Type = "Category"/>
    <Filt Name = "IsMaxPlusMatrixSemigroup"           Arg = "obj" Type = "Category"/>
    <Filt Name = "IsMinPlusMatrixSemigroup"           Arg = "obj" Type = "Category"/>
    <Filt Name = "IsTropicalMatrixSemigroup"          Arg = "obj" Type = "Category"/>
    <Filt Name = "IsTropicalMaxPlusMatrixSemigroup"   Arg = "obj" Type = "Category"/>
    <Filt Name = "IsTropicalMinPlusMatrixSemigroup"   Arg = "obj" Type = "Category"/>
    <!-- <Filt Name = "IsProjectiveMaxPlusMatrixSemigroup" Arg = "obj" Type = "Category"/> -->
    <Filt Name = "IsNTPMatrixSemigroup"               Arg = "obj" Type = "Category"/>
    <Filt Name = "IsIntegerMatrixSemigroup"           Arg = "obj" Type = "Category"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      The above are the currently supported types of matrix semigroups. For
      monoids see Section <Ref Sect = "IsXMatrixMonoid"/>.

    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsXMatrixMonoid">
  <ManSection Label = "IsXMatrixMonoid">
    <Heading>Matrix monoid filters</Heading>
    <Filt Name = "IsMatrixOverSemiringMonoid"      Arg = "obj" Type = "Category"/>
    <Filt Name = "IsBooleanMatMonoid"              Arg = "obj" Type = "Category"/>
    <Filt Name = "IsMatrixOverFiniteFieldMonoid"   Arg = "obj" Type = "Category"/>
    <Filt Name = "IsMaxPlusMatrixMonoid"           Arg = "obj" Type = "Category"/>
    <Filt Name = "IsMinPlusMatrixMonoid"           Arg = "obj" Type = "Category"/>
    <Filt Name = "IsTropicalMatrixMonoid"          Arg = "obj" Type = "Category"/>
    <Filt Name = "IsTropicalMaxPlusMatrixMonoid"   Arg = "obj" Type = "Category"/>
    <Filt Name = "IsTropicalMinPlusMatrixMonoid"   Arg = "obj" Type = "Category"/>
    <!-- <Filt Name = "IsProjectiveMaxPlusMatrixMonoid" Arg = "obj" Type = "Category"/> -->
    <Filt Name = "IsNTPMatrixMonoid"               Arg = "obj" Type = "Category"/>
    <Filt Name = "IsIntegerMatrixMonoid"           Arg = "obj" Type = "Category"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      The above are the currently supported types of matrix monoids.  They
      correspond to the matrix semigroup types in
      Section <Ref Sect = "IsXMatrixSemigroup"/>.
      For matrix semigroups over finite fields there is also 
      <Ref Filt = "IsMatrixOverFiniteFieldGroup"/>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsFinite">
  <ManSection>
    <Prop Name = "IsFinite" Arg = "S"/>
    <Returns><K>true</K> or <K>false</K>. </Returns>
    <Description>
      If <A>S</A> is a max-plus or min-plus matrix semigroup (i.e. belongs to
      the category <Ref Filt = "IsMaxPlusMatrixSemigroup"/>), then
      <C>IsFinite</C> returns <K>true</K> if <A>S</A> is finite and
      <K>false</K> otherwise. This method is based on
      <Cite Key="Gaubert1996aa"/> (max-plus) and <Cite Key="Simon1978aa"/>
      (min-plus). For min-plus matrix semigroups, this method is only
      valid if each min-plus matrix in the semigroup contains only non-negative
      integers. Note, this method is terminating and does not involve
      enumerating semigroups.
      <Example><![CDATA[
gap> IsFinite(Semigroup(Matrix(IsMaxPlusMatrix,
>                              [[0, -3],
>                               [-2, -10]])));
true
gap> IsFinite(Semigroup(Matrix(IsMaxPlusMatrix,
>                              [[1, -infinity, 2],
>                               [-2, 4, -infinity],
>                               [1, 0, 3]])));
false
gap> IsFinite(Semigroup(Matrix(IsMinPlusMatrix,
>                              [[infinity, 0],
>                               [5, 4]])));
false
gap> IsFinite(Semigroup(Matrix(IsMinPlusMatrix,
>                              [[1, 0],
>                               [0, infinity]])));
true
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsTorsion">
  <ManSection>
    <Attr Name = "IsTorsion" Arg = "S"/>
    <Returns><K>true</K> or <K>false</K>.</Returns>
    <Description>
      If <A>S</A> is a max-plus matrix semigroup (i.e. belongs to the
      category <Ref Filt = "IsMaxPlusMatrixSemigroup"/>), then
      <C>IsTorsion</C> returns <K>true</K> if <A>S</A> is torsion and
      <K>false</K> otherwise. This method is based on
      <Cite Key="Gaubert1996aa"/> and draws on <Cite Key="Burrell2016aa"/>,
      <Cite Key="Bacelli1992aa"/> and <Cite Key="Kacie2009aa"/>.
 
      <Example><![CDATA[
gap> IsTorsion(Semigroup(Matrix(IsMaxPlusMatrix,
>                              [[0, -3],
>                               [-2, -10]])));
true
gap> IsTorsion(Semigroup(Matrix(IsMaxPlusMatrix,
>                               [[1, -infinity, 2],
>                                [-2, 4, -infinity],
>                                [1, 0, 3]])));
false
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="NormalizeSemigroup">
  <ManSection>
    <Oper Name = "NormalizeSemigroup" Arg = "S"/>
    <Returns>A semigroup.</Returns>
    <Description>
      This method applies to max-plus matrix semigroups (i.e. those belonging to
      the category <Ref Filt = "IsMaxPlusMatrixSemigroup"/>) that are
      finitely generated, such that the spectral radius of the matrix equal to
      the sum of the generators (with respect to the max-plus semiring) is zero. 
      <C>NormalizeSemigroup</C> returns  a semigroup of matrices all with
      strictly non-positive entries. Note that the output is isomorphic to a
      min-plus matrix semigroup. This method is based on
      <Cite Key="Gaubert1996aa"/> and  <Cite Key="Burrell2016aa"/>.
      <Example><![CDATA[
gap> NormalizeSemigroup(Semigroup(Matrix(IsMaxPlusMatrix,
>                                        [[0, -3],
>                                         [-2, -10]])));
<commutative semigroup of 2x2 max-plus matrices with 1 generator>
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>
