diff --git a/Makefile.rules b/Makefile.rules index 1aec140fdd..74d62a9ca0 100644 --- a/Makefile.rules +++ b/Makefile.rules @@ -584,9 +584,13 @@ clean: rm -rf .libs rm -f doc/wsp.g rm -f cnf/GAP-* + rm -f configure~ src/config.h.in~ rmdir bin cnf dev doc extern src 2>/dev/null || : # remove dirs if they are now empty -.PHONY: clean distclean +cleanall: clean distclean clean-doc + rm -f src/config.h.in + +.PHONY: clean distclean cleanall ######################################################################## @@ -976,6 +980,7 @@ clean-doc: rm -f doc/*/chooser.html doc/*/manual*.pdf rm -f doc/*/*.{aux,bbl,blg,brf,idx,ilg,ind,lab,log,out,pnr,six,tex,toc} rm -f doc/manualbib.xml.bib + rm -f doc/ref/user_pref_list.xml # FIXME: we currently build the manual inside $srcdir; so we don't want "make clean" # to remove it, as other builds might share the manual. @@ -1007,6 +1012,7 @@ tst/testlibgap/%: build/obj/tst/testlibgap/%.c.o build/obj/tst/testlibgap/common clean: clean-testlibgap clean-testlibgap: rm -f ${LIBGAPTESTS} + rm -f $(addsuffix .out,$(LIBGAPTESTS)) # run all the tests in tst/testlibgap testlibgap: ${LIBGAPTESTS} @@ -1048,6 +1054,7 @@ tst/testkernel/%: build/obj/tst/testkernel/%.c.o libgap$(SHLIB_EXT) clean: clean-testkernel clean-testkernel: rm -f ${KERNELTESTS} + rm -f $(addsuffix .out,$(KERNELTESTS)) # run all the tests in tst/testkernel testkernel: ${KERNELTESTS} diff --git a/doc/ref/matobj.xml b/doc/ref/matobj.xml index ddbaa2871d..27fdfc1310 100644 --- a/doc/ref/matobj.xml +++ b/doc/ref/matobj.xml @@ -21,6 +21,63 @@ cf. Chapters and . + +
+Some Elementary Examples +Just to give a flavour of these new objects, we construct here two vectors +and matrices in these new forms. +The elements should all belong to a semiring R +(the BaseDomain). +To construct these objects we use the operations +Vector and Matrix which are described in Section +. +

+Basic arithmetic operations for vectors and matrices are available: +see Sections and +. +

+Note that if m2, like m2, had been defined over the integers +then attempting to have displayed its inverse would have thrown an error. +

+ dom := Integers;; +gap> v1 := Vector( dom, [3,4,7,8] );; +gap> Print( v1 ); +NewVector(IsPlistVectorRep,Integers,[ 3, 4, 7, 8 ]) +gap> m1 := Matrix( dom, [ [1,2,3,4], [6,7,8,9] ] );; +gap> Display( m1 ); +<2x4-matrix over Integers: +[[ 1, 2, 3, 4 ] + [ 6, 7, 8, 9 ] +]> +gap> v2 := Vector( [-7..-4], v1 ); + +gap> Print( v1 + v2 ); +NewVector(IsPlistVectorRep,Integers,[ -4, -2, 2, 4 ]) +gap> Display( (v1+v2) * TransposedMat( m1 ) ); + +gap> m2 := Matrix( Rationals, [ [8,5], [7,4] ] );; +gap> Display( m2^(-1) ); +<2x2-matrix over Rationals: +[[ -4/3, 5/3 ] + [ 7/3, -8/3 ] +]> +]]> + +These objects need to know their type, or filter. +The simplest of these use plain lists, namely +and , +which &GAP; chooses automatically for v1 and M. +Note that v2 acquires its type by being defined relative to v1. +Other available types are listed in Sections + and +. + +

+ +
Categories of Vector and Matrix Objects @@ -55,13 +112,13 @@ More can be added as soon as there is need for them.
Constructing Vector and Matrix Objects -<#Include Label="NewVector"> <#Include Label="Vector"> <#Include Label="VectorObj_ZeroVector"> -<#Include Label="NewMatrix"> +<#Include Label="NewVector"> <#Include Label="MatObj_Matrix"> <#Include Label="MatObj_ZeroMatrix"> <#Include Label="MatObj_IdentityMatrix"> +<#Include Label="NewMatrix">
diff --git a/lib/matobj.gi b/lib/matobj.gi index 35ae1ccbe0..58e4184e6d 100644 --- a/lib/matobj.gi +++ b/lib/matobj.gi @@ -885,6 +885,23 @@ end ); ## otherwise it is not specified what happens. ## If the result is a vector object then it has the same representation and ## the same base domain as the given vector object(s). +##

+## v1 := Vector( Rationals, [-1,-1/2,0,1/2,1] );; Print( v1 ); +## NewVector(IsPlistVectorRep,Rationals,[ -1, -1/2, 0, 1/2, 1 ]) +## gap> v2 := Vector( [0,1,2,4,8], v1 );; Print( v2 ); +## NewVector(IsPlistVectorRep,Rationals,[ 0, 1, 2, 4, 8 ]) +## gap> Print( v1 + v2 ); +## NewVector(IsPlistVectorRep,Rationals,[ -1, 1/2, 2, 9/2, 9 ]) +## gap> Unpack( v2 - v1 ); +## [ 1, 3/2, 2, 7/2, 7 ] +## gap> Unpack( 2 * v1 ); Unpack( v1 * 4 ); Unpack( v2 / 4 ); +## [ -2, -1, 0, 1, 2 ] +## [ -4, -2, 0, 2, 4 ] +## [ 0, 1/4, 1/2, 1, 2 ] +## gap> v1 * v2; +## 19/2 +## ]]> ## ## ## <#/GAPDoc> @@ -1123,6 +1140,26 @@ InstallMethod( MultVectorRight, ## otherwise it is not specified what happens. ## If the result is a matrix object then it has the same representation and ## the same base domain as the given matrix object(s). +##

+## m1 := Matrix( Rationals, [ [3,4,5], [6,7,8] ] );; +## gap> m2 := Matrix( [ [1,0,1], [0,1,0] ], m1 );; +## gap> Print( m1 + m2, "\n", m1 - m2 ); +## NewMatrix(IsPlistMatrixRep,Rationals,3,[ [ 4, 4, 6 ], [ 6, 8, 8 ] ]) +## NewMatrix(IsPlistMatrixRep,Rationals,3,[ [ 2, 4, 4 ], [ 6, 6, 8 ] ]) +## gap> Unpack( 3 * m2 ); Unpack( m2 * 5 ); Unpack( m2 / 2 ); +## [ [ 3, 0, 3 ], [ 0, 3, 0 ] ] +## [ [ 5, 0, 5 ], [ 0, 5, 0 ] ] +## [ [ 1/2, 0, 1/2 ], [ 0, 1/2, 0 ] ] +## gap> m3 := Matrix( Integers, [ [1,1], [0,1] ] );; +## gap> m4 := Matrix( Integers, [ [3,5], [4,7] ] );; +## gap> Print( m3 * m4 ); +## NewMatrix(IsPlistMatrixRep,Integers,2,[ [ 7, 12 ], [ 4, 7 ] ]) +## gap> Unpack( m3 * m4 ); Unpack( m3^6 ); Unpack( m4^-1 ); +## [ [ 7, 12 ], [ 4, 7 ] ] +## [ [ 1, 6 ], [ 0, 1 ] ] +## [ [ 7, -5 ], [ -4, 3 ] ] +## ]]> ## ## ## <#/GAPDoc> @@ -1404,7 +1441,7 @@ InstallMethod( Characteristic, ## ## a matrix object ## -## For a vector object M, +## For a matrix object M, ## the operations for computing the additive inverse with prescribed ## mutability return a matrix object with the same ## and diff --git a/lib/matobj1.gd b/lib/matobj1.gd index ff53201b9c..c19130890f 100644 --- a/lib/matobj1.gd +++ b/lib/matobj1.gd @@ -110,16 +110,12 @@ DeclareCategory( "IsVectorObj", IsVector and IsVecOrMatObj and IsRowVectorOrVect ## argument. ##

## m:= IdentityMat( 2, GF(2) );; -## gap> IsMatrix( m ); IsMatrixObj( m ); IsMatrixOrMatrixObj( m ); -## true -## false -## true -## gap> m:= NewIdentityMatrix( IsPlistMatrixRep, GF(2), 2 );; -## gap> IsMatrix( m ); IsMatrixObj( m ); IsMatrixOrMatrixObj( m ); -## false -## true -## true +## gap> m := [ [1,2,3,4], [6,7,8,9] ];; +## gap> [ IsMatrix( m ), IsMatrixObj( m ), IsMatrixOrMatrixObj( m ) ]; +## [ true, false, true ] +## gap> m1 := Matrix( Integers, [ [1,2,3,4], [6,7,8,9] ] );; +## gap> [ IsMatrix( m1 ), IsMatrixObj( m1 ), IsMatrixOrMatrixObj( m1 ) ]; +## [ false, true, true ] ## ]]> ## ## @@ -246,7 +242,7 @@ DeclareCategory( "IsMatrixObj", IsMatrixOrMatrixObj ); ## the i-th row of M, ## for 1 \leq i \leq NumberRows( M ). ##

-## All rows are objects in the same +## All rows are objects in the compatible ## representation. ## Several rows of a row list matrix object can be identical objects, ## and different row list matrices may share rows. @@ -256,6 +252,14 @@ DeclareCategory( "IsMatrixObj", IsMatrixOrMatrixObj ); ## Matrix objects in are not ## necessarily in , ## and then they need not obey the general rules for lists. +##

+## m1 := Matrix( Integers, [ [1,2,3,4], [6,7,8,9] ] );; +## gap> IsRowListMatrix( m1 ); +## true +## gap> Print( m1[2] ); +## NewVector(IsPlistVectorRep,Integers,[ 6, 7, 8, 9 ]) +## ]]> ## ## ## <#/GAPDoc> @@ -283,6 +287,12 @@ DeclareCategory( "IsRowListMatrix", IsMatrixObj ); ## its base domain with respect to ## , see Section ## . +##

+## v := Vector( Rationals, [ 3, 4, 7, 8 ] );; +## gap> BaseDomain( v ); +## Rationals +## ]]> ## ## ## <#/GAPDoc> @@ -292,44 +302,6 @@ DeclareAttribute( "BaseDomain", IsVecOrMatObj ); #DeclareAttribute( "BaseDomain", IsMatrixOrMatrixObj ); -############################################################################# -## -#A NumberRows( ) -#A NrRows( ) -#A NumberColumns( ) -#A NrCols( ) -## -## <#GAPDoc Label="NumberRowsNumberColumns"> -## -## NumberRows and NumberColumns -## -## -## -## -## -## -## For a matrix object M, -## and -## store the -## number of rows and columns of M, respectively. -##

-## and -## are synonyms of -## and -## , respectively. -## -## -## <#/GAPDoc> -## -DeclareAttributeKernel( "NumberRows", IsMatrixOrMatrixObj, NUMBER_ROWS ); -DeclareSynonymAttr( "NrRows", NumberRows ); -InstallTrueMethod( HasNumberRows, IsMatrixOrMatrixObj and IsPlistRep); - -DeclareAttributeKernel( "NumberColumns", IsMatrixOrMatrixObj, NUMBER_COLUMNS ); -DeclareSynonymAttr( "NrCols", NumberColumns ); -InstallTrueMethod( HasNumberColumns, IsMatrixOrMatrixObj and IsPlistRep ); - - ############################################################################# ## #A OneOfBaseDomain( ) @@ -374,6 +346,52 @@ DeclareAttribute( "ZeroOfBaseDomain", IsVecOrMatObj ); #DeclareAttribute( "ZeroOfBaseDomain", IsMatrixOrMatrixObj ); +############################################################################# +## +#A NumberRows( ) +#A NrRows( ) +#A NumberColumns( ) +#A NrCols( ) +## +## <#GAPDoc Label="NumberRowsNumberColumns"> +## +## NumberRows and NumberColumns +## +## +## +## +## +## +## For a matrix object M, +## and +## store the +## number of rows and columns of M, respectively. +##

+## and +## are synonyms of +## and +## , respectively. +##

+## m1 := Matrix( Integers, [ [1,2,3,4], [6,7,8,9] ] );; +## gap> NumberRows( m1 ); +## 2 +## gap> NrCols( m1 ); +## 4 +## ]]> +## +## +## <#/GAPDoc> +## +DeclareAttributeKernel( "NumberRows", IsMatrixOrMatrixObj, NUMBER_ROWS ); +DeclareSynonymAttr( "NrRows", NumberRows ); +InstallTrueMethod( HasNumberRows, IsMatrixOrMatrixObj and IsPlistRep); + +DeclareAttributeKernel( "NumberColumns", IsMatrixOrMatrixObj, NUMBER_COLUMNS ); +DeclareSynonymAttr( "NrCols", NumberColumns ); +InstallTrueMethod( HasNumberColumns, IsMatrixOrMatrixObj and IsPlistRep ); + + ############################################################################# ## #V ConstructingFiltersForMatrixGroupElements diff --git a/lib/matobj2.gd b/lib/matobj2.gd index e2f457d734..6a153401e2 100644 --- a/lib/matobj2.gd +++ b/lib/matobj2.gd @@ -155,24 +155,6 @@ ## -############################################################################# -## -#A Length( ) -## -## <#GAPDoc Label="Length_IsVectorObj"> -## -## -## -## -## returns the length of the vector object v, -## which is defined to be the number of entries of v. -## -## -## <#/GAPDoc> -## -DeclareAttribute( "Length", IsVectorObj ); - - ############################################################################# ## #A ConstructingFilter( ) @@ -198,6 +180,12 @@ DeclareAttribute( "Length", IsVectorObj ); ## value of v or M implies then ## mutable versions of v or M can be created, ## otherwise all vector or matrix objects with this filter are immutable. +##

