<!-- 

  matrices.xml            cvec package documentation           Max Neunhoeffer

  Copyright (C) 2007  Max Neunhoeffer, Lehrstuhl D f. Math., RWTH Aachen
  This file is free software, see license information at the end.

This chapter covers compressed matrices.

-->

<Chapter Label="matrices">
<Heading>Matrices</Heading>

A compressed matrix (a <C>cmat</C>) behaves very much like a list of
<C>cvec</C>s. However, it insists on having only <C>cvec</C>s of the
same length and over the same base field as its elements, and it insists
on being a list without holes. Apart from these restrictions, you can
use all the standard list operations with <C>cmat</C>s (see Section
<Ref Sect="matlists"/>. <P/>

In the rest of this chapter, we document all methods for matrices for the
sake of completeness. If they behave exactly as is to be expected by the
already defined operation no further explanation is given.

<Section Label="matcreation">
<Heading>Creation</Heading>

The basic operation to create new <C>cmat</C>s is <F>CMat</F>, for which
a variety of methods is available:

<ManSection>
<Meth Name="CMat" Arg="l, cl, dochecks"/>
<Meth Name="CMat" Arg="l, cl"/>
<Returns> a new <C>cmat</C> </Returns>
<Description>
    A new <C>cmat</C> is created with rows being in the <C>cvecclass</C>
    <A>cl</A>. All elements of the list <A>l</A> must be <C>cvec</C>s in
    that class. The boolean flag <A>dochecks</A> indicates, whether
    this should be checked or not. If the flag is omitted, checks are
    performed. Note that <A>l</A> may be the empty list.
</Description>
</ManSection>

<ManSection>
<Meth Name="CMat" Arg="l, dochecks"/>
<Meth Name="CMat" Arg="l"/>
<Returns> a new <C>cmat</C> </Returns>
<Description>
    A new <C>cmat</C> is created with rows being in the <C>cvecclass</C>
    of the vectors in <A>l</A>. All elements of the list <A>l</A> must 
    be <C>cvec</C>s in the same class. 
    The boolean flag <A>dochecks</A> indicates, whether
    this should be checked or not. If the flag is omitted, checks are
    performed. Note that <A>l</A> may not be the empty list.
</Description>
</ManSection>

<ManSection>
<Meth Name="CMat" Arg="l, v"/>
<Returns> a new <C>cmat</C> </Returns>
<Description>
    A new <C>cmat</C> is created with rows being in the <C>cvecclass</C>
    of the <C>cvec</C> <A>v</A>. All elements of the list <A>l</A> must 
    be <C>cvec</C>s in the that same class. This is checked.
    Note that <A>l</A> may be the empty list.
</Description>
</ManSection>

<ManSection>
<Meth Name="CMat" Arg="m"/>
<Returns> a new <C>cmat</C> </Returns>
<Description>
Creates a new <C>cmat</C> which is equal to <A>m</A>, which must be a
compressed matrix in the filter <F>IsGF2MatrixRep</F>
or the filter <F>Is8BitMatrixRep</F>.
</Description>
</ManSection>

There are some methods to create <C>cmat</C>s of special form:

<ManSection>
<Func Name="CVEC_ZeroMat" Arg="rows, cl"/>
<Func Name="CVEC_ZeroMat" Arg="rows, cols, p, d"/>
<Returns> a new <C>cmat</C> </Returns>
<Description>
    Creates a zero matrix with <A>rows</A> rows and <A>cols</A> columns
    over the field <C>GF(<A>p</A>,<A>d</A>)</C>. If a <C>cvecclass</C>
    <A>cl</A> is given, the number of columns and the field follow
    from that.
</Description>
</ManSection>

<ManSection>
<Func Name="CVEC_IdentityMat" Arg="cl"/>
<Func Name="CVEC_IdentityMat" Arg="n, p, d"/>
<Returns> a new <C>cmat</C> </Returns>
<Description>
    Creates an identity matrix with <A>n</A> rows and columns
    over the field <C>GF(<A>p</A>,<A>d</A>)</C>. If a <C>cvecclass</C>
    <A>cl</A> is given, the number of columns and the field follow
    from that.
</Description>
</ManSection>

<ManSection>
<Func Name="CVEC_RandomMat" Arg="rows, cl"/>
<Func Name="CVEC_RandomMat" Arg="rows, cols, p, d"/>
<Returns> a new <C>cmat</C> </Returns>
<Description>
    Creates a random matrix with <A>rows</A> rows and <A>cols</A> columns
    over the field <C>GF(<A>p</A>,<A>d</A>)</C>. If a <C>cvecclass</C>
    <A>cl</A> is given, the number of columns and the field follow
    from that. Note that this is not particularly efficient.
</Description>
</ManSection>

<ManSection>
<Meth Name="MutableCopyMat" Arg="m"/>
<Returns> a mutable copy of <A>m</A> </Returns>
<Description>
    Creates a mutable copy of the <C>cmat</C> <A>m</A>.
</Description>
</ManSection>

<ManSection>
<Meth Name="Matrix" Arg="vectorlist, vector"/>
<Meth Name="MatrixNC" Arg="vectorlist, vector"/>
<Returns> a new mutable <C>cmat</C> </Returns>
<Description>
    Returns a new <C>cmat</C> containing the vectors in
    <A>vectorlist</A> as rows. The elements in <A>vectorlist</A> must be
    vectors of the same length as the sample vector <A>vector</A> and must
    live over the same base field. The sample
vector is always necessary to be able to use the method selection. The
<A>vectorlist</A> may be empty. The NC method does not check the inputs.
</Description>
</ManSection>

</Section>

<Section Label="matlists">
<Heading>Matrices as lists</Heading>

In this section, arguments named <A>m</A> and <A>n</A> are <C>cmat</C>s
and <A>v</A> and <A>w</A> are <C>cvec</C>s that fit into the corresponding
matrices. <A>pos</A> is an integer between <M>1</M> and <C>Length(m)</C>
if it applies to the matrix <A>m</A>.

<ManSection>
<Meth Name="Add" Arg="m, v [,pos]"/>
<Returns> nothing </Returns>
<Description>
Behaves exactly as expected. Note that one can only add <C>cvec</C>s of the
right length and over the right field.
</Description>
</ManSection>

<ManSection>
<Meth Name="Remove" Arg="m [, pos]"/>
<Returns> a <C>cvec</C> </Returns>
<Description>
Behaves exactly as expected. No holes can be made.
</Description>
</ManSection>

<ManSection>
<Meth Name="ELM_LIST" Arg="m, pos"/>
<Returns> a <C>cvec</C> </Returns>
<Description>
    Behaves exactly as expected. Note that this method is triggered when
    one uses the (reading) syntax <Q><C>m[pos]</C></Q>.
</Description>
</ManSection>

<ManSection>
<Meth Name="ASS_LIST" Arg="m, pos, v"/>
<Returns> nothing </Returns>
<Description>
    Behaves exactly as expected. Note that one can only assign to positions
    such that the resulting matrix has no holes. This method is triggered
    when one uses the (assignment) syntax <Q><C>m[pos] := </C></Q>.
</Description>
</ManSection>

<ManSection>
<Meth Name="ELMS_LIST" Arg="m, poss"/>
<Returns> a sub <C>cmat</C></Returns>
<Description>
    Behaves exactly as expected: A new matrix containing a subset of the
    rows is returned. Note that the row vectors are the same &GAP; objects
    as the corresponding rows of <A>m</A>. This operation is triggered
    by the expression <A>m</A><C>{<A>poss</A>}</C>.
</Description>
</ManSection>

<ManSection>
    <Meth Name="ASSS_LIST" Arg="m, poss, vals"/>
<Returns> nothing </Returns>
<Description>
    Behaves exactly as expected. Of course all values in <A>vals</A>
    must be <C>cvec</C>s over the correct field and the <C>cmat</C>
    <A>m</A> must be a dense list afterwards. This operation is triggered
    by the statement <A>m</A><C>{<A>poss</A>} := <A>vals</A></C>.
</Description>
</ManSection>

<ManSection>
<Meth Name="Length" Arg="m"/>
<Returns> the number of rows of the <C>cmat</C> <A>m</A></Returns>
<Description>
Behaves exactly as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="ShallowCopy" Arg="m"/>
<Returns> a new matrix containing the same rows than the <C>cmat</C> <A>m</A>
</Returns>
<Description>
    Behaves exactly as expected. Note that the rows of the result are the very
    same &GAP; objects than the rows of the <C>cmat</C> <A>m</A>.
</Description>
</ManSection>

<ManSection>
<Meth Name="Collected" Arg="m"/>
<Returns> the same as the collected list of the rows of <A>m</A></Returns>
<Description>
    Behaves exactly as expected. Just uses the standard 
    <Ref Oper="Collected" BookName="Ref"/> on the list of rows.
</Description>
</ManSection>

<ManSection>
<Meth Name="DuplicateFreeList" Arg="m"/>
<Returns> a new mutable <C>cmat</C> containing the rows of <A>m</A>
with duplicates removed</Returns>
<Description>
    Behaves exactly as expected. Just uses the standard 
    <Ref Oper="DuplicateFreeList" BookName="Ref"/> on the list of rows.
</Description>
</ManSection>

<ManSection>
<Meth Name="Append" Arg="m, n"/>
<Returns> nothing </Returns>
<Description>
    Behaves exactly as expected. Of course, the <C>cmat</C>s <A>m</A> and
    <A>n</A> must be over the same field and have the same number of
    columns. Note that the rows of <A>n</A> themselves (and no copies)
    will be put into the matrix <A>m</A>.
</Description>
</ManSection>

<ManSection>
<Meth Name="Filtered" Arg="m, f"/>
<Returns> a new <C>cmat</C> containing some of the rows of <A>m</A></Returns>
<Description>
    Behaves exactly as expected. The function <A>f</A> will be called for
    each row of <A>m</A>.
</Description>
</ManSection>

<ManSection>
<Meth Name="Unbind" Arg="m, f"/>
<Returns> nothing </Returns>
<Description>
    Behaves exactly as expected. Of course, only the last bound row may be
    unbound.
</Description>
</ManSection>

</Section>

<Section Label="arithmetic">
<Heading>Arithmetic</Heading>

Of course, the standard arithmetic infix operations <M>+</M>, <M>-</M> and
<M>*</M> (for vectors and scalars) work as expected by using the  
methods below. The comments on the usage of
scalars in arithmetic operations involving vectors from Subsection
<Ref Subsect="scahandl"/> apply analogously.

<ManSection>
<Meth Name="\+" Arg="m, n" Label="cmatcmat"/>
<Returns>the sum <M><A>m</A>+<A>n</A></M> as a new <C>cmat</C></Returns>
<Description>
    For two <C>cmat</C>s <A>m</A> and <A>n</A>. Works as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="\-" Arg="m, n" Label="cmatcmat"/>
<Returns>the difference <M><A>m</A>-<A>n</A></M> as a new <C>cmat</C></Returns>
<Description>
    For two <C>cmat</C>s <A>m</A> and <A>n</A>. Works as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="AdditiveInverseSameMutability" Arg="m" Label="cmat"/>
<Meth Name="\-" Arg="m" Label="cmat"/>
<Returns>the additive inverse of <A>m</A> as a new <C>cmat</C></Returns>
<Description>
For a <C>cmat</C> <A>m</A>. Works as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="AdditiveInverseMutable" Arg="m" Label="cmat"/>
<Returns>the additive inverse of <A>m</A> as a new mutable <C>cmat</C>
</Returns>
<Description>
For a <C>cmat</C> <A>m</A>. Works as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="\*" Arg="m, s" Label="cmatsca"/>
<Meth Name="\*" Arg="s, m" Label="scacmat"/>
<Returns>the scalar multiple <A>s</A><M>\cdot</M><A>m</A></Returns>
<Description>
    For a <C>cmat</C> <A>m</A> and a scalar <A>s</A>. For the format
    of the scalar see <Ref Subsect="scahandl"/>. Works as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="\*" Arg="v, m" Label="cveccmat"/>
<Returns>the product <A>v</A><M>\cdot</M><A>m</A></Returns>
<Description>
    For a <C>cmat</C> <A>m</A> and a <C>cvec</C> <A>s</A> with the same
    length as the number of rows of <A>m</A>. Works as expected. Note
    that there is a very fast method for the case that <A>m</A> is
    pre-greased (see <Ref Sect="greasemat"/>).
</Description>
</ManSection>

<ManSection>
<Meth Name="\^" Arg="v, m" Label="cveccmat"/>
<Returns>the product <A>v</A><M>\cdot</M><A>m</A></Returns>
<Description>
    For a <C>cmat</C> <A>m</A> and a <C>cvec</C> <A>s</A> with the same
    length as the number of rows of <A>m</A>. Works as expected. Note
    that there is a very fast method for the case that <A>m</A> is
    pre-greased (see <Ref Sect="greasemat"/>).
</Description>
</ManSection>

<ManSection>
<Meth Name="\*" Arg="m, n" Label="cmatcmat"/>
<Returns>the product <A>m</A><M>\cdot</M><A>n</A></Returns>
<Description>
    Of course, the <C>cmat</C> <A>m</A> must have as many columns as
    the <C>cmat</C> <A>n</A> has rows. Works as expected. Note that
    there is a very fast method for the case that <A>n</A> is pre-greased
    (see <Ref Sect="greasemat"/>).
</Description>
</ManSection>

<ManSection>
<Meth Name="ZeroSameMutability" Arg="m" Label="cmat"/>
<Returns>the zero <C>cmat</C> over the same field and with the same
    dimensions as <A>m</A>
</Returns>
<Description>
<A>m</A> must be a <C>cmat</C>.
</Description>
</ManSection>

<ManSection>
<Meth Name="ZeroMutable" Arg="m" Label="cmat"/>
<Returns>a mutable copy of the zero <C>cmat</C> over the same field and
    with the same dimensions as <A>m</A>
</Returns>
<Description>
<A>m</A> must be a <C>cmat</C>.
</Description>
</ManSection>

<ManSection>
<Meth Name="OneSameMutability" Arg="m" Label="cmat"/>
<Returns>the identity <C>cmat</C> over the same field and with the same
    dimensions as <A>m</A>
</Returns>
<Description>
<A>m</A> must be a square <C>cmat</C>.
</Description>
</ManSection>

<ManSection>
<Meth Name="OneMutable" Arg="m" Label="cmat"/>
<Returns>a mutable copy of the identity <C>cmat</C> over the same field and
    with the same dimensions as <A>m</A>
</Returns>
<Description>
<A>m</A> must be a square <C>cmat</C>.
</Description>
</ManSection>

<ManSection>
<Meth Name="InverseMutable" Arg="m"/>
<Returns> the multiplicative inverse of <A>m</A></Returns>
<Description>
    If the <C>cmat</C> is not square or not invertible then <C>fail</C>
    is returned. Behaves exactly as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="InverseSameMutability" Arg="m"/>
<Returns> the multiplicative inverse of <A>m</A></Returns>
<Description>
    If the <C>cmat</C> is not square or not invertible then <C>fail</C>
    is returned. Behaves exactly as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="TransposedMat" Arg="m"/>
<Returns> the transpose of <A>m</A></Returns>
<Description>
    Behaves exactly as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="KroneckerProduct" Arg="m, n"/>
<Returns> the Kronecker product of <A>m</A> and <A>n</A> </Returns>
<Description>
    Behaves exactly as expected.
</Description>
</ManSection>

</Section>


<Section Label="comparemat">
<Heading>Comparison of matrices and other information</Heading>

<ManSection>
<Meth Name="=" Arg="m, n"/>
<Returns><C>true</C> or <C>false</C></Returns>
<Description>
    Returns <C>true</C> if the <C>cmat</C>s <A>m</A> and <A>n</A> are
    equal. The matrices must be over the same field and must have equal
    dimensions.
</Description>
</ManSection>

<ManSection>
    <Meth Name="LT" Arg="m, n"/>
<Returns><C>true</C> or <C>false</C></Returns>
<Description>
    Returns <C>true</C> if the <C>cmat</C> <A>m</A> is smaller than <A>n</A>.
    The matrices must be over the same field and must have equal
    dimensions. The method implements the lexicographic order and uses
    <Ref Meth="LT"/> for the ordering of vectors.
    Note that the operation <C>LT</C> is the same as <C>&bslash;&lt;</C>.
</Description>
</ManSection>

<ManSection>
<Meth Name="IsZero" Arg="m"/>
<Returns><C>true</C> or <C>false</C></Returns>
<Description>
    Returns <C>true</C> if the <C>cmat</C> <A>m</A> is equal to zero, meaning
    that all entries are equal to zero.
</Description>
</ManSection>

<ManSection>
<Meth Name="IsOne" Arg="m"/>
<Returns><C>true</C> or <C>false</C></Returns>
<Description>
    Returns <C>true</C> iff the <C>cmat</C> <A>m</A> is equal to the identity
    matrix.
</Description>
</ManSection>

<ManSection>
<Meth Name="IsDiagonalMat" Arg="m"/>
<Returns><C>true</C> or <C>false</C></Returns>
<Description>
    Returns <C>true</C> iff the <C>cmat</C> <A>m</A> is a diagonal matrix.
</Description>
</ManSection>

<ManSection>
<Meth Name="IsUpperTriangularMat" Arg="m"/>
<Returns><C>true</C> or <C>false</C></Returns>
<Description>
    Returns <C>true</C> iff the <C>cmat</C> <A>m</A> is an upper triangular 
    matrix.
</Description>
</ManSection>

<ManSection>
<Meth Name="IsLowerTriangularMat" Arg="m"/>
<Returns><C>true</C> or <C>false</C></Returns>
<Description>
    Returns <C>true</C> iff the <C>cmat</C> <A>m</A> is a lower triangular 
    matrix.
</Description>
</ManSection>

<ManSection>
<Func Name="CVEC_HashFunctionForCMats" Arg="m, data"/>
<Returns>an integer hash value</Returns>
<Description>
    This is a hash function usable for the <Ref Oper="ChooseHashFunction"
BookName="orb"/> framework. It takes as arguments a <C>cmat</C>
<A>m</A> and a list <A>data</A> of length <M>2</M>. The first entry of
<A>data</A> is the length of the hash table used and the second entry
is the number of bytes looked at in the <C>cvec</C>s in the matrices.
</Description>
</ManSection>

<ManSection>
<Meth Name="ChooseHashFunction" Arg="m, l"/>
<Returns> a record with entries <C>func</C> and <C>data</C>.</Returns>
<Description>
    Chooses a hash function to be used for <C>cmat</C>s like <A>m</A>
    (that is, over the same field with the same number of columns) and
    for hash tables of length <A>l</A>. The hash function itself is
    stored in the <C>func</C> component of the resulting record. The
    hash function has to be called with two arguments: the first must
    be a matrix like <A>m</A> and the second must be the value of the
    <C>data</C> component of the resulting record.
</Description>
</ManSection>

</Section>

<Section Label="slicingmat">
<Heading>Slicing and submatrices</Heading>

As described in Section <Ref Sect="matlists"/> you can use the slicing
operator <C>&bslash;&obrace;&bslash;&cbrace;</C> for read and write
access of a subset of the rows of a <C>cmat</C>. However, the double
slicing operator is not supported. The reason for this is twofold: First
there is a technical issue that the double slicing operator cannot easily
be overloaded in the &GAP; system. The second is, that very often the
double slicing operator is used to copy a part of one matrix to another
part of another matrix using double slicing on both sides of an assignment.
This is quite inefficient because it creates an intermediate object, namely
the submatrix which is extracted.

<P/>
Therefore we have chosen to support submatrix access through two operations
<Ref Oper="ExtractSubMatrix"/> and <Ref Oper="CopySubMatrix"/> described
below.

<ManSection>
<Oper Name="ExtractSubMatrix" Arg="m, rows, cols"/>
<Returns> a submatrix of <A>m</A> </Returns>
<Description>
    This operation extracts the submatrix of the matrix <A>m</A> consisting
    of the rows described by the integer list (or range) <A>rows</A> and
    of the columns described by the integer list (or range) <A>cols</A>.
    This is thus equivalent to the usage 
    <A>m</A><C>&obrace;</C><A>rows</A><C>&cbrace;&obrace;</C><A>cols</A><C>&cbrace;</C>. 
    Note that the latter does not work for <C>cmat</C>s,
    whereas a quite efficient method for <Ref Oper="ExtractSubMatrix"/>
    is available for <C>cmat</C>s.
</Description>
</ManSection>

<ManSection>
<Oper Name="CopySubMatrix" Arg="src, dst, srows, drows, scols, dcols"/>
<Returns> nothing </Returns>
<Description>
    This operation extracts the submatrix of the matrix <A>src</A> consisting
    of the rows described by the integer list (or range) <A>srows</A> and
    of the columns described by the integer list (or range) <A>scols</A> and
    copies it into the submatrix of <A>dst</A> described by the integer lists
    (or ranges) <A>drows</A> and <A>dcols</A>. No intermediate object is
    created.
    This is thus equivalent to the usage 
    <A>dst</A><C>&obrace;</C><A>drows</A><C>&cbrace;&obrace;</C><A>dcols</A><C>&cbrace; := </C><A>src</A><C>&obrace;</C><A>srows</A><C>&cbrace;&obrace;</C><A>scols</A><C>&cbrace;</C>. 
    Note that the latter does not work for <C>cmat</C>s,
    whereas a quite efficient method for <Ref Oper="CopySubMatrix"/>
    is available for <C>cmat</C>s.
</Description>
</ManSection>

</Section>

<Section Label="matinfo">
<Heading>Information about matrices</Heading>

<ManSection>
<Meth Name="BaseField" Arg="m" Label="cmat"/>
<Returns>the base field of <A>m</A>
</Returns>
<Description>
    For a <C>cmat</C> <A>m</A> this returns
    the &GAP; object <C>GF(p,d)</C> corresponding to the base field of
    <A>m</A>. Note that this is a relatively fast lookup.
</Description>
</ManSection>

<ManSection>
<Meth Name="Characteristic" Arg="m" Label="cmat"/>
<Returns>the characteristic of the base field of <A>m</A>
</Returns>
<Description>
    Returns the characteristic of the base field of <A>m</A> (see
    <Ref Meth="BaseField" Label="cmat"/>).
</Description>
</ManSection>

<ManSection>
<Meth Name="DegreeFFE" Arg="m" Label="cmat"/>
<Returns>the degree of the base field of <A>m</A> over its prime field
</Returns>
<Description>
    Returns the degree of the base field of <A>m</A> over its prime field (see
    <Ref Meth="BaseField" Label="cmat"/>).
</Description>
</ManSection>

<ManSection>
<Meth Name="DefaultField" Arg="m" Label="cmat"/>
<Returns>the base field of <A>m</A></Returns>
<Description>
    For a <C>cmat</C> <A>m</A> this returns
    the &GAP; object <C>GF(p,d)</C> corresponding to the base field of
    <A>m</A>. Note that this is a relatively fast lookup.
</Description>
</ManSection>

</Section>

<Section Label="matio">
<Heading>Input and output</Heading>

<ManSection>
<Meth Name="CVEC_WriteMat" Arg="f, m"/>
<Returns><C>true</C> or <C>fail</C></Returns>
<Description>
    <A>f</A> must be a file object from the <Package>IO</Package> package (see
    <Ref Filt="IsFile" BookName="IO"/>) and <A>m</A> must be a <C>cmat</C>.
    The matrix <A>m</A> is written to the file <A>f</A>. Note that
    the format (see Section <Ref Sect="extrep"/>) is platform
    independent, such that matrices can be exchanged between different
    architectures. The result is <C>true</C> or <C>fail</C> depending
    on whether everything worked or an error occurred respectively.
</Description>
</ManSection>

<ManSection>
<Meth Name="CVEC_WriteMatToFile" Arg="fn, m"/>
<Returns><C>true</C> or <C>fail</C></Returns>
<Description>
    <A>fn</A> must be a string object containing a file name
    and <A>m</A> must be a <C>cmat</C>.
    The matrix <A>m</A> is written to the file with name <A>fn</A>
    on the local storage. Note that
    the format (see Section <Ref Sect="extrep"/>) is platform
    independent, such that matrices can be exchanged between different
    architectures. The result is <C>true</C> or <C>fail</C> depending
    on whether everything worked or an error occurred respectively.
</Description>
</ManSection>

<ManSection>
<Meth Name="CVEC_WriteMatsToFile" Arg="fnpref, l"/>
<Returns><C>true</C> or <C>fail</C></Returns>
<Description>
    <A>fnpref</A> must be a string object containing a file name prefix
    and <A>m</A> must be a list of <C>cmat</C>s.
    The matrices in <A>l</A> are written to the files with names determined
    by using the string <A>fnpref</A> and appending the natural numbers
    from <M>1</M> to the length of <A>l</A> on the local storage. Note that
    the format (see Section <Ref Sect="extrep"/>) is platform
    independent, such that matrices can be exchanged between different
    architectures. The result is <C>true</C> or <C>fail</C> depending
    on whether everything worked or an error occurred respectively.
</Description>
</ManSection>

<ManSection>
<Meth Name="CVEC_ReadMat" Arg="f"/>
<Returns>a <C>cmat</C> or <C>fail</C> </Returns>
<Description>
    <A>f</A> must be a file object from the <Package>IO</Package> package (see
    <Ref Filt="IsFile" BookName="IO"/>).
    A matrix is read from the file <A>f</A>. Note that
    the format (see Section <Ref Sect="extrep"/>) is platform
    independent, such that matrices can be exchanged between different
    architectures. The result is <C>fail</C> if
    an error occurred.
</Description>
</ManSection>

<ManSection>
<Meth Name="CVEC_ReadMatFromFile" Arg="fn"/>
<Returns> a <C>cmat</C> or <C>fail</C></Returns>
<Description>
    <A>fn</A> must be a string object containing a file name.
    A matrix is read from the file with name <A>fn</A>
    on the local storage. Note that
    the format (see Section <Ref Sect="extrep"/>) is platform
    independent, such that matrices can be exchanged between different
    architectures. The result is <C>fail</C> if
    an error occurred.
</Description>
</ManSection>

<ManSection>
<Meth Name="CVEC_ReadMatsFromFile" Arg="fnpref"/>
<Returns>a list of <C>cmat</C>s or <C>fail</C></Returns>
<Description>
    <A>fnpref</A> must be a string object containing a file name prefix.
    A list of matrices is read from the files with names determined
    by using the string <A>fnpref</A> and appending the natural numbers
    from <M>1</M> on from the local storage. The number of matrices
    read is determined by the highest number such that the corresponding
    filename exists in the filesystem. Note that
    the format (see Section <Ref Sect="extrep"/>) is platform
    independent, such that matrices can be exchanged between different
    architectures. The result is <C>fail</C> if
    an error occurred.
</Description>
</ManSection>

</Section>

<Section Label="greasemat">
<Heading>Grease</Heading>

The basic idea behind the <Q>grease</Q> technique is that over a finite 
field there are only finitely many linear combinations of a fixed list
of vectors. Thus, many operations including matrix multiplication can be
speeded up by precomputing all possible linear combinations and then just
looking up the right one. For the case of matrix multiplication this can
for example gain a factor of about <M>4</M> over the field with
<M>2</M> elements using <Q>grease level<M>8</M></Q>, which means that
for blocks of <M>8</M> rows all linear combinations are precomputed.

<P/>
The <Package>cvec</Package> uses grease whenever appropriate automatically
for example for matrix multiplication. However, occasionally the user
has to take a conscious decision, which matrices to grease, because this 
of course uses more memory.

<P/>
A <C>cmat</C> can be <Q>pre-greased</Q> with level <M>l</M>, which means that 
it is chopped into chunks of <M>l</M> rows and for each such chunk all
possible linear combinations are precomputed and stored. This increases
the memory used to store the matrix by a factor of <M>q^l</M> if the 
base field of the matrix has <M>q</M> elements. However, operations like
vector matrix multiplication and matrix matrix multiplication (here the
right hand side matrix must be greased!) are speeded up. As a rule of
thumb the factor one can hope for is about <M>l \cdot (q-1)/q</M>.
Note that for big matrices matrix multiplication does greasing on the
fly anyway and therefore one cannot hope for such a big factor by
pre-greasing.


<ManSection>
<Oper Name="GreaseMat" Arg="m, l"/>
<Oper Name="GreaseMat" Arg="m"/>
<Returns>nothing</Returns>
<Description>
    <A>m</A> must be a <C>cmat</C>. It is pregreased with level <A>l</A>.
    Without the argument <A>l</A> a grease level depending of the field
    size is chosen automatically. Note that the matrix will need much more
    memory when pregreased.
</Description>
</ManSection>

<ManSection>
<Oper Name="UnGreaseMat" Arg="m"/>
<Returns>nothing</Returns>
<Description>
    <A>m</A> must be a <C>cmat</C>. The pregreased information is deleted.
    This can save a lot of memory.
</Description>
</ManSection>

</Section>

<Section Label="sonst">
<Heading>Everything else</Heading>

<ManSection>
<Meth Name="Randomize" Arg="m" Label="cmat"/>
<Meth Name="Randomize" Arg="m, rs" Label="cmatrandomsource"/>
<Returns>the matrix <A>m</A></Returns>
<Description>
<A>m</A> must be a <C>cmat</C> and <A>rs</A> must be a random source
object if given. This method changes the matrix <A>m</A> in place by
(pseudo) random values in the field over which the matrix lives. If
a random source is given, the pseudo random numbers used are taken from
this source, otherwise the global random source in the &GAP; library
is taken.
</Description>
</ManSection>

<ManSection>
<Func Name="OverviewMat" Arg="m" Label="cmat"/>
<Returns> nothing </Returns>
<Description>
    An ASCII art overview over the <C>cmat</C> <A>m</A> is printed.
    Stars indicate nonzero blocks in the matrix and dots zero blocks.
</Description>
</ManSection>

<ManSection>
<Meth Name="Unpack" Arg="m" Label="cmat"/>
<Returns>a list of lists of finite field elements</Returns>
<Description>
    This operation unpacks a <C>cmat</C> <A>m</A>. A new plain list of plain
    lists containing
    the corresponding numbers as &GAP; finite field elements. Note that
    the matrix <A>m</A> remains unchanged.
</Description>
</ManSection>

</Section>

<!-- ############################################################ -->

</Chapter>

<!--
  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License,
  or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-->

