matobj.xml

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!--   matobj.xml               GAP documentation        Max Neunhoeffer  -->
<!--                                                                      -->
<!--   Copyright (C) 2011 The GAP Group                                   -->
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<Chapter Label="Vector and Matrix Objects">
<Heading>Vector and Matrix Objects</Heading>

This chapter describes an interface to vector and matrix objects
which are not represented by plain lists (of plain lists),
cf. Chapters <Ref Chap="Row Vectors"/> and <Ref Chap="Matrices"/>.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Concepts and Rules for Vector and Matrix Objects">
<Heading>Concepts and Rules for Vector and Matrix Objects</Heading>

<#Include Label="MatObj_Overview">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Categories of Vector and Matrix Objects">
<Heading>Categories of Vector and Matrix Objects</Heading>

Currently the following categories of vector and matrix objects
are supported in &GAP;.
More can be added as soon as there is need for them.
<!-- For example, flat matrices? -->

<#Include Label="IsVectorObj">
<#Include Label="IsMatrixObj">
<#Include Label="IsMatrixOrMatrixObj">
<#Include Label="IsRowListMatrix">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Defining Attributes of Vector and Matrix Objects">
<Heading>Defining Attributes of Vector and Matrix Objects</Heading>

<#Include Label="BaseDomain">
<#Include Label="ConstructingFilter">
<#Include Label="CompatibleVectorFilter">
<#Include Label="Length_IsVectorObj">
<#Include Label="NumberRowsNumberColumns">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Constructing Vector and Matrix Objects">
<Heading>Constructing Vector and Matrix Objects</Heading>

<#Include Label="NewVector">
<#Include Label="Vector">
<#Include Label="VectorObj_ZeroVector">
<#Include Label="NewMatrix">
<#Include Label="MatObj_Matrix">
<#Include Label="MatObj_ZeroMatrix">
<#Include Label="MatObj_IdentityMatrix">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Operations for Base Domains of Vector and Matrix Objects">
<Heading>Operations for Base Domains of Vector and Matrix Objects</Heading>

<#Include Label="OneOfBaseDomain">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Operations for Vector and Matrix Objects">
<Heading>Operations for Vector and Matrix Objects</Heading>

<#Include Label="MatrixObjCompare">
<#Include Label="Unpack">
<#Include Label="ChangedBaseDomain">
<#Include Label="Randomize">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="List Like Operations for Vector Objects">
<Heading>List Like Operations for Vector Objects</Heading>

The following operations that are defined for lists are useful
also for vector objects.
(More such operations can be added if this is appropriate.)

<#Include Label="ElementAccessVectorObj">
<#Include Label="MatObj_PositionNonZero">
<#Include Label="MatObj_PositionLastNonZero">
<#Include Label="MatObj_ListOp">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Arithmetical Operations for Vector Objects">
<Heading>Arithmetical Operations for Vector Objects</Heading>

<#Include Label="VectorObj_UnaryArithmetics">
<#Include Label="VectorObj_BinaryArithmetics">
<#Include Label="MatObj_AddVector">
<#Include Label="MatObj_MultVectorLeft">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Operations for Vector Objects">
<Heading>Operations for Vector Objects</Heading>

<#Include Label="MatObj_ConcatenationOfVectors">
<#Include Label="MatObj_ExtractSubVector">
<#Include Label="CopySubVector">
<#Include Label="MatObj_WeightOfVector">
<#Include Label="MatObj_DistanceOfVectors">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Arithmetical Operations for Matrix Objects">
<Heading>Arithmetical Operations for Matrix Objects</Heading>

<#Include Label="MatrixObj_UnaryArithmetics">
<#Include Label="MatrixObj_BinaryArithmetics">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Operations for Matrix Objects">
<Heading>Operations for Matrix Objects</Heading>

<#Include Label="MatObj_MatElm">
<#Include Label="MatObj_SetMatElm">
<#Include Label="ExtractSubMatrix">
<#Include Label="MutableCopyMatrix">
<#Include Label="CopySubMatrix">
<#Include Label="CompatibleVector">
<#Include Label="RowsOfMatrix">
<#Include Label="MatObj_CompanionMatrix">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Operations for Row List Matrix Objects">
<Heading>Operations for Row List Matrix Objects</Heading>

