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.
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]" Label="for a list and a cvec"/>
<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]" Label="for a list"/>
<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" Label="for an integer and a cvec"/>
<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" Label="for a cmat"/>
<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" Label="for an integer and a cvecclass"/>
<Func Name="CVEC_ZeroMat" Arg="rows, cols, p, d" Label="for four integers"/>
<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" Label="for a cvecclass"/>
<Func Name="CVEC_IdentityMat" Arg="n, p, d" Label="for three integers"/>
<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" Label="for an integer and a cvecclass"/>
<Func Name="CVEC_RandomMat" Arg="rows, cols, p, d" Label="for four integers"/>
<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" Label="for matrices"/>
<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" Label="for matrices"/>
<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" Label="for matrices"/>
<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" Label="for matrices"/>
<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" Label="for matrices"/>
<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>
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" Label="for matrices"/>
<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" Label="for matrices"/>
<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" Label="for vectors"/> for the ordering of vectors.
Note that the operation <C>LT</C> is the same as <C>&bslash;<</C>.
</Description>
</ManSection>
<ManSection>
<Meth Name="IsZero" Arg="m" Label="for a matrix"/>
<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" Label="for matrices"/>
<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>
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]"/>
<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>
<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>
<!-- 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
-->
¤ Dauer der Verarbeitung: 0.15 Sekunden
(vorverarbeitet)
¤
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