+## v := Vector( Rationals, [3,4,7,8] );; +## gap> ConstructingFilter( v ); +## +## ]]> ## ## ## <#/GAPDoc> @@ -222,6 +210,14 @@ DeclareAttribute( "ConstructingFilter", IsVecOrMatObj ); ## value ## f are compatible in the sense that M can be multiplied with ## these vector objects, of fail if no such filter is known. +##

+## m1 := Matrix( Integers, [ [1,2,3,4], [6,7,8,9] ] );; +## gap> ConstructingFilter( m1 ); +## +## gap> CompatibleVectorFilter( m1 ); +## +## ]]> ## ## ## <#/GAPDoc> @@ -231,126 +227,608 @@ DeclareAttribute( "CompatibleVectorFilter", IsMatrixOrMatrixObj ); ############################################################################# ## -## List Like Operations for Vector Objects +#A Length( ) +## +## <#GAPDoc Label="Length_IsVectorObj"> +## +## +## +## +## returns the length of the vector object v, +## which is defined to be the number of entries of v. +## +## +## <#/GAPDoc> ## +DeclareAttribute( "Length", IsVectorObj ); ############################################################################# ## -#O \[\]( , ) -#O \[\]\:\=( , , ) -#O \{\}( , ) +#O Vector( , , ) +#O Vector( , ) +#O Vector( , , ) +#O Vector( , ) +#O Vector( , ) +#O Vector( , ) ## -## <#GAPDoc Label="ElementAccessVectorObj"> +## <#GAPDoc Label="Vector"> ## -## Element Access and Assignment for Vector Objects -## -## -## -## +## Vector +## +## +## +## +## ## +## a vector object ## -## For a vector object v and a positive integer i that is -## not larger than the length of v -## (see ), -## v[i] is the entry at position i. +## If a filter filt is given as the first argument then +## a vector object is returned that has +## +## value filt, is defined over the base domain R, +## and has the entries given by the list list or the vector object +## vecobj, respectively. ##

-## If v is mutable, i is as above, and obj is an object -## from the base domain of v then -## v[i]:= obj assigns obj to the -## i-th position of v. +## If a semiring R is given as the first argument then +## a vector object is returned whose +## +## value is guessed from R, again with base domain R +## and entries given by the last argument. ##

-## If list is a list of positive integers that are not larger than -## the length of v then -## v{list} returns a new mutable vector object -## in the same representation as v -## (see ) -## that contains the list[ k ]-th entry of v at -## position k. +## In the remaining cases with two arguments, +## the first argument is a list or a vector object +## that defines the entries of the result, +## and the second argument is a vector object whose +## and +## are taken for the +## result. +##

+## The variant +## Vector( vecobj, vecobj_example ) +## is supported also for the case that vecobj is a row vector +## but not a vector object. +## In this situation, the result is a row vector that is equal to +## vecobj and whose +## and +## +## are taken from the example. +##

+## If only a list list is given then both the +## and the +## are guessed from +## this list. ##

## If the global option check is set to false then -## +## ## need not perform consistency checks. ##

-## Note that the sublist assignment operation -## is left out here since it tempts the programmer to use constructions like -## v{ [ 1 .. 3 ] }:= w{ [ 4 .. 6 ] } -## which produces an unnecessary intermediate object; -## one should use instead. +## If the +## value of the result implies then the result is +## mutable if and only if the argument that determines the entries of the +## result (list, v, v1) is mutable. +##

+## In the case of a mutable result, it is not guaranteed that +## the given list of entries is copied. +##

+## Default methods for +## +## delegate to . +##

+## v1 := Vector( Integers, [3,4,7,8] );; Print( v1 ); +## NewVector(IsPlistVectorRep,Integers,[ 3, 4, 7, 8 ]) +## gap> v2 := Vector( Rationals, v1 );; Print( v2 ); +## NewVector(IsPlistVectorRep,Rationals,[ 3, 4, 7, 8 ]) +## gap> v3 := Vector( [ 11..13], v1) ;; Print( v3 ); +## NewVector(IsPlistVectorRep,Integers,[ 11, 12, 13 ]) +## gap> v0 := [6..9];; IsVector( v0 ); +## true +## gap> Print( Vector( v0, v1 ) ); +## NewVector(IsPlistVectorRep,Integers,[ 6, 7, 8, 9 ]) +## gap> v4 := Vector( [ 2, 5/2, 7/3, 3 ] );; Print( v4 ); +## NewVector(IsPlistVectorRep,Rationals,[ 2, 5/2, 7/3, 3 ]) +## gap> v5 := Vector( IsGF2VectorRep, GF(2), [ 0, 1, 2 ]*Z(2)^0 );; +## gap> Print( v5 ); +## [ 0*Z(2), Z(2)^0, 0*Z(2) ] +## gap> v6 := Vector( IsZmodnZVectorRep, ZmodnZ(8), v1 ); +## +## gap> BaseDomain( v6 ); +## (Integers mod 8) +## gap> v7 := Vector( IsZmodnZVectorRep, ZmodnZ(12), v0 ); +## +## ]]> ## ## ## <#/GAPDoc> ## -DeclareOperation( "[]", [ IsVectorObj, IsPosInt ] ); - -DeclareOperation( "[]:=", [ IsVectorObj, IsPosInt, IsObject ] ); - -DeclareOperation( "{}", [ IsVectorObj, IsList ] ); +DeclareOperation( "Vector", [ IsOperation, IsSemiring, IsList ] ); +DeclareOperation( "Vector", [ IsSemiring, IsList ] ); +DeclareOperation( "Vector", [ IsOperation, IsSemiring, IsVectorObj ] ); +DeclareOperation( "Vector", [ IsSemiring, IsVectorObj ] ); +DeclareOperation( "Vector", [ IsList, IsVectorObj ] ); +DeclareOperation( "Vector", [ IsVectorObj, IsVectorObj ] ); +DeclareOperation( "Vector", [ IsList ] ); ############################################################################# ## -## <#GAPDoc Label="MatObj_PositionNonZero"> +#O ZeroVector( , ) +#O ZeroVector( , ) +#O ZeroVector( , ) +#O ZeroVector( , , ) +## +## <#GAPDoc Label="VectorObj_ZeroVector"> ## -## +## ZeroVector +## +## +## +## ## -## An integer +## a vector object ## -## Returns the index of the first entry in the vector object v -## that is not zero. -## If all entries are zero, -## the function returns Length(v) + 1. +## For a semiring R and a nonnegative integer len, +## this operation returns a new vector object of length len +## over R in the representation filt containing only zeros. +## &GAP; guesses a suitable representation. +##

+## For a vector object v and a nonnegative integer len, +## this operation returns a new vector object of length len +## in the same representation as v containing only zeros. +##

+## For a matrix object M and a nonnegative integer len, +## this operation returns a new zero vector object of length +## len in the representation given by the +## value +## of M, provided that such a representation exists. +##

+## For a filter filt, a semiring R and a nonnegative integer +## len, this operation returns a new vector object of length +## len over R in the representation filt +## containing only zeros. +##

+## If the +## value of the result implies then the result is +## mutable. +##

+## Default methods for +## +## delegate to . +##

+## z1 := ZeroVector( Rationals, 4 );; Print( z1 ); +## NewVector(IsPlistVectorRep,Rationals,[ 0, 0, 0, 0 ]) +## gap> v5 := Vector( GF(5), [3,4]*Z(5) );; z5 := ZeroVector(3,v5);; Print(z5); +## [ 0*Z(5), 0*Z(5), 0*Z(5) ] +## gap> m6:=Matrix(Integers,[[1,3],[5,7]]);; z6:=ZeroVector(6,m6);; Print(z6); +## NewVector(IsPlistVectorRep,Integers,[ 0, 0, 0, 0, 0, 0 ]) +## gap> z8 := ZeroVector( IsZmodnZVectorRep, ZmodnZ(8), 4 );; Print( z8 ); +## NewVector(IsZmodnZVectorRep,Monoid( ... ),[ 0, 0, 0, 0 ]) +## ]]> ## ## ## <#/GAPDoc> ## -DeclareOperation( "PositionNonZero", [ IsVectorObj ] ); +DeclareOperation( "ZeroVector", [ IsSemiring, IsInt ] ); +DeclareOperation( "ZeroVector", [ IsInt, IsVecOrMatObj ] ); +DeclareOperation( "ZeroVector", [ IsOperation, IsSemiring, IsInt ] ); +#DeclareOperation( "ZeroVector", [ IsInt, IsVectorObj ] ); +#DeclareOperation( "ZeroVector", [ IsInt, IsMatrixOrMatrixObj ] ); ############################################################################# ## -## <#GAPDoc Label="MatObj_PositionLastNonZero"> +#O NewVector( , , ) +#O NewZeroVector( , , ) +## +## <#GAPDoc Label="NewVector"> ## -## +## NewVector and NewZeroVector +## +## ## -## An integer ## -## Returns the index of the last entry in the vector object v -## that is not zero. -## If all entries are zero, the function returns 0. +## These two operations are constructors, and should only be used +## when or +## +## do not give the desired result. +##

+## For a filter filt, a semiring R, and a list list +## of elements that belong to R, +## returns a vector object which has +## the +## filt, +## the R, +## and the entries in list. +## The list list is guaranteed not to be changed by this operation. +##

+## If the global option check is set to false then +## need not perform consistency checks. +##

+## Similarly, returns a vector object +## of length n which has filt and R as +## and +## values, +## and contains the zero of R in each position. +##

+## The returned object is mutable if and only if filt implies +## . +##

+## v := NewVector( IsGF2VectorRep, GF(2), [1,0,1,0,1]*Z(2) ); +## +## gap> Print(v); +## [ Z(2)^0, 0*Z(2), Z(2)^0, 0*Z(2), Z(2)^0 ] +## gap> NewZeroVector( IsZmodnZVectorRep, ZmodnZ(7), 5 ); +## +## ]]> ## ## ## <#/GAPDoc> ## -DeclareOperation( "PositionLastNonZero", [ IsVectorObj ] ); +DeclareTagBasedOperation( "NewVector", [ IsOperation, IsSemiring, IsList ] ); + +DeclareTagBasedOperation( "NewZeroVector", + [ IsOperation, IsSemiring, IsInt ] ); ############################################################################# ## -#O ListOp( [, ] ) +#O Matrix( , , , ) +#O Matrix( , , ) +#O Matrix( , , ) +#O Matrix( , ) +#O Matrix( , , ) +#O Matrix( , ) +#O Matrix( , , ) +#O Matrix( , ) +#O Matrix( , ) +#O Matrix( , ) +#O Matrix( ) ## -## <#GAPDoc Label="MatObj_ListOp"> +## <#GAPDoc Label="MatObj_Matrix"> ## -## +## Matrix +## +## +## +## +## ## -## A plain list +## a matrix object ## -## Applies the function func to each entry of the vector object -## v and returns the results as a mutable plain list. -## This allows for calling -## on vector objects. +## If a filter filt is given as the first argument +## then a matrix object is returned that has +## +## value filt, is defined over the base domain R, +## and has the entries given by the list list +## or the matrix object matobj, respectively. +## Here list can be either a list of plain lists that describe the +## entries of the rows, or a flat list of the entries in row major order, +## where ncols defines the number of columns. ##

-## If the argument func is not given, -## applies to all entries. +## If a semiring R is given as the first argument then +## a matrix object is returned whose +## +## value filt is guessed from R, +## again with base domain R and entries given by the last argument. +##

+## In those cases where the last argument is a matrix object, +## the first argument is a list or a matrix object +## that defines the entries of the result, then the +## and +## +## of the last argument are taken for the result. +##

+## Finally, if only a list list and perhaps ncols is given +## then both the +## and the +## are guessed from +## the list. +##

+## If the global option check is set to false then +## +## need not perform consistency checks. +##

+## If the +## value of the result implies then the result is +## mutable if and only if the argument that determines the entries of the +## result (list or matobj) is mutable. +##

+## In the case of a mutable result, it is guaranteed that the given list +## list is copied in the sense of , +## and if list is a nested list then it is not guaranteed +## that also the entries of list are copied. +##

+## Default methods for +## +## delegate to . +##