In general, matrix objects are not lists in the sense of <Ref Filt="IsList"/>,
and they need not behave like lists,
that is, they need not obey all the rules for lists that are stated in
Chapter <Ref Chap="Lists"/>.
There are situations where one wants to have matrix objects
that can on the one hand benefit from &GAP;'s method selection,
as is explained in
Section <Ref Sect="Concepts and Rules for Vector and Matrix Objects"/>,
and do on the other hands support access to &GAP; objects that represent
their rows (which are suitable vector objects).
Matrix objects whose
<Ref Attr="ConstructingFilter" Label="for a matrix object"/> value implies
<Ref Filt="IsRowListMatrix"/> support the operations described in this
section.

<P/>

One implementation of such matrices is given by the
<Ref Attr="ConstructingFilter" Label="for a matrix object"/> value
<Ref Filt="IsPlistMatrixRep"/>,
and any row of these matrices is a vector object in
<Ref Filt="IsPlistVectorRep"/>.
Note that these objects do <E>not</E> lie in <Ref Filt="IsList"/>
(and in particular not in <Ref Filt="IsPlistRep"/>),
thus we are allowed to define the above operations only restrictively,
as follows.

<P/>

Unbinding an entry in a row or unbinding a row in a matrix is allowed only
in the last position,
that is, the vector and matrix objects insist on being dense.
All rows of a matrix must have the same length and the same base domain.

<#Include Label="RowListMatObj_[]">
<#Include Label="RowListMatObj_[]_ASS">
<#Include Label="RowListMatObj_{}">
<#Include Label="RowListMatObj_{}_ASS">
<#Include Label="RowListMatObj_IsBound">
<#Include Label="RowListMatObj_Unbind">
<#Include Label="RowListMatObj_Add">
<#Include Label="RowListMatObj_Remove">
<#Include Label="RowListMatObj_Append">
<#Include Label="RowListMatObj_ShallowCopy">
<#Include Label="RowListMatObj_ListOp">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Basic operations for row/column reductions">
<Heading>Basic operations for row/column reductions</Heading>

<#Include Label="MultMatrixRow">
<#Include Label="MultMatrixRowRight">
<#Include Label="MultMatrixColumn">
<#Include Label="MultMatrixColumnLeft">
<#Include Label="AddMatrixRows">
<#Include Label="AddMatrixRowsRight">
<#Include Label="AddMatrixColumns">
<#Include Label="AddMatrixColumnsLeft">
<#Include Label="PositionNonZeroInRow">
<#Include Label="SwapMatrixRows">
<#Include Label="SwapMatrixColumns">
<#Include Label="AddMatrix">
<#Include Label="MultMatrix">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Implementing New Vector and Matrix Objects Types">
<Heading>Implementing New Vector and Matrix Objects Types</Heading>

The first step in the design of a new type of vector or matrix objects
is to create a new filter that serves as the
<Ref Attr="ConstructingFilter" Label="for a vector object"/>
of the new objects,
see the sections <Ref Sect="Available Representations of Vector Objects"/>
and <Ref Sect="Available Representations of Matrix Objects"/>
for an overview of such filters that are already available.

<P/>

Here we list those operations for vector and matrix objects
for which no default methods can be installed.
When one implements a new type of vector or matrix objects
then one has to install specific methods at least for these operations,
in order to make the objects behave as described in this chapter.
It is advisable to install specific methods also for other
operations, for performance reasons.
The installations of default methods can be found in the file
<F>lib/matobj.gi</F> of the &GAP; distribution.
There one can check for which operations it makes sense to overload them
for the new type of vector or matrix objects.
Note that the specific methods must be installed with
<Ref Func="InstallTagBasedMethod"/> whenever the default method is installed
with this function.

<P/>

<E>Vector objects</E>

<List>
<Item>
  <Ref Attr="BaseDomain" Label="for a vector object"/>,
</Item>
<Item>
  <Ref Attr="Length" Label="for a vector object"/>,
