%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% $Id: ModuleWithBasis.tex,v 1.1.1.5 2004/10/04 17:25:13 nthiery Exp $
% File:		lib/DOMAINS/CATEGORY/DOC/ModuleWithBasis.tex
% Authors:	Nicolas M. Thiéry <nthiery@users.sourceforge.net>
% Purpose:	Documentation for the category Cat::ModuleWithBasis
% Created:	Wed Sep  3 14:54:08 2003
% License:	LGPL
% Project:	MuPAD-Combinat, http://mupad-combinat.sf.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{Mhelppage}{ModuleWithBasis}{Nicolas M. Thiéry}
  [ImplState=stable,TestState=stable,DocState=stable]
\Mproofread{nthiery}{22/09/2003}{reasonably complete, but not proofread}
\Mproofread{hivert}{6/02/2004}{proofread}

\begin{MInfo}
  \eng{the category of modules over a distinguished basis}
  \de{}
\end{MInfo}

\begin{MIntro}
  \eng{\Mthis{} represents the category of modules over a distinguished basis.}
  \de{}
\end{MIntro}

\begin{MCatConst}
  \MCall{coeffRing}
\end{MCatConst}

\begin{MParameters}
  \param{coeffRing}
    \eng{A domain which must be from the category \Mex{Cat::Ring}.}
    \de{}
\end{MParameters}

\begin{MCategories}
  \Mupc{Cat::Module}{R} (or \Mupc{Cat::VectorSpace}{R})
  \Mup{Cat::UseOverloading}
\end{MCategories}

\begin{MDetails}
  \eng{A domain of the category \Mex{\Mthis(coeffRing)} is a domain of the
    category \Mupc{Cat::Module}{coeffRing} where \Mpar{coeffRing} is a
    \Mup{Cat::Ring}, with as a distinguished basis indexed by some
    combinatorial class \Mex{baseClass} in the category
    \Mup{Cat::CombinatorialClass}.  By this we mean that there exists a
    family $(b_\lambda)_\lambda$ of elements of the module such that any
    element $x$ of the module can be represented as a (formal) linear
    combination $x=\sum_\lambda c_\lambda b_\lambda$ with coefficients
    $c_\lambda$ in \Mpar{coeffRing}. The linear combination may be finite or
    infinite, and two syntactically different linear combinations may be
    mathematically equal.}
  
  \eng{\Mex{\Mthis(coeffRing)} is the basic super category for anything "that
    looks like a polynomial or a series". This includes for example
    differential operators or forms, Ore polynomials, elements of
    combinatorial algebras, and so on.}
  \de{}
  \eng{The support of $x$ is the set of all $\lambda$'s such that
    $c_\lambda\ne0$. The terms and monomials $x$ are respectively the
    $b_\lambda$'s and $c_\lambda\ b_\lambda$'s where $\lambda$ is in
    the support of $x$. When the combinatorial class is totally
    ordered, the leading support, term, and monomial (and their
    trailing equivalents) are defined in the natural way by extending
    the usual notions for polynomials. They need not exist when $x$
    has an infinite support.}
  \de{}%
  \eng{By default, the method \Mslot{_mult} is set to
    \Mex{operators::_mult}, which in turn uses \Mex{operators::mult2}.
    Furthermore, the later is overloaded with the following signatures
    and associated implementations:
    \begin{itemize}
    \item{} [dom, coeffRing] : \Mslot{multcoeffs}
    \item{} [coeffRing, dom] : \Mslot{multcoeffsLeft}
    \end{itemize}
    In other words, a \Mthis{} just has to implement
    \Mslot{multcoeffs} and \Mslot{multcoeffsLeft}. Then, \Mslot{_mult}
    will be implemented appropriately to handle both left and right
    multiplication by scalars. This differs from the plain
    \Mup{Cat::Module} category for which the domain has to provide
    this \Mslot{_mult} method. In a future version, this feature will
    be extended to \Mup{Cat::Module}.}
  \de{}%
  \eng{Defaults implementations are provided for most of the methods;
    they can be quite inefficient though, so it is highly recommended
    to redefine them. At the very least, the domain just needs to
    implement the constructor \Mslot{monomial}, and the methods
    \Mslot{toList} and \Mslot{coeff}.}
\end{MDetails}

%% A Cat::MonoidRing has besides the obvious methods stemming from the super
%% categories the following methods:
%%    lmonomial(x) :    the leading monomial of x (with respect to
%%                      the ordering of S)
%%    lcoeff(x) :       the coefficient of the lmonomial(x)
%%    lterm(x) :        the term of the lmonomial(x)
%%    reductum(x) :     x - lmonomial(x)
%%    const(x) :        the coefficient of the constant term
%%    monomial(r,s):    generates a monomial from its components
%%    coeff(x,s) :      the coefficient of x for a given generator
%%    isMonomial(x) :   TRUE, if x consists of only one monomial
%% Default implementations are provided for lmonomial, reductum and const. If S
%% has a method degree, then this method is extended to the monoid ring.