+## m1 := Matrix( Integers, [ [3,4,5], [6,7,8] ] );; Print( m1 ); +## NewMatrix(IsPlistMatrixRep,Integers,3,[ [ 3, 4, 5 ], [ 6, 7, 8 ] ]) +## gap> m2 := Matrix( Rationals, [10..30], 7 );; Display( m2 ); +## <3x7-matrix over Rationals: +## [[ 10 .. 16 ] +## [ 17 .. 23 ] +## [ 24 .. 30 ] +## ]> +## gap> Print( Matrix( Integers, m2 ) ); +## NewMatrix(IsPlistMatrixRep,Integers,7, +## [ [ 10 .. 16 ], [ 17 .. 23 ], [ 24 .. 30 ] ]) +## gap> m3 := Matrix( [[7,6],[4,3]], m2 );; Print(m3); +## NewMatrix(IsPlistMatrixRep,Rationals,2,[ [ 7, 6 ], [ 4, 3 ] ]) +## gap> m4 := Matrix( [-7..-2], 3, m2 );; Print(m4); +## NewMatrix(IsPlistMatrixRep,Rationals,3,[ [ -7, -6, -5 ], [ -4, -3, -2 ] ]) +## gap> m0 := [[-1,-2],[-3,-4]];; IsMatrix(m0); +## true +## gap> Print( Matrix( m0, m1 ) ); +## NewMatrix(IsPlistMatrixRep,Integers,2,[ [ -1, -2 ], [ -3, -4 ] ]) +## gap> m5 := Matrix( [ [0,1,2], [7,8,9] ] );; Print( m5 ); +## NewMatrix(IsPlistMatrixRep,Rationals,3,[ [ 0, 1, 2 ], [ 7, 8, 9 ] ]) +## gap> Print( Matrix( [-9..-4], 3, m1 ) ); +## NewMatrix(IsPlistMatrixRep,Integers,3,[ [ -9, -8, -7 ], [ -6, -5, -4 ] ]) +## gap> m6 := Matrix( IsGF2MatrixRep, GF(2), [[1,0,1],[0,1,0]]*Z(2)^0 );; +## gap> Display( m6 ); +## 1 . 1 +## . 1 . +## gap> m7 := Matrix( IsZmodnZMatrixRep, ZmodnZ(8), [1..6], 3 ); +## +## gap> m8 := Matrix( IsZmodnZMatrixRep, ZmodnZ(12), m0 ); +## +## ]]> ## ## ## <#/GAPDoc> ## -DeclareOperation( "ListOp", [ IsVectorObj ] ); -DeclareOperation( "ListOp", [ IsVectorObj, IsFunction ] ); +DeclareOperation( "Matrix", [ IsOperation, IsSemiring, IsList, IsInt ] ); +DeclareOperation( "Matrix", [ IsOperation, IsSemiring, IsList ] ); +DeclareOperation( "Matrix", [ IsOperation, IsSemiring, IsMatrixOrMatrixObj ] ); +DeclareOperation( "Matrix", [ IsSemiring, IsList, IsInt ] ); +DeclareOperation( "Matrix", [ IsSemiring, IsList ] ); +DeclareOperation( "Matrix", [ IsSemiring, IsMatrixOrMatrixObj ] ); +DeclareOperation( "Matrix", [ IsList, IsInt, IsMatrixOrMatrixObj ] ); +DeclareOperation( "Matrix", [ IsList, IsMatrixOrMatrixObj ] ); +DeclareOperation( "Matrix", [ IsMatrixOrMatrixObj, IsMatrixOrMatrixObj ] ); +DeclareOperation( "Matrix", [ IsList, IsInt ] ); +DeclareOperation( "Matrix", [ IsList ]); + + +############################################################################# +## +#O ZeroMatrix( , , ) +#O ZeroMatrix( , , ) +#O ZeroMatrix( , , , ) +## +## <#GAPDoc Label="MatObj_ZeroMatrix"> +## +## ZeroMatrix +## +## +## +## +## a matrix object +## +## For a matrix object M and two nonnegative integers m +## and n, this operation returns a new matrix object +## with m rows and n columns +## in the same representation and over the same base domain as M +## containing only zeros. +##

+## If a semiring R and two nonnegative integers m and +## n are given, +## the representation of the result is guessed from R. +##

+## If a filter filt and a semiring R are given as the first +## and second argument, they are taken as the values of +## and +## of the result. +##

+## If the +## value of the result implies then the result is +## fully mutable. +##

+## Default methods for +## +## delegate to . +##

+## m7 := Matrix( IsZmodnZMatrixRep, ZmodnZ(8), [1..6], 3 );; +## gap> z7 := ZeroMatrix( 2, 2, m7 );; Print( z7 ); +## NewMatrix(IsZmodnZMatrixRep,Monoid( ... ),2, +## [ [ ZmodnZObj( 0, 8 ), ZmodnZObj( 0, 8 ) ], +## [ ZmodnZObj( 0, 8 ), ZmodnZObj( 0, 8 ) ] ]) +## gap> z23 := ZeroMatrix( Rationals, 2, 3 );; Print( z23 ); +## NewMatrix(IsPlistMatrixRep,Rationals,3,[ [ 0, 0, 0 ], [ 0, 0, 0 ] ]) +## gap> z5 := ZeroMatrix( IsGF2MatrixRep, GF(2), 2, 5 );; Display( z5 ); +## . . . . . +## . . . . . +## ]]> +## +## +## <#/GAPDoc> +## +DeclareOperation( "ZeroMatrix", [ IsInt, IsInt, IsMatrixOrMatrixObj ] ); +DeclareOperation( "ZeroMatrix", [ IsSemiring, IsInt, IsInt ] ); +DeclareOperation( "ZeroMatrix", [ IsOperation, IsSemiring, IsInt, IsInt ] ); + + +############################################################################# +## +#O IdentityMatrix( , ) +#O IdentityMatrix( , ) +#O IdentityMatrix( , , ) +## +## <#GAPDoc Label="MatObj_IdentityMatrix"> +## +## IdentityMatrix +## +## +## +## +## a matrix object +## +## For a matrix object M and a nonnegative integer n, +## this operation returns a new identity matrix object +## with n rows and columns +## in the same representation and over the same base domain as M. +##

+## If a semiring R and a nonnegative integer n is given, +## the representation of the result is guessed from R. +##

+## If a filter filt and a semiring R are given as the first +## and second argument, they are taken as the values of +## and +## of the result. +##

+## If the +## value of the result implies then the result is +## fully mutable. +##

+## Default methods for +## +## delegate to . +##

+## m7 := Matrix( IsZmodnZMatrixRep, ZmodnZ(8), [1..6], 3 );; +## gap> id7 := IdentityMatrix( 2, m7 );; Print( id7 ); +## NewMatrix(IsZmodnZMatrixRep,Monoid( ... ),2, +## [ [ ZmodnZObj( 1, 8 ), ZmodnZObj( 0, 8 ) ], +## [ ZmodnZObj( 0, 8 ), ZmodnZObj( 1, 8 ) ] ]) +## gap> id2 := IdentityMatrix( Rationals, 2 );; Print( id2 ); +## NewMatrix(IsPlistMatrixRep,Rationals,2,[ [ 1, 0 ], [ 0, 1 ] ]) +## gap> id3 := IdentityMatrix( IsGF2MatrixRep, GF(2), 3 );; Display( id3 ); +## 1 . . +## . 1 . +## . . 1 +## ]]> +## +## +## <#/GAPDoc> +## +DeclareOperation( "IdentityMatrix", [ IsInt, IsMatrixOrMatrixObj ] ); +DeclareOperation( "IdentityMatrix", [ IsSemiring, IsInt ] ); +DeclareOperation( "IdentityMatrix", [ IsOperation, IsSemiring, IsInt ] ); + + +############################################################################# +## +#O NewMatrix( , , , ) +#O NewMatrix( , , , ) +#O NewMatrix( , , ) +#O NewZeroMatrix( , , , ) +#O NewIdentityMatrix( , , ) +## +## <#GAPDoc Label="NewMatrix"> +## +## NewMatrix, NewZeroMatrix, NewIdentityMatrix +## +## +## +## +## +## +## +## These three operations are constructors, and should only be used +## by those implementing new material for matrix objects. +## Most users should find +## , +## or +## +## sufficient for their requirements. +##

+## For a filter filt, a semiring R, +## a positive integer ncols, and a list list, +## returns a matrix object which has +## the +## filt, +## the R, +## n columns +## (see ), +## and the entries described by list, +## which can be either a plain list of vector objects of length ncols +## or a plain list of plain lists of length ncols +## or a plain list of length a multiple of ncols containing the +## entries in row major order. +## The list list is guaranteed not to be changed by this operation. +##

+## The corresponding entries must be in or compatible with R. +## If list already contains vector objects, they are copied. +##

+## The second and third alternatives for NewMatrix have been added +## for consistency with the corresponding versions of Matrix. +## They just call the first version. +##

+## If the global option check is set to false then +## need not perform consistency checks. +##

+## Similarly, returns a zero matrix +## object with m rows and n columns +## which has filt and R as +## and +## values. +##

+## Similarly, returns an identity +## matrix object with n rows and columns +## which has filt and R as +## and +## values, +## and contains the identity element of R in the diagonal +## and the zero of R in each off-diagonal position. +##

+## The returned object is mutable if and only if filt implies +## . +##

+## m1 := NewMatrix( IsPlistMatrixRep, Integers, 3, [ [4,5,6], [7,8,9] ] );; +## gap> Display( m1 ); +## <2x3-matrix over Integers: +## [[ 4, 5, 6 ] +## [ 7, 8, 9 ] +## ]> +## gap> NewZeroMatrix( IsPlistMatrixRep, Rationals, 5, 3 ); +## <5x3-matrix over Rationals> +## gap> NewIdentityMatrix( IsGF2MatrixRep, GF(2), 4 ); +## +## ]]> +## +## +## <#/GAPDoc> +## +DeclareTagBasedOperation( "NewMatrix", + [ IsOperation, IsSemiring, IsInt, IsList] ); + +DeclareOperation( "NewMatrix", + [ IsOperation, IsSemiring, IsList, IsInt] ); + +DeclareOperation( "NewMatrix", + [ IsOperation, IsSemiring, IsList] ); + +DeclareTagBasedOperation( "NewZeroMatrix", + [ IsOperation, IsSemiring, IsInt, IsInt ] ); + +DeclareTagBasedOperation( "NewIdentityMatrix", + [ IsOperation, IsSemiring, IsInt ] ); + + +############################################################################# +## +## Operations for Vector and Matrix Objects +## ############################################################################# @@ -374,6 +852,12 @@ DeclareOperation( "ListOp", [ IsVectorObj, IsFunction ] ); ##

## Changing the result does not change v or M, respectively. ## The entries themselves are not copied. +##

+## m1 := Matrix( Integers, [ [1,2,3,4], [6,7,8,9] ] );; +## gap> Unpack( m1 ); +## [ [ 1, 2, 3, 4 ], [ 6, 7, 8, 9 ] ] +## ]]> ## ## ## <#/GAPDoc> @@ -388,54 +872,241 @@ DeclareOperation( "Unpack", [ IsVecOrMatObj ] ); ############################################################################# ## -## <#GAPDoc Label="MatObj_ConcatenationOfVectors"> +#O ChangedBaseDomain( , ) +#O ChangedBaseDomain( , ) +## +## <#GAPDoc Label="ChangedBaseDomain"> ## -## ConcatenationOfVectors -## -## +## ChangedBaseDomain +## +## ## -## a vector object +## +## For a vector object v (a matrix object M) +## and a semiring R, +## returns +## a new vector object (matrix object) +## with value R, +## value +## equal to that of v (M), +## and the same entries as v (M). +##

+## The result is mutable if and only if v (M) is mutable. +##

+## For example, one can create a vector defined over GF(4) +## from a vector defined over GF(2) with this operation. +##

+## v1 := Vector( Integers, [ 3, 5, 7, 9 ] );; +## gap> ChangedBaseDomain( v1, Rationals ); +## +## gap> m6 := Matrix( IsGF2MatrixRep, GF(2), [[1,0,1],[0,1,0]]*Z(2)^0 );; +## gap> m64 := ChangedBaseDomain( m6, GF(4) ); +## [ [ Z(2)^0, 0*Z(2), Z(2)^0 ], [ 0*Z(2), Z(2)^0, 0*Z(2) ] ] +## gap> ConstructingFilter( m64 ); +## +## ]]> +## +## +## <#/GAPDoc> +## +DeclareOperation( "ChangedBaseDomain", [ IsVecOrMatObj, IsSemiring ] ); +#DeclareOperation( "ChangedBaseDomain", [ IsVectorObj, IsSemiring ] ); +#DeclareOperation( "ChangedBaseDomain", [ IsMatrixOrMatrixObj, IsSemiring ] ); + + +############################################################################ ## +#O Randomize( [Rs, ]v ) +#O Randomize( [Rs, ]M ) +## +## <#GAPDoc Label="Randomize"> +## +## Randomize +## +## ## -## Returns a new mutable vector object in the representation of v1 -## or the first entry of the nonempty list vlist of vector objects, -## respectively, -## such that the entries are the concatenation of the given vector objects. +## Replaces every entry in the mutable vector object v +## or matrix object M, respectively, with +## a random one from the base domain of v or M, +## respectively, and returns the argument. ##

-## (Note that -## is a function for which no methods can be installed.) +## If given, the random source Rs is used to compute the +## random elements. +## Note that in this case, +## a +## method must be available that takes a random source as its first +## argument and the base domain as its second argument. +## m6 := ZeroMatrix( IsGF2MatrixRep, GF(2), 2, 10 );; +## gap> Randomize( m6 ); Display( m6 ); +## +## . 1 . . 1 . 1 . . . +## . . 1 . . . 1 1 . 1 +## ]]> ## ## ## <#/GAPDoc> ## -DeclareGlobalFunction( "ConcatenationOfVectors" ); +DeclareOperation( "Randomize", [ IsVectorObj and IsMutable ] ); +DeclareOperation( "Randomize", [ IsRandomSource, IsVectorObj and IsMutable ] ); +DeclareOperation( "Randomize", [ IsMatrixOrMatrixObj and IsMutable ] ); +DeclareOperation( "Randomize", [ IsRandomSource, IsMatrixOrMatrixObj and IsMutable ] ); ############################################################################# ## -## <#GAPDoc Label="MatObj_ExtractSubVector"> +## List Like Operations for Vector Objects +## + + +############################################################################# +## +#O \[\]( , ) +#O \[\]\:\=( , , ) +#O \{\}( , ) +## +## <#GAPDoc Label="ElementAccessVectorObj"> ## -## +## Element Access and Assignment for Vector Objects ## -## a vector object +## +## +## ## ## -## Returns a new mutable vector object of the same vector representation -## as v, containing the entries of v at the positions in -## the list l. +## For a vector object v and a positive integer i that is +## not larger than the length of v +## (see ), +## v[i] is the entry at position i. +##

+## If v is mutable, i is as above, and obj is an object +## from the base domain of v then +## v[i]:= obj assigns obj to the +## i-th position of v. +##

+## If list is a list of positive integers that are not larger than +## the length of v then +## v{list} returns a new mutable vector object +## in the same representation as v +## (see ) +## that contains the list[ k ]-th entry of v at +## position k. +##

+## If the global option check is set to false then +## +## need not perform consistency checks. +##

+## Note that the sublist assignment operation +## is left out here since it tempts the programmer to use constructions like +## v{ [ 1 .. 3 ] }:= w{ [ 4 .. 6 ] } +## which produces an unnecessary intermediate object; +## one should use instead. +##