</Item>
<Item>
  <Ref Oper="\[\]" Label="for a vector object and an integer"/>,
</Item>
<Item>
  <Ref Oper="\[\]\:\=" Label="for a vector object and an integer"/>
  (with consistency checks if the global option <C>check</C> is not set to
  <K>false</K>),
</Item>
<Item>
  <Ref Oper="\&lt;"/> (see <Ref Oper="\&lt;" Label="for two vector objects"/>),
</Item>
<Item>
  <Ref Attr="ConstructingFilter" Label="for a vector object"/>,
</Item>
<Item>
  <Ref Oper="NewVector"/>
  (with consistency checks if the global option <C>check</C> is not set to
  <K>false</K>, install the method with <Ref Func="InstallTagBasedMethod"/>).
</Item>
</List>

<P/>

<E>Matrix objects</E>

<List>
<Item>
  <Ref Attr="BaseDomain" Label="for a matrix object"/>,
</Item>
<Item>
  <Ref Attr="NumberRows" Label="for a matrix object"/>,
</Item>
<Item>
  <Ref Attr="NumberColumns" Label="for a matrix object"/>,
</Item>
<Item>
  <Ref Oper="MatElm"/>,
</Item>
<Item>
  <Ref Oper="SetMatElm"/>
  (with consistency checks if the global option <C>check</C> is not set to
  <K>false</K>),
</Item>
<Item>
  <Ref Oper="\&lt;"/> (see <Ref Oper="\&lt;" Label="for two matrix objects"/>),
</Item>
<Item>
  <Ref Attr="ConstructingFilter" Label="for a matrix object"/>,
</Item>
<Item>
  <Ref Attr="CompatibleVectorFilter" Label="for a matrix object"/>,
</Item>
<Item>
  <Ref Oper="NewMatrix"/>
  (with consistency checks if the global option <C>check</C> is not set to
  <K>false</K>, install the method with <Ref Func="InstallTagBasedMethod"/>).
</Item>
</List>

<P/>

Methods for <Ref Oper="NewVector"/> and
<Ref Oper="NewMatrix"/> must check their arguments for consistency
(do the given filter and base domain fit together,
are the entries compatible with the given base domain,
is the number of matrix entries a multiple of the given number of columns)
except if the global option <C>check</C> is set to <K>false</K>.
(See Chapter <Ref Chap="Options Stack"/> for information about global
options.)
The same holds for methods for operations that modify mutable vector
or matrix objects,
such as <Ref Oper="\[\]\:\=" Label="for a vector object and an integer"/>,
<Ref Oper="SetMatElm"/>, <Ref Oper="CopySubVector"/>,
<Ref Oper="CopySubMatrix"/>,
and for those methods of
<Ref Oper="Vector" Label="for filter, base domain, and list"/> and
<Ref Oper="Matrix" Label="for filter, base domain, list, ncols"/>
that do not delegate to <Ref Oper="NewVector"/> and
<Ref Oper="NewMatrix"/>, respectively.

<P/>

For the implementation of new vector and matrix object types,
we recommend that the low level function <Ref Func="Objectify"/> gets called
only by some helper functions that handle the choice of the type of
the desired object and the consistency checks for the internal data.
An example can be found in the file <F>lib/matobjplist.gi</F>,
the helper functions are <C>MakeIsPlistVectorRep</C> and
<C>MakeIsPlistMatrixRep</C>.

</Section>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Available Representations of Vector Objects">
<Heading>Available Representations of Vector Objects</Heading>

The following filters define vector objects for which the the functionality
described in this chapter is supported.

<#Include Label="IsGF2VectorRep">
<#Include Label="Is8BitVectorRep">
<#Include Label="IsPlistVectorRep">
<#Include Label="IsZmodnZVectorRep">

</Section>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Available Representations of Matrix Objects">
<Heading>Available Representations of Matrix Objects</Heading>

The following filters define matrix objects for which the the functionality
described in this chapter is supported.

<#Include Label="IsGF2MatrixRep">
<#Include Label="Is8BitMatrixRep">
<#Include Label="IsPlistMatrixRep">
<#Include Label="IsZmodnZMatrixRep">

