1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% 3%% math_matrix.tex LiDIA documentation 4%% 5%% This file contains the documentation of the class bigint_matrix 6%% 7%% Copyright (c) 1995 by LiDIA-Group 8%% 9%% Authors: Patrick Theobald 10%% 11 12 13%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 14 15\NAME 16 17\CLASS{math_matrix< T >} \dotfill parametrized matrix class with basic mathematical 18operations 19 20 21%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 22 23\ABSTRACT 24 25\code{math_matrix< T >} is a class for doing simple mathematical operations over matrices of 26type \code{T} which is allowed to be either a built-in type or a class such as matrix 27multiplication or addition. 28 29According to the template introduction (see page \pageref{template_introduction2}) the class 30\code{math_matrix< T >} is derived from \code{base_matrix< T >}. So you can apply all the 31functions and operators of class \code{base_matrix< T >} to instances of the type 32\code{math_matrix< T >}. 33 34 35%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 36 37\DESCRIPTION 38 39A variable of type \code{math_matrix< T >} contains the same components as \code{base_matrix< T 40 >}. 41 42In the following descriptions we use \code{$A$.rows} to label the number of rows and 43\code{$A$.columns} to label the number of columns of matrix $A$. 44 45 46%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 47 48\CONS 49 50If $a\leq 0$ or $b\leq 0$ or $v = \code{NULL}$ in one of the following constructors the \LEH 51will be invoked. 52 53\begin{fcode}{ct}{math_matrix< T >}{} 54 constructs a $1 \times 1$ matrix initialized with values generated by the default constructor 55 for type \code{T}. 56\end{fcode} 57 58\begin{fcode}{ct}{math_matrix< T >}{lidia_size_t $a$, lidia_size_t $b$} 59 constructs an $a \times b$ matrix initialized with values generated by the default constructor 60 for type \code{T}. 61\end{fcode} 62 63\begin{fcode}{ct}{math_matrix< T >}{lidia_size_t $a$, lidia_size_t $b$, const T ** $v$} 64 constructs an $a \times b$ matrix initialized with the values of the 2-dimensional array $v$. 65 The behaviour of this constructor is undefined if the array $v$ has less than $a$ rows or less 66 than $b$ columns. 67\end{fcode} 68 69\begin{fcode}{ct}{math_matrix< T >}{const math_matrix< T > & $A$} 70 constructs a copy of matrix $A$. 71\end{fcode} 72 73\begin{fcode}{dt}{~math_matrix< T >}{} 74\end{fcode} 75 76 77%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 78 79\ARTH 80 81The class \code{math_matrix< T >} supports the following operators: 82\begin{center} 83 \begin{tabular}{|c|rcl|l|}\hline 84 unary & & $op$ & \code{math_matrix< T >} & $op \in \{ \code{-} \}$ \\\hline 85 binary & \code{math_matrix< T >} & $op$ & \code{math_matrix< T >} 86 & $op \in \{ \code{+}, \code{-}, \code{*} \}$\\\hline 87 binary with & \code{math_matrix< T >} & $op$ & \code{math_matrix< T >} 88 & $op \in \{ \code{+=}, \code{-=}, \code{*=} \}$\\ 89 assignment & & & &\\\hline 90 binary & \code{math_matrix< T >} & $op$ & \code{T} 91 & $op \in \{ \code{+}, \code{-}, \code{*}, \code{/} \}$\\\hline 92 binary & \code{T} & $op$ & \code{math_matrix< T >} 93 & $op \in \{ \code{+}, \code{-}, \code{*} \}$\\\hline 94 binary with & \code{math_matrix< T >} & $op$ & \code{T} 95 & $op \in \{ \code{+=}, \code{-=}, \code{*=}, \code{/=} \}$\\ 96 assignment & & & &\\\hline 97 binary & \code{math_matrix< T >} & $op$ & \code{(T *)} & $op \in \{ \code{*} \}$\\\hline 98 binary & \code{(T *)} & $op$ & \code{math_matrix< T >} & $op \in \{ \code{*} \}$\\\hline 99 binary & \code{math_matrix< T >} & $op$ & \code{math_vector< T >} 100 & $op \in \{ \code{*} \}$\\\hline 101 binary & \code{math_vector< T >} & $op$ & \code{math_matrix< T >} 102 & $op \in \{ \code{*} \}$\\\hline 103 \end{tabular} 104\end{center} 105Here the operators operating on two matrices and the unary minus implement the usual operations 106known from linear algebra. If the dimensions of the operands do not satisfy the usual 107restrictions, the \LEH will be invoked. Note that the dimensions of the resulting matrix are 108adapted to the right dimensions known from linear algebra if necessary. 109 110The operators 111\begin{center} 112 \code{math_matrix< T > * (T *)}\\ 113 \code{(T *) * math_matrix< T >}\\ 114 \code{math_matrix< T > * math_vector< T >}\\ 115 \code{math_vector< T > * math_matrix< T >} 116\end{center} 117realize the matrix vector multiplication and the vector matrix multiplication. If the number of 118elements does not satisfy the usual restrictions known from linear algebra the \LEH will be 119invoked in case of vectors or the behaviour is undefined in case of arrays. 120 121The operators $op$ which have a single element of type \code{T} in their list of arguments 122perform the operation $op$ componentwise, e.g.~\code{T * math_matrix< T >} multiplies each entry 123of the matrix by the given scalar. 124 125To avoid copying, all operators also exist as functions and of course the restrictions for the 126dimensions are still valid: 127 128 129%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 130 131\SSTITLE{Addition} 132 133\begin{fcode}{void}{add}{math_matrix< T > & $C$, const math_matrix< T > & $A$, const math_matrix< T > & $B$} 134 $C \assign A + B$. 135\end{fcode} 136 137\begin{fcode}{void}{add}{math_matrix< T > & $C$, const math_matrix< T > & $B$, const T & $e$} 138 Let $r = \code{$B$.rows}$ and $c = \code{$B$.columns}$. 139 \begin{displaymath} 140 \begin{pmatrix} 141 c_{0,0} & \dots & c_{0,c-1}\\ 142 \vdots & \ddots & \vdots \\ 143 c_{r-1,0} & \dots & c_{r-1,c-1} 144 \end{pmatrix} = 145 \begin{pmatrix} 146 b_{0,0}+e & \dots & b_{0,c-1}+e\\ 147 \vdots & \ddots & \vdots \\ 148 b_{r-1,0}+e & \dots & b_{r-1,c-1}+e 149 \end{pmatrix} \enspace. 150 \end{displaymath} 151\end{fcode} 152 153\begin{fcode}{void}{add}{math_matrix< T > & $C$, const T & $e$, const math_matrix< T > & $B$} 154 Let $r = \code{$B$.rows}$ and $c = \code{$B$.columns}$. 155 \begin{displaymath} 156 \begin{pmatrix} 157 c_{0,0} & \dots & c_{0,c-1}\\ 158 \vdots & \ddots & \vdots \\ 159 c_{r-1,0} & \dots & c_{r-1,c-1} 160 \end{pmatrix} = 161 \begin{pmatrix} 162 e+b_{0,0} & \dots & e+b_{0,c-1}\\ 163 \vdots & \ddots & \vdots \\ 164 e+b_{r-1,0} & \dots & e+b_{r-1,c-1} 165 \end{pmatrix} \enspace. 166 \end{displaymath} 167\end{fcode} 168 169 170%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 171 172\SSTITLE{Subtraction} 173 174\begin{fcode}{void}{subtract}{math_matrix< T > & $C$, const math_matrix< T > & $A$, const math_matrix< T > & $B$} 175 $C \assign A - B$. 176\end{fcode} 177 178\begin{fcode}{void}{subtract}{math_matrix< T > & $C$, const math_matrix< T > & $B$, const T & $e$} 179 Let $r = \code{$B$.rows}$ and $c = \code{$B$.columns}$. 180 \begin{displaymath} 181 \begin{pmatrix} 182 c_{0,0} & \dots & c_{0,c-1}\\ 183 \vdots & \ddots & \vdots \\ 184 c_{r-1,0} & \dots & c_{r-1,c-1} 185 \end{pmatrix} = 186 \begin{pmatrix} 187 b_{0,0}-e & \dots & b_{0,c-1}-e\\ 188 \vdots & \ddots & \vdots \\ 189 b_{r-1,0}-e & \dots & b_{r-1,c-1}-e 190 \end{pmatrix} \enspace. 191 \end{displaymath} 192\end{fcode} 193 194\begin{fcode}{void}{subtract}{math_matrix< T > & $C$, const T & $e$, const math_matrix< T > & $B$} 195 Let $r = \code{$B$.rows}$ and $c = \code{$B$.columns}$. 196 \begin{displaymath} 197 \begin{pmatrix} 198 c_{0,0} & \dots & c_{0,c-1}\\ 199 \vdots & \ddots & \vdots \\ 200 c_{r-1,0} & \dots & c_{r-1,c-1} 201 \end{pmatrix} = 202 \begin{pmatrix} 203 e-b_{0,0} & \dots & e-b_{0,c-1}\\ 204 \vdots & \ddots & \vdots \\ 205 e-b_{r-1,0} & \dots & e-b_{r-1,c-1} 206 \end{pmatrix} \enspace. 207 \end{displaymath} 208\end{fcode} 209 210 211%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 212 213\SSTITLE{Multiplication} 214 215\begin{fcode}{void}{multiply}{math_matrix< T > & $C$, const math_matrix< T > & $A$, const math_matrix< T > & $B$} 216 $C \assign A \cdot B$. 217\end{fcode} 218 219\begin{fcode}{void}{multiply}{math_matrix< T >& $C$, const math_matrix< T > & $B$, const T & $e$} 220 Let $r = \code{$B$.rows}$ and $c = \code{$B$.columns}$. 221 \begin{displaymath} 222 \begin{pmatrix} 223 c_{0,0} & \dots & c_{0,c-1}\\ 224 \vdots & \ddots & \vdots \\ 225 c_{r-1,0} & \dots & c_{r-1,c-1} 226 \end{pmatrix} = 227 \begin{pmatrix} 228 b_{0,0} \cdot e & \dots & b_{0,c-1} \cdot e\\ 229 \vdots & \ddots & \vdots \\ 230 b_{r-1,0} \cdot e & \dots & b_{r-1,c-1} \cdot e 231 \end{pmatrix} \enspace. 232 \end{displaymath} 233\end{fcode} 234 235\begin{fcode}{void}{multiply}{math_matrix< T >& $C$, const T & $e$, const math_matrix< T > & $B$} 236 Let $r = \code{$B$.rows}$ and $c = \code{$B$.columns}$. 237 \begin{displaymath} 238 \begin{pmatrix} 239 c_{0,0} & \dots & c_{0,c-1}\\ 240 \vdots & \ddots & \vdots \\ 241 c_{r-1,0} & \dots & c_{r-1,c-1} 242 \end{pmatrix} = 243 \begin{pmatrix} 244 e \cdot b_{0,0} & \dots & e \cdot b_{0,c-1}\\ 245 \vdots & \ddots & \vdots \\ 246 e \cdot b_{r-1,0} & \dots & e \cdot b_{r-1,c-1} 247 \end{pmatrix} \enspace. 248 \end{displaymath} 249\end{fcode} 250 251 252\begin{fcode}{void}{compwise_multiply}{math_matrix< T >& $C$, 253 const math_matrix< T > & $A$, const math_matrix< T > & $B$}% 254 Let $r = \code{$B$.rows} = \code{$A$.rows}$ and $c = \code{$B$.columns} = \code{$A$.columns}$. 255 \begin{displaymath} 256 \begin{pmatrix} 257 c_{0,0} & \dots & c_{0,c-1}\\ 258 \vdots & \ddots & \vdots \\ 259 c_{r-1,0} & \dots & c_{r-1,c-1} 260 \end{pmatrix}= 261 \begin{pmatrix} 262 a_{0,0} \cdot b_{0,0} & \dots & a_{0,c-1} \cdot b_{0,c-1}\\ 263 \vdots & \ddots & \vdots \\ 264 a_{r-1,0} \cdot b_{r-1,0} & \dots & a_{r-1,c-1} \cdot b_{r-1,c-1} 265 \end{pmatrix} \enspace. 266 \end{displaymath} 267\end{fcode} 268 269\begin{fcode}{void}{multiply}{T *& $v$, const math_matrix< T > & $A$, const T * $w$} 270 assigns the result of the muliplication $A \cdot w$ to $v$ (matrix vector multiplication). If 271 no memory has been allocated for the array $w$, the \LEH will be invoked. If the array $w$ 272 has less than \code{$A$.columns} elements, the behaviour of this function is undefined. Note 273 that if $v = \code{NULL}$, this function allocates memory in the right size and if the array 274 $v$ has less than \code{$A$.rows} elements, the behaviour of this function is undefined. 275\end{fcode} 276 277\begin{fcode}{void}{multiply}{math_vector< T > & $v$, const math_matrix< T > & $A$, const math_vector< T > & $w$} 278 assigns the result of the muliplication $A \cdot w$ to vector $v$ (matrix vector 279 multiplication). If $w.size \neq \code{$A$.columns}$, the \LEH will be invoked. Note, that 280 if vector $v$ has less than \code{$A$.rows} elements, the size is adapted automatically. 281\end{fcode} 282 283\begin{fcode}{void}{multiply}{T *& $v$, const T * $w$, const math_matrix< T > & $A$} 284 assigns the result of the muliplication $w \cdot A$ to $v$ (vector matrix multiplication). If 285 no memory has been allocated for the array $w$, the \LEH will be invoked. If the array $w$ 286 has less than \code{$A$.rows} elements, the behaviour of this function is undefined. Note 287 that if $v = \code{NULL}$, this function allocates memory in the right size and if array $v$ 288 has less than \code{$A$.columns} elements, the behaviour of this function is undefined. 289\end{fcode} 290 291\begin{fcode}{void}{multiply}{math_vector< T > & $v$, const math_vector< T > & $w$, const math_matrix< T > & $A$} 292 assigns the result of the muliplication $w \cdot A$ to vector $v$ (vector matrix 293 multiplication). If $w.size \neq \code{$A$.rows}$, the \LEH will be invoked. Note that if 294 vector $v$ has less than \code{$A$.columns} elements, the size is adapted automatically. 295\end{fcode} 296 297 298%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 299 300\SSTITLE{Division} 301 302\begin{fcode}{void}{divide}{math_matrix< T >& $C$, const math_matrix< T > & $B$, const T & $e$} 303 Let $r = \code{$B$.rows}$ and $c = \code{$B$.columns}$. 304 \begin{displaymath} 305 \begin{pmatrix} 306 c_{0,0} & \dots & c_{0,c-1}\\ 307 \vdots & \ddots & \vdots \\ 308 c_{r-1,0} & \dots & c_{r-1,c-1} 309 \end{pmatrix} = 310 \begin{pmatrix} 311 b_{0,0}/e & \dots & b_{0,c-1}/e\\ 312 \vdots & \ddots & \vdots \\ 313 b_{r-1,0}/e & \dots & b_{r-1,c-1}/e 314 \end{pmatrix} \enspace. 315 \end{displaymath} 316\end{fcode} 317 318\begin{fcode}{void}{compwise_divide}{math_matrix< T >& $C$, 319 const math_matrix< T > & $A$, const math_matrix< T > & $B$}% 320 Let $r = \code{$B$.rows} = \code{$A$.rows}$ and $c = \code{$B$.columns} = \code{$A$.columns}$. 321 \begin{displaymath} 322 \begin{pmatrix} 323 c_{0,0} & \dots & c_{0,c-1}\\ 324 \vdots & \ddots & \vdots \\ 325 c_{r-1,0} & \dots & c_{r-1,c-1} 326 \end{pmatrix} = 327 \begin{pmatrix} 328 a_{0,0}/b_{0,0} & \dots & a_{0,c-1}/b_{0,c-1}\\ 329 \vdots & \ddots & \vdots \\ 330 a_{r-1,0}/b_{r-1,0} & \dots & a_{r-1,c-1}/b_{r-1,c-1} 331 \end{pmatrix} \enspace. 332 \end{displaymath} 333\end{fcode} 334 335 336%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 337 338\SSTITLE{Negation} 339 340\begin{fcode}{void}{negate}{math_matrix< T >& $B$, const math_matrix< T > & $A$} 341 $B \assign -A$. 342\end{fcode} 343 344 345%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 346 347\COMP 348 349The binary operators \code{==} and \code{!=} are overloaded and can be used for comparison by 350components. Let $A$ be an instance of type \code{math_matrix< T >}. 351 352\begin{cfcode}{bool}{$A$.equal}{const math_matrix< T > & $B$} 353 returns \TRUE if $A$ and $B$ are identical, \FALSE otherwise. 354\end{cfcode} 355 356\begin{fcode}{bool}{equal}{const math_matrix< T > & $A$, const math_matrix< T > & $B$} 357 returns \TRUE if $A$ and $B$ are identical, \FALSE otherwise. 358\end{fcode} 359 360\begin{cfcode}{bool}{$A$.unequal}{const math_matrix< T > & $B$} 361 returns \FALSE if $A$ and $B$ are identical, \TRUE otherwise. 362\end{cfcode} 363 364\begin{fcode}{bool}{unequal}{const math_matrix< T > & $A$, const math_matrix< T > & $B$} 365 returns \FALSE if $A$ and $B$ are identical, \TRUE otherwise. 366\end{fcode} 367 368 369%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 370 371\STITLE{Trace} 372 373\begin{cfcode}{void}{$A$.trace}{T & $\mathit{tr}$} 374 assigns the trace of matrix $A$ to $\mathit{tr}$. 375\end{cfcode} 376 377\begin{cfcode}{T}{$A$.trace}{} 378 returns the trace of matrix $A$. 379\end{cfcode} 380 381\begin{fcode}{T}{trace}{const math_matrix< T > & $A$} 382 returns the trace of matrix $A$. 383\end{fcode} 384 385 386%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 387 388\SEEALSO 389 390\SEE{base_matrix}, \SEE{bigint_matrix}, 391\SEE{base_vector}, \SEE{math_vector} 392 393 394%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 395 396\NOTES 397 398As described in the template introduction (see page \pageref{template_introduction2}) for using 399an instance of type \code{math_matrix< T >} the type \code{T} has to have at least 400\begin{itemize} 401\item a swap-function \code{void swap(T &, T&)}, 402\item the input-operator \code{>>}, 403\item the output-operator \code{<<}, 404\item the assignment-operator \code{=}, 405\item the multiply-operator \code{*}, 406\item the addition-operator \code{+}, 407\item the division-operator \code{/}, 408\item the subtract-operator \code{-}, 409\item the unary minus \code{-} and 410\item the equal-operator \code{==}. 411\end{itemize} 412 413 414%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 415 416\EXAMPLES 417 418\begin{quote} 419\begin{verbatim} 420#include <LiDIA/math_matrix.h> 421 422int main() 423{ 424 math_matrix < double > A, B; 425 426 cin >> A >> B; 427 cout << "trace(A) = " << trace(A) << endl; 428 cout << "trace(A+B) = " << trace(A+B) << endl; 429 cout << "trace(A*B) = " << trace(A*B) << endl; 430 431 return 0; 432} 433\end{verbatim} 434\end{quote} 435 436For further examples please refer to \path{LiDIA/src/simple_classes/math_matrix_appl.cc}. 437 438%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 439 440\AUTHOR 441 442Stefan Neis, Patrick Theobald 443