MatrixObj: Doc, Code and Tests for MultRowVector

- Split MultRowVector to MultRowVectorLeft / MultRowVectorRight.
  The reason being that MultRowVector( v, s ) is already defined and
  performs s * v.
- MultRowVectorLeft is declared a synonym for MultRowVector.
- MultRowVectorOp is renamed to MultRowVectorLeftOp on the C level.
- Add four argument declarations for MultRowVectorLeft( vec, mul, from, to )
  and ..Right
- Remove the five argument version of MultRowVector in MatrixObj.
  Deprecate it also in the library. This version was not used anywhere in
  the library or packages
- Use IsMultElement instead of IsObject as a filter for operations doing
  multiplication with scalars

- Add generic and plist implementations of MultRowVector where necessary
  - Implement and declare ..Left and ..Right versions in matrixobj*
  - Only do the ..Left version in listcoef.g?. The methods from listcoef.gi
    are only used for integers and FFEs in the library.
    Adding the ..Right versions would only introduce lots of unused code.
    People wanting to use the ..Right versions should use vector objs.
- Have a kernel function MULT_ROW_VECTOR_LEFT_RIGHT_2 which is called by
  MULT_ROW_VECTOR_LEFT_2 and ..RIGHT_2

- Tests for MultRowVector

Author: ssiccha

lib/listcoef.gd

@@ -97,30 +97,28 @@ DeclareOperation(
 
 #############################################################################
 ##
-#O  MultRowVector( <list1>, <poss1>, <list2>, <poss2>, <mul> )
-#O  MultRowVector( <list>, <mul> )
+#O  MultRowVectorLeft( <list>, <mul> )
 ##
-##  <#GAPDoc Label="MultRowVector">
+##  <#GAPDoc Label="MultRowVectorLeft">
 ##  <ManSection>
-##  <Oper Name="MultRowVector" Arg='list1, [poss1, list2, poss2, ]mul'/>
+##  <Oper Name="MultRowVector" Arg='list1, mul'/>
+##  <Oper Name="MultRowVectorLeft" Arg='list1, mul'/>
+##  <Returns>nothing</Returns>
 ##
 ##  <Description>
-##  The five argument version of this operation replaces
-##  <A>list1</A><C>[</C><A>poss1</A><C>[</C><M>i</M><C>]]</C> by
-##  <C><A>mul</A>*<A>list2</A>[<A>poss2</A>[</C><M>i</M><C>]]</C> for <M>i</M>
-##  between <M>1</M> and <C>Length( <A>poss1</A> )</C>.
+##  This operation calculates <A>mul</A>*<A>list1</A> in-place.
 ##  <P/>
-##  The two-argument version simply multiplies each element of <A>list1</A>, 
-##  in-place, by <A>mul</A>.
+##  Note that <C>MultRowVector</C> is just a synonym for
+##  <C>MultRowVectorLeft</C>.
 ##  </Description>
 ##  </ManSection>
 ##  <#/GAPDoc>
 ##
 DeclareOperation(
-    "MultRowVector",
-        [ IsMutable and IsList, 
-          IsList, IsList, IsList, IsMultiplicativeElement ] );
-
+    "MultRowVectorLeft",
+        [ IsMutable and IsList,
+          IsMultiplicativeElement ] );
+DeclareSynonym( "MultRowVector", MultRowVectorLeft );
 
 #############################################################################
 ##

lib/listcoef.gi

@@ -262,73 +262,50 @@ end );
 
 #############################################################################
 ##
-#M  MultRowVector( <list1>, <poss1>, <list2>, <poss2>, <mult> )
+#M  MultRowVectorLeft( <list>, <mul> )
 ##