</Section>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Groups Consisting of Matrix Objects">
<Heading>Groups Consisting of Matrix Objects</Heading>

One application of matrix objects is to construct groups whose elements
are matrix objects.
The following conventions hold for such a group <C>G</C>.

<List>
<Item>
  All elements of <C>G</C> have the same
  <Ref Attr="ConstructingFilter" Label="for a matrix object"/>
  and the same <Ref Attr="BaseDomain" Label="for a matrix object"/>.
  For a given matrix or matrix object <C>M</C>,
  a matrix object that can be multiplied with elements of <C>G</C>
  can be constructed as <C>Matrix( M, Representative( G ) )</C>,
  and the result can be tested for membership in <C>G</C>.
</Item>
</List>

<#Include Label="ConstructingFiltersForMatrixGroupElements">

</Section>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="How to Write Code for Vector and Matrix Objects">
<Heading>How to Write Code for Vector and Matrix Objects</Heading>

Vector and matrix objects have a number of different representations in &GAP;
which are optimised for different things;
see the list <Ref Var="ConstructingFiltersForMatrixGroupElements"/> for
examples of available
<Ref Attr="ConstructingFilter" Label="for a matrix object"/> values
of matrix objects.
Most &GAP; functions accepting vector or matrix objects as arguments
do not depend on any particular representation for these objects.
If the output of such a function involves vector and matrix objects,
then these are expected to have the same representations as the inputs.
For example, a function that computes the Kronecker product of two
matrix objects <C>mat1</C>, <C>mat2</C> may take the two inputs,
which must have the same
<Ref Attr="ConstructingFilter" Label="for a matrix object"/> value,
create a new matrix object which also lies in this filter,
for example by calling <C>ZeroMatrix( m, n, mat1 )</C>,
and then set the entries in this matrix.

<P/>

Functions like
<Ref Oper="ZeroMatrix" Label="for dimensions and matrix object"/>,
<Ref Oper="IdentityMatrix" Label="for dimension and matrix object"/>,
and <Ref Oper="Matrix" Label="for a list and a matrix object"/>
admit different kinds of inputs.
<C>ZeroMatrix( R, m, n )</C> can be used, for example,
if we want to leave the decision about the representation of the result
to &GAP;.
This might be useful if the result of <C>ZeroMatrix( R, m, n )</C> is
the first matrix we create, and then later matrices are created
relative to this matrix.
If we already have a matrix object <C>M</C> and want <C>ZeroMatrix</C>
to return a new matrix object that has the same representation as <C>M</C>,
then <C>ZeroMatrix( R, m, n )</C> may not return a matrix with the expected
representation.
For example, even if we use the same <C>R</C> as before, &GAP; might decide
to use a sparse representation for large enough <C>m</C> and <C>n</C>.
It is possible to create a <C>ZeroMatrix</C> in the same representation
as <C>M</C> by fully specifying this representation as follows
<C>ZeroMatrix( ConstructingFilter( M ), BaseDomain( M ), m, n )</C>.
It is also possible to produce the same result using the more convenient
<C>ZeroMatrix( m, n, M )</C>.

<P/>

This approach works also in many situation where the input involves
the <Q>list of list</Q> matrices in the filter <Ref Filt="IsMatrix"/>.
In practice, the question is often the other way round:
one has old &GAP; code that was written for objects in <Ref Filt="IsMatrix"/>,
and wants to rewrite it such that it works for general matrix objects also.
In such cases, the following guidelines may be useful.

<List>
<Item>
  Use <C>M[i, j]</C> not <C>M[i][j]</C>
  for accessing/assigning matrix entries.
  <P/>
  <E>Reason:</E>
  <C>M[i][j]</C> means to fetch or even create <C>M[i]</C>
  and then take the <C>j</C>-th entry of it.
</Item>
<Item>
  Use <C>ExtractSubMatrix( M, rows, cols )</C> not <C>M{ rows }{ cols }</C>
  for accessing submatrices,
  similarly use <C>CopySubMatrix( src, dst, srows, drows, scols, dcols )</C>.
  <P/>
  <E>Reason:</E>
  The <C>M{ rows }</C> syntax is supported only for
  row-list matrices, see <Ref Filt="IsRowListMatrix"/>.
