Examples of Vector objects and Matrix objects

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}

doc/ref/matobj.xml

@@ -21,6 +21,63 @@ cf. Chapters <Ref Chap="Row Vectors"/> and <Ref Chap="Matrices"/>.
 </Section>
 
 
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<Section Label="Some Elementary Examples">
+<Heading>Some Elementary Examples</Heading>
+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 <A>R</A>
+(the <C>BaseDomain</C>).
+To construct these objects we use the operations
+<C>Vector</C> and <C>Matrix</C> which are described in Section
+<Ref Sect="Constructing Vector and Matrix Objects"/>.
+<P/>
+Basic arithmetic operations for vectors and matrices are available: 
+see Sections <Ref Sect="Arithmetical Operations for Vector Objects"/> and
+<Ref Sect="Arithmetical Operations for Matrix Objects"/>.
+<P/>
+Note that if <A>m2</A>, like <A>m2</A>, had been defined over the integers
+then attempting to have displayed its inverse would have thrown an error. 
+<P/>
+<Example><![CDATA[
+gap> 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 );
+<plist vector over Integers of length 4>
+gap> Print( v1 + v2 );
+NewVector(IsPlistVectorRep,Integers,[ -4, -2, 2, 4 ])
+gap> Display( (v1+v2) * TransposedMat( m1 ) );
+<a plist vector over Integers:
+[ 14, 14 ]
+>
+gap> m2 := Matrix( Rationals, [ [8,5], [7,4] ] );;
+gap> Display( m2^(-1) );
+<2x2-matrix over Rationals:
+[[ -4/3, 5/3 ]
+ [ 7/3, -8/3 ]
+]>
+]]></Example>
+
+These objects need to know their <E>type</E>, or <E>filter</E>.
+The simplest of these use plain lists, namely <Ref Filt="IsPlistVectorRep"/>
+and <Ref Filt="IsPlistMatrixRep"/>, 
+which &GAP; chooses automatically for <A>v1</A> and <A>M</A>.
+Note that <A>v2</A> acquires its type by being defined relative to <A>v1</A>.
+Other available types are listed in Sections
+<Ref Sect="Available Representations of Vector Objects"/> and
+<Ref Sect="Available Representations of Matrix Objects"/>.
+
+</Section>
+
+
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <Section Label="Categories of Vector and Matrix Objects">
 <Heading>Categories of Vector and Matrix Objects</Heading>
@@ -55,13 +112,13 @@ More can be added as soon as there is need for them.
 <Section Label="Constructing Vector and Matrix Objects">
 <Heading>Constructing Vector and Matrix Objects</Heading>
 
-<#Include Label="NewVector">
 <#Include Label="Vector">
 <#Include Label="VectorObj_ZeroVector">
-<#Include Label="NewMatrix">
+<#Include Label="NewVector">
 <#Include Label="MatObj_Matrix">
 <#Include Label="MatObj_ZeroMatrix">
 <#Include Label="MatObj_IdentityMatrix">
+<#Include Label="NewMatrix">
 
 </Section>
 

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).
+##  <P/>
+##  <Example><![CDATA[
+##  gap> 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
+##  ]]></Example>
 ##  </Description>
 ##  </ManSection>
 ##  <#/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).
+##  <P/>
+##  <Example><![CDATA[
+##  gap> 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 ] ]
+##  ]]></Example>
 ##  </Description>
 ##  </ManSection>
 ##  <#/GAPDoc>
