\begin{Mhelppage}{SemiRing}{E.~Laugerotte}
  [ImplState=beta,TestState=alpha,DocState=beta]
\Mproofread{nthiery}{30/09/2004}{quick proofreading}

\begin{MInfo}
\eng{constructor of semi-rings}
\de{}
\end{MInfo}

\MDeclareOption{\Prop}{Prop}

\MDeclareOption{\Plus}{Plus}
\MDeclareOption{\Zero}{Zero}
\MDeclareOption{\Negate}{Negate}

\MDeclareOption{\Mult}{Mult}
\MDeclareOption{\One}{One}
\MDeclareOption{\Invert}{Invert}

\MDeclareOption{\Star}{Star}
\MDeclareOption{\Categ}{Categ}

%\begin{todo}
%\end{todo}

\begin{MIntro}
\eng{\Mthis\Mex{(Coefficient=coefficient, \Mseq)} creates a semi-ring domain.}
\end{MIntro}

\begin{MDetails}
  \eng{The domain \Mthis\Mex{(Coefficient=coefficient
      \Mopt{,Prop=prop, Plus=plus, Zero=zero, Negate=negate,
        Mult=mult, One=one, Invert=invert, Star=star, Categ=categ>|})}
    represents the semi-ring whose elements belong to
    \Mpar{coefficient} and satisfy the property \Mpar{prop}.  The
    addition, zero and opposites can be specified with the options \Plus,
    \Zero{}, and \Negate{} respectively. The multiplication, one, and
    inverses with \Mult, \One{} and \Invert{} respectively.}

  \eng{For more complicated semi-rings, it is recommended to create a
    new domain which inherits from this one.}
\end{MDetails}

\begin{MDomConst}
  \MCall{Coefficient=coefficient \Mopt{, Prop=prop, Plus=plus,
      Zero=zero, Negate=negate, Mult=mult, One=one, Invert=invert,
      Star=star, Categ=categ>}}
\end{MDomConst}

\begin{MParameters}
\param{coefficient}
\eng{a set of elements, given as a domain, a set, or a list.}
\de{}
\param{prop}
\eng{a property given by a type.}
\de{}
\param{plus}
\eng{the addition of the semiring, given as a function.}
\de{}
\param{zero}
\eng{the neutral element for the addition of the semiring which must verify 
the property (if it is a parameter) and, in this case, it must also be a 
coefficient.}
\de{}
\param{negate}
\eng{opposites of the semiring, given as a function.}
\de{}
\param{mult}
\eng{the multiplication of the semiring, given as a function.}
\de{}
\param{one}
\eng{the neutral element for the multiplication of the semiring; it
  must verify the property (if it is a parameter) and, in this case,
  it must also be a coefficient.}
\de{}
\param{invert}
\eng{inverses of the semiring, given as a function.}
\de{}
\param{star}
\eng{the star of the semiring, given as a function.}
\de{}
\param{categ}
\eng{a category inheriting from \Mup{Cat::SemiRing}.}
\de{}
\end{MParameters}

\begin{MCategories}
\Mup{Cat::SemiRing}
\end{MCategories}

\MRelatedDomains{}

\begin{MDomEntries}
\MDomEntry{zero}
\eng{the neutral element for the addition of the semiring.}
\de{}
\MDomEntry{one}
\eng{the neutral element for the multiplication of the semiring.}
\de{}
\end{MDomEntries}

\MMathMethods

\begin{MMethodDetails}{_plus}
  \infoEng{addition of semiring values}
    \infoDe{}  
\call{\Mseq{\Mtype{dom} a1}}
\eng{The operation \Mex{a1+a2+\ldots{}+ak} realizes the addition of the 
semiring values \Mex{a1,a2,\ldots{},ak}.}
\de{}
\eng{This method overloads the function \Mup{_plus}.}
\end{MMethodDetails}

\begin{MMethodDetails}{_mult}
  \infoEng{multiplication of semiring values}
    \infoDe{}  
\call{\Mseq{\Mtype{dom} a1}}
\eng{The operation \Mex{a1*a2*\ldots{}*ak} realizes the multiplication of the 
semiring values \Mex{a1,a2,\ldots{},ak}.}
\de{}
\eng{This method overloads the function \Mup{_mult}.}
\end{MMethodDetails}

\begin{MMethodDetails}{_negate}
  \infoEng{opposite of a semiring value}
    \infoDe{}  
\call{\Mseq{\Mtype{dom} a1}}
\eng{\Mex{-a1} represents the opposite of a semiring value \Mex{a1} if it 
exists, FAIL otherwise.}
\de{}
\eng{This method overloads the function \Mup{_negate}.}
\end{MMethodDetails}

\begin{MMethodDetails}{_invert}
  \infoEng{inverse of a semiring value}
    \infoDe{}  
\call{\Mseq{\Mtype{dom} a1}}
\eng{\Mex{1/a1} represents the inverse of a semiring value \Mex{a1} if it 
exists, FAIL otherwise.}
\de{}
\eng{This method overloads the function \Mup{_invert}.}
\end{MMethodDetails}

\begin{MMethodDetails}{_power}
\infoEng{power of a semiring value}
\infoDe{}
\call{\Mtype{dom} a,\Mtype{Dom::Integer} n}
\eng{ The nth power \Mex{a^n} of a semiring value \Mex{a}.}
\de{}
\eng{This method overloads the function \Mup{_power}.}
\end{MMethodDetails}

\MConvMethods

\begin{MMethodDetails}{changeCoeffRing}
    \infoEng{conversion of a semiring value into another semiring value}
    \infoDe{}
\call{\Mtype{dom} a, \Mtype{any} T}
\eng{The conversion of \Mex{a} into a semiring \Mex{T}. Currently, only a 
conversion into a type of scalars.}
\de{}
\end{MMethodDetails}

\begin{MExample}{ex1}
\eng{This example shows how to create the boolean semiring:}

  \begin{Mexin}
Bplus := (x, y) -> (if bool(x = 1) or bool(y = 1) then 
    1
  else 
    0
  end_if) :
  \end{Mexin}
  \begin{Mexin}
Bmult := (x, y) -> (if bool(x = 1) and bool(y = 1) then 
    1
  else 
    0
  end_if) :
  \end{Mexin}
  \begin{Mexin}
Bstar := x -> 1 :
  \end{Mexin}
  \begin{Mexin}
B := Dom::SemiRing(Coefficient = {0, 1}, Plus = Bplus, Zero = 0, Mult = Bmult, One = 1, Star = Bstar) :
  \end{Mexin}
    \begin{Mexin}
B(1) + B(1) ;
  \end{Mexin}
  \begin{Mexout}
                               1
  \end{Mexout}
\end{MExample}
\begin{MExample}{ex2}
\eng{We can overload Dom::Rational with a method star:}

  \begin{Mexin}
Q := Dom::Rational :
  \end{Mexin}
  \begin{Mexin}
s := x -> (if x = 1 then 
    FAIL
  else 
    1/(1 - x)
  end_if) :
  \end{Mexin}
  \begin{Mexin}
Qs := Dom::SemiRing(Coefficient = Q, Star = s, Categ = Cat::Field) :
  \end{Mexin}
  \begin{Mexin}
Qs::star(Qs(1/2)) ;
  \end{Mexin}
  \begin{Mexout}
                               2
  \end{Mexout}
\end{MExample}

\MSuperDomain{Dom::BaseDomain}

\begin{MAxioms}
  \Mup{Ax::canonicalRep, Ax::normalRep}
\end{MAxioms}

\begin{MChanges}
  \version{3.1}
  \new
\end{MChanges}

\end{Mhelppage}
