%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% $Id: AlgebraWithBasis.tex,v 1.1.1.6 2005/01/26 13:42:22 nthiery Exp $
% File:		lib/DOMAINS/CATEGORY/DOC/AlgebraWithBasis.tex
% Authors:	Nicolas M. Thiéry <nthiery@users.sourceforge.net>
% Purpose:	Documentation for the category Cat::AlgebraWithBasis
% Created:	Wed Sep  3 14:50:04 2003
% License:	LGPL
% Project:	MuPAD-Combinat, http://mupad-combinat.sf.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{Mhelppage}{AlgebraWithBasis}{Nicolas M. Thiéry}
  [ImplState=stable,TestState=stable,DocState=stable]
  %\Mproofread{...}{...}{...}

\begin{MInfo}
  \eng{the category of associative algebras with a distinguished basis}
  \de{}
\end{MInfo}

\Mproofread{nthiery}{22/09/2003}{complete, but not proofread}
\Mproofread{hivert}{6/02/2004}{proofread}

\begin{MIntro}
  \eng{\Mex{\Mthis(coeffRing)} represents the category of associative
    \Mex{coeffRing}-algebras with 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::Algebra}{coeffRing}, \Mupc{Cat::ModuleWithBasis}{coeffRing}
\end{MCategories}

\begin{MDetails}
  \eng{A \Mex{\Mthis(coeffRing)} is a \Mpar{coeffRing}-algebra with a distinguished
    basis. The multiplication is typically implemented by extending by
    linearity its definition on the basis elements. }
  \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, dom] : \Mslot{mult2}
    \item{} [dom, coeffRing] : \Mslot{multcoeffs}
    \item{} [coeffRing, dom] : \Mslot{multcoeffsLeft}
    \end{itemize}
    In other words, a \Mthis{} just has to implement the methods
    \Mslot{mult2}, \Mslot{multcoeffs}, and \Mslot{multcoeffsLeft}. Then,
    \Mslot{_mult} will be implemented appropriately to handle all the
    possible ways it can be called in (binary and n-ary internal
    multiplications of elements, left and right multiplications by
    scalar, \Mseq{}). This differs from the plain \Mup{Cat::Algebra}
    category for which the domain has to provide this \Mslot{_mult}
    method. In a future version, this feature will be extended to
    \Mup{Cat::Algebra}.}

  \de{}
\end{MDetails}

\begin{MDomBasEntries}
  \MDomEntry{oneBasis}
  \eng{If the unit of the algebra is a basis element, the index of
    this basis element can be provided here, instead of defining
    \Mslot{one}.}
\end{MDomBasEntries}

\begin{MMethodDetails}{fromCoeffRing}
  \infoEng{natural embedding of the coefficient ring}
  \infoDe{}
  \call{\Mopt{\Mtype{coeffRing} c}}
  \eng{Returns the natural embedding \Mex{c*dom::one} of the
    coefficient \Mex{c} as an element of this algebra.}
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{ground}
  \infoEng{ground coefficient }
  \infoDe{}
  \call{\Mopt{\Mtype{dom} x}}
  \eng{Returns the ground coefficient of x, that is the coefficient of
    \Mpar{x} on the unit of the algebra.}
  \eng{This only makes sense if the unit of the algebra is a basis
    element, so this method is optional. A default implementation is
    provided when \Mslot{oneBasis} is defined.}
  \de{}
\end{MMethodDetails}

\MMathMethods %---------------------------------------------------------------

\begin{MMethodDetails}{mult2Basis}
  \infoEng{binary multiplication of basis elements}
  \infoDe{}
  \call{\Mtype{dom::basisIndices} x, \Mtype{dom::basisIndices} y}
  \eng{Returns the product of the basis elements indexed by \Mpar{x}
    and \Mpar{y}. }
  \eng{The default implementation is \Mslot{multBasis}; so, the domain
    may define either one of them, or both, at the programmers
    convenience. }
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{mult2}
  \infoEng{binary multiplication}
  \infoDe{}
  \call{\Mtype{dom} x, \Mtype{dom} y}
  \eng{Returns the product of \Mpar{x} by \Mpar{y}.}
  \eng{\Mpar{x} and \Mpar{y} are required to be of this domain; no
    coercion is attempted.}
  \eng{The default implementation extends \Mslot{mult2Basis} by bilinearity. }
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{multBasis}
  \infoEng{n-ary multiplication of basis elements}
  \infoDe{}
  \call{\Mopt{\Mtype{dom::basisIndices} x, \Mseq{}}}
  \eng{Returns the product of the basis elements indexed by the arguments. }
  \de{}
