Add basic operations for row/column reductions in matrix objects

doc/ref/matobj.xml

@@ -287,5 +287,22 @@ for your new type of vector or matrix objects.)
 
 </Section>
 
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<Section Label="Basic operations for row/column reductions">
+<Heading>Basic operations for row/column reductions</Heading>
+
+<#Include Label="MultMatrixRow">
+<#Include Label="MultMatrixRowRight">
+<#Include Label="MultMatrixColumn">
+<#Include Label="MultMatrixColumnLeft">
+<#Include Label="AddMatrixRows">
+<#Include Label="AddMatrixRowsRight">
+<#Include Label="AddMatrixColumns">
+<#Include Label="AddMatrixColumnsLeft">
+<#Include Label="SwapMatrixRows">
+<#Include Label="SwapMatrixColumns">
+
+</Section>
+
 </Chapter>
 

lib/matobj.gi

@@ -1569,3 +1569,142 @@ InstallMethod( \[\,\]\:\=, "for a matrix object, two positions, and an object",
   end );
 
 
+############################################################################
+# Elementary matrix operations
+############################################################################
+
+InstallMethod( MultMatrixRowLeft, "for a mutable matrix object, a row number, and a scalar",
+  [ IsMatrixObj and IsMutable, IsInt, IsObject ],
+  function( mat, row, scalar )
+    local i;
+
+    for i in [1..NrCols(mat)] do
+        mat[row,i] := scalar * mat[row,i];
+    od;
+
+  end );
+
+############################################################################
+
+InstallMethod( MultMatrixColumnRight, "for a mutable matrix object, a column number, and a scalar",
+  [ IsMatrixObj and IsMutable, IsInt, IsObject ],
+  function( mat, column, scalar )
+    local i;
+
+    for i in [1..NrRows(mat)] do
+        mat[i,column] := mat[i,column] * scalar;
+    od;
+
+  end );
+
+############################################################################
+
+InstallMethod( MultMatrixRowRight, "for a mutable matrix object, a row number, and a scalar",
+  [ IsMatrixObj and IsMutable, IsInt, IsObject ],
+  function( mat, row, scalar )
+      local i;
+
+    for i in [1..NrCols(mat)] do
+        mat[row,i] := mat[row,i] * scalar;
+    od;
+
+  end );
+
+############################################################################
+
+InstallMethod( MultMatrixColumnLeft, "for a mutable matrix object, a column number, and a scalar",
+  [ IsMatrixObj and IsMutable, IsInt, IsObject ],
+  function( mat, column, scalar )
+    local i;
+
+    for i in [1..NrRows(mat)] do
+        mat[i,column] := scalar * mat[i,column];
+    od;
+
+  end );
+
+############################################################################
+
+InstallMethod( AddMatrixRowsLeft, "for a mutable matrix object, two row numbers, and a scalar",
+  [ IsMatrixObj and IsMutable, IsInt, IsInt, IsObject ] ,
+  function( mat, row1, row2, scalar )
+    local i;
+
+    for i in [1..NrCols(mat)] do
+        mat[row1,i] := mat[row1,i] + scalar * mat[row2,i];
+    od;
+
+  end );
+
+ ############################################################################
+
+InstallMethod( AddMatrixRowsRight, "for a mutable matrix object, two row numbers, and a scalar",
+  [ IsMatrixObj and IsMutable, IsInt, IsInt, IsObject ] ,
+  function( mat, row1, row2, scalar )
+    local i;
+
+    for i in [1..NrCols(mat)] do
+        mat[row1,i] := mat[row1,i] + mat[row2,i] * scalar;
+    od;
+
+  end );
+
+############################################################################
+
+InstallMethod( AddMatrixColumnsRight, "for a mutable matrix object, two column numbers, and a scalar",
+  [ IsMatrixObj and IsMutable, IsInt, IsInt, IsObject ] ,
+  function( mat, column1, column2, scalar )
+    local i;
+
+    for i in [1..NrRows(mat)] do
+        mat[i,column1] := mat[i,column1] + mat[i,column2] * scalar;
+    od;
+
+  end );
+
+############################################################################
+
+InstallMethod( AddMatrixColumnsLeft, "for a mutable matrix object, two column numbers, and a scalar",
+  [ IsMatrixObj and IsMutable, IsInt, IsInt, IsObject ] ,
+  function( mat, column1, column2, scalar )
+    local i;
+
+    for i in [1..NrRows(mat)] do
+        mat[i,column1] := mat[i,column1] + scalar * mat[i,column2] ;
+    od;
+
+  end );
+
+############################################################################  
+
+InstallMethod( SwapMatrixRows, "for a mutable matrix object, and two row numbers",
+  [ IsMatrixObj and IsMutable, IsInt, IsInt ],
+  function( mat, row1, row2 )
+    local temp, i;
+
+    if row1 <> row2 then
+        for i in [1..NrCols(mat)] do
+            temp := mat[row1,i];
+            mat[row1,i] := mat[row2,i];
+            mat[row2,i] := temp;
+        od; 
+    fi;
+
+  end );
+
+############################################################################
+
+InstallMethod( SwapMatrixColumns, "for a mutable matrix object, and two column numbers",
+  [ IsMatrixObj and IsMutable, IsInt, IsInt ],
+  function( mat, column1, column2 )
+    local temp, i;
+
+    if column1 <> column2 then
+        for i in [1..NrRows(mat)] do
+            temp := mat[i,column1];
+            mat[i,column1] := mat[i,column2];
+            mat[i,column2] := temp;
+        od; 
+    fi;
+
+  end );