-InstallMethod( MultRowVector,"generic method",
+InstallMethod( MultRowVectorLeft,
+    "for a mutable dense list, and a multiplicative element",
     true,
     [ IsDenseList and IsMutable,
-      IsDenseList,
-      IsDenseList,
-      IsDenseList,
       IsMultiplicativeElement ],
     0,
-
-function( l1, p1, l2, p2, m )
-    l1{p1} := m * l2{p2};
-end );
-
-InstallOtherMethod( MultRowVector,"error if immutable",true,
-    [ IsList,IsObject,IsObject,IsObject,IsObject],0,
-    L1_IMMUTABLE_ERROR);
-
-#############################################################################
-##
-#M  MultRowVector( <list>, <mul> )
-##
-InstallOtherMethod( MultRowVector,
-        "two argument generic method",
-    true,
-    [ IsDenseList and IsMutable,
-      IsMultiplicativeElement ],
-    0,
-
 function( l, m )
     local   i;
-
     for i  in [ 1 .. Length(l) ]  do
         l[i] := m * l[i];
     od;
 end );
-
-InstallOtherMethod( MultRowVector,"error if immutable",true,
-    [ IsList,IsObject],0,
+InstallOtherMethod( MultRowVectorLeft, "error if immutable", true,
+    [ IsList, IsMultiplicativeElement ],
+    0,
     L1_IMMUTABLE_ERROR);
 
-InstallOtherMethod( MultRowVector,
-        "Two argument kernel method for small list",
+InstallMethod( MultRowVectorLeft,
+    "kernel method for a mutable dense small list, and a \
+multiplicative element",
     IsCollsElms,
     [ IsSmallList and IsDenseList and IsMutable,
       IsMultiplicativeElement ],
     0,
-    MULT_ROW_VECTOR_2    
+    MULT_ROW_VECTOR_LEFT_2
 );
-
-InstallOtherMethod( MultRowVector,
-        "Two argument kernel method for plain list of cyclotomics and an integer",
+InstallMethod( MultRowVector,
+    "kernel method for a mutable dense plain list of \
+cyclotomics, and a cyclotomic",
     IsCollsElms,
-        [ IsSmallList and IsDenseList and IsMutable and IsPlistRep and
-          IsCyclotomicCollection,
+    [ IsDenseList and IsMutable and IsPlistRep and IsCyclotomicCollection,
       IsCyclotomic ],
     0,
-    MULT_ROW_VECTOR_2_FAST    
+    MULT_ROW_VECTOR_2_FAST
 );
-
-InstallOtherMethod( MultRowVector,
-        "kernel method for vecffe (2 args)",
-        IsCollsElms,
-        [ IsRowVector and IsMutable and IsPlistRep and IsFFECollection,
-          IsFFE],0,
-        MULT_ROWVECTOR_VECFFES );
+InstallMethod( MultRowVector,
+    "kernel method for a mutable row vector of ffes in \
+plain list rep, and an ffe",
+    IsCollsElms,
+    [ IsRowVector and IsMutable and IsPlistRep and IsFFECollection,
+      IsFFE],0,
+    MULT_ROWVECTOR_VECFFES );
 
 
 #############################################################################

lib/matobj.gi

@@ -568,6 +568,51 @@ InstallMethod( Randomize,
     od;
 end );
 
+############################################################################
+# Arithmetical operations:
+############################################################################
+InstallMethod( MultRowVectorLeft,
+  "generic method for a mutable vector, and a multiplicative element",
+  [ IsVectorObj and IsMutable, IsMultiplicativeElement ],
+  function( v, s )
+    local i;
+    for i in [1 .. Length(v)] do
+      v[i] := s * v[i];
+    od;
+  end );
+
+InstallMethod( MultRowVectorRight,
+  "generic method for a mutable vector, and a multiplicative element",
+  [ IsVectorObj and IsMutable, IsMultiplicativeElement ],
+  function( v, s )
+    local i;
+    for i in [1 .. Length(v)] do
+      v[i] := v[i] * s;
+    od;
+  end );
+
+InstallMethod( MultRowVectorLeft,
+  "generic method for a mutable vector, a multiplicative element, an int, \
+and an int",
+  [ IsVectorObj and IsMutable, IsMultiplicativeElement, IsInt, IsInt ],
+  function( v, s, from, to )
+    local i;
+    for i in [from .. to] do
+      v[i] := s * v[i];
+    od;
+  end );
+
+InstallMethod( MultRowVectorRight,
+  "generic method for a mutable vector, a multiplicative element, an int, \
+and an int",
+  [ IsVectorObj and IsMutable, IsMultiplicativeElement, IsInt, IsInt ],
+  function( v, s, from, to )
+    local i;
+    for i in [from .. to] do
+      v[i] := v[i] * s;
+    od;
+  end );
+
 #
 # Compatibility code: Install MatrixObj methods for IsMatrix.
 #

lib/matobj2.gd

@@ -350,23 +350,47 @@ DeclareOperation( "AddRowVector",
 
 # TODO: rename MultRowVector to MultVector; but keep in mind that
 # historically there already was MultRowVector, so be careful to not break that
-DeclareOperation( "MultRowVector",
-  [ IsVectorObj and IsMutable, IsObject ] );
-
-#
-# Also, make it explicit from which side we multiply
-# DeclareOperation( "MultRowVectorFromLeft",
-#   [ IsVectorObj and IsMutable, IsObject ] );
-# DeclareOperation( "MultRowVectorFromRight",
-#   [ IsVectorObj and IsMutable, IsObject ] );
-#DeclareSynonym( "MultRowVector", MultRowVectorFromRight );
-
-# do we really need the following? for what? is any code using this right now?
-# ( a, pa, b, pb, s ) ->  a{pa} := b{pb} * s;
-DeclareOperation( "MultRowVector",
-  [ IsVectorObj and IsMutable, IsList, IsVectorObj, IsList, IsObject ] );
-
-# maybe have this:   vec := vec{[from..to]} * scal ?? cvec has it
+#############################################################################
+##
+#O  MultRowVector( <vec>, <mul>[, <from>, <to>] )
+#O  MultRowVectorLeft( <vec>, <mul>[, <from>, <to>] )
+#O  MultRowVectorRight( <vec>, <mul>[, <from>, <to>] )
+##
+##  <#GAPDoc Label="MatObj_MultRowVector">
+##  <#GAPDoc Label="MatObj_MultRowVectorLeft">
+##  <#GAPDoc Label="MatObj_MultRowVectorRight">
+##  <ManSection>
+##  <Oper Name="MultRowVectorLeft" Arg='vec, mul[, from, to]'/>
+##  <Oper Name="MultRowVectorRight" Arg='vec, mul[, from, to]'/>
+##  <Returns>nothing</Returns>
+##
+##  <Description>
+##  Note that <C>MultRowVector</C> is only a Synonym for
+##  <C>MultRowVectorLeft</C>.
+##  </P>
+##  These operations multiply <A>vec</A> with <A>mul</A> in-place and write
+##  the result to <A>vec</A>.
+##  <C>MultRowVectorLeft</C> multiplies <A>mul</A> to <A>vec</A> from the
+##  left. <C>MultRowVectorRight</C> does so from the right.
+##  </P>
+##  The optional parameters <A>from</A> and <A>to</A> can be used to restrict
+##  the effect of the operation to the entries
+##  <C><A>vec</A>{[<A>from</A>..<A>to</A>]}.
+##  This can be helpful if entries of <A>vec</A> are known to be zero.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareOperation( "MultRowVectorLeft",
+  [ IsVectorObj and IsMutable, IsMultiplicativeElement ] );
+DeclareOperation( "MultRowVectorRight",
+  [ IsVectorObj and IsMutable, IsMultiplicativeElement ] );
+DeclareOperation( "MultRowVectorLeft",
+  [ IsVectorObj and IsMutable, IsMultiplicativeElement, IsInt, IsInt ] );
+DeclareOperation( "MultRowVectorRight",
+  [ IsVectorObj and IsMutable, IsMultiplicativeElement, IsInt, IsInt ] );
+#  Note that MultRowVector is declared a Synonym for MultRowVectorLeft in
+#  listcoef.gd
 
 
 # The following operations for scalars and vectors are possible for scalars in the BaseDomain

lib/matobjplist.gi

@@ -532,57 +532,28 @@ InstallMethod( AddRowVector,
     fi;
   end );
 
-InstallMethod( MultRowVector, "for a plist vector, and a scalar",
-  [ IsPlistVectorRep and IsMutable, IsObject ],
+InstallMethod( MultRowVectorLeft,
+  "for a plist vector, and a multiplicative element",
+  [ IsPlistVectorRep and IsMutable, IsMultiplicativeElement ],
   function( v, s )
-    MULT_ROW_VECTOR_2(v![ELSPOS],s);
+    MULT_ROW_VECTOR_LEFT_2(v![ELSPOS],s);
   end );
 
-InstallMethod( MultRowVector, "for a checking plist vector, and a scalar",
-  [ IsPlistVectorRep and IsCheckingVector and IsMutable, IsObject ],
+InstallMethod( MultRowVectorRight,
+  "for a plist vector, and a multiplicative element",
+  [ IsPlistVectorRep and IsMutable, IsMultiplicativeElement ],
   function( v, s )
-    if not s in v![BDPOS] then
-        ErrorNoReturn("MultRowVector: Scalar is not in base domain");
-    fi;
-    MULT_ROW_VECTOR_2(v![ELSPOS],s);
+    MULT_ROW_VECTOR_RIGHT_2(v![ELSPOS],s);
   end );
 
-InstallMethod( MultRowVector, "for a plist vector, and a scalar",
-  [ IsPlistVectorRep and IsIntVector and IsMutable, IsObject ],
+InstallOtherMethod( MultRowVector, "for an integer vector, and a small integer",
+  [ IsPlistVectorRep and IsIntVector and IsMutable, IsSmallIntRep ],
   function( v, s )
-    if IsSmallIntRep(s) then
-        MULT_ROW_VECTOR_2_FAST(v![ELSPOS],s);
-    else
-        MULT_ROW_VECTOR_2(v![ELSPOS],s);
-    fi;
-  end );
-
-InstallMethod( MultRowVector,
-  "for a plist vector, a list, a plist vector, a list, and a scalar",
-  [ IsPlistVectorRep and IsMutable, IsList,
-    IsPlistVectorRep, IsList, IsObject ],
-  function( a, pa, b, pb, s )
-    a![ELSPOS]{pa} := b![ELSPOS]{pb} * s;
+    MULT_ROW_VECTOR_2_FAST(v![ELSPOS],s);
   end );
 
-InstallMethod( MultRowVector,
-  "for a checking plist vector, a list, a ch. plist vector, a list, a scalar",
-  [ IsPlistVectorRep and IsCheckingVector and IsMutable, IsList,
-    IsPlistVectorRep and IsCheckingVector, IsList, IsObject ],
-  function( a, pa, b, pb, s )
-    local l;
-    l := Length(a![ELSPOS]);
-    if not ForAll(pa,x->x >= 1 and x <= l) then
-        ErrorNoReturn("MultRowVector: Positions pa must lie in first vector");
-    fi;
-    if not IsIdenticalObj(a![BDPOS],b![BDPOS]) then
-        ErrorNoReturn("MultRowVector: Cannot add vectors over different base domains");
-    fi;
-    if not s in a![BDPOS] then
-        ErrorNoReturn("MultRowVector: Scalar not in base domain");
-    fi;
-    a![ELSPOS]{pa} := b![ELSPOS]{pb} * s;
-  end );
+# The four argument version of MultRowVector uses the generic implementation
+# in matobj.gi
 
 InstallMethod( \*, "for a plist vector and a scalar",
   [ IsPlistVectorRep, IsScalar ],

lib/obsolete.gd

@@ -529,6 +529,31 @@ end);
 ## still used by GAPDoc (01/2016)
 DeclareOperation( "PositionFirstComponent", [IsList,IsObject] );
 
+#############################################################################
+##
+#O  MultRowVector( <list1>, <poss1>, <list2>, <poss2>, <mul> )
+##
+##  <#GAPDoc Label="MultRowVector">
+##  <ManSection>
+##  <Oper Name="MultRowVector" Arg='list1, [poss1, list2, poss2, ]mul'/>
+##  <Returns>nothing</Returns>
+##
+##  <Description>
+##  The two argument version of this operation is just a synonym for
+##  <C>MultVectorLeft</C>, which calculates <A>mul</A>*<A>list1</A> in-place.
+##  <P/>
+##  <E>The five argument version of this operation is kept for compatibility
+##  with older versions of &GAP; and will be removed eventually.</E>
+##  It replaces
+##  <A>list1</A><C>[</C><A>poss1</A><C>[</C><M>i</M><C>]]</C> by
+##  <C><A>mul</A>*<A>list2</A>[<A>poss2</A>[</C><M>i</M><C>]]</C> for <M>i</M>
+##  between <M>1</M> and <C>Length( <A>poss1</A> )</C>.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareObsoleteSynonym( "MultRowVector", "MultVectorLeft" );
+
 #############################################################################
 ##
 #O  ReadTest 

lib/obsolete.gi

@@ -877,6 +877,28 @@ local lo,up,s;
 #  fi;
 end );
 
+#############################################################################
+##
+#M  MultRowVector( <list1>, <poss1>, <list2>, <poss2>, <mult> )
+##
+InstallOtherMethod( MultRowVector, "obsolete five argument method",
+    true,
+    [ IsDenseList and IsMutable,
+      IsDenseList,
+      IsDenseList,
+      IsDenseList,
+      IsMultiplicativeElement ],
+    0,
+function( l1, p1, l2, p2, m )
+    InfoObsolete(1, "This usage of `MultRowVector` is no longer",
+           "supported and will be removed eventually." );
+    l1{p1} := m * l2{p2};
+end );
+
+InstallOtherMethod( MultRowVector, "error if immutable", true,
+    [ IsList,IsObject,IsObject,IsObject,IsObject],0,
+    L1_IMMUTABLE_ERROR);
+
 #############################################################################
 ##
 #F  SetUserPreferences