\begin{MDomBasEntries}
  \MDomEntry{basisIndices}
  \eng{the combinatorial class \Mex{baseClass} of the indices of the basis;
    it must be a \Mup{Cat::CombinatorialClass}.}
  \de{}
  \MDomEntry{zero}
  \eng{the zero element}
\end{MDomBasEntries}

\begin{MMethodDetails}{term}
  \infoEng{term constructor}
  \infoDe{}
  \call{\Mtype{baseClass} lambda}
  \eng{Returns the basis element $b_\lambda$ indexed by the element \Mex{lambda} of
    the combinatorial class \Mex{baseClass}.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{monomial}
  \infoEng{monomial constructor}
  \infoDe{}
  \call{\Mtype{coeffRing} c, \Mtype{baseClass} lambda}
  \eng{Returns the monomial $c b_\lambda$ indexed by the element
    \Mex{lambda} of \Mex{baseClass} with coefficient \Mpar{c}.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{fromList}
  \infoEng{constructor from list}
  \infoDe{}
  \call{\Mtype{list} l}%
  \eng{\Mpar{l} should be a list of the form
    \Mex{[[c1,lambda1],\Mseq{},[ck,lambdak]]}, where \Mex{c1,\Mseq{},ck}
    belongs to the coefficient ring \Mex{coeffRing} and
    \Mex{lambda1,\Mseq{},lambdak} belongs to the combinatorial class
    \Mex{baseClass}. This list does not need to be sorted in any way, and the
    $\lambda_i$'s are not required to be distinct.}
  \de{}%
  \eng{Returns the linear combination $c_1
    b_{\lambda_1}+\dots+c_kb_{\lambda_k}$ described by the list.}
  \de{}%
  \eng{This method is very similar to the creation of \mupad{} polynomials
    from a list.}
\end{MMethodDetails}

\begin{MMethodDetails}{toList}
  \infoEng{list}
  \infoDe{}
  \call{\Mtype{dom} x}%
  \eng{Returns a list describing the structure of \Mex{x}.}%
  \de{}%
  \eng{This is the inverse function of \Mslot{fromList}.}
  \de{}%
  \eng{This method is very similar to the \Mup{poly2list} method for
    \mupad{} polynomials.}
  \de{}%
\end{MMethodDetails}

\begin{MMethodDetails}{nterms}
  \infoEng{nterms}
  \infoDe{}
  \call{\Mtype{dom} x}
  \eng{Returns the number of terms of \Mpar{x}.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{support}
  \infoEng{support}
  \infoDe{}
  \call{\Mtype{dom} x}
  \eng{Returns the support of \Mpar{x}$=\sum_\lambda c_\lambda b_\lambda$
    that is the list of all $\lambda$'s such
    that $c_\lambda\ne0$. It a list of elements of \Mex{baseClass} whereas
  \Mex{term} (see below) is a list of elements of \Mex{dom}.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{terms}
  \infoEng{terms}
  \infoDe{}
  \call{\Mtype{dom} x}
  \eng{Returns the list of the terms of \Mpar{x}$=\sum_\lambda c_\lambda
  b_\lambda$ that is the list of all
    $b_\lambda$'s such that $c_\lambda\ne0$. It a list of element of
  \Mex{dom}, whereas \Mex{support} is a list of elements of \Mex{baseClass}.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{monomials}
  \infoEng{monomials}
  \infoDe{}
  \call{\Mtype{dom} x}
  \eng{Returns the list of the monomials of \Mpar{x}$=\sum_\lambda c_\lambda
  b_\lambda$ that is the list of all
    $c_\lambda\ b_\lambda$'s.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{coeffs}
  \infoEng{coefficients}
  \infoDe{}
  \call{\Mtype{dom} x}
  \eng{Returns the list of all the non-zero coefficients
    $c_\lambda$ of \Mpar{x}.}
  \de{}%
\end{MMethodDetails}

\begin{MMethodDetails}{coeff}
  \infoEng{coefficient(s)}
  \infoDe{}
  \call{\Mtype{dom} x}
  \eng{Returns the sequence of all the non-zero coefficients
    $c_\lambda$ of \Mpar{x}.}
  \de{}
  \call{\Mtype{dom} x, \Mtype{baseClass} lambda}
  \eng{Returns the coefficient $c_\lambda$ of \Mpar{x} at the index
    \Mpar{lambda}.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{lsupport}
  \infoEng{support of the leading term}
  \infoDe{}
  \call{\Mtype{dom} x}
  \eng{Returns the support of the leading term of \Mpar{x}.}
  \eng{If \Mpar{x} is zero, then \Mup{FAIL} is returned.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{lterm}
  \infoEng{leading term}
  \infoDe{}
  \call{\Mtype{dom} x}
  \eng{Returns the leading term of \Mpar{x}.}
  \eng{If \Mpar{x} is zero, then the zero of this domain is returned.
    This convention ensures the compatibility with standard \mupad{}
    polynomials.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{lmonomial}
  \infoEng{leading monomial}
  \infoDe{}
  \call{\Mtype{dom} x}
  \eng{Returns the leading monomial of \Mpar{x}.}
  \eng{If \Mpar{x} is zero, then the zero of this domain is returned.
    This convention ensures the compatibility with standard \mupad{}
    polynomials.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{lcoeff}
  \infoEng{leading coefficient}
  \infoDe{}
  \call{\Mtype{dom} x}
  \eng{Returns the leading coefficient of \Mpar{x}.}
  \eng{If \Mpar{x} is zero, then the zero of the coefficient ring is returned.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{tsupport}
  \infoEng{support of the trailing term}
  \infoDe{}
  \call{\Mtype{dom} x}
  \eng{Returns the support of the trailing term of \Mpar{x}.}
  \eng{If \Mpar{x} is zero, then \Mup{FAIL} is returned.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{tterm}
  \infoEng{trailing term}
  \infoDe{}
  \call{\Mtype{dom} x}
  \eng{Returns the trailing term of \Mpar{x}.}
  \eng{If \Mpar{x} is zero, then the zero of this domain is returned.
    This convention ensures the compatibility with standard \mupad{}
    polynomials.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{tmonomial}
  \infoEng{trailing monomial}
  \infoDe{}
  \call{\Mtype{dom} x}
  \eng{Returns the trailing monomial of \Mpar{x}.}
  \eng{If \Mpar{x} is zero, then the zero of this domain is returned.
    This convention ensures the compatibility with standard \mupad{}
    polynomials.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{tcoeff}
  \infoEng{trailing coefficient}
  \infoDe{}
  \call{\Mtype{dom} x}
  \eng{Returns the trailing coefficient of \Mpar{x}.}
  \eng{If \Mpar{x} is zero, then the zero of the coefficient ring is returned. }
  \de{}
\end{MMethodDetails}


\begin{MMethodDetails}{nthsupport}
  \infoEng{support of the $n$-th term}
  \infoDe{}
  \call{\Mtype{dom} x, \Mtype{positive integer} n}
  \eng{Returns the support of the \Mpar{n}-th term of \Mpar{x}.}
  \eng{If \Mpar{n} exceeds strictly the number of terms of \Mpar{x},
    then \Mup{FAIL} is returned. }
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{nthterm}
  \infoEng{$n$-th term}
  \infoDe{}
  \call{\Mtype{dom} x, \Mtype{positive integer} n}
  \eng{Returns the \Mpar{n}-th term of \Mpar{x}.}
  \eng{If \Mpar{n} exceeds strictly the number of terms of \Mpar{x},
    then \Mup{FAIL} is returned. }
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{nthmonomial}
  \infoEng{$n$-th monomial}
  \infoDe{}
  \call{\Mtype{dom} x, \Mtype{positive integer} n}
  \eng{Returns the \Mpar{n}-th monomial of \Mpar{x}.}
  \eng{If \Mpar{n} exceeds strictly the number of terms of \Mpar{x},
    then \Mup{FAIL} is returned. }
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{nthcoeff}
  \infoEng{$n$-th coefficient}
  \infoDe{}
  \call{\Mtype{dom} x, \Mtype{positive integer} n}
  \eng{Returns the \Mpar{n}-th coefficient of \Mpar{x}.}
  \eng{If \Mpar{n} exceeds strictly the number of terms of \Mpar{x},
    then \Mup{FAIL} is returned. }
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{mapcoeffs}
  \infoEng{apply a function on all coefficients}
  \infoDe{}
  \call{\Mtype{dom} x, \Mtype{function} f\Mopt{, option1, \Mseq}}
  \eng{Returns a copy of \Mpar{x}, where each coefficient $c$ has been
    replaced by \Mex{f(c, option1, \Mseq)}. }
  \eng{\Mex{f} should always return elements of the coefficient
    ring. For efficiency reason, this is not necessarily checked.}
\end{MMethodDetails}

\begin{MMethodDetails}{multcoeffs}
  \infoEng{(right) multiplication of all coefficients by a constant}
  \infoDe{}
  \call{\Mtype{dom} x, \Mtype{constant} c}
  \eng{Returns a copy of \Mpar{x}, where all the coefficients have
    been multiplied (on the right) by \Mex{c}.}

  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{multcoeffsLeft}
  \infoEng{left multiplication of all coefficients by a constant}
  \infoDe{}
  \call{\Mtype{constant} c, \Mtype{dom} x}

  \eng{Returns a copy of \Mpar{x}, where all the coefficients have
    been multiplied on the left by \Mex{c}.}
  
  \eng{If the ring is commutative, this method and the method
    \Mslot{multcoeffsLeft} coincide.}

  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{mapsupport}
  \infoEng{apply a function on all elements of the support}
  \infoDe{}
  \call{\Mtype{dom} x, \Mtype{function} f\Mopt{, option1, \Mseq}}
  \eng{Returns a copy of \Mpar{x}, where each element of the support
    $t$ has been replaced by \Mex{f(c, option1, \Mseq)}. }
  \eng{\Mex{f} should always return elements of the underlying
    combinatorial class. For efficiency reason, this is not
    necessarily checked.}
\end{MMethodDetails}


\begin{MChanges}
  \version{3.0}
  \eng[New category]{\Mthis{} is a new category} %
\end{MChanges}

\end{Mhelppage}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: 