\end{MMethodDetails}

\begin{MMethodDetails}{mult}
  \infoEng{n-ary multiplication}
  \infoDe{}
  \call{\Mopt{\Mtype{dom} x, \Mseq{}}}
  \eng{Returns the product of the arguments. If no argument is
    provided, returns the unit of the algebra (\Mslot{one})}.
  \eng{The arguments are required to be of this domain; no coercion
    is attempted.}
  \eng{The default implementation extends \Mslot{mult2} by associativity.
    Sometime in the future, it may instead extend \Mslot{multBasis} by
    multilinearity.}
  \de{}
\end{MMethodDetails}


\begin{MExample}{ex-basic}
  \eng{We define the algebra of the symmetric group on \Mex{4} elements:}
  \begin{Mexin}
domain SymmetricGroupAlgebra(N: Type::NonNegInt)
    inherits Dom::FreeModule(Dom::ExpressionField(),
			     combinat::subClass(combinat::permutations,
                                                Parameters=N));
    category Cat::AlgebraWithBasis(Dom::ExpressionField());

    one := dom::term([$1..N]);
    mult2Basis := dom::term @ combinat::permutations::_mult;
end_domain;
A4 := SymmetricGroupAlgebra(4):
  \end{Mexin} % $
  \begin{Mexout}
  \end{Mexout}
  \eng{Now, we create some elements of \Mex{A4}, and do some
    simple computations with them:}
  \begin{Mexin}
a := A4::one;
a + a;
A4([1,2,3,4]) - A4::one;
a := A4([2,3,4,1]);
a^2;
a^4;
  \end{Mexin}
  \begin{Mexout}
                        B([1, 2, 3, 4])

                       2 B([1, 2, 3, 4])

                               0

                        B([2, 3, 4, 1])

                        B([3, 4, 1, 2])

                        B([1, 2, 3, 4])
  \end{Mexout}
  \eng{Here are some more advanced computations:}
  \begin{Mexin}
3*a + 4/5*A4([1, 3, 2, 4])
  \end{Mexin}
  \begin{Mexout}
            4/5 B([1, 3, 2, 4]) + 3 B([2, 3, 4, 1])
  \end{Mexout}

  \begin{Mexin}
a^2*x + (a*y)^3 + A4::one + A4([3, 2, 1, 4])*z
  \end{Mexin}
  \begin{Mexout}
                     3
z B([3, 2, 1, 4]) + y  B([4, 1, 2, 3]) + x B([3, 4, 1, 2]) +

   B([1, 2, 3, 4])
  \end{Mexout}
\end{MExample}

\begin{MExample}{ex-linear-algebra}
  \eng{Now we demonstrate how to do some basic linear algebra, say to
    find the minimal polynomial of an element of \Mex{A4}:}
  \begin{Mexin}
a := A4([2,3,1,4]);
P := X^0 + x1*X^1 + x2*X^2 + x3*X^3 + x4*X^4;
b := subs(P, X=a);
solution := linsolve([coeff(b)], [x1,x2,x3,x4]);
subs(P, solution);
  \end{Mexin}
  \begin{Mexout}
                        B([2, 3, 1, 4])

                   4       3       2
               x4 X  + x3 X  + x2 X  + x1 X + 1

x2 B([3, 1, 2, 4]) + (x1 + x4) B([2, 3, 1, 4]) +

   (x3 + 1) B([1, 2, 3, 4])

                  [x1 = -x4, x2 = 0, x3 = -1]

                         4    3
                     x4 X  - X  - x4 X + 1
  \end{Mexout}
\end{MExample}

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

\end{Mhelppage}