@@ -1404,7 +1441,7 @@ InstallMethod( Characteristic,
 ##
 ##  <Returns>a matrix object</Returns>
 ##  <Description>
-##  For a vector object <A>M</A>,
+##  For a matrix object <A>M</A>,
 ##  the operations for computing the additive inverse with prescribed
 ##  mutability return a matrix object with the same
 ##  <Ref Attr="ConstructingFilter" Label="for a matrix object"/> and

lib/matobj1.gd

@@ -110,16 +110,12 @@ DeclareCategory( "IsVectorObj", IsVector and IsVecOrMatObj and IsRowVectorOrVect
 ##  argument.
 ##  <P/>
 ##  <Example><![CDATA[
-##  gap> 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 ]
 ##  ]]></Example>
 ##  </Description>
 ##  </ManSection>
@@ -246,7 +242,7 @@ DeclareCategory( "IsMatrixObj", IsMatrixOrMatrixObj );
 ##  the <M>i</M>-th row of <M>M</M>,
 ##  for <M>1 \leq i \leq</M> <C>NumberRows( </C><M>M</M><C> )</C>.
 ##  <P/>
-##  All rows are <Ref Filt="IsVectorObj"/> objects in the same
+##  All rows are <Ref Filt="IsVectorObj"/> 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 <Ref Filt="IsRowListMatrix"/> are <E>not</E>
 ##  necessarily in <Ref Filt="IsList"/>,
 ##  and then they need not obey the general rules for lists.
+##  <P/>
+##  <Example><![CDATA[
+##  gap> 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 ])
+##  ]]></Example>
 ##  </Description>
 ##  </ManSection>
 ##  <#/GAPDoc>
@@ -283,6 +287,12 @@ DeclareCategory( "IsRowListMatrix", IsMatrixObj );
 ##  its base domain with respect to
 ##  <Ref Oper="\in" Label="for a collection"/>, see Section
 ##  <Ref Sect="Concepts and Rules for Vector and Matrix Objects"/>.
+##  <P/>
+##  <Example><![CDATA[
+##  gap> v := Vector( Rationals, [ 3, 4, 7, 8 ] );;
+##  gap> BaseDomain( v );
+##  Rationals
+##  ]]></Example>
 ##  </Description>
 ##  </ManSection>
 ##  <#/GAPDoc>
@@ -292,44 +302,6 @@ DeclareAttribute( "BaseDomain", IsVecOrMatObj );
 #DeclareAttribute( "BaseDomain", IsMatrixOrMatrixObj );
 
 
-#############################################################################
-##
-#A  NumberRows( <M> )
-#A  NrRows( <M> )
-#A  NumberColumns( <M> )
-#A  NrCols( <M> )
-##
-##  <#GAPDoc Label="NumberRowsNumberColumns">
-##  <ManSection>
-##  <Heading>NumberRows and NumberColumns</Heading>
-##  <Attr Name="NumberRows" Arg='M' Label="for a matrix object"/>
-##  <Attr Name="NrRows" Arg='M' Label="for a matrix object"/>
-##  <Attr Name="NumberColumns" Arg='M' Label="for a matrix object"/>
-##  <Attr Name="NrCols" Arg='M' Label="for a matrix object"/>
-##
-##  <Description>
-##  For a matrix object <A>M</A>,
-##  <Ref Attr="NumberRows" Label="for a matrix object"/> and
-##  <Ref Attr="NumberColumns" Label="for a matrix object"/> store the
-##  number of rows and columns of <A>M</A>, respectively.
-##  <P/>
-##  <Ref Attr="NrRows" Label="for a matrix object"/> and
-##  <Ref Attr="NrCols" Label="for a matrix object"/> are synonyms of
-##  <Ref Attr="NumberRows" Label="for a matrix object"/> and
-##  <Ref Attr="NumberColumns" Label="for a matrix object"/>, respectively.
-##  </Description>
-##  </ManSection>
-##  <#/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( <v> )
@@ -374,6 +346,52 @@ DeclareAttribute( "ZeroOfBaseDomain", IsVecOrMatObj );
 #DeclareAttribute( "ZeroOfBaseDomain", IsMatrixOrMatrixObj );
 
 
+#############################################################################
+##
+#A  NumberRows( <M> )
+#A  NrRows( <M> )
+#A  NumberColumns( <M> )
+#A  NrCols( <M> )
+##
+##  <#GAPDoc Label="NumberRowsNumberColumns">
+##  <ManSection>
+##  <Heading>NumberRows and NumberColumns</Heading>
+##  <Attr Name="NumberRows" Arg='M' Label="for a matrix object"/>
+##  <Attr Name="NrRows" Arg='M' Label="for a matrix object"/>
+##  <Attr Name="NumberColumns" Arg='M' Label="for a matrix object"/>
+##  <Attr Name="NrCols" Arg='M' Label="for a matrix object"/>
+##
+##  <Description>
+##  For a matrix object <A>M</A>,
+##  <Ref Attr="NumberRows" Label="for a matrix object"/> and
+##  <Ref Attr="NumberColumns" Label="for a matrix object"/> store the
+##  number of rows and columns of <A>M</A>, respectively.
+##  <P/>
+##  <Ref Attr="NrRows" Label="for a matrix object"/> and
+##  <Ref Attr="NrCols" Label="for a matrix object"/> are synonyms of
+##  <Ref Attr="NumberRows" Label="for a matrix object"/> and
+##  <Ref Attr="NumberColumns" Label="for a matrix object"/>, respectively.
+##  <P/>
+##  <Example><![CDATA[
+##  gap> m1 := Matrix( Integers, [ [1,2,3,4], [6,7,8,9] ] );;
+##  gap> NumberRows( m1 );
+##  2
+##  gap> NrCols( m1 );
+##  4
+##  ]]></Example>
+##  </Description>
+##  </ManSection>
+##  <#/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