% $Id: SparseMatrix_LinBox.tex,v 1.1.1.3 2004/10/04 17:25:13 nthiery Exp $
\begin{Mhelppage}{SparseMatrix_LinBox}{N.~Thiéry}
  [ImplState=beta,TestState=alpha,DocState=alpha]
%\Mproofread{...}{...}{...}

\begin{MInfo}
\eng{Interface to the sparse matrix C++ library LinBox}
\end{MInfo}

\begin{MIntro}
  \eng{\Mthis\Mex{(R)} creates a domain for sparse matrices over the
    ring \Mex{R}, with computations done by
    \Mhref{http://linalg.org/}{linbox}.}
\end{MIntro}

\begin{MDomConst}
  \MCall{R}
\end{MDomConst}

\begin{MParameters}
 \param{R}
\eng{a ring}
\end{MParameters}

\begin{MDetails}
  \eng{Experimental. You need to have \texttt{Linbox} installed
    separately.  More precisely, our interface currently uses the
    little binary \texttt{smithform\_gap} that Jean-Guillaume Dumas
    wrote for his \texttt{gap} interface. All you have to do is to
    download the appropriate homology binary package form
    \url{http://www.linalg.org/gap.html}, and put the included
    \texttt{smithform\_gap} binary somewhere on your path.}
\end{MDetails}

\begin{MIntro}
  \eng{}
\end{MIntro}

\begin{MDomElConst}
  \MCall[\Mthis(n)]{l}
\end{MDomElConst}

\begin{MParameters}
  \param{l}
  \eng{}
\end{MParameters}

\begin{MCategories}
%  \Mup{...}
\end{MCategories}

%\MRelatedDomains{}

\begin{MDomEntries}
  \MDomEntry{linbox}
  \eng{the name of the LinBox executable.}
\end{MDomEntries}

%\MMathMethods

%\begin{MMethodDetails}{order}
%\infoEng{order of a permutation}
% \infoDe{}
% \call{\Mtype{dom} a}
% \eng{The order of \Mex{a} is defined to be the least positive integer
% \Mex{k} for which $a^k$ is the identity.}
% \de{}
% \end{MMethodDetails}

\MAccessMethods

\begin{MMethodDetails}{matdim}
  \infoEng{size of a matrix}
  \call{\Mtype{dom}}
  \eng{Returns the size of the matrix as a list of two integers
    \Mex{[nrows, ncols]}.}
\end{MMethodDetails}

\begin{MMethodDetails}{rank}
  \infoEng{rank of a matrix}
  \call{\Mtype{dom} m}
  \eng{Returns the rank of the matrix. Computed by LinBox using
    blackbox method.}
\end{MMethodDetails}

\begin{MMethodDetails}{rankGauss}
  \infoEng{rank of a matrix}
  \call{\Mtype{dom} m}
  \eng{Returns the rank of the matrix. Computed by LinBox using
    gauss elimination.}
\end{MMethodDetails}

\begin{MMethodDetails}{characteristicColumns}
  \infoEng{characteristic columns of a matrix}
  \call{\Mtype{dom} m}
  \eng{Returns a list of indexes of columns of the matrix which are
    linearly independent. Computed by LinBox using elimination.}
\end{MMethodDetails}

%\MConvMethods
\begin{MExample}{ex1}
  \eng{Here is a sample session:}
  \begin{Mvin}{test=false}
Z5 := Dom::IntegerMod(5):
M:=Dom::SparseMatrix_LinBox(Z5);
m:=M();
m:=m::dom::appendRow(m, [[4,Z5(3)]]);
m:=m::dom::appendRow(m, [[2,Z5(7)],[3,Z5(4)]]);
m:=m::dom::appendRow(m, [[1,Z5(3)],[2,Z5(8)]]);
m:=m::dom::fix(m);
m::dom::matdim(m);
m::dom::file(m);
system("cat /tmp/matrix"):
m::dom::rank(m);			// Broken
m::dom::rankGauss(m);
m::dom::characteristicColumns(m);
  \end{Mvin}{test=false}
  \begin{Mvout}{test=false}
         Dom::SparseMatrix_LinBox(Dom::IntegerMod(5))

        <LinBox matrix, file="/tmp/matrix", size=0x0 >

        <LinBox matrix, file="/tmp/matrix", size=1x4 >

        <LinBox matrix, file="/tmp/matrix", size=2x4 >

        <LinBox matrix, file="/tmp/matrix", size=3x4 >

        <LinBox matrix, file="/tmp/matrix", size=3x4 >

                            [3, 4]

                         "/tmp/matrix"
0 0 M
1 4 3
2 2 2
2 3 4
3 1 3
3 2 3
0 0 0
#I:D   Wiedemann: Computing rank via Wiedemann algorithm
#I:D   Wiedemann: Computing rank mod 5 in GF(15625).
#I:D   Wiedemann: Rank 0, computed deterministically.
#I:T   Wiedemann: cpu  time : 0.13 seconds
#I:T   Wiedemann: sys  time : 0 seconds
#I:T   Wiedemann: real time : 0.168739 seconds

                               3
#I:D   Gauss Reordering: 4 x 3
#I:R   Gauss Reordering: Rank : 3 over GF(5)
#I:T   Gauss Reordering: cpu  time : 0 seconds
#I:T   Gauss Reordering: sys  time : 0 seconds
#I:T   Gauss Reordering: real time : 9.0003e-05 seconds

                               3
#I:D   Gauss Reordering: 4 x 3
#I:R   Gauss Reordering: Rank : 3 over GF(5)
#I:T   Gauss Reordering: cpu  time : 0 seconds
#I:T   Gauss Reordering: sys  time : 0 seconds
#I:T   Gauss Reordering: real time : 0.00518698 seconds

                           [0, 1, 3]
  \end{Mvout}
\end{MExample}

%\MSuperDomain{Dom::PermutationGroup}

%\begin{MAxioms}
%  \Mup{Ax::canonicalRep}
%\end{MAxioms}

%\begin{MBackground}
%\end{MBackground}

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

\end{Mhelppage}