+## v1 := Vector( Integers, [3,4,7,8] );; +## gap> v1[4]; +## 8 +## gap> v1[2] := 6;; Print( v1 ); +## NewVector(IsPlistVectorRep,Integers,[ 3, 6, 7, 8 ]) +## gap> Print( v1{[2..3]} ); +## NewVector(IsPlistVectorRep,Integers,[ 6, 7 ]) +## ]]> +## +## +## <#/GAPDoc> +## +DeclareOperation( "[]", [ IsVectorObj, IsPosInt ] ); + +DeclareOperation( "[]:=", [ IsVectorObj, IsPosInt, IsObject ] ); + +DeclareOperation( "{}", [ IsVectorObj, IsList ] ); + + +############################################################################# +## +## <#GAPDoc Label="MatObj_PositionNonZero"> +## +## +## +## An integer +## +## Returns the index of the first entry in the vector object v +## that is not zero. +## If all entries are zero, +## the function returns Length(v) + 1. +##

+## v := Vector( Integers, [0,0,1,1,2,2,0,0,0] );; Unpack( v ); +## [ 0, 0, 1, 1, 2, 2, 0, 0, 0 ] +## gap> PositionNonZero( v ); +## 3 +## ]]> +## +## +## <#/GAPDoc> +## +DeclareOperation( "PositionNonZero", [ IsVectorObj ] ); + + +############################################################################# +## +## <#GAPDoc Label="MatObj_PositionLastNonZero"> +## +## +## +## An integer +## +## Returns the index of the last entry in the vector object v +## that is not zero. +## If all entries are zero, the function returns 0. +##

+## v := Vector( Integers, [0,0,1,1,2,2,0,0,0] );; Unpack( v ); +## [ 0, 0, 1, 1, 2, 2, 0, 0, 0 ] +## gap> PositionLastNonZero( v ); +## 6 +## ]]> +## +## +## <#/GAPDoc> +## +DeclareOperation( "PositionLastNonZero", [ IsVectorObj ] ); + + +############################################################################# +## +#O ListOp( [, ] ) +## +## <#GAPDoc Label="MatObj_ListOp"> +## +## +## +## A plain list +## +## Applies the function func to each entry of the vector object +## v and returns the results as a mutable plain list. +## This allows for calling +## on vector objects. +##

+## If the argument func is not given, +## applies to all entries. ##

-## This is the same as v{l}, -## the name was introduced in analogy to -## , for which no equivalent syntax using -## curly brackets is available. +## v := Vector( Integers, [0,0,1,1,2,2,0,0,0] );; Unpack( v ); +## [ 0, 0, 1, 1, 2, 2, 0, 0, 0 ] +## gap> List( v, x -> x-1 ); +## [ -1, -1, 0, 0, 1, 1, -1, -1, -1 ] +## ]]> ## ## ## <#/GAPDoc> ## -DeclareOperationKernel( "ExtractSubVector", - [ IsRowVectorOrVectorObj, IsList ], EXTRACT_SUB_VECTOR ); +DeclareOperation( "ListOp", [ IsVectorObj ] ); +DeclareOperation( "ListOp", [ IsVectorObj, IsFunction ] ); ############################################################################# @@ -443,7 +1114,6 @@ DeclareOperationKernel( "ExtractSubVector", ## Arithmetical operations for vector objects ## - ############################################################################# ## #O AddVector( , [, [, , ]] ) @@ -475,6 +1145,17 @@ DeclareOperationKernel( "ExtractSubVector", ## This can be helpful if entries of src are known to be zero. ##

## If from is bigger than to, the operation does nothing. +##

+## v1 := Vector( Integers, [0,1,2,4,8] );; Print( v1 ); +## NewVector(IsPlistVectorRep,Integers,[ 0, 1, 2, 4, 8 ]) +## gap> v2 := Vector( [1,0,1,0,1], v1 );; Print( v2 ); +## NewVector(IsPlistVectorRep,Integers,[ 1, 0, 1, 0, 1 ]) +## gap> AddVector( v1, v2 ); Unpack( v1 ); +## [ 1, 1, 3, 4, 9 ] +## gap> AddVector( v1, v2, -2 ); Unpack( v1 ); +## [ -1, 1, 1, 4, 7 ] +## ]]> ## ## ## <#/GAPDoc> @@ -530,6 +1211,11 @@ DeclareOperation( "AddVector", ## This can be helpful if entries of v are known to be zero. ## If from is bigger than to, the operation does nothing. ##

+## v1 := Vector( Integers, [0,1,2,4,8] );; +## gap> MultVector( v1, 2 ); Unpack( v1 ); +## [ 0, 2, 4, 8, 16 ] +## ]]> ## ## ## <#/GAPDoc> @@ -544,7 +1230,6 @@ DeclareOperation( "MultVectorRight", DeclareOperation( "MultVectorRight", [ IsVectorObj and IsMutable, IsObject, IsInt, IsInt ] ); - # This is defined for two vectors of equal length, # it returns the standard scalar product. # (The documentation is in the section about arithm. operations.) @@ -553,316 +1238,142 @@ DeclareOperation( "ScalarProduct", [ IsVectorObj, IsVectorObj ] ); ############################################################################# ## -#O ZeroVector( , , ) -#O ZeroVector( , ) -#O ZeroVector( , ) -#O ZeroVector( , ) -## -## <#GAPDoc Label="VectorObj_ZeroVector"> -## -## ZeroVector -## -## -## -## -## -## a vector object -## -## For a filter filt, a semiring R and a nonnegative integer len, -## this operation returns a new vector object of length len over R -## in the representation filt containing only zeros. -##

-## If only R and len are given, -## then &GAP; guesses a suitable representation. -##

-## For a vector object v and a nonnegative integer len, -## this operation returns a new vector object of length len -## in the same representation as v containing only zeros. -##

-## For a matrix object M and a nonnegative integer len, -## this operation returns a new zero vector object of length -## len in the representation given by the -## value -## of M, provided that such a representation exists. -##

-## If the -## value of the result implies then the result is -## mutable. -##

-## Default methods for -## -## delegate to . -## -## -## <#/GAPDoc> -## -DeclareOperation( "ZeroVector", [ IsOperation, IsSemiring, IsInt ] ); -DeclareOperation( "ZeroVector", [ IsSemiring, IsInt ] ); -DeclareOperation( "ZeroVector", [ IsInt, IsVecOrMatObj ] ); -#DeclareOperation( "ZeroVector", [ IsInt, IsVectorObj ] ); -#DeclareOperation( "ZeroVector", [ IsInt, IsMatrixOrMatrixObj ] ); - - -############################################################################# -## -#O Vector( , , ) -#O Vector( , , ) -#O Vector( , ) -#O Vector( , ) -#O Vector( , ) -#O Vector( , ) -## -## <#GAPDoc Label="Vector"> -## -## Vector -## -## -## -## -## -## -## -## -## a vector object -## -## If a filter filt is given as the first argument then -## a vector object is returned that has -## -## value filt, is defined over the base domain R, -## and has the entries given by the list list or the vector object -## v, respectively. -##

-## If a semiring R is given as the first argument then -## a vector object is returned whose -## -## value is guessed from R, again with base domain R -## and entries given by the last argument. -##

-## In the remaining cases with two arguments, -## the first argument is a list or a vector object -## that defines the entries of the result, -## and the second argument is a vector object whose -## and -## are taken for the -## result. -##

-## If only a list list is given then both the -## and the -## are guessed from -## this list. -##

-## The variant Vector( v1, v2 ) -## is supported also for the case that v2 is a row vector but not -## a vector object. -## In this situation, the result is a row vector that is equal to -## v1 and whose internal representation fits to that of v2. -##

-## If the global option check is set to false then -## -## need not perform consistency checks. -##

-## If the -## value of the result implies then the result is -## mutable if and only if the argument that determines the entries of the -## result (list, v, v1) is mutable. -##

-## In the case of a mutable result, it is not guaranteed that -## the given list of entries is copied. -##

-## Default methods for -## -## delegate to . -## -## -## <#/GAPDoc> -## -DeclareOperation( "Vector", [ IsOperation, IsSemiring, IsList ] ); -DeclareOperation( "Vector", [ IsOperation, IsSemiring, IsVectorObj ] ); -DeclareOperation( "Vector", [ IsSemiring, IsList ] ); -DeclareOperation( "Vector", [ IsSemiring, IsVectorObj ] ); -DeclareOperation( "Vector", [ IsList, IsVectorObj ] ); -DeclareOperation( "Vector", [ IsVectorObj, IsVectorObj ] ); -DeclareOperation( "Vector", [ IsList ] ); - - -############################################################################# -## -#O NewVector( , , ) -#O NewZeroVector( , , ) -## -## <#GAPDoc Label="NewVector"> -## -## NewVector and NewZeroVector -## -## -## -## -## For a filter filt, a semiring R, and a list list -## of elements that belong to R, -## returns a vector object which has -## the -## filt, -## the R, -## and the entries in list. -## The list list is guaranteed not to be changed by this operation. -##

-## If the global option check is set to false then -## need not perform consistency checks. -##

-## Similarly, returns a vector object -## of length n which has filt and R as -## and -## values, -## and contains the zero of R in each position. -##

-## The returned object is mutable if and only if filt implies -## . -## -## -## <#/GAPDoc> +## Operations for Vector Objects ## -DeclareTagBasedOperation( "NewVector", [ IsOperation, IsSemiring, IsList ] ); - -DeclareTagBasedOperation( "NewZeroVector", - [ IsOperation, IsSemiring, IsInt ] ); - ############################################################################# ## -#O NewMatrix( , , , ) -#O NewZeroMatrix( , , , ) -#O NewIdentityMatrix( , , ) -## -## <#GAPDoc Label="NewMatrix"> +## <#GAPDoc Label="MatObj_ConcatenationOfVectors"> ## -## NewMatrix, NewZeroMatrix, NewIdentityMatrix -## -## -## -## -## -## For a filter filt, a semiring R, -## a positive integer ncols, and a list list, -## returns a matrix object which has -## the -## filt, -## the R, -## n columns -## (see ), -## and the entries described by list, -## which can be either a plain list of vector objects of length ncols -## or a plain list of plain lists of length ncols -## or a plain list of length a multiple of ncols containing the -## entries in row major order. -## The list list is guaranteed not to be changed by this operation. -##

-## The corresponding entries must be in or compatible with R. -## If list already contains vector objects, they are copied. -##

-## If the global option check is set to false then -## need not perform consistency checks. -##

-## Similarly, returns a zero matrix -## object with m rows and n columns -## which has filt and R as -## and -## values. -##

-## Similarly, returns an identity -## matrix object with n rows and columns -## which has filt and R as -## and -## values, -## and contains the identity element of R in the diagonal -## and the zero of R in each off-diagonal position. -##

-## The returned object is mutable if and only if filt implies -## . -## -## -## <#/GAPDoc> -## -DeclareTagBasedOperation( "NewMatrix", - [ IsOperation, IsSemiring, IsInt, IsList] ); - -DeclareTagBasedOperation( "NewZeroMatrix", - [ IsOperation, IsSemiring, IsInt, IsInt ] ); - -DeclareTagBasedOperation( "NewIdentityMatrix", - [ IsOperation, IsSemiring, IsInt ] ); - - -############################################################################# -## -#O ChangedBaseDomain( , ) -#O ChangedBaseDomain( , ) +## ConcatenationOfVectors +## +## ## -## <#GAPDoc Label="ChangedBaseDomain"> -## -## ChangedBaseDomain -## -## +## a vector object ## ## -## For a vector object v (a matrix object M) -## and a semiring R, -## returns -## a new vector object (matrix object) -## with value R, -## value -## equal to that of v (M), -## and the same entries as v (M). +## Returns a new mutable vector object in the representation of v1 +## or the first entry of the nonempty list vlist of vector objects, +## respectively, +## such that the entries are the concatenation of the given vector objects. ##

-## The result is mutable if and only if v (M) is mutable. +## (Note that +## is a function for which no methods can be installed.) ##

-## For example, one can create a vector defined over GF(4) -## from a vector defined over GF(2) with this operation. +## v1 := Vector( Integers, [1,2,3] );; +## gap> v2 := Vector( Integers, [6,7,8,9] );; +## gap> Print( ConcatenationOfVectors( v1, v2 ) ); +## NewVector(IsPlistVectorRep,Integers,[ 1, 2, 3, 6, 7, 8, 9 ]) +## gap> Print( ConcatenationOfVectors( v2, [0,1] ) ); +## NewVector(IsPlistVectorRep,Integers,[ 6, 7, 8, 9, 0, 1 ]) +## gap> Print( ConcatenationOfVectors( [ v1, [0,0,0], v2 ] ) ); +## NewVector(IsPlistVectorRep,Integers,[ 1, 2, 3, 0, 0, 0, 6, 7, 8, 9 ]) +## ]]> ## ## ## <#/GAPDoc> ## -DeclareOperation( "ChangedBaseDomain", [ IsVecOrMatObj, IsSemiring ] ); -#DeclareOperation( "ChangedBaseDomain", [ IsVectorObj, IsSemiring ] ); -#DeclareOperation( "ChangedBaseDomain", [ IsMatrixOrMatrixObj, IsSemiring ] ); +DeclareGlobalFunction( "ConcatenationOfVectors" ); -############################################################################ -## -#O Randomize( [Rs, ]v ) -#O Randomize( [Rs, ]M ) +############################################################################# ## -## <#GAPDoc Label="Randomize"> +## <#GAPDoc Label="MatObj_ExtractSubVector"> ## -## Randomize -## -## +## +## +## a vector object +## ## -## Replaces every entry in the mutable vector object v -## or matrix object M, respectively, with -## a random one from the base domain of v or M, -## respectively, and returns the argument. +## Returns a new mutable vector object of the same vector representation +## as v, containing the entries of v at the positions in +## the list l. ##

-## If given, the random source Rs is used to compute the -## random elements. -## Note that in this case, -## a -## method must be available that takes a random source as its first -## argument and the base domain as its second argument. +## This is the same as v{l}, +## the name was introduced in analogy to +## , for which no equivalent syntax using +## curly brackets is available. +##

+## v1 := Vector( Rationals, [-5..5] );; +## gap> v2 := ExtractSubVector( v1, [1,3,5,7,9,11] );; Print( v2 ); +## NewVector(IsPlistVectorRep,Rationals,[ -5, -3, -1, 1, 3, 5 ]) +## ]]> +##

