MatrixObj: Doc, Code and Tests for MultRowVector

- Split MultRowVector to MultRowVectorLeft / MultRowVectorRight.
- MultRowVector is declared a synonym for MultRowVectorLeft.
- 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

- 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

- Add tests for MultRowVector

Author: ssiccha

doc/ref/obsolete.xml

@@ -174,6 +174,10 @@ Here are some further name changes.
   <Item><C>MutableNullMat</C></Item>
   <Item><Ref Func="NullMat"/></Item>
 </Row>
+<Row>
+  <Item><C>MultRowVector</C></Item>
+  <Item><Ref Oper="MultVectorLeft"/></Item>
+</Row>
 </Table>
 
 
@@ -185,6 +189,11 @@ Instead of <C>PositionFirstComponent(list,obj)</C>, you may use
 <C>PositionProperty(list,x->x[1]=obj)</C> as a replacement, depending on
 your specific use case.
 
+<Index Key="MultRowVector"><C>MultRowVector</C></Index>
+The five argument version of the operation <C>MultRowVector</C> has been
+deprecated in GAP 4.10 since it was unused and only available for coefficient
+lists.
+Note that <C>MultRowVector</C> was also renamed to <C>MultVectorLeft</C>.
 
 <ManSection>
 <InfoClass Name="InfoObsolete"/>

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">
 ##  <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>MultRowVectorLeft</C> is just a synonym for
+##  <C>MultRowVector</C>.
 ##  </Description>
 ##  </ManSection>
 ##  <#/GAPDoc>
 ##
 DeclareOperation(
     "MultRowVector",
-        [ IsMutable and IsList, 
-          IsList, IsList, IsList, IsMultiplicativeElement ] );
-
+        [ IsMutable and IsList,
+          IsMultiplicativeElement ] );
+DeclareSynonym( "MultRowVectorLeft", MultRowVector );
 
 #############################################################################
 ##

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

@@ -577,6 +577,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

@@ -384,23 +384,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

@@ -415,30 +415,29 @@ InstallMethod( AddRowVector,
     fi;
   end );
 
-InstallMethod( MultRowVector, "for a plist vector, and a scalar",
+InstallMethod( MultRowVectorLeft,
+  "for a plist vector, and an object",
   [ IsPlistVectorRep and IsMutable, IsObject ],
   function( v, s )
-    MULT_ROW_VECTOR_2(v![ELSPOS],s);
+    MULT_ROW_VECTOR_LEFT_2(v![ELSPOS],s);
   end );
 
-InstallMethod( MultRowVector, "for a plist vector, and a scalar",
-  [ IsPlistVectorRep and IsIntVector and IsMutable, IsObject ],
+InstallMethod( MultRowVectorRight,
+  "for a plist vector, and an object",
+  [ IsPlistVectorRep and IsMutable, IsObject ],
   function( v, s )
-    if IsSmallIntRep(s) then
-        MULT_ROW_VECTOR_2_FAST(v![ELSPOS],s);
-    else
-        MULT_ROW_VECTOR_2(v![ELSPOS],s);
-    fi;
+    MULT_ROW_VECTOR_RIGHT_2(v![ELSPOS],s);
   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;
+InstallOtherMethod( MultRowVector, "for an integer vector, and a small integer",
+  [ IsPlistVectorRep and IsIntVector and IsMutable, IsSmallIntRep ],
+  function( v, s )
+    MULT_ROW_VECTOR_2_FAST(v![ELSPOS],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 ],
   function( v, s )

lib/obsolete.gd

@@ -559,6 +559,33 @@ DeclareObsoleteSynonym( "MutableNullMat", "NullMat" );
 ## Not used in any redistributed packages (11/2017)
 #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 an obsolete synonym for
+##  <C>MultVectorLeft</C>, which calculates <A>mul</A>*<A>list1</A> in-place.
+##  New code should use <C>MultVectorLeft</C> or its synonym
+##  <C>MultVector</C> instead.
+##  <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", "MultVector" );
+
 #############################################################################
 ##
 #O  ReadTest 

lib/obsolete.gi

@@ -877,6 +877,28 @@ end);
 # #  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