Skip to content

Commit

Permalink
attempt to make vector and matrix objects official
Browse files Browse the repository at this point in the history 
- turned the raw documentation for vector and matrix objects into
  GAPDoc format, which is included in the GAP Reference Manual;
  this concerns also row list matrices (`lib/matobjplist.gd`);
  the manual chapter "Matrix Objects" now contains the relevant information,
  still some material will have to be moved between the chapters
  "Matrices" and "Matrix Objects"

- added a preliminary version of missing default methods;
  due to that, many tests from GAP's test suite now fail;
  apparently the 'IsMatrixObj' methods get higher rank than the
  methods for `IsPlistRep` matrices, note that some of the latter ones
  do not require `IsMatrix` but just `IsListDefault`;
  and note that some `IsMatrixObj` methods do not only override
  methods for `IsPlistRep` matrices but also methods for other
  wrapped objects which claim to be in `IsMatrix`, such as some basis objects
  and Lie objects

- default methods using 'Unpack' must make sure that they are not
  called with `IsPlistRep` arguments,
  in order to avoid recursion depth traps or segmentation faults;
  this is due to the decision that `IsMatrix` implies `IsMatrixObj`
  --it would be technically easier to separate the worlds of `IsMatrix`
  and `IsMatrixObj`, but I still think that the implication is logically
  better.

- renamed some operations in matrix.gd, kept the old names;
  renamed also `AddRowVector` to `AddVector`, kept the old name

- removed the `TraceMat` method installed for `IsList`,
  which is taken over by the method for `IsMatrixObj`;
  perhaps more methods can eventually disappear this way

- some open items are listed at the end of the files
  `matobj2.gd` (one TODO, Backwards compatibility, Open items) and
  `matobj.gi` (Backwards compatibility)

- next steps before this stuff can be merged:

  - make the tests pass again; for that, I have to make more experiments
    with the default methods for `IsMatrixObj`

  - deal with the open items; some decisions are still to be made

  - add manual examples, perhaps with a type of matrix objects for which
    not more than the compulsory methods are installed

  - add generic tests for implementations of vector/matrix objects,
    similar to the ones in 'tst/teststandard/arithlst.g'

  - revisit the available implementations of vector/matrix objects
    in the GAP library and in packages
  • Loading branch information
@ThomasBreuer
ThomasBreuer committed Feb 3, 2020
1 parent ccc7fb1 commit 52509bb
Show file tree
Hide file tree
Showing 17 changed files with 3,527 additions and 1,488 deletions.
4 changes: 3 additions & 1 deletion doc/ref/makedocreldata.g
View file
Original file line number Diff line number Diff line change
Expand Up @@ -110,9 +110,11 @@ GAPInfo.ManualDataRef:= rec(
"../../lib/mapping.gd",
"../../lib/matblock.gd",
"../../lib/matint.gd",
"../../lib/matrix.gd",
"../../lib/matobj.gi",
"../../lib/matobj1.gd",
"../../lib/matobj2.gd",
"../../lib/matobjplist.gd",
"../../lib/matrix.gd",
"../../lib/memusage.gd",
"../../lib/methsel2.g",
"../../lib/methwhy.g",
Expand Down
295 changes: 257 additions & 38 deletions doc/ref/matobj.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,65 +7,284 @@
<Chapter Label="Vector and Matrix Objects">
<Heading>Vector and Matrix Objects</Heading>

This chapter is work in progress. It will eventually describe the new
interface to vector and matrix objects.
<P/>
Traditionally, vectors in &GAP; have been lists and matrices have been
lists of lists (of equal length). Unfortunately, such lists cannot
store their type and so it is impossible to use the full advantages of
&GAP;'s method selection on them. This situation is unsustainable in the
long run since more special representations (compressed,
sparse, etc.) have already been and even more will be implemented.
To eventually solve
this problem, this chapter describes a new programming interface to
vectors and matrices.

<Section Label="Fundamental Ideas and Rules">
<Heading>Fundamental Ideas and Rules</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 Vectors and Matrices">
<Heading>Categories of Vectors and Matrices</Heading>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<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="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>
<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_PositionNonZero">
<#Include Label="MatObj_PositionLastNonZero">
<#Include Label="MatObj_ListOp">
<#Include Label="MatObj_UnpackVector">
<#Include Label="MatObj_ConcatenationOfVectors">
<#Include Label="MatObj_ExtractSubVector">
<#Include Label="MatObj_ZeroVector">
<#Include Label="MatObj_ConstructingFilter_Vector">
<#Include Label="MatObj_Randomize_Vectors">
<#Include Label="MatObj_WeightOfVector">
<#Include Label="MatObj_DistanceOfVectors">
<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="Operations for Row List Matrix Objects">
<Heading>Operations for Row List Matrix Objects</Heading>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<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 Flat Matrix Objects">
<Heading>Operations for Flat Matrix Objects</Heading>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<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>

</Chapter>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %E -->
<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),
such that the operations described in this section are supported
for these matrix objects.

<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="IsPlistVectorRep">
<#Include Label="IsPlistMatrixRep">
<#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="Operations for Vector and Matrix Objects, without Defaults">
<Heading>Operations for Vector and Matrix Objects, without Defaults</Heading>

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.
(Of course, 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,
just check for which operations it makes sense to overload them
for your new type of vector or matrix objects.)

<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"/>,
</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"/>.
</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"/>,
</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"/>.
</Item>
</List>

</Section>

</Chapter>

9 changes: 5 additions & 4 deletions doc/ref/matrix.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,11 @@
<Chapter Label="Matrices">
<Heading>Matrices</Heading>

Matrices are represented in &GAP; by lists of row vectors
(see <Ref Chap="Row Vectors"/>) (for future changes to this
policy see Chapter <Ref Chap="Vector and Matrix Objects"/>).
The vectors must all have the same length, and their elements must lie in
In &GAP;, Matrices can be represented by lists of row vectors,
see <Ref Chap="Row Vectors"/>.
(For a more general way to represent vectors and matrices,
see Chapter <Ref Chap="Vector and Matrix Objects"/>).
The row vectors must all have the same length, and their elements must lie in
a common ring. However, since checking rectangularness can be expensive
functions and methods of operations for matrices often will not give an error
message for non-rectangular lists of lists &ndash;in such cases the result is
Expand Down
15 changes: 9 additions & 6 deletions hpcgap/lib/upolyirr.gi
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,15 +99,17 @@ end;

#############################################################################
##
#F CompanionMat( <poly>
#M CompanionMatrix( <poly> )
#M CompanionMatrix( <coeffs> )
##
InstallGlobalFunction( CompanionMat, function ( arg )

InstallMethod( CompanionMatrix,
[ IsObject ],
function( obj )
local c, l, res, i, F, c1;

# for the moment allow coefficients as well
if not IsList( arg[1] ) then
c := CoefficientsOfLaurentPolynomial( arg[1] );
if not IsList( obj ) then
c := CoefficientsOfLaurentPolynomial( obj );
if c[2] < 0 then
Error( "This polynomial does not have a companion matrix" );
fi;
Expand All @@ -116,7 +118,7 @@ InstallGlobalFunction( CompanionMat, function ( arg )
Append( c1, c[1] );
c:= c1;
else
c := arg[1];
c := obj;
F:= DefaultField( c );
fi;

Expand All @@ -132,6 +134,7 @@ InstallGlobalFunction( CompanionMat, function ( arg )
od;
return res;
end );


#############################################################################
##
Expand Down
Loading

0 comments on commit 52509bb

Please sign in to comment.