lib/matobj2.gd

@@ -614,7 +614,10 @@ DeclareOperation( "AddVector",
 ##  <P/>
 ##  Note that <Ref Oper="MultVector" Label="for a vector object"/>
 ##  is just a synonym for
-##  <Ref Oper="MultVectorLeft" Label="for a vector object"/>.
+##  <Ref Oper="MultVectorLeft" Label="for a vector object"/>. This was chosen because vectors in
+##  GAP are by default row vectors and scalar multiplication is usually written as
+##  <M>a \cdot v = a \cdot [v_1,...,v_n] = [a\cdot v_1,...,a\cdot v_n]</M> with scalars being
+##  applied from the left.
 ##  <P/>
 ##  If the optional parameters <A>from</A> and <A>to</A> are given then
 ##  only the index range <C>[<A>from</A>..<A>to</A>]</C> is guaranteed to be
@@ -1813,3 +1816,210 @@ DeclareOperation( "Randomize", [ IsMatrixOrMatrixObj and IsMutable, IsRandomSour
 ##
 DeclareOperation( "[]", [ IsMatrixOrMatrixObj, IsPosInt, IsPosInt ] );
 DeclareOperation( "[]:=", [ IsMatrixOrMatrixObj, IsPosInt, IsPosInt, IsObject ] );
+
+
+############################################################################
+# Elementary matrix operations
+############################################################################
+#
+############################################################################
+##
+##  <#GAPDoc Label="MultMatrixRow">
+##  <ManSection>
+##  <Oper Name="MultMatrixRowLeft" Arg='mat,i,elm'/>
+##  <Oper Name="MultMatrixRow" Arg='mat,i,elm'/>
+##  
+##  <Returns>nothing</Returns>
+##
+##  <Description>
+##  <P/>
+##  Multiplies the <A>i</A>-th row of the mutable matrix <A>mat</A> with the scalar 
+##  <A>elm</A> from the left in-place.
+##  <P/>
+##  <Ref Oper="MultMatrixRow"/> is a synonym of <Ref Oper="MultMatrixRowLeft"/>. This was chosen
+##  because linear combinations of rows of matrices are usually written as
+##  <M> v \cdot A = [v_1, ... ,v_n] \cdot A</M> which multiplies scalars from the left.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareOperation( "MultMatrixRowLeft", [ IsMatrixObj and IsMutable, IsInt, IsObject ] );
+DeclareSynonym( "MultMatrixRow", MultMatrixRowLeft);
+
+############################################################################
+##
+##  <#GAPDoc Label="MultMatrixRowRight">
+##  <ManSection>
+##  <Oper Name="MultMatrixRowRight" Arg='mat,i,elm'/>
+##  
+##  <Returns>nothing</Returns>
+##
+##  <Description>
+##  <P/>
+##  Multiplies the <A>i</A>-th row of the mutable matrix <A>mat</A> with the scalar 
+##  <A>elm</A> from the right in-place.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareOperation( "MultMatrixRowRight", [ IsMatrixObj and IsMutable, IsInt, IsObject ]);
+
+############################################################################
+##
+##  <#GAPDoc Label="MultMatrixColumn">
+##  <ManSection>
+##  <Oper Name="MultMatrixColumnRight" Arg='mat,i,elm'/>
+##  <Oper Name="MultMatrixColumn" Arg='mat,i,elm'/>
+##  
+##  <Returns>nothing</Returns>
+##
+##  <Description>
+##  <P/>
+##  Multiplies the <A>i</A>-th column of the mutable matrix <A>mat</A> with the scalar 
+##  <A>elm</A> from the right in-place.
+##  <P/>
+##  <Ref Oper="MultMatrixColumn"/> is a synonym of <Ref Oper="MultMatrixColumnRight"/>. This was
+##  chosen because linear combinations of columns of matrices are usually written as
+##  <M>A \cdot v^T = A \cdot [v_1, ... ,v_n]^T</M> which multiplies scalars from the right.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareOperation( "MultMatrixColumnRight", [ IsMatrixObj and IsMutable, IsInt, IsObject ] );
+DeclareSynonym( "MultMatrixColumn",  MultMatrixColumnRight);
+
+############################################################################
+##
+##  <#GAPDoc Label="MultMatrixColumnLeft">
+##  <ManSection>
+##  <Oper Name="MultMatrixColumnLeft" Arg='mat,i,elm'/>
+##  
+##  <Returns>nothing</Returns>
+##
+##  <Description>
+##  <P/>
+##  Multiplies the <A>i</A>-th column of the mutable matrix <A>mat</A> with the scalar 
+##  <A>elm</A> from the left in-place.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareOperation( "MultMatrixColumnLeft", [ IsMatrixObj and IsMutable, IsInt, IsObject ] );
+
+############################################################################
+##
+##  <#GAPDoc Label="AddMatrixRows">
+##  <ManSection>
+##  <Oper Name="AddMatrixRowsLeft" Arg='mat,i,j,elm'/>
+##  <Oper Name="AddMatrixRows" Arg='mat,i,j,elm'/>
+##  
+##  <Returns>nothing</Returns>
+##
+##  <Description>
+##  <P/>
+##  Adds the product of <A>elm</A> with the <A>j</A>-th row of the mutable matrix <A>mat</A> to its <A>i</A>-th 
+##  row in-place. The <A>j</A>-th row is multiplied with <A>elm</A> from the left.
+##  <P/>
+##  <Ref Oper="AddMatrixRows"/> is a synonym of <Ref Oper="AddMatrixRowsLeft"/>. This was chosen
+##  because linear combinations of rows of matrices are usually written as
+##  <M> v \cdot A = [v_1, ... ,v_n] \cdot A</M> which multiplies scalars from the left.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareOperation( "AddMatrixRowsLeft", [ IsMatrixObj and IsMutable, IsInt, IsInt, IsObject ] );
+DeclareSynonym( "AddMatrixRows", AddMatrixRowsLeft);
+
+############################################################################
+##
+##  <#GAPDoc Label="AddMatrixRowsRight">
+##  <ManSection>
+##  <Oper Name="AddMatrixRowsRight" Arg='mat,i,j,elm'/>
+##  
+##  <Returns>nothing</Returns>
+##
+##  <Description>
+##  <P/>
+##  Adds the product of <A>elm</A> with the <A>j</A>-th row of the mutable matrix <A>mat</A> to its <A>i</A>-th 
+##  row in-place. The <A>j</A>-th row is multiplied with <A>elm</A> from the right.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareOperation( "AddMatrixRowsRight", [ IsMatrixObj and IsMutable, IsInt, IsInt, IsObject ] );
+
+############################################################################
+##
+##  <#GAPDoc Label="AddMatrixColumns">
+##  <ManSection>
+##  <Oper Name="AddMatrixColumnsRight" Arg='mat,i,j,elm'/>
+##  <Oper Name="AddMatrixColumns" Arg='mat,i,j,elm'/>
+##  
+##  <Returns>nothing</Returns>
+##
+##  <Description>
+##  <P/>
+##  Adds the product of <A>elm</A> with the <A>j</A>-th column of the mutable matrix <A>mat</A> to its <A>i</A>-th 
+##  column in-place. The <A>j</A>-th column is multiplied with <A>elm</A> from the right.
+##  <P/>
+##  <Ref Oper="AddMatrixColumns"/> is a synonym of <Ref Oper="AddMatrixColumnsRight"/>. This was
+##  chosen because linear combinations of columns of matrices are usually written as
+##  <M>A \cdot v^T = A \cdot [v_1, ... ,v_n]^T</M> which multiplies scalars from the right.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareOperation( "AddMatrixColumnsRight", [ IsMatrixObj and IsMutable, IsInt, IsInt, IsObject ] );
+DeclareSynonym( "AddMatrixColumns", AddMatrixColumnsRight);
+
+############################################################################
+##
+##  <#GAPDoc Label="AddMatrixColumnsLeft">
+##  <ManSection>
+##  <Oper Name="AddMatrixColumnsLeft" Arg='mat,i,j,elm'/>
+##  
+##  <Returns>nothing</Returns>
+##
+##  <Description>
+##  <P/>
+##  Adds the product of <A>elm</A> with the <A>j</A>-th column of the mutable matrix <A>mat</A> to its <A>i</A>-th 
+##  column in-place. The <A>j</A>-th column is multiplied with <A>elm</A> from the left.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareOperation( "AddMatrixColumnsLeft", [ IsMatrixObj and IsMutable, IsInt, IsInt, IsObject ] );
+
+############################################################################
+##
+##  <#GAPDoc Label="SwapMatrixRows">
+##  <ManSection>
+##  <Oper Name="SwapMatrixRows" Arg='mat,i,j'/>
+##  
+##  <Returns>nothing</Returns>
+##
+##  <Description>
+##  <P/>
+##  Swaps the <A>i</A>-th row and <A>j</A>-th row of a mutable matrix <A>mat</A>.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareOperation( "SwapMatrixRows", [ IsMatrixObj and IsMutable, IsInt, IsInt ] );
+
+############################################################################
+##
+##  <#GAPDoc Label="SwapMatrixColumns">
+##  <ManSection>
+##  <Oper Name="SwapMatrixColumns" Arg='mat,i,j'/>
+##  
+##  <Returns>nothing</Returns>
+##
+##  <Description>
+##  <P/>
+##  Swaps the <A>i</A>-th column and <A>j</A>-th column of a mutable matrix <A>mat</A>.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareOperation( "SwapMatrixColumns", [ IsMatrixObj and IsMutable, IsInt, IsInt ] );