+## In the remaining cases with two arguments, +## the first argument is a list or a vector object +## that defines the entries of the result, +## and the second argument is a vector object whose +## and +## are taken for the +## result. +##

+## The variant Vector( v1, v2 ) +## is supported also for the case that v2 is a row vector but not +## a vector object. +## In this situation, the result is a row vector that is equal to +## v1 and whose internal representation fits to that of v2. +##

+## If only a list list is given then both the +## and the +## are guessed from +## this list. +##

+## If a filter filt is given as the first argument then +## a vector object is returned that has +## +## value filt, is defined over the base domain R, +## and has the entries given by the list list or the vector object +## v, respectively. +##

+## If the global option check is set to false then +## +## need not perform consistency checks. +##

+## If the +## value of the result implies then the result is +## mutable if and only if the argument that determines the entries of the +## result (list, v, v1) is mutable. +##

+## In the case of a mutable result, it is not guaranteed that +## the given list of entries is copied. +##

+## Default methods for +## +## delegate to . +##

+## v1 := Vector( Integers, [3,4,7,8] );; Print( v1 ); +## NewVector(IsPlistVectorRep,Integers,[ 3, 4, 7, 8 ]) +## gap> v2 := Vector( Rationals, v1 );; Print( v2 ); +## NewVector(IsPlistVectorRep,Rationals,[ 3, 4, 7, 8 ]) +## gap> v3 := Vector( [ 11..13], v1) ;; Print( v3 ); +## NewVector(IsPlistVectorRep,Integers,[ 11, 12, 13 ]) +## gap> v0 := [6..9];; IsVector( v0 ); +## true +## gap> Print( Vector( v0, v1 ) ); +## NewVector(IsPlistVectorRep,Integers,[ 6, 7, 8, 9 ]) +## gap> v4 := Vector( [ 2, 5/2, 7/3, 3 ] );; Print( v4 ); +## NewVector(IsPlistVectorRep,Rationals,[ 2, 5/2, 7/3, 3 ]) +## gap> v5 := Vector( IsGF2VectorRep, GF(2), [ 0, 1, 2 ]*Z(2)^0 );; +## gap> Print( v5 ); +## [ 0*Z(2), Z(2)^0, 0*Z(2) ] +## gap> v6 := Vector( IsZmodnZVectorRep, ZmodnZ(8), v1 ); +## +## gap> BaseDomain( v6 ); +## (Integers mod 8) +## gap> v7 := Vector( IsZmodnZVectorRep, ZmodnZ(12), v0 ); +## +## ]]> ## ## ## <#/GAPDoc> ## -DeclareOperation( "Randomize", [ IsVectorObj and IsMutable ] ); -DeclareOperation( "Randomize", [ IsRandomSource, IsVectorObj and IsMutable ] ); -DeclareOperation( "Randomize", [ IsMatrixOrMatrixObj and IsMutable ] ); -DeclareOperation( "Randomize", [ IsRandomSource, IsMatrixOrMatrixObj and IsMutable ] ); +DeclareOperationKernel( "ExtractSubVector", + [ IsRowVectorOrVectorObj, IsList ], EXTRACT_SUB_VECTOR ); ############################################################################# @@ -893,6 +1404,13 @@ DeclareOperation( "Randomize", [ IsRandomSource, IsMatrixOrMatrixObj and IsMutab ##

## If the global option check is set to false then ## need not perform consistency checks. +##

+## v1 := Vector( Integers, [ 2,3,5,6,8,9 ] );; +## gap> v2 := Vector( Integers, [ 9,8,6,5,3,2 ] );; +## gap> CopySubVector( v1, v2, [2..4], [3..5] ); Print( v2 ); +## NewVector(IsPlistVectorRep,Integers,[ 9, 8, 3, 5, 6, 2 ]) +## ]]> ## ## ## <#/GAPDoc> @@ -911,6 +1429,14 @@ DeclareOperationKernel( "CopySubVector", ## ## returns the Hamming weight of the vector object v, ## i.e., the number of nonzero entries in v. +##

+## v1 := Vector( Integers, [2,3,5,6,8,9] );; +## gap> v2 := Vector( Integers, [2,3,0,0,8,9] );; +## gap> v3 := ZeroVector( Integers, 6 );; +## gap> [ WeightOfVector(v1), WeightOfVector(v2), WeightOfVector(v3) ]; +## [ 6, 4, 0 ] +## ]]> ## ## ## <#/GAPDoc> @@ -929,89 +1455,19 @@ DeclareOperation( "WeightOfVector", [ IsVectorObj ] ); ## returns the Hamming distance of the vector objects v1 and ## v2, i.e., the number of entries in which the vectors differ. ## The vectors must have equal length. -## -## -## <#/GAPDoc> -## -DeclareOperation( "DistanceOfVectors", [ IsVectorObj, IsVectorObj ] ); - - -############################################################################# -## -#O ExtractSubMatrix( , , ) -## -## <#GAPDoc Label="ExtractSubMatrix"> -## -## -## -## -## Creates a copy of the submatrix described by the two -## lists, which mean subsets of row and column positions, respectively. -## This does M{rows}{cols} and returns the result. -## It preserves the representation of the matrix. -##

-## If the -## value of the result implies then the result is -## fully mutable. -## -## -## <#/GAPDoc> -## -DeclareOperationKernel( "ExtractSubMatrix", - [ IsMatrixOrMatrixObj, IsList, IsList ], EXTRACT_SUB_MATRIX ); - - -############################################################################# -## -#O MutableCopyMatrix( ) -## -## <#GAPDoc Label="MutableCopyMatrix"> -## -## -## -## -## For a matrix object M, this operation returns a fully mutable -## copy of M, with the same -## and -## values, -## -## -## <#/GAPDoc> -## -DeclareOperation( "MutableCopyMatrix", [ IsMatrixOrMatrixObj ] ); - - -############################################################################# -## -#O CopySubMatrix( , , , , , ) -## -## <#GAPDoc Label="CopySubMatrix"> -## -## -## -## nothing -## -## -## Does dst{drows}{dcols} := -## src{srows}{scols} -## without creating an intermediate object and thus -## –at least in special cases– -## much more efficiently. -## For certain objects like compressed vectors this might be -## significantly more efficient if scols and dcols are -## ranges with increment 1. ##

-## If the global option check is set to false then -## need not perform consistency checks. +## v1 := Vector( Integers, [2,3,5,6,8,9] );; +## gap> v2 := Vector( Integers, [2,3,0,0,8,9] );; +## gap> v3 := ZeroVector( Integers, 6 );; +## gap> [ DistanceOfVectors( v1, v2 ), DistanceOfVectors( v2, v3 ) ]; +## [ 2, 4 ] +## ]]> ## ## ## <#/GAPDoc> ## -DeclareOperationKernel( "CopySubMatrix", - [ IsMatrixOrMatrixObj, IsMatrixOrMatrixObj, IsList, IsList, IsList, IsList ], - COPY_SUB_MATRIX ); -#T We intentionally keep the second argument declaration broad, mirroring -#T the pre-existing operation declaration for compatibility with packages. +DeclareOperation( "DistanceOfVectors", [ IsVectorObj, IsVectorObj ] ); ############################################################################# @@ -1036,6 +1492,12 @@ DeclareOperationKernel( "CopySubMatrix", ## M[ row ][ col ], ## which would first try to access M[ row ], ## and this is in general not possible. +##

+## m1 := Matrix( Rationals, [ [3,4,5], [6,7,8] ] );; +## gap> [ MatElm( m1, 2, 2 ), m1[2,3] ]; +## [ 7, 8 ] +## ]]> ## ## ## <#/GAPDoc> @@ -1071,267 +1533,123 @@ DeclareSynonym( "MatElm", ELM_MAT ); ## and this is in general not possible. ##

## If the global option check is set to false then -## need not perform consistency checks. -## -## -## <#/GAPDoc> -## -DeclareOperationKernel( "[,]:=", [ IsMatrixOrMatrixObj, IsInt, IsInt, IsObject ], - ASS_MAT ); -#T We want to require also 'IsMutable' for the first argument, -#T but some package may have installed methods without this requirement. -#T Note that if we declare the operation twice, once with requirement -#T 'IsMutable' and once without, each method installation will show -#T a complaint that it matches more than one declaration. -DeclareSynonym( "SetMatElm", ASS_MAT ); - - -############################################################################# -## -#O ZeroMatrix( , , ) -#O ZeroMatrix( , , ) -#O ZeroMatrix( , , , ) -## -## <#GAPDoc Label="MatObj_ZeroMatrix"> -## -## ZeroMatrix -## -## -## -## -## a matrix object -## -## For a matrix object M and two nonnegative integers m -## and n, this operation returns a new matrix object -## with m rows and n columns -## in the same representation and over the same base domain as M -## containing only zeros. -##

-## If a semiring R and two nonnegative integers m and -## n are given, -## the representation of the result is guessed from R. -##

-## If a filter filt and a semiring R are given as the first -## and second argument, they are taken as the values of -## and -## of the result. -##

-## If the -## value of the result implies then the result is -## fully mutable. +## need not perform consistency checks. ##

-## Default methods for -## -## delegate to . +## m1 := Matrix( Rationals, [ [3,4,5], [6,7,8] ] );; +## gap> SetMatElm( m1, 1, 3, 0 ); +## gap> m1[2,1] := 0;; Unpack( m1 ); +## [ [ 3, 4, 0 ], [ 0, 7, 8 ] ] +## ]]> ## ## ## <#/GAPDoc> ## -DeclareOperation( "ZeroMatrix", [ IsInt, IsInt, IsMatrixOrMatrixObj ] ); -DeclareOperation( "ZeroMatrix", [ IsSemiring, IsInt, IsInt ] ); -DeclareOperation( "ZeroMatrix", [ IsOperation, IsSemiring, IsInt, IsInt ] ); +DeclareOperationKernel( "[,]:=", [ IsMatrixOrMatrixObj, IsInt, IsInt, IsObject ], + ASS_MAT ); +#T We want to require also 'IsMutable' for the first argument, +#T but some package may have installed methods without this requirement. +#T Note that if we declare the operation twice, once with requirement +#T 'IsMutable' and once without, each method installation will show +#T a complaint that it matches more than one declaration. +DeclareSynonym( "SetMatElm", ASS_MAT ); ############################################################################# ## -#O IdentityMatrix( , ) -#O IdentityMatrix( , ) -#O IdentityMatrix( , , ) +#O ExtractSubMatrix( , , ) ## -## <#GAPDoc Label="MatObj_IdentityMatrix"> +## <#GAPDoc Label="ExtractSubMatrix"> ## -## IdentityMatrix -## -## -## +## ## -## a matrix object ## -## For a matrix object M and a nonnegative integer n, -## this operation returns a new identity matrix object -## with n rows and columns -## in the same representation and over the same base domain as M. -##

-## If a semiring R and a nonnegative integer n is given, -## the representation of the result is guessed from R. -##

-## If a filter filt and a semiring R are given as the first -## and second argument, they are taken as the values of -## and -## of the result. +## Creates a copy of the submatrix described by the two +## lists, which mean subsets of row and column positions, respectively. +## This does M{rows}{cols} and returns the result. +## It preserves the representation of the matrix. ##

## If the ## value of the result implies then the result is ## fully mutable. ##

-## Default methods for -## -## delegate to . +## m1 := Matrix( Integers, [1..20], 5 );; Unpack( m1 ); +## [ [ 1 .. 5 ], [ 6 .. 10 ], [ 11 .. 15 ], [ 16 .. 20 ] ] +## gap> m2 := ExtractSubMatrix( m1, [2,3], [2..4] );; Unpack( m2 ); +## [ [ 7 .. 9 ], [ 12 .. 14 ] ] +## gap> m3 := ExtractSubMatrix( m1, [4,1], [5,1] );; Unpack( m3 ); +## [ [ 20, 16 ], [ 5, 1 ] ] +## ]]> ## ## ## <#/GAPDoc> ## -DeclareOperation( "IdentityMatrix", [ IsInt, IsMatrixOrMatrixObj ] ); -DeclareOperation( "IdentityMatrix", [ IsSemiring, IsInt ] ); -DeclareOperation( "IdentityMatrix", [ IsOperation, IsSemiring, IsInt ] ); +DeclareOperationKernel( "ExtractSubMatrix", + [ IsMatrixOrMatrixObj, IsList, IsList ], EXTRACT_SUB_MATRIX ); ############################################################################# ## -#O CompanionMatrix( , ) -#O CompanionMatrix( [, ], ) +#O MutableCopyMatrix( ) ## -## <#GAPDoc Label="MatObj_CompanionMatrix"> +## <#GAPDoc Label="MutableCopyMatrix"> ## -## CompanionMatrix -## -## -## +## ## -## a matrix object ## -## For a monic, univariate polynomial pol whose coefficients lie in -## the base domain of the matrix object M, -## -## returns the companion matrix of pol, -## as a matrix object with the same +## For a matrix object M, this operation returns a fully mutable +## copy of M, with the same ## and -## values as M. -##

-## We use column convention, that is, the negatives of the coefficients of -## pol appear in the last column of the result. -##

-## If a filter filt and a semiring R are given then the -## companion matrix is returned as a matrix object with -## value -## filt and -## value R. -##

-## If only pol and a semiring R are given, -## the representation of the result is guessed from R. -##

-## If the -## value of the result implies then the result is -## fully mutable. -##

