<Chapter Label = "Matrices over semirings">
  <Heading>
    Matrices over semirings
  </Heading>

  <!--**********************************************************************-->
  <!--**********************************************************************-->

  In this chapter we describe the functionality in &SEMIGROUPS; for creating
  matrices over semirings.  <B>Only square matrices are currently
  supported.</B> We use the term <B>matrix</B> to mean <B>square matrix</B>
  everywhere in this manual.
  <P/>

  For reference, matrices over the following semirings are currently supported:
  <List>
    <Mark>the Boolean semiring</Mark>
    <Item>
      the set <M>\{0, 1\}</M> where <M>0 + 0 = 0</M>,
      <M>0 + 1 = 1 + 1 = 1 + 0 = 1</M>, <M>1\cdot 0 = 0 \cdot 0 = 0
        \cdot 1 = 0</M>, and <M>1\cdot 1 = 1</M>.
    </Item>

    <Mark>the max-plus semiring</Mark>
    <Item>
      the set of integers and negative
      infinity <M>\mathbb{Z}\cup \{-\infty\}</M> with operations max and
      plus.
    </Item>

    <Mark>the min-plus semiring</Mark>
    <Item>
      the set of integers and
      infinity <M>\mathbb{Z}\cup \{\infty\}</M> with operations min and
      plus;
    </Item>

    <Mark>tropical max-plus semirings</Mark>
    <Item>
      the set <M>\{-\infty, 0, 1, \ldots, t\}</M> for some threshold <M>t</M>
      with operations max and plus;
    </Item>

    <Mark>tropical min-plus semirings</Mark>
    <Item>
      the set <M>\{0, 1, \ldots, t, \infty\}</M> for some threshold <M>t</M>
      with operations min and plus;
    </Item>

    <!-- <Mark>the projective max-plus semiring</Mark>
    <Item>
      the projective max-plus semiring;
    </Item> -->

    <Mark>the semiring <M>\mathbb{N}_{t,p}</M></Mark>
    <Item>
      the semiring
      <M>\mathbb{N}_{t,p} = \{0, 1, \ldots, t, t + 1, \ldots, t + p - 1\}</M>
      for some threshold <M>t</M> and period <M>p</M> under addition and
      multiplication modulo the congruence <M>t = t + p</M>;
    </Item>

    <Mark>the integers</Mark>
    <Item>
      the usual ring of integers;
    </Item>

    <Mark>finite fields</Mark>
    <Item>
      the finite fields <C>GF(q^d)</C> for prime <C>q</C> and some positive
      integer <C>d</C>.
    </Item>
  </List>

  With the exception of matrices of finite fields, semigroups of matrices in
  &SEMIGROUPS; are of the second type described in Section <Ref Sect =
  "Underlying algorithms"/>.  In other words, a version of the Froidure-Pin
  Algorithm <Cite Key = "Froidure1997aa"/> is used to compute semigroups of
  these types, i.e it is possible that all of the elements of such a
  semigroup are enumerated and stored in the memory of your computer.

  <!--**********************************************************************-->
  <!--**********************************************************************-->

  <Section Label = "Matrices over arbitrary semirings">
    <Heading>Creating matrices over semirings</Heading>
    In this section we describe the two main operations for creating matrices
    over semirings in &SEMIGROUPS;, and the categories, attributes, and
    operations which apply to every matrix over one of the semirings given at
    the start of this chapter.<P/>

    There are several special methods for boolean matrices, which can be found
    in Section <Ref Sect = "Boolean matrices"/>.

    There are also several special methods for finite fields, which can be found
    in section <Ref Sect = "Matrices over finite fields"/>.

    <#Include Label = "IsMatrixOverSemiring">
    <#Include Label = "IsMatrixOverSemiringCollection">
    <#Include Label = "DimensionOfMatrixOverSemiring">
    <#Include Label = "DimensionOfMatrixOverSemiringCollection">
    <#Include Label = "Matrix">
    <#Include Label = "AsMatrix"/>
    <#Include Label = "RandomMatrix">
    <#Include Label = "IsXMatrix"/>
    <#Include Label = "IsXMatrixCollection"/>
    <#Include Label = "AsList"/>

    <!-- the following could go in a section of their own if there are more at
          some point -->
    <#Include Label = "ThresholdTropicalMatrix"/>
    <#Include Label = "ThresholdNTPMatrix"/>
  </Section>

  <!--**********************************************************************-->
  <!--**********************************************************************-->

  <Section Label = "Operators for matrices over semirings">
    <Heading>Operators for matrices over semirings</Heading>
    <List>
      <Mark><C><A>mat1</A> * <A>mat2</A></C></Mark>
      <Item>
        <Index Key = "*"><C>*</C> (for matrices over a semiring)</Index> returns
        the product of the matrices <A>mat1</A> and <A>mat2</A> of equal
        dimension over the same semiring using the usual matrix multiplication
        with the operations <C>+</C> and <C>*</C> from the underlying semiring.
      </Item>
      <Mark><C><A>mat1</A> &lt; <A>mat2</A></C></Mark>
      <Item>
        <Index Key = "&lt;"><C>&lt;</C> (for matrices over a semiring)</Index>
        returns <K>true</K> if when considered as a list of rows, the matrix
        <A>mat1</A> is short-lex less than the matrix <A>mat2</A>, and
        <K>false</K> if this is not the case. This means that a matrix of lower
        dimension is less than a matrix of higher dimension.
      </Item>
      <Mark><C><A>mat1</A> = <A>mat2</A></C></Mark>
      <Item>
        <Index Key = "="><C>=</C> (for matrices over a semiring)</Index>
        returns <K>true</K> if the matrix <A>mat1</A> equals the
        matrix <A>mat2</A> (i.e. the entries are equal and the underlying
        semirings are equal) and returns <K>false</K> if it does not.
      </Item>
    </List>
  </Section>

  <!--**********************************************************************-->
  <!--**********************************************************************-->

  <Section Label = "Boolean matrices">
    <Heading>
      Boolean matrices
    </Heading>

    In this section we describe the operations, properties, and attributes in
    &SEMIGROUPS; specifically for Boolean matrices.  These include:

    <List>
      <Item>
        <Ref Oper = "NumberBooleanMat"/>
      </Item>
      <Item>
        <Ref Attr = "Successors"/>
      </Item>
      <Item>
        <Ref Prop = "IsRowTrimBooleanMat"/>,
        <Ref Prop = "IsColTrimBooleanMat"/>,
        and
        <Ref Prop = "IsTrimBooleanMat"/>,
      </Item>
      <Item>
        <Ref Oper = "CanonicalBooleanMat"/>
      </Item>
      <Item>
        <Ref Prop = "IsSymmetricBooleanMat"/>
      </Item>
      <Item>
        <Ref Prop = "IsAntiSymmetricBooleanMat"/>
      </Item>
      <Item>
        <Ref Prop = "IsTransitiveBooleanMat"/>
      </Item>
      <Item>
        <Ref Prop = "IsReflexiveBooleanMat"/>
      </Item>
      <Item>
        <Ref Prop = "IsTotalBooleanMat"/>
      </Item>
      <Item>
        <Ref Prop = "IsOntoBooleanMat"/>
      </Item>
      <Item>
        <Ref Prop = "IsPartialOrderBooleanMat"/>
      </Item>
      <Item>
        <Ref Prop = "IsEquivalenceBooleanMat"/>
      </Item>
    </List>

    <#Include Label = "BooleanMat">
    <#Include Label = "AsBooleanMat">

    <#Include Label = "ContainmentBooleanMats">
    <#Include Label = "OnBlist">
    <#Include Label = "Successors">
    <#Include Label = "NumberBooleanMat">
    <#Include Label = "NumberBlist">
    <#Include Label = "CanonicalBooleanMat">

    <#Include Label = "IsRowTrimBooleanMat">
    <#Include Label = "IsSymmetricBooleanMat">
    <#Include Label = "IsReflexiveBooleanMat">
    <#Include Label = "IsTransitiveBooleanMat">
    <#Include Label = "IsAntiSymmetricBooleanMat">
    <#Include Label = "IsTotalBooleanMat">
    <#Include Label = "IsPartialOrderBooleanMat">
    <#Include Label = "IsEquivalenceBooleanMat">
    <#Include Label = "IsTransformationBooleanMat">
  </Section>

  <!--**********************************************************************-->
  <!--**********************************************************************-->

  <Section Label = "Matrices over finite fields">
    <Heading>
      Matrices over finite fields
    </Heading>

    In this section we describe some operations in &SEMIGROUPS; for matrices
    over finite fields that are required for such matrices to form semigroups
    satisfying <Ref Filt="IsActingSemigroup"/>. <P/>

    From v5.0.0, &SEMIGROUPS; uses the &GAP; library implementation of matrices
    over finite fields belonging to the category <Ref Filt="IsMatrixObj"
    BookName="ref"/> rather than the previous implementation in the
    &SEMIGROUPS; package. This means that from v5.0.0, matrices over a finite
    field no longer belong to the category <Ref
    Filt="IsMatrixOverSemiring"/>.
    <P/>

    The following methods are implemented in &SEMIGROUPS; for matrix objects
    over finite fields.
    <#Include Label="RowSpaceBasis"/>
    <#Include Label="RightInverse"/>
  </Section>

  <!--**********************************************************************-->
  <!--**********************************************************************-->

  <Section Label = "Matrices over the integers">
    <Heading>
      Matrices over the integers
    </Heading>
    In this section we describe operations in &SEMIGROUPS; specifically for
    integer matrices. <P/>

    From v5.0.0, &SEMIGROUPS; uses the &GAP; library implementation of matrices
    over the integers belonging to the category <Ref Filt="IsMatrixObj"
    BookName="ref"/> rather than the previous implementation in the
    &SEMIGROUPS; package. This means that from v5.0.0, matrices over the
    integers no longer belong to the category <Ref
    Filt="IsMatrixOverSemiring"/>.<P/>

    The following methods are implemented in &SEMIGROUPS; for matrix objects
    over the integers.

    <#Include Label = "IntInverseOp">
    <#Include Label = "IntIsTorsion">
    <#Include Label = "IntOrder">
  </Section>

  <!--**********************************************************************-->
  <!--**********************************************************************-->

  <Section Label = "Max-plus and min-plus matrices">
    <Heading>
      Max-plus and min-plus matrices
    </Heading>

    In this section we describe operations in &SEMIGROUPS; specifically for
    max-plus and min-plus matrices. These are in addition to those given
    elsewhere in this chapter for arbitrary matrices over semirings. These
    include:

    <List>
      <Item>
        <Ref Oper = "InverseOp"/>
      </Item>
      <Item>
        <Ref Oper = "RadialEigenvector"/>
      </Item>
      <Item>
        <Ref Oper = "SpectralRadius"/>
      </Item>
      <Item>
        <Ref Oper = "UnweightedPrecedenceDigraph"/>
      </Item>
    </List>

    <#Include Label = "InverseOp">
    <#Include Label = "RadialEigenvector">
    <#Include Label = "SpectralRadius">
    <#Include Label = "UnweightedPrecedenceDigraph">
  </Section>

  <!--**********************************************************************-->
  <!--**********************************************************************-->

  <Section Label = "Matrix semigroups">
    <Heading>
      Matrix semigroups
    </Heading>

    In this section we describe operations and attributes in
    &SEMIGROUPS; specifically for matrix semigroups. These are in addition to
    those given elsewhere in this chapter for arbitrary matrices over
    semirings. These include:

    <List>
      <Item>
        <Ref Filt = "IsXMatrixSemigroup"/>
      </Item>
      <Item>
        <Ref Prop = "IsFinite"/>
      </Item>
      <Item>
        <Ref Attr = "IsTorsion"/>
      </Item>
      <Item>
        <Ref Oper = "NormalizeSemigroup"/>
      </Item>
    </List>

    Random matrix semigroups can be created by using the function
    <Ref Func="RandomSemigroup"/>.  We can also create a matrix semigroup
    isomorphic to a given semigroup by using <Ref Oper="IsomorphismSemigroup"/>
    and <Ref Oper="AsSemigroup"/>.  These functions require a filter, and accept
    any of the filters in Section <Ref Sect="IsXMatrixSemigroup"/>. <P/>

    There are corresponding functions which can be used for matrix monoids:
    <Ref Func="RandomMonoid"/>, <Ref Oper="IsomorphismMonoid"/>, and
    <Ref Oper="AsMonoid"/>.  These can be used with the filters in
    Section <Ref Sect="IsXMatrixMonoid"/>. <P/>

    <#Include Label = "IsXMatrixSemigroup">
    <#Include Label = "IsXMatrixMonoid">
    <#Include Label = "IsFinite">
    <#Include Label = "IsTorsion">
    <#Include Label = "NormalizeSemigroup">

  </Section>

  <!--**********************************************************************-->
  <!--**********************************************************************-->

</Chapter>