</Item>
<Item>
  Use <C>ZeroVector( R, n )</C> not <C>[ 1 .. n ] * Zero( R )</C> for
  creating a zero vector over a given domain <C>R</C>.
  <P/>
  <E>Reason:</E>
  The latter syntax creates an unnecessary new object <C>[ 1 .. n ]</C>,
  multiplies each of its entries with <C>Zero( R )</C>
  (not knowing that the result will be <C>Zero( R )</C> in each case),
  and creates not a vector object but a plain list of the results.
</Item>
<Item>
  Use <C>ZeroVector( n, M )</C> not <C>0 * M[1]</C> for a
  given matrix object <C>M</C> with <C>n</C> columns.
  <P/>
  <E>Reason:</E>
  Calling <C>M[1]</C> may have to create an unnecessary new object
  <C>M[1]</C>.
</Item>
<Item>
  Use <Ref Attr="BaseDomain" Label="for a matrix object"/>
  not <Ref Attr="DefaultFieldOfMatrix"/>.
  <P/>
  <E>Reason:</E>
  This is just a conceptual issue, the results should in fact coincide.
  A matrix object <C>M</C> which is not a list of lists stores its
  <Ref Attr="BaseDomain" Label="for a matrix object"/> value.
  For convenience, <C>DefaultFieldOfMatrix( M )</C> is defined
  to return this value (although this need not be a field).
  On the other hand, a list of lists <C>M</C> in <Ref Filt="IsMatrix"/>
  does not store the two attribute values,
  <Ref Attr="DefaultFieldOfMatrix"/> value is computed from the entries
  of <C>M</C>,
  and for convenience, <C>BaseDomain( M )</C> is defined to return the
  <Ref Attr="DefaultFieldOfMatrix"/> value.
</Item>
<Item>
  Do not use the unary versions of
  <Ref Func="ConvertToVectorRep" Label="for a list (and a field)"/>
  and <Ref Func="ConvertToMatrixRep" Label="for a list (and a field)"/>.
  <P/>
  <E>Reason:</E>
  For example, consider the two matrices <C>M1 = [ [ Z(4) ] ]</C> and
  <C>M2 = [ [ Z(4)^3 ] ]</C> over the field with four elements.
  The latter is in fact a matrix over the field with two elements,
  and <C>ConvertToMatrixRep( M2 )</C> turns it into a matrix in
  <Ref Filt="IsGF2MatrixRep"/>, whereas <C>ConvertToMatrixRep( M1 )</C>
  yields a matrix in <Ref Filt="Is8BitMatrixRep"/>.
  Thus computing products or sums of these matrices is more expensive
  than computations with two matrices in <Ref Filt="Is8BitMatrixRep"/>.
</Item>
<Item>
  Use <Ref Oper="ImmutableMatrix"/> and the binary versions of
  <Ref Func="ConvertToVectorRep" Label="for a list (and a field)"/>
  and <Ref Func="ConvertToMatrixRep" Label="for a list (and a field)"/>
  only when creating initial objects
  which need not be compatible with given vectors or matrices.
  <P/>
  <E>Reason:</E>
  The idea behind these functions is to choose a good representation
  for initial data (for example for some expensive MeatAxe computations,
  see Chapter <Ref Chap="The MeatAxe"/>).
  The results of computations with these data should then automatically
  be in the same representation.
  If not then the code in question has problems,
  and <Q>adjusting</Q> the representation of intermediate results by
  calling the abovementioned conversion functions just hides these problems.
</Item>
</List>

Conversely, do <E>not</E> use functions for vector and matrix objects
when you want to create an object that shall be used just as a list.
For example, use <C>ListWithIdenticalEntries( n, Zero( R ) )</C>
not <C>Vector( R, n )</C> in this case.
For creating a list with <C>n</C> entries, you can also first call
<Ref Func="EmptyPlist"/> for creating a big enough list,
and then enter the values.

</Section>

</Chapter>