-## x:= X( GF(5) );; pol:= x^3 + x^2 + 2*x + 3;; -## gap> M:= CompanionMatrix( IsPlistMatrixRep, pol, GF(25) );; -## gap> Display( M ); -## <3x3-matrix over GF(5^2): -## [[ 0*Z(5), 0*Z(5), Z(5) ] -## [ Z(5)^0, 0*Z(5), Z(5)^3 ] -## [ 0*Z(5), Z(5)^0, Z(5)^2 ] -## ]> -## ]]> +## values, ## ## ## <#/GAPDoc> ## -DeclareOperation( "CompanionMatrix", - [ IsUnivariatePolynomial, IsMatrixOrMatrixObj ] ); -DeclareOperation( "CompanionMatrix", - [ IsOperation, IsUnivariatePolynomial, IsSemiring ] ); -DeclareOperation( "CompanionMatrix", - [ IsUnivariatePolynomial, IsSemiring ] ); +DeclareOperation( "MutableCopyMatrix", [ IsMatrixOrMatrixObj ] ); ############################################################################# ## -#O Matrix( , , , ) -#O Matrix( , , ) -#O Matrix( , , ) -#O Matrix( , , ) -#O Matrix( , ) -#O Matrix( , ) -#O Matrix( , , ) -#O Matrix( , ) -#O Matrix( , ) -#O Matrix( , ) -#O Matrix( ) +#O CopySubMatrix( , , , , , ) ## -## <#GAPDoc Label="MatObj_Matrix"> +## <#GAPDoc Label="CopySubMatrix"> ## -## Matrix -## -## -## -## -## +## +## +## nothing ## -## a matrix object ## -## If a filter filt is given as the first argument then -## a matrix object is returned that has -## -## value filt, is defined over the base domain R, -## and has the entries given by the list list or the matrix object -## matobj, respectively. -## Here list can be either a list of plain lists that describe the -## entries of the rows, or a flat list of the entries in row major order, -## where ncols defines the number of columns. -##

-## If a semiring R is given as the first argument then -## a matrix object is returned whose -## -## value is guessed from R, again with base domain R -## and entries given by the last argument. -##

-## In those remaining cases where the last argument is a matrix object, -## the first argument is a list or a matrix object -## that defines (together with ncols if applicable) the entries of -## the result, and the -## and -## of the last argument -## are taken for the result. -##

-## Finally, if only a list list and perhaps ncols is given -## then both the -## and the -## are guessed from -## the list. +## Does dst{drows}{dcols} := +## src{srows}{scols} +## without creating an intermediate object and thus +## –at least in special cases– +## much more efficiently. +## For certain objects like compressed vectors this might be +## significantly more efficient if scols and dcols are +## ranges with increment 1. ##

## If the global option check is set to false then -## -## need not perform consistency checks. -##

-## If the -## value of the result implies then the result is -## mutable if and only if the argument that determines the entries of the -## result (list or matobj) is mutable. -##

-## In the case of a mutable result, it is guaranteed that the given list -## list is copied in the sense of , -## and if list is a nested list then it is not guaranteed -## that also the entries of list are copied. +## need not perform consistency checks. ##

-## Default methods for -## -## delegate to . +## m1 := Matrix( Integers, [1..20], 5 );; Unpack( m1 ); +## [ [ 1 .. 5 ], [ 6 .. 10 ], [ 11 .. 15 ], [ 16 .. 20 ] ] +## gap> m0 := ZeroMatrix( Integers, 2, 9 );; +## gap> CopySubMatrix( m1, m0, [2,3], [1,2], [2..4], [3..5] ); Unpack( m0 ); +## [ [ 0, 0, 7, 8, 9, 0, 0, 0, 0 ], [ 0, 0, 12, 13, 14, 0, 0, 0, 0 ] ] +## gap> CopySubMatrix( m1, m0, [4,1], [1,2], [5,1], [7,8] ); Unpack( m0 ); +## [ [ 0, 0, 7, 8, 9, 0, 20, 16, 0 ], [ 0, 0, 12, 13, 14, 0, 5, 1, 0 ] ] +## ]]> ## ## ## <#/GAPDoc> ## -DeclareOperation( "Matrix", [ IsOperation, IsSemiring, IsList, IsInt ] ); -DeclareOperation( "Matrix", [ IsOperation, IsSemiring, IsList ] ); -DeclareOperation( "Matrix", [ IsOperation, IsSemiring, IsMatrixOrMatrixObj ] ); -DeclareOperation( "Matrix", [ IsSemiring, IsList, IsInt ] ); -DeclareOperation( "Matrix", [ IsSemiring, IsList ] ); -DeclareOperation( "Matrix", [ IsSemiring, IsMatrixOrMatrixObj ] ); -DeclareOperation( "Matrix", [ IsList, IsInt, IsMatrixOrMatrixObj ] ); -DeclareOperation( "Matrix", [ IsList, IsMatrixOrMatrixObj ] ); -DeclareOperation( "Matrix", [ IsMatrixOrMatrixObj, IsMatrixOrMatrixObj ] ); -DeclareOperation( "Matrix", [ IsList, IsInt ] ); -DeclareOperation( "Matrix", [ IsList ]); +DeclareOperationKernel( "CopySubMatrix", + [ IsMatrixOrMatrixObj, IsMatrixOrMatrixObj, IsList, IsList, IsList, IsList ], + COPY_SUB_MATRIX ); +#T We intentionally keep the second argument declaration broad, mirroring +#T the pre-existing operation declaration for compatibility with packages. ############################################################################ @@ -1353,6 +1671,16 @@ DeclareOperation( "Matrix", [ IsList ]); ##

## The idea is that there should be an efficient way to ## form the product vM. +##

+## m1 := Matrix( Integers, [ [2,3], [5,6], [8,9] ] );; +## gap> v1 := CompatibleVector( m1 );; Unpack( v1 ); +## [ 0, 0, 0 ] +## gap> v1[1] := -1;; v1[3] := -1;; Unpack( v1 ); +## [ -1, 0, -1 ] +## gap> Print( v1 * m1 ); +## NewVector(IsPlistVectorRep,Integers,[ -10, -12 ]) +## ]]> ## ## ## <#/GAPDoc> @@ -1376,20 +1704,90 @@ DeclareOperation( "CompatibleVector", [ IsMatrixOrMatrixObj ] ); ## value ## of M (provided that such a representation exists), ## where the i-th entry describes the i-th row of the input. +##

+## m1 := Matrix( Integers, [ [3,4,5], [7,8,9] ] );; +## gap> Print( RowsOfMatrix( m1 ) ); +## [ NewVector(IsPlistVectorRep,Integers,[ 3, 4, 5 ]), +## NewVector(IsPlistVectorRep,Integers,[ 7, 8, 9 ]) ] +## ]]> +## +## +## <#/GAPDoc> +## +## This function is used for creating an isomorphic permutation group +## of a matrix group that consists of matrix objects. +## +## +## We assume that the matrix knows how to create suitable vector objects; +## entering a template vector as the second argument is not an option +## in this situation. +## +DeclareAttribute( "RowsOfMatrix", IsMatrixOrMatrixObj ); + + +############################################################################# +## +#O CompanionMatrix( , ) +#O CompanionMatrix( [, ], ) +## +## <#GAPDoc Label="MatObj_CompanionMatrix"> +## +## CompanionMatrix +## +## +## +## +## a matrix object +## +## For a monic, univariate polynomial pol whose coefficients lie in +## the base domain of the matrix object M, +## +## returns the companion matrix of pol, +## as a matrix object with the same +## and +## values as M. +##

+## We use column convention, that is, the negatives of the coefficients of +## pol appear in the last column of the result. +##

+## If a filter filt and a semiring R are given then the +## companion matrix is returned as a matrix object with +## value +## filt and +## value R. +##

+## If only pol and a semiring R are given, +## the representation of the result is guessed from R. +##

+## If the +## value of the result implies then the result is +## fully mutable. +##

+## x:= X( GF(5) );; pol:= x^3 + x^2 + 2*x + 3;; +## gap> M:= CompanionMatrix( IsPlistMatrixRep, pol, GF(25) );; +## gap> Display( M ); +## <3x3-matrix over GF(5^2): +## [[ 0*Z(5), 0*Z(5), Z(5) ] +## [ Z(5)^0, 0*Z(5), Z(5)^3 ] +## [ 0*Z(5), Z(5)^0, Z(5)^2 ] +## ]> +## ]]> ## ## ## <#/GAPDoc> ## -## This function is used for creating an isomorphic permutation group -## of a matrix group that consists of matrix objects. -## -## -## We assume that the matrix knows how to create suitable vector objects; -## entering a template vector as the second argument is not an option -## in this situation. -## -DeclareAttribute( "RowsOfMatrix", IsMatrixOrMatrixObj ); +DeclareOperation( "CompanionMatrix", + [ IsUnivariatePolynomial, IsMatrixOrMatrixObj ] ); +DeclareOperation( "CompanionMatrix", + [ IsOperation, IsUnivariatePolynomial, IsSemiring ] ); +DeclareOperation( "CompanionMatrix", + [ IsUnivariatePolynomial, IsSemiring ] ); ############################################################################# @@ -1408,7 +1806,6 @@ DeclareGlobalFunction( "DefaultMatrixRepForBaseDomain" ); ## Operations for Row List Matrix Objects ## - ############################################################################ ## #O [ ] @@ -1426,6 +1823,12 @@ DeclareGlobalFunction( "DefaultMatrixRepForBaseDomain" ); ## this operation returns the pos-th row of M. ##

## It is not specified what happens if pos is larger. +##

+## m1 := Matrix( Integers, [ [2,3], [5,6], [8,9] ] );; +## gap> Print( m1[2] ); +## NewVector(IsPlistVectorRep,Integers,[ 5, 6 ]) +## ]]> ## ## ## <#/GAPDoc> @@ -1456,6 +1859,13 @@ DeclareOperation( "[]", [ IsRowListMatrix, IsPosInt ] ); ## M. ##

## In all other situations, it is not specified what happens. +##

+## m1 := Matrix( Integers, [ [2,3], [5,6], [8,9] ] );; +## gap> v1 := ZeroVector( 2, m1 );; +## gap> m1[2] := v1;; Unpack( m1 ); +## [ [ 2, 3 ], [ 0, 0 ], [ 8, 9 ] ] +## ]]> ## ## ## <#/GAPDoc> @@ -1480,6 +1890,12 @@ DeclareOperation( "[]:=", [ IsRowListMatrix, IsPosInt, IsVectorObj ] ); ## row list matrix with the same representation as M, ## whose rows are identical to the rows at the positions ## in the list poss in M. +##

+## m1 := Matrix( Integers, [ [0,1], [3,4], [6,7], [9,0] ] );; +## gap> m2 := m1{ [2..3] };; Print( m2 ); +## NewMatrix(IsPlistMatrixRep,Integers,2,[ [ 3, 4 ], [ 6, 7 ] ]) +## ]]> ## ## ## <#/GAPDoc> @@ -1508,6 +1924,13 @@ DeclareOperation( "{}", [IsRowListMatrix,IsList] ); ##

## It is not specified what happens if the resulting range of row positions ## is not dense. +##

+## m1 := Matrix( Integers, [ [1,1], [2,2], [3,3], [4,4], [5,5] ] );; +## gap> m2 := Matrix( [ [7,7], [8,8], [9,9] ], m1 );; +## gap> ## the following appears to fail at present +## gap> ## m1{ [2..4] } := m2; +## ]]> ## ## ## <#/GAPDoc> @@ -1530,6 +1953,12 @@ DeclareOperation( "{}:=", [IsRowListMatrix,IsList,IsRowListMatrix] ); ## IsBound( M[ pos ] ) returns ## true if pos is at most the number of rows of M, ## and false otherwise. +##

+## m1 := Matrix( Integers, [ [3,4,5], [7,8,9] ] );; +## gap> [ IsBound( m1[2] ), IsBound( m1[3] ) ]; +## [ true, false ] +## ]]> ## ## ## <#/GAPDoc> @@ -1552,6 +1981,12 @@ DeclareOperation( "IsBound[]", [ IsRowListMatrix, IsPosInt ] ); ## Unbind( M[ pos ] ) removes the last ## row. ## It is not specified what happens if pos has another value. +##

+## m1 := Matrix( Integers, [ [2,3], [5,6], [8,9] ] );; +## gap> Unbind( m1[3] ); Unpack( m1 ); +## [ [ 2, 3 ], [ 5, 6 ] ] +## ]]> ## ## ## <#/GAPDoc> @@ -1578,6 +2013,14 @@ DeclareOperation( "Unbind[]", [ IsRowListMatrix, IsPosInt ] ); ##

## If a positive integer pos is given then v is added in ## position pos, and all later rows are shifted up by one position. +##

+## m1 := Matrix( Integers, [ [2,3], [5,6], [8,9] ] );; +## gap> Add( m1, v1 ); Unpack( m1 ); +## [ [ 2, 3 ], [ 5, 6 ], [ 8, 9 ], [ 0, 0 ] ] +## gap> Add( m1, v1, 2 ); Unpack( m1 ); +## [ [ 2, 3 ], [ 0, 0 ], [ 5, 6 ], [ 8, 9 ], [ 0, 0 ] ] +## ]]> ## ## ## <#/GAPDoc> @@ -1600,243 +2043,115 @@ DeclareOperation( "Add", [ IsRowListMatrix, IsVectorObj, IsPosInt ] ); ## ## For a mutable row list matrix M, ## this operation removes the pos-th row and shifts the later rows -## down by one position. +## up by one position. ## The default for pos is the number of rows of M. ##

