The AddMultiple function performs the operation $\mathrm{mult}B+A$ placing the output in a new object, or in C, depending on calling sequence. All of A, B, and C must be mod m Matrices or Vectors, and mult must be a scalar.

The first calling sequence returns a new mod m Matrix or Vector for the result with the specified ordering, order, or the ordering of the input objects A and B.

Note: If A and B have different ordering, order must be specified.

The second calling sequence places the output of the computation into C, returning NULL.

Note: The parameter C can be the same Matrix or Vector as A or B as long as the operation is performed with direct overlap.  For example, if A and C are the same Matrix, the operation involving the entry $A_{i,j}$ must have the result going to $C_{i,j}$.

The multiplier, mult, is an optional parameter.  However, if it is not specified, it is assumed to be 1. The multiplier must be in the range $0..m-1$.  This function can be used to perform Matrix or Vector subtraction by the selection of $\mathrm{mult}=m-1$. This is coded efficiently, that is, without multiplication.

If specified, the optional keyword 'sparse', is only applicable if the multiplier is not $1$ or $m-1$ and the datatype is a hardware datatype.  It indicates that the algorithm checks for zero entries before performing multiplications. This typically provides an efficiency gain if matrices have 10% or more entries in B equal to zero. This is not implemented for the integer datatype, as it typically provides very little gain.

Note: In cases for which sparse does not apply but has been specified, the option is ignored.

The AddMultiple function allows the use of sub-Matrix and sub-Vector specifications for both input and output Matrices or Vectors. For example, the function can be used to add a row of a Matrix to a row Vector, placing the result in the column of another Matrix.

Note: If the used portion of A or B, and C overlap, but not directly, the behavior of AddMultiple is undefined.

This command is part of the LinearAlgebra[Modular] package, so it can be used in the form AddMultiple(..) only after executing the command with(LinearAlgebra[Modular]).  However, it can always be used in the form LinearAlgebra[Modular][AddMultiple](..).

$\mathrm{with}\left(\mathrm{LinearAlgebra}\left[\mathrm{Modular}\right]\right)\:$

$A≔\mathrm{Mod}\left(13\,\mathrm{Matrix}\left(4\,4\,\left(i\,j\right)\mapsto \mathrm{rand}\left(\right)\right)\,\mathrm{integer}\left[\right]\right)$

$A≔\left[\begin{array}{cccc}10& 0& 8& 12\\ 2& 6& 0& 11\\ 9& 2& 11& 7\\ 4& 11& 12& 11\end{array}\right]$

$B≔\mathrm{Mod}\left(13\,\mathrm{Matrix}\left(4\,4\,\left(i\,j\right)\mapsto \mathbf{if}i=j\mathbf{then}1\mathbf{else}0\mathbf{end}\mathbf{if}\right)\,\mathrm{integer}\left[\right]\right)$

$B≔\left[\begin{array}{cccc}1& 0& 0& 0\\ 0& 1& 0& 0\\ 0& 0& 1& 0\\ 0& 0& 0& 1\end{array}\right]$

$\mathrm{AddMultiple}\left(13\,A\,B\right)$

$\left[\begin{array}{cccc}11& 0& 8& 12\\ 2& 7& 0& 11\\ 9& 2& 12& 7\\ 4& 11& 12& 12\end{array}\right]$

$\mathrm{AddMultiple}\left(13\,2\,A\,B\right)$

$\left[\begin{array}{cccc}12& 0& 8& 12\\ 2& 8& 0& 11\\ 9& 2& 0& 7\\ 4& 11& 12& 0\end{array}\right]$

$\mathrm{AddMultiple}\left(13\,2\,A\,B\,A\right)\:$

$A$

$\left[\begin{array}{cccc}12& 0& 8& 12\\ 2& 8& 0& 11\\ 9& 2& 0& 7\\ 4& 11& 12& 0\end{array}\right]$

$\mathrm{AddMultiple}\left(13\,A\,3\,'\mathrm{transpose}'\,A\,2\,'\mathrm{transpose}'\,B\,1..-1\,1\right)\:$

$A,B$

$\left[\begin{array}{cccc}12& 0& 8& 12\\ 2& 8& 0& 11\\ 9& 2& 0& 7\\ 4& 11& 12& 0\end{array}\right],\left[\begin{array}{cccc}11& 0& 0& 0\\ 10& 1& 0& 0\\ 0& 0& 1& 0\\ 5& 0& 0& 1\end{array}\right]$

$N≔100\:$

$p≔65535\:$

$A≔\mathrm{Mod}\left(p\,\mathrm{Matrix}\left(N\,N\,\left(i\,j\right)\mapsto \mathrm{rand}\left(\right)\right)\,\mathrm{float}\left[8\right]\right)$

$B≔\mathrm{Mod}\left(p\,\mathrm{Matrix}\left(N\,N\,\left(i\,j\right)\mapsto \mathbf{if}i=j\mathbf{then}1\mathbf{else}0\mathbf{end}\mathbf{if}\right)\,\mathrm{float}\left[8\right]\right)$

$t≔\mathrm{time}\left(\right)\:$

$$\begin{gathered} \mathbf{for}i\mathbf{to}2000\mathbf{do} \\ \mathrm{AddMultiple}\left(p\,327\,A\,B\,A\right) \\ \mathbf{end}\mathbf{do}\: \end{gathered}$$$\mathrm{time}\left(\right)-t$

$0.224$

$t≔\mathrm{time}\left(\right)\:$

$$\begin{gathered} \mathbf{for}i\mathbf{to}2000\mathbf{do} \\ \mathrm{AddMultiple}\left(p\,327\,A\,B\,A\,'\mathrm{sparse}'\right) \\ \mathbf{end}\mathbf{do}\: \end{gathered}$$$\mathrm{time}\left(\right)-t$

$0.091$