## If the pos-th row existed in M then it is returned, ## otherwise nothing is returned. -## -## -## <#/GAPDoc> -## -DeclareOperation( "Remove", [ IsRowListMatrix ] ); -DeclareOperation( "Remove", [ IsRowListMatrix, IsPosInt ] ); - - -############################################################################# -## -#O Append( , ) -## -## <#GAPDoc Label="RowListMatObj_Append"> -## -## -## -## nothing -## -## -## For two row list matrices M1, M2 -## such that M1 is mutable and such that the -## and -## values are equal, -## this operation appends the rows of M2 to the -## rows of M1. -## -## -## <#/GAPDoc> -## -DeclareOperation( "Append", [ IsRowListMatrix, IsRowListMatrix ] ); - - -############################################################################# -## -#O ShallowCopy( ) -## -## <#GAPDoc Label="RowListMatObj_ShallowCopy"> -## -## -## -## a matrix object -## -## -## For a row list matrix M, -## this operation returns a new mutable matrix with the same -## and -## values as M, -## which shares its rows with M. -## -## -## <#/GAPDoc> -## - - -############################################################################# -## -#O ListOp( [ ] ) -## -## <#GAPDoc Label="RowListMatObj_ListOp"> -## -## -## -## a plain list -## -## -## For a row list matrix M, -## the variant with one argument returns the plain list -## (see ) of its rows, -## and the variant with two arguments returns the plain list of values -## of these rows under the function func. -## -## -## <#/GAPDoc> -## -DeclareOperation( "ListOp", [ IsRowListMatrix ] ); -DeclareOperation( "ListOp", [ IsRowListMatrix, IsFunction ] ); - - -############################################################################# -## -## IsEmptyMatrix( ) -## -## <#GAPDoc Label="MatObj_IsEmptyMatrix"> -## -## -## A boolean -## -## Is true if the matrix object M either has zero columns -## or zero rows, and false otherwise. -## In other words, a matrix object is empty if it has no entries. -## -## -## <#/GAPDoc> -## -DeclareProperty( "IsEmptyMatrix", IsMatrixOrMatrixObj ); - - -############################################################################# -## -## TODO: -## -## Do we REALLY want to support and document the following feature? -## If yes then it is intended as permanent, -## although it contradicts the intended use of matrix objects. -## -## Is this a feature with a generic solution, -## such that the implementors of new kinds of matrix objects need not -## care about it? -## If not then it will be very annoying to be forced to support something -## which will not be used at all as long as the code is used as intended. -## (In particular, the documentation claims on the one hand that it is not -## compulsory to provide a compatible vector object representation for one's -## matrix object implementation, but the ``row access'' will force one to -## provide one.) - -############################################################################ -# In the following sense matrices behave like lists: -############################################################################ - -DeclareOperation( "[]", [IsMatrixOrMatrixObj,IsPosInt] ); # , -# This is guaranteed to return a vector object that has the property -# that changing it changes th row (?) of the matrix ! -# A matrix which is not a row-lists internally has to create an intermediate object that refers to some -# row within it to allow the old GAP syntax M[i][j] for read and write -# access to work. Note that this will never be particularly efficient -# for matrices which are not row-lists. Efficient code will have to use MatElm and -# SetMatElm instead. - -# TODO: ... resp. it will use use M[i,j] -# TODO: provide a default method which creates a proxy object for the given row -# and translates accesses to it to corresponding MatElm / SetMatElm calls; -# creating such a proxy object prints an InfoWarning; -# but for the method for plist matrices, no warning is shown, as it is efficient -# anyway - -# TODO: maybe also add GetRow(mat, i) and GetColumn(mat, i) ??? -# these return IsVectorObj objects. -# these again must be objects which are "linked" to the original matrix, as above... -# TODO: perhaps also have ExtractRow(mat, i) and ExtractColumn(mat, i) - - -############################################################################# -## -## Backwards compatibility -## -## We have to declare the operations/synonyms because otherwise -## the method installations in some packages may not work. -## We should remove them as soon as they are not used anymore. -## - -############################################################################# -## -#C IsRowVectorObj( ) -## -## Existing code which uses this name (most notably, the cvec package) -## should be supported for some time. -## -DeclareSynonym( "IsRowVectorObj", IsVectorObj ); - - -############################################################################# -## -#A DimensionsMat( ) -## -## only for backwards compatibility with existing code: -## -> [ NrRows( ), NrCols( ) ] -## -DeclareAttribute( "DimensionsMat", IsMatrixOrMatrixObj ); - - -############################################################################# -## -#A Length( ) -## -## They had been used in older versions. -## -DeclareAttribute( "Length", IsMatrixOrMatrixObj ); - - -############################################################################# -## -#O NewCompanionMatrix( , , ) -## -## This operation is intended for the installation of tag based methods for -## 'CompanionMatrix', such that 'CompanionMatrix' admits method dispatch -## based on . -## -## (Currently 'NewCompanionMatrix' is undocumented. -## Perhaps we can simply declare 'CompanionMatrix' itself as a tag based -## operation for the given requirement. -## This would work also for `DiagonalMatrix`, `RandomMatrix`, -## `ReflectionMatrix`, etc. -## We could even get rid of `NewMatrix`, `NewZeroMatrix`, -## `NewIdentityMatrix`, by declaring `Matrix`, `ZeroMatrix`, -## `IdentityMatrix` as tag based operations for the requirements in -## question, except that the ordering of the arguments for the four -## argument versions of `NewMatrix` and `Matrix` does not fit.) +##

+## m1 := Matrix( Integers, [ [1,1], [2,2], [3,3], [4,4], [5,5] ] );; +## gap> v1 := Remove( m1 );; Unpack( v1 ); +## [ 5, 5 ] +## gap> Unpack( m1 ); +## [ [ 1, 1 ], [ 2, 2 ], [ 3, 3 ], [ 4, 4 ] ] +## gap> Remove( m1, 2 );; Unpack( m1 ); +## [ [ 1, 1 ], [ 3, 3 ], [ 4, 4 ] ] +## ]]> +## +## +## <#/GAPDoc> ## -DeclareTagBasedOperation( "NewCompanionMatrix", - [ IsOperation, IsUnivariatePolynomial, IsSemiring ] ); +DeclareOperation( "Remove", [ IsRowListMatrix ] ); +DeclareOperation( "Remove", [ IsRowListMatrix, IsPosInt ] ); ############################################################################# ## -#O NewRowVector( ... ) +#O Append( , ) ## -DeclareSynonym( "NewRowVector", NewVector ); +## <#GAPDoc Label="RowListMatObj_Append"> +## +## +## +## nothing +## +## +## For two row list matrices M1, M2 +## such that M1 is mutable and such that the +## and +## values are equal, +## this operation appends the rows of M2 to the +## rows of M1. +##

+## m1 := Matrix( Integers, [ [3,4,5], [7,8,9] ] );; +## gap> m2 := Matrix( Integers, [ [1,0,1], [0,1,0] ] );; +## gap> Append( m1, m2 ); Unpack( m1 ); +## [ [ 3, 4, 5 ], [ 7, 8, 9 ], [ 1, 0, 1 ], [ 0, 1, 0 ] ] +## ]]> +## +## +## <#/GAPDoc> +## +DeclareOperation( "Append", [ IsRowListMatrix, IsRowListMatrix ] ); ############################################################################# ## -#O Randomize( ... ) +#O ShallowCopy( ) ## -## for backwards compatibility with the cvec package +## <#GAPDoc Label="RowListMatObj_ShallowCopy"> +## +## +## +## a matrix object +## +## +## For a row list matrix M, +## this operation returns a new mutable matrix with the same +## and +## values as M, +## which shares its rows with M. +## +## +## <#/GAPDoc> ## -DeclareOperation( "Randomize", [ IsVectorObj and IsMutable, IsRandomSource ] ); -DeclareOperation( "Randomize", [ IsMatrixOrMatrixObj and IsMutable, IsRandomSource ] ); ############################################################################# ## -#O [ , ] -#O [ , ]:= +#O ListOp( [ ] ) ## -DeclareOperation( "[]", [ IsMatrixOrMatrixObj, IsPosInt, IsPosInt ] ); -DeclareOperation( "[]:=", [ IsMatrixOrMatrixObj, IsPosInt, IsPosInt, IsObject ] ); +## <#GAPDoc Label="RowListMatObj_ListOp"> +## +## +## +## a plain list +## +## +## For a row list matrix M, +## the variant with one argument returns the plain list +## (see ) of its rows, +## and the variant with two arguments returns the plain list of values +## of these rows under the function func. +##

+## +## +## +## <#/GAPDoc> +## +DeclareOperation( "ListOp", [ IsRowListMatrix ] ); +DeclareOperation( "ListOp", [ IsRowListMatrix, IsFunction ] ); ############################################################################ # Elementary matrix operations ############################################################################ # + ############################################################################ ## ## <#GAPDoc Label="MultMatrixRow"> @@ -1848,12 +2163,19 @@ DeclareOperation( "[]:=", [ IsMatrixOrMatrixObj, IsPosInt, IsPosInt, IsObject ] ## ## ##

-## Multiplies the i-th row of the mutable matrix mat with the scalar -## elm from the left in-place. +## Multiplies the i-th row of the mutable matrix mat +## with the scalar elm from the left in-place. +##

+## is a synonym of . +## This was chosen because linear combinations of rows of matrices are usually +## written as v \cdot A = [v_1, ... ,v_n] \cdot A +## which multiplies scalars from the left. ##

-## is a synonym of . This was chosen -## because linear combinations of rows of matrices are usually written as -## v \cdot A = [v_1, ... ,v_n] \cdot A which multiplies scalars from the left. +## m1 := Matrix( Integers, [ [2,3], [5,6], [8,9] ] );; +## gap> MultMatrixRow( m1, 2, -10 ); Unpack( m1 ); +## [ [ 2, 3 ], [ -50, -60 ], [ 8, 9 ] ] +## ]]> ## ## ## <#/GAPDoc> @@ -1890,12 +2212,20 @@ DeclareOperation( "MultMatrixRowRight", [ IsMatrixOrMatrixObj and IsMutable, IsI ## ## ##

-## Multiplies the i-th column of the mutable matrix M with the scalar -## elm from the right in-place. +## Multiplies the i-th column of the mutable matrix M +## with the scalar elm from the right in-place. +##

+## is a synonym of +## . +## This was chosen because linear combinations of columns of matrices +## are usually written as A \cdot v^T = A \cdot [v_1, ... ,v_n]^T +## which multiplies scalars from the right. ##

-## is a synonym of . This was -## chosen because linear combinations of columns of matrices are usually written as -## A \cdot v^T = A \cdot [v_1, ... ,v_n]^T which multiplies scalars from the right. +## m1 := Matrix( Integers, [ [3,4,5], [7,8,9] ] );; +## gap> MultMatrixColumn( m1, 2, -10 ); Unpack( m1 ); +## [ [ 3, -40, 5 ], [ 7, -80, 9 ] ] +## ]]> ## ## ## <#/GAPDoc> @@ -1913,8 +2243,8 @@ DeclareSynonym( "MultMatrixColumn", MultMatrixColumnRight); ## ## ##

-## Multiplies the i-th column of the mutable matrix M with the scalar -## elm from the left in-place. +## Multiplies the i-th column of the mutable matrix M +## with the scalar elm from the left in-place. ## ## ## <#/GAPDoc> @@ -1932,12 +2262,20 @@ DeclareOperation( "MultMatrixColumnLeft", [ IsMatrixOrMatrixObj and IsMutable, I ## ## ##

-## Adds the product of elm with the j-th row of the mutable matrix M to its i-th -## row in-place. The j-th row is multiplied with elm from the left. +## Adds the product of elm with the j-th row of the mutable +## matrix M to its i-th row in-place. +## The j-th row is multiplied with elm from the left. ##

-## is a synonym of . This was chosen -## because linear combinations of rows of matrices are usually written as -## v \cdot A = [v_1, ... ,v_n] \cdot A which multiplies scalars from the left. +## is a synonym of . +## This was chosen because linear combinations of rows of matrices are usually +## written as v \cdot A = [v_1, ... ,v_n] \cdot A +## which multiplies scalars from the left. +##

+## m1 := Matrix( Integers, [ [1,1,1], [2,2,2], [3,3,3] ] );; +## gap> AddMatrixRows( m1, 1, 3, 10 ); Unpack( m1 ); +## [ [ 31, 31, 31 ], [ 2, 2, 2 ], [ 3, 3, 3 ] ] +## ]]> ## ## ## <#/GAPDoc> @@ -1955,8 +2293,9 @@ DeclareSynonym( "AddMatrixRows", AddMatrixRowsLeft); ## ## ##

-## Adds the product of elm with the j-th row of the mutable matrix M to its i-th -## row in-place. The j-th row is multiplied with elm from the right. +## Adds the product of elm with the j-th row of the mutable +## matrix M to its i-th row in-place. +## The j-th row is multiplied with elm from the right. ## ## ## <#/GAPDoc> @@ -1974,12 +2313,21 @@ DeclareOperation( "AddMatrixRowsRight", [ IsMatrixOrMatrixObj and IsMutable, IsI ## ## ##

-## Adds the product of elm with the j-th column of the mutable matrix M to its i-th -## column in-place. The j-th column is multiplied with elm from the right. +## Adds the product of elm with the j-th column of the mutable +## matrix M to its i-th column in-place. +## The j-th column is multiplied with elm from the right. ##

-## is a synonym of . This was -## chosen because linear combinations of columns of matrices are usually written as -## A \cdot v^T = A \cdot [v_1, ... ,v_n]^T which multiplies scalars from the right. +## is a synonym of +## . +## This was chosen because linear combinations of columns of matrices are +## usually written as A \cdot v^T = A \cdot [v_1, ... ,v_n]^T +## which multiplies scalars from the right. +##

+## m1 := Matrix( Integers, [ [1,1,1], [2,2,2], [3,3,3] ] );; +## gap> AddMatrixColumns( m1, 1, 3, 10 ); Unpack( m1 ); +## [ [ 11, 1, 1 ], [ 22, 2, 2 ], [ 33, 3, 3 ] ] +## ]]> ## ## ## <#/GAPDoc> @@ -2019,6 +2367,12 @@ DeclareOperation( "AddMatrixColumnsLeft", [ IsMatrixOrMatrixObj and IsMutable, I ## the matrix M, or NrCols( M ) + 1 if the row is zero. ## If the optional argument from is given, the search starts after ## position from. +##

+## m1 := Matrix( Integers, [ [0,0,1,1,1], [1,0,0,1,1] ] );; +## gap> [ PositionNonZeroInRow( m1, 1 ), PositionNonZeroInRow( m1, 2, 2 ) ]; +## [ 3, 4 ] +## ]]> ## ## ## <#/GAPDoc> @@ -2037,6 +2391,12 @@ DeclareOperation( "PositionNonZeroInRow", [ IsMatrixOrMatrixObj, IsPosInt, IsInt ## ##

## Swaps the i-th row and j-th row of a mutable matrix M. +##

+## m1 := Matrix( Integers, [ [1,1], [2,2], [3,3], [4,4], [5,5] ] );; +## gap> SwapMatrixRows( m1, 2, 4 ); Unpack( m1 ); +## [ [ 1, 1 ], [ 4, 4 ], [ 3, 3 ], [ 2, 2 ], [ 5, 5 ] ] +## ]]> ## ## ## <#/GAPDoc> @@ -2054,6 +2414,12 @@ DeclareOperationKernel( "SwapMatrixRows", [ IsMatrixOrMatrixObj and IsMutable, I ## ##

## Swaps the i-th column and j-th column of a mutable matrix M. +##

+## m1 := Matrix( Integers, [ [1,2,3,4,5], [6,7,8,9,10] ] );; +## gap> SwapMatrixColumns( m1, 2, 4 ); Unpack( m1 ); +## [ [ 1, 4, 3, 2, 5 ], [ 6, 9, 8, 7, 10 ] ] +## ]]> ## ## ## <#/GAPDoc> @@ -2076,6 +2442,7 @@ DeclareOperationKernel( "SwapMatrixColumns", [ IsMatrixOrMatrixObj and IsMutable ## representation. ## If both of the matrices are lists-of-lists, then the operation is delegated ## row by row to . +##

## mat1 := [ [ 1, 2 ], [ 3, 4 ] ]; ## [ [ 1, 2 ], [ 3, 4 ] ] @@ -2115,13 +2482,15 @@ DeclareOperation( "AddMatrix", [ IsMatrixOrMatrixObj and IsMutable, IsMatrixOrMa ## In all of these, if the matrix mat is a lists-of-lists, then the ## operation is delegated row by row to and ## . +##

## mat1 := [ [ 1, 2 ], [ 3, 4 ] ]; ## [ [ 1, 2 ], [ 3, 4 ] ] ## gap> MultMatrixRight(mat1, -2); ## gap> mat1; ## [ [ -2, -4 ], [ -6, -8 ] ] -## gap> MultMatrix(mat1, -2); # Note that this is the same as calling MultMatrixLeft(mat1, -2) +## gap> MultMatrix(mat1, -2); +## gap> # Note that this is the same as calling MultMatrixLeft(mat1, -2) ## gap> mat1; ## [ [ 4, 8 ], [ 12, 16 ] ] ## gap> A := FreeAssociativeAlgebra(Rationals, 2); @@ -2144,3 +2513,155 @@ DeclareOperation( "AddMatrix", [ IsMatrixOrMatrixObj and IsMutable, IsMatrixOrMa DeclareOperation( "MultMatrixRight", [ IsMatrixOrMatrixObj and IsMutable, IsScalar ] ); DeclareOperation( "MultMatrixLeft", [ IsMatrixOrMatrixObj and IsMutable, IsScalar ] ); DeclareSynonym( "MultMatrix", MultMatrixLeft ); + + +############################################################################# +## +## IsEmptyMatrix( ) +## +## <#GAPDoc Label="MatObj_IsEmptyMatrix"> +## +## +## A boolean +## +## Is true if the matrix object M either has zero columns +## or zero rows, and false otherwise. +## In other words, a matrix object is empty if it has no entries. +## +## +## <#/GAPDoc> +## +DeclareProperty( "IsEmptyMatrix", IsMatrixOrMatrixObj ); + + +############################################################################# +## +## TODO: +## +## Do we REALLY want to support and document the following feature? +## If yes then it is intended as permanent, +## although it contradicts the intended use of matrix objects. +## +## Is this a feature with a generic solution, +## such that the implementors of new kinds of matrix objects need not +## care about it? +## If not then it will be very annoying to be forced to support something +## which will not be used at all as long as the code is used as intended. +## (In particular, the documentation claims on the one hand that it is not +## compulsory to provide a compatible vector object representation for one's +## matrix object implementation, but the ``row access'' will force one to +## provide one.) + +############################################################################ +# In the following sense matrices behave like lists: +############################################################################ + +DeclareOperation( "[]", [IsMatrixOrMatrixObj,IsPosInt] ); # , +# This is guaranteed to return a vector object that has the property +# that changing it changes th row (?) of the matrix ! +# A matrix which is not a row-lists internally has to create an intermediate object that refers to some +# row within it to allow the old GAP syntax M[i][j] for read and write +# access to work. Note that this will never be particularly efficient +# for matrices which are not row-lists. Efficient code will have to use MatElm and +# SetMatElm instead. + +# TODO: ... resp. it will use use M[i,j] +# TODO: provide a default method which creates a proxy object for the given row +# and translates accesses to it to corresponding MatElm / SetMatElm calls; +# creating such a proxy object prints an InfoWarning; +# but for the method for plist matrices, no warning is shown, as it is efficient +# anyway + +# TODO: maybe also add GetRow(mat, i) and GetColumn(mat, i) ??? +# these return IsVectorObj objects. +# these again must be objects which are "linked" to the original matrix, as above... +# TODO: perhaps also have ExtractRow(mat, i) and ExtractColumn(mat, i) + + +############################################################################# +## +## Backwards compatibility +## +## We have to declare the operations/synonyms because otherwise +## the method installations in some packages may not work. +## We should remove them as soon as they are not used anymore. +## + +############################################################################# +## +#C IsRowVectorObj( ) +## +## Existing code which uses this name (most notably, the cvec package) +## should be supported for some time. +## +DeclareSynonym( "IsRowVectorObj", IsVectorObj ); + + +############################################################################# +## +#A DimensionsMat( ) +## +## only for backwards compatibility with existing code: +## -> [ NrRows( ), NrCols( ) ] +## +DeclareAttribute( "DimensionsMat", IsMatrixOrMatrixObj ); + + +############################################################################# +## +#A Length( ) +## +## They had been used in older versions. +## +DeclareAttribute( "Length", IsMatrixOrMatrixObj ); + + +############################################################################# +## +#O NewCompanionMatrix( , , ) +## +## This operation is intended for the installation of tag based methods for +## 'CompanionMatrix', such that 'CompanionMatrix' admits method dispatch +## based on . +## +## (Currently 'NewCompanionMatrix' is undocumented. +## Perhaps we can simply declare 'CompanionMatrix' itself as a tag based +## operation for the given requirement. +## This would work also for `DiagonalMatrix`, `RandomMatrix`, +## `ReflectionMatrix`, etc. +## We could even get rid of `NewMatrix`, `NewZeroMatrix`, +## `NewIdentityMatrix`, by declaring `Matrix`, `ZeroMatrix`, +## `IdentityMatrix` as tag based operations for the requirements in +## question, except that the ordering of the arguments for the four +## argument versions of `NewMatrix` and `Matrix` does not fit.) +## +DeclareTagBasedOperation( "NewCompanionMatrix", + [ IsOperation, IsUnivariatePolynomial, IsSemiring ] ); + + +############################################################################# +## +#O NewRowVector( ... ) +## +DeclareSynonym( "NewRowVector", NewVector ); + + +############################################################################# +## +#O Randomize( ... ) +## +## for backwards compatibility with the cvec package +## +DeclareOperation( "Randomize", [ IsVectorObj and IsMutable, IsRandomSource ] ); +DeclareOperation( "Randomize", [ IsMatrixOrMatrixObj and IsMutable, IsRandomSource ] ); + + +############################################################################# +## +#O [ , ] +#O [ , ]:= +## +DeclareOperation( "[]", [ IsMatrixOrMatrixObj, IsPosInt, IsPosInt ] ); +DeclareOperation( "[]:=", [ IsMatrixOrMatrixObj, IsPosInt, IsPosInt, IsObject ] ); + + diff --git a/lib/matobjplist.gi b/lib/matobjplist.gi index 69a5106d54..c9af75c590 100644 --- a/lib/matobjplist.gi +++ b/lib/matobjplist.gi @@ -188,6 +188,17 @@ InstallTagBasedMethod( NewZeroVector, return MakeIsPlistVectorRep(basedomain, list, false); end ); +# these two methods align NewMatrix with Matrix +InstallMethod( NewMatrix, [ IsOperation, IsSemiring, IsList, IsInt ], + function( filter, basedomain, list, ncols ) + return NewMatrix( filter, basedomain, ncols, list ); + end); + +InstallMethod( NewMatrix, [ IsOperation, IsSemiring, IsList ], + function( filter, basedomain, list ) + return NewMatrix( filter, basedomain, Length( list[1] ), list ); + end); + InstallTagBasedMethod( NewMatrix, IsPlistMatrixRep, function( filter, basedomain, ncols, list ) diff --git a/lib/oprt.gd b/lib/oprt.gd index c369951114..20bae46045 100644 --- a/lib/oprt.gd +++ b/lib/oprt.gd @@ -2743,11 +2743,16 @@ DeclareGlobalFunction("OnLines"); ## ## ## implements the action on sets of sets. -## For the special case that the sets are pairwise disjoint, +## set must be a proper set whose entries are again proper sets +## (see ). +##

+## returns the proper set whose elements are +## the images obtained by applying the action function +## to x and g, +## for each element x of set. +##

+## For the special case that the elements of set are pairwise disjoint, ## it is possible to use . -## set must be a sorted list whose entries are again sorted lists, -## otherwise an error is triggered -## (see ). ## OnSetsSets( [ [ 1, 2 ], [ 3, 4 ] ], (1,2,3) ); ## [ [ 1, 4 ], [ 2, 3 ] ] @@ -2774,9 +2779,16 @@ DeclareGlobalFunction( "OnSetsSets" ); ## ## implements the action on sets of pairwise disjoint sets ## (see also ). -## set must be a sorted list whose entries are again sorted lists, -## otherwise an error is triggered -## (see ). +## set must be a proper set whose entries are pairwise +## disjoint proper sets. +## However, it is not checked that the entries of +## set are indeed pairwise disjoint. +##

+## returns the proper +## set whose elements are +## the images obtained by applying the action function +## to x and g, +## for each element x of set. ## ## ## <#/GAPDoc> @@ -2794,9 +2806,13 @@ DeclareGlobalFunction( "OnSetsDisjointSets" ); ## ## ## implements the action on sets of tuples. -## set must be a sorted list, -## otherwise an error is triggered -## (see ). +## set must be a proper set of lists without holes +## (see ). +##

+## returns the proper set whose elements are +## the images obtained by applying the action function +## to x and g, +## for each element x of set. ## OnSetsTuples( [ [ 1, 2 ], [ 3, 4 ] ], (1,2,3) ); ## [ [ 1, 4 ], [ 2, 3 ] ] @@ -2815,17 +2831,21 @@ DeclareGlobalFunction("OnSetsTuples"); ############################################################################# ## -#F OnTuplesSets( , ) +#F OnTuplesSets( , ) ## ## <#GAPDoc Label="OnTuplesSets"> ## -## +## ## ## ## implements the action on tuples of sets. -## set must be a list whose entries are again sorted lists, -## otherwise an error is triggered -## (see ). +## tup must be a list without holes whose entries are proper sets +## (see ). +##

+## returns the list of +## the corresponding images obtained by applying the action function +## to x and g, +## for each entry x of tup. ## OnTuplesSets( [ [ 2, 3 ], [ 3, 4 ] ], (1,2,3) ); ## [ [ 1, 3 ], [ 1, 4 ] ] @@ -2844,14 +2864,21 @@ DeclareGlobalFunction("OnTuplesSets"); ############################################################################# ## -#F OnTuplesTuples( , ) +#F OnTuplesTuples( , ) ## ## <#GAPDoc Label="OnTuplesTuples"> ## -## +## ## ## ## implements the action on tuples of tuples. +## tup must be a list without holes whose entries are again +## lists without holes. +##

+## returns the list of +## the corresponding images obtained by applying the action function +## to x and g, +## for each entry x of the list tup. ## OnTuplesTuples( [ [ 2, 3 ], [ 3, 4 ] ], (1,2,3) ); ## [ [ 3, 1 ], [ 1, 4 ] ] diff --git a/tst/testinstall/MatrixObj/ExtractSubMatrix.tst b/tst/testinstall/MatrixObj/ExtractSubMatrix.tst index eeb77a8213..445c4d82e8 100644 --- a/tst/testinstall/MatrixObj/ExtractSubMatrix.tst +++ b/tst/testinstall/MatrixObj/ExtractSubMatrix.tst @@ -1,15 +1,14 @@ gap> START_TEST("ExtractSubMatrix.tst"); - -# +gap> IsBoundGlobal("EXTRACT_SUB_MATRIX"); +true +gap> EXTRACT_SUB_MATRIX = ExtractSubMatrix; +true gap> m1 := [ [ 1, 2, 3 ], [ 4, 5, 6 ] ]; [ [ 1, 2, 3 ], [ 4, 5, 6 ] ] gap> ExtractSubMatrix( m1, [ 2, 1 ], [ 3, 1 ] ); [ [ 6, 4 ], [ 3, 1 ] ] -gap> m2 := IdentityMatrix( Integers, 4 ); -<4x4-matrix over Integers> -gap> m3 := ExtractSubMatrix( m2, [ 2, 4 ], [ 4, 2 ] ); -<2x2-matrix over Integers> -gap> Unpack( m3 ); +gap> m2 := IdentityMatrix( Integers, 4 );; +gap> Unpack( ExtractSubMatrix( m2, [ 2, 4 ], [ 4, 2 ] ) ); [ [ 0, 1 ], [ 1, 0 ] ] # IsGF2MatrixRep @@ -27,6 +26,7 @@ gap> m2 := ExtractSubMatrix( m1, [ 11..30 ], [ 11..30 ] ); < mutable compressed matrix 20x20 over GF(3) > gap> IsOne(m2); true - -# +gap> m2 := IdentityMatrix( Integers, 4 );; +gap> Unpack( ExtractSubMatrix( m2, [ 2, 4 ], [ 4, 2 ] ) ); +[ [ 0, 1 ], [ 1, 0 ] ] gap> STOP_TEST("ExtractSubMatrix.tst");