ug4
math_matrix_functions.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2009-2015: G-CSC, Goethe University Frankfurt
3  * Author: Andreas Vogel
4  *
5  * This file is part of UG4.
6  *
7  * UG4 is free software: you can redistribute it and/or modify it under the
8  * terms of the GNU Lesser General Public License version 3 (as published by the
9  * Free Software Foundation) with the following additional attribution
10  * requirements (according to LGPL/GPL v3 §7):
11  *
12  * (1) The following notice must be displayed in the Appropriate Legal Notices
13  * of covered and combined works: "Based on UG4 (www.ug4.org/license)".
14  *
15  * (2) The following notice must be displayed at a prominent place in the
16  * terminal output of covered works: "Based on UG4 (www.ug4.org/license)".
17  *
18  * (3) The following bibliography is recommended for citation and must be
19  * preserved in all covered files:
20  * "Reiter, S., Vogel, A., Heppner, I., Rupp, M., and Wittum, G. A massively
21  * parallel geometric multigrid solver on hierarchically distributed grids.
22  * Computing and visualization in science 16, 4 (2013), 151-164"
23  * "Vogel, A., Reiter, S., Rupp, M., Nägel, A., and Wittum, G. UG4 -- a novel
24  * flexible software system for simulating pde based models on high performance
25  * computers. Computing and visualization in science 16, 4 (2013), 165-179"
26  *
27  * This program is distributed in the hope that it will be useful,
28  * but WITHOUT ANY WARRANTY; without even the implied warranty of
29  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
30  * GNU Lesser General Public License for more details.
31  */
32 
33 #ifndef __H__UG__COMMON__MATH_MATRIX_FUNCTIONS__
34 #define __H__UG__COMMON__MATH_MATRIX_FUNCTIONS__
35 
36 #include "math_matrix.h"
37 
38 namespace ug{
39 
42 
44 // Addition of Matrices
46 
48 // mOut = m1 + m2
49 template <typename matrix_t>
50 inline void
51 MatAdd(matrix_t& mOut, const matrix_t& m1, const matrix_t& m2);
52 
54 // Subtraction of Matrices
56 
58 // mOut = m1 - m2
59 template <typename matrix_t>
60 inline void
61 MatSubtract(matrix_t& mOut, const matrix_t& m1, const matrix_t& m2);
62 
64 // Multiplication of Matrices
66 
68 // mOut = m1 * m2
69 template <size_t N, size_t M, size_t L, typename T>
70 inline void
71 MatMultiply(MathMatrix<N, M, T>& mOut,
72  const MathMatrix<N, L, T>& m1, const MathMatrix<L, M, T>& m2);
73 
75 // mOut = m1 * m2 * m3
76 template <size_t N, size_t M, size_t L, size_t P, typename T>
77 inline void
78 MatMultiply(MathMatrix<N, M, T>& mOut, const MathMatrix<N, L, T>& m1,
79  const MathMatrix<L, P, T>& m2, const MathMatrix<P, M, T>& m3);
80 
82 // mOut = m1^T * m2^T
83 template <size_t N, size_t M, size_t L, typename T>
84 inline void
85 MatMultiplyTransposed(MathMatrix<N, M, T>& mOut,
86  const MathMatrix<L, N, T>& m1, const MathMatrix<M, L, T>& m2);
87 
89 // mOut = m^T * m
90 template <size_t N, size_t M, typename T>
91 inline void
92 MatMultiplyMTM(MathMatrix<N, N, T>& mOut, const MathMatrix<M, N, T>& m);
93 
95 // mOut = m * m^T
96 template <size_t N, size_t M, typename T>
97 inline void
98 MatMultiplyMMT(MathMatrix<M, M, T>& mOut, const MathMatrix<M, N, T>& m);
99 
101 // mOut = m1 * m2^T
102 template <size_t N, size_t M, size_t L, typename T>
103 inline void
104 MatMultiplyMBT(MathMatrix<N, M, T>& mOut, const MathMatrix<N, L, T>& m1,
105  const MathMatrix<M, L, T>& m2);
106 
108 // mOut = m1^T * m2
109 template <size_t N, size_t M, size_t L, typename T>
110 inline void
111 MatMultiplyMTB(MathMatrix<N, M, T>& mOut, const MathMatrix<L, N, T>& m1,
112  const MathMatrix<L, M, T>& m2);
113 
116 // mOut = m1 * m2 * m1^T
117 template <size_t N, size_t M, typename T>
118 inline void
119 MatMultiplyMBMT(MathMatrix<N, N, T>& mOut, const MathMatrix<N, M, T>& m1,
120  const MathMatrix<M, M, T>& m2);
121 
124 // mOut = m1^T * m2 * m1
125 template <size_t N, size_t M, typename T>
126 inline void
127 MatMultiplyMTBM(MathMatrix<N, N, T>& mOut, const MathMatrix<M, N, T>& m1,
128  const MathMatrix<M, M, T>& m2);
129 
131 // "Contraction" for Matrices (note: contraction is usually known regarding tensors!)
133 
134 template <typename matrix_t>
135 inline typename matrix_t::value_type
136 MatContraction(const matrix_t& m1, const matrix_t& m2);
137 
139 // "Deviator" and trace for Matrices
141 
142 template <typename matrix_t>
143 inline typename matrix_t::value_type
144 MatDeviatorTrace(const matrix_t& m, matrix_t& dev);
145 
147 // Scaling of Matrices
149 
151 // mOut = s * m
152 template <typename matrix_t>
153 inline void
154 MatScale(matrix_t& mOut, typename matrix_t::value_type s, const matrix_t& m);
155 
157 // mOut += s * m
158 template <typename matrix_t>
159 inline void
160 MatScaleAppend(matrix_t& mOut, typename matrix_t::value_type s, const matrix_t& m);
161 
163 // Transposed of Matrix
165 
167 template <size_t N, size_t M, typename T>
168 inline void
169 Transpose(MathMatrix<N,M,T>& mOut, const MathMatrix<M,N,T>& m);
170 
172 template <typename matrix_t>
173 inline void
174 Transpose(matrix_t& m);
175 
177 // Determinant of Matrix
179 
181 
188 template <size_t N, typename T>
189 inline typename MathMatrix<N,N,T>::value_type
190 Determinant(const MathMatrix<N,N,T>& m);
191 
192 template <typename T>
193 inline typename MathMatrix<1,1,T>::value_type
194 Determinant(const MathMatrix<1,1,T>& m);
195 
196 template <typename T>
197 inline typename MathMatrix<2,2,T>::value_type
198 Determinant(const MathMatrix<2,2,T>& m);
199 
200 template <typename T>
201 inline typename MathMatrix<3,3,T>::value_type
202 Determinant(const MathMatrix<3,3,T>& m);
204 
206 // Gram Determinant of Matrix
208 
210 
216 template <size_t N, size_t M, typename T>
217 inline typename MathMatrix<N,M,T>::value_type
218 GramDeterminant(const MathMatrix<N,M,T>& m);
219 
220 template <typename T>
221 inline typename MathMatrix<1,1,T>::value_type
222 GramDeterminant(const MathMatrix<1,1,T>& m);
223 
224 template <typename T>
225 inline typename MathMatrix<2,2,T>::value_type
226 GramDeterminant(const MathMatrix<2,2,T>& m);
227 
228 template <typename T>
229 inline typename MathMatrix<3,3,T>::value_type
230 GramDeterminant(const MathMatrix<3,3,T>& m);
232 
234 // Square root of Gram Determinant of Matrix
236 
238 
245 template <size_t N, size_t M, typename T>
246 inline typename MathMatrix<N,M,T>::value_type
247 SqrtGramDeterminant(const MathMatrix<N,M,T>& m);
248 
249 template <typename T>
250 inline typename MathMatrix<1,1,T>::value_type
251 SqrtGramDeterminant(const MathMatrix<1,1,T>& m);
252 
253 template <typename T>
254 inline typename MathMatrix<2,2,T>::value_type
255 SqrtGramDeterminant(const MathMatrix<2,2,T>& m);
256 
257 template <typename T>
258 inline typename MathMatrix<3,3,T>::value_type
259 SqrtGramDeterminant(const MathMatrix<3,3,T>& m);
261 
263 // Inverse of Matrix
265 
267 
275 template <size_t N, size_t M, typename T>
276 inline typename MathMatrix<N,M,T>::value_type
277 Inverse(MathMatrix<N,M,T>& mOut, const MathMatrix<M,N,T>& m);
278 
279 template <typename T>
280 inline typename MathMatrix<1,1,T>::value_type
281 Inverse(MathMatrix<1,1,T>& mOut, const MathMatrix<1,1,T>& m);
282 
283 template <typename T>
284 inline typename MathMatrix<2,2,T>::value_type
285 Inverse(MathMatrix<2,2,T>& mOut, const MathMatrix<2,2,T>& m);
286 
287 template <typename T>
288 inline typename MathMatrix<3,3,T>::value_type
289 Inverse(MathMatrix<3,3,T>& mOut, const MathMatrix<3,3,T>& m);
291 
293 // Inverse Transposed of Matrix
295 
297 
305 template <size_t N, size_t M, typename T>
306 inline typename MathMatrix<N,M,T>::value_type
307 InverseTransposed(MathMatrix<N,M,T>& mOut, const MathMatrix<M,N,T>& m);
308 
309 template <typename T>
310 inline typename MathMatrix<1,1,T>::value_type
311 InverseTransposed(MathMatrix<1,1,T>& mOut, const MathMatrix<1,1,T>& m);
312 
313 template <typename T>
314 inline typename MathMatrix<2,2,T>::value_type
315 InverseTransposed(MathMatrix<2,2,T>& mOut, const MathMatrix<2,2,T>& m);
316 
317 template <typename T>
318 inline typename MathMatrix<3,3,T>::value_type
319 InverseTransposed(MathMatrix<3,3,T>& mOut, const MathMatrix<3,3,T>& m);
321 
323 // Right-Inverse of Matrix
325 
327 
346 template <size_t N, size_t M, typename T>
347 inline typename MathMatrix<N,M,T>::value_type
348 RightInverse(MathMatrix<N,M,T>& mOut, const MathMatrix<M,N,T>& m);
349 
350 template <typename T>
351 inline typename MathMatrix<1,1,T>::value_type
352 RightInverse(MathMatrix<1,1>& mOut, const MathMatrix<1,1>& m);
353 
354 template <typename T>
355 inline typename MathMatrix<2,2,T>::value_type
356 RightInverse(MathMatrix<2,2>& mOut, const MathMatrix<2,2>& m);
357 
358 template <typename T>
359 inline typename MathMatrix<3,3,T>::value_type
360 RightInverse(MathMatrix<3,3>& mOut, const MathMatrix<3,3>& m);
362 
364 // Left-Inverse of Matrix
366 
368 
387 template <size_t N, size_t M, typename T>
388 inline typename MathMatrix<N,M,T>::value_type
389 LeftInverse(MathMatrix<N,M,T>& mOut, const MathMatrix<M,N,T>& m);
390 
391 template <typename T>
392 inline typename MathMatrix<1,1,T>::value_type
393 LeftInverse(MathMatrix<1,1>& mOut, const MathMatrix<1,1>& m);
394 
395 template <typename T>
396 inline typename MathMatrix<2,2,T>::value_type
397 LeftInverse(MathMatrix<2,2>& mOut, const MathMatrix<2,2>& m);
398 
399 template <typename T>
400 inline typename MathMatrix<3,3,T>::value_type
401 LeftInverse(MathMatrix<3,3>& mOut, const MathMatrix<3,3>& m);
403 
405 // Trace of Matrix
407 
409 
413 template <typename T>
414 inline typename MathMatrix<1,1,T>::value_type
415 Trace(const MathMatrix<1,1,T>& m);
416 
417 template <typename T>
418 inline typename MathMatrix<2,2,T>::value_type
419 Trace(const MathMatrix<2,2,T>& m);
420 
421 template <typename T>
422 inline typename MathMatrix<3,3,T>::value_type
423 Trace(const MathMatrix<3,3,T>& m);
425 
427 // Scalar operations for Matrices
429 
431 template <typename matrix_t>
432 inline void
433 MatSet(matrix_t& mInOut, typename matrix_t::value_type s);
434 
436 template <typename matrix_t>
437 inline void
438 MatDiagSet(matrix_t& mInOut, typename matrix_t::value_type s);
439 
441 template <typename matrix_t>
442 inline void
443 MatAdd(matrix_t& mOut, const matrix_t& m, typename matrix_t::value_type s);
444 
446 template <typename matrix_t>
447 inline void
448 MatSubtract(matrix_t& mOut, const matrix_t& m, typename matrix_t::value_type s);
449 
451 template <typename matrix_t>
452 inline void
453 MatDivide(matrix_t& mOut, const matrix_t& m, typename matrix_t::value_type s);
454 
456 template <typename matrix_t>
457 inline void
458 MatMultiply(matrix_t& mOut, const matrix_t& m, typename matrix_t::value_type s);
459 
461 template <typename matrix_t>
462 inline void
463 MatIdentity(matrix_t& mOut);
464 
466 
468 template <typename matrix_t>
469 inline void
470 MatRotationX(matrix_t& mOut, typename matrix_t::value_type rads);
471 
473 
475 template <typename matrix_t>
476 inline void
477 MatRotationY(matrix_t& mOut, typename matrix_t::value_type rads);
478 
480 
482 template <typename matrix_t>
483 inline void
484 MatRotationZ(matrix_t& mOut, typename matrix_t::value_type rads);
485 
489 template <typename matrix_t>
490 inline void
491 MatRotationYawPitchRoll(matrix_t& mOut,
492  typename matrix_t::value_type yaw,
493  typename matrix_t::value_type pitch,
494  typename matrix_t::value_type roll);
495 
500 
501 template <typename matrix_t, typename vector_t>
502 inline void
503 MatHouseholder(matrix_t& mOut, const vector_t& orthoVec);
504 
506 // Norms for Matrices
508 
509 template <typename matrix_t>
510 inline typename matrix_t::value_type
511 MatFrobeniusNormSq(matrix_t& m);
512 
513 template <typename matrix_t>
514 inline typename matrix_t::value_type
515 MatFrobeniusNorm(matrix_t& m);
516 
517 template <typename matrix_t>
518 inline typename matrix_t::value_type
519 MatOneNorm(matrix_t& m);
520 
521 template <typename matrix_t>
522 inline typename matrix_t::value_type
523 MatInftyNorm(matrix_t& m);
524 
525 template <typename matrix_t>
526 inline typename matrix_t::value_type
527 MatMaxNorm(matrix_t& m);
528 
530 template <size_t N, size_t M, typename T>
531 inline typename MathMatrix<N,M,T>::value_type
532 MaxAbsEigenvalue(const MathMatrix<M,N,T>& m);
533 
535 template <size_t N, size_t M, typename T>
536 inline typename MathMatrix<N,M,T>::value_type
537 MinAbsEigenvalue(const MathMatrix<M,N,T>& m);
538 
539 
540 // end group math_matrix
542 
543 } //end of namespace
544 
545 // include a general, but not very fast implementation of the declared methods above.
546 #include "math_matrix_functions_common_impl.hpp"
547 
548 #endif /* __H__UG__COMMON__MATH_MATRIX_FUNCTIONS__ */
ug::MathMatrix
A class for fixed size, dense matrices.
Definition: math_matrix.h:52
ug::MathMatrix::value_type
T value_type
Definition: math_matrix.h:65
ug::MatMultiplyMMT
void MatMultiplyMMT(MathMatrix< M, M, T > &mOut, const MathMatrix< M, N, T > &m)
multiply a matrix with its transposed and stores the result in a second one
Definition: math_matrix_functions_common_impl.hpp:164
ug::MatDeviatorTrace
matrix_t::value_type MatDeviatorTrace(const matrix_t &m, matrix_t &dev)
Definition: math_matrix_functions_common_impl.hpp:295
ug::SqrtGramDeterminant
MathMatrix< N, M, T >::value_type SqrtGramDeterminant(const MathMatrix< N, M, T > &m)
Square root of Gram Determinant of a matrix.
Definition: math_matrix_functions_common_impl.hpp:508
ug::MatContraction
matrix_t::value_type MatContraction(const matrix_t &m1, const matrix_t &m2)
Definition: math_matrix_functions_common_impl.hpp:275
ug::RightInverse
MathMatrix< N, M, T >::value_type RightInverse(MathMatrix< N, M, T > &mOut, const MathMatrix< M, N, T > &m)
Right-Inverse of a Matrix.
Definition: math_matrix_functions_common_impl.hpp:680
ug::MatMultiplyMBMT
void MatMultiplyMBMT(MathMatrix< N, N, T > &mOut, const MathMatrix< N, M, T > &m1, const MathMatrix< M, M, T > &m2)
Definition: math_matrix_functions_common_impl.hpp:223
ug::MinAbsEigenvalue
MathMatrix< N, M, T >::value_type MinAbsEigenvalue(const MathMatrix< M, N, T > &m)
Computes minimum eigenvalue of a (symmetric) matrix.
ug::MatRotationX
void MatRotationX(matrix_t &mOut, typename matrix_t::value_type rads)
Fills the matrix with a matrix that rotates around the x-axis in 3 dimensions.
Definition: math_matrix_functions_common_impl.hpp:857
ug::Transpose
void Transpose(MathMatrix< N, M, T > &mOut, const MathMatrix< M, N, T > &m)
transpose a matrix
Definition: math_matrix_functions_common_impl.hpp:345
ug::Trace
MathMatrix< 1, 1, T >::value_type Trace(const MathMatrix< 1, 1, T > &m)
Trace of a Matrix.
Definition: math_matrix_functions_common_impl.hpp:753
ug::MatInftyNorm
matrix_t::value_type MatInftyNorm(matrix_t &m)
Definition: math_matrix_functions_common_impl.hpp:990
ug::MatMultiplyMTB
void MatMultiplyMTB(MathMatrix< N, M, T > &mOut, const MathMatrix< L, N, T > &m1, const MathMatrix< L, M, T > &m2)
multiply the transposed of a matrix with a matrix and stores the result in mOut
Definition: math_matrix_functions_common_impl.hpp:205
ug::MatMultiplyMBT
void MatMultiplyMBT(MathMatrix< N, M, T > &mOut, const MathMatrix< N, L, T > &m1, const MathMatrix< M, L, T > &m2)
multiply a matrix with the transposed of a second one and stores the result in mOut
Definition: math_matrix_functions_common_impl.hpp:187
ug::MatMultiplyTransposed
void MatMultiplyTransposed(MathMatrix< N, M, T > &mOut, const MathMatrix< L, N, T > &m1, const MathMatrix< M, L, T > &m2)
multiply two transposed matrices and stores the result in a third one
Definition: math_matrix_functions_common_impl.hpp:125
ug::MatIdentity
void MatIdentity(matrix_t &mOut)
Fills the matrix with the identity matrix.
Definition: math_matrix_functions_common_impl.hpp:849
ug::MatSet
void MatSet(matrix_t &mInOut, typename matrix_t::value_type s)
Set each matrix entry to a scalar (componentwise)
Definition: math_matrix_functions_common_impl.hpp:778
ug::Determinant
MathMatrix< N, N, T >::value_type Determinant(const MathMatrix< N, N, T > &m)
Determinant of a matrix.
Definition: math_matrix_functions_common_impl.hpp:382
ug::MatDiagSet
void MatDiagSet(matrix_t &mInOut, typename matrix_t::value_type s)
Set diagonal entries of a matrix to a scalar (other entries are not changed)
Definition: math_matrix_functions_common_impl.hpp:790
ug::MatRotationZ
void MatRotationZ(matrix_t &mOut, typename matrix_t::value_type rads)
Fills the matrix with a matrix that rotates around the y-axis in 2 or 3 dimensions.
Definition: math_matrix_functions_common_impl.hpp:887
ug::MatOneNorm
matrix_t::value_type MatOneNorm(matrix_t &m)
Definition: math_matrix_functions_common_impl.hpp:972
ug::MatRotationY
void MatRotationY(matrix_t &mOut, typename matrix_t::value_type rads)
Fills the matrix with a matrix that rotates around the y-axis in 3 dimensions.
Definition: math_matrix_functions_common_impl.hpp:872
ug::MatFrobeniusNormSq
matrix_t::value_type MatFrobeniusNormSq(matrix_t &m)
Definition: math_matrix_functions_common_impl.hpp:950
ug::MatMaxNorm
matrix_t::value_type MatMaxNorm(matrix_t &m)
Definition: math_matrix_functions_common_impl.hpp:1008
ug::MatMultiplyMTM
void MatMultiplyMTM(MathMatrix< N, N, T > &mOut, const MathMatrix< M, N, T > &m)
multiply a transposed matrix with itself and stores the result in a second one
Definition: math_matrix_functions_common_impl.hpp:141
ug::GramDeterminant
MathMatrix< N, M, T >::value_type GramDeterminant(const MathMatrix< N, M, T > &m)
Gram Determinant of a matrix.
Definition: math_matrix_functions_common_impl.hpp:444
ug::MatAdd
void MatAdd(matrix_t &mOut, const matrix_t &m1, const matrix_t &m2)
adds two matrices and stores the result in a third one
Definition: math_matrix_functions_common_impl.hpp:52
ug::MatScale
void MatScale(matrix_t &mOut, typename matrix_t::value_type s, const matrix_t &m)
scales a matrix_t
Definition: math_matrix_functions_common_impl.hpp:317
ug::MatRotationYawPitchRoll
void MatRotationYawPitchRoll(matrix_t &mOut, typename matrix_t::value_type yaw, typename matrix_t::value_type pitch, typename matrix_t::value_type roll)
Creates a rotation matrix given yaw, pitch and roll in radiants.
Definition: math_matrix_functions_common_impl.hpp:903
ug::LeftInverse
MathMatrix< N, M, T >::value_type LeftInverse(MathMatrix< N, M, T > &mOut, const MathMatrix< M, N, T > &m)
Left-Inverse of a Matrix.
Definition: math_matrix_functions_common_impl.hpp:716
ug::MatFrobeniusNorm
matrix_t::value_type MatFrobeniusNorm(matrix_t &m)
Definition: math_matrix_functions_common_impl.hpp:965
ug::InverseTransposed
MathMatrix< N, M, T >::value_type InverseTransposed(MathMatrix< N, M, T > &mOut, const MathMatrix< M, N, T > &m)
Transposed-Inverse of a Matrix (= Inverse-Transposed of a Matrix)
Definition: math_matrix_functions_common_impl.hpp:623
ug::MatMultiply
void MatMultiply(MathMatrix< N, M, T > &mOut, const MathMatrix< N, L, T > &m1, const MathMatrix< L, M, T > &m2)
multiply two matrices and stores the result in a third one
Definition: math_matrix_functions_common_impl.hpp:85
ug::MatMultiplyMTBM
void MatMultiplyMTBM(MathMatrix< N, N, T > &mOut, const MathMatrix< M, N, T > &m1, const MathMatrix< M, M, T > &m2)
Definition: math_matrix_functions_common_impl.hpp:247
ug::Inverse
MathMatrix< N, M, T >::value_type Inverse(MathMatrix< N, M, T > &mOut, const MathMatrix< M, N, T > &m)
Inverse of a matrix.
Definition: math_matrix_functions_common_impl.hpp:561
ug::MatSubtract
void MatSubtract(matrix_t &mOut, const matrix_t &m1, const matrix_t &m2)
subtracts m2 from m1 and stores the result in a mOut
Definition: math_matrix_functions_common_impl.hpp:68
ug::MaxAbsEigenvalue
MathMatrix< N, M, T >::value_type MaxAbsEigenvalue(const MathMatrix< M, N, T > &m)
Computes maximum eigenvalue of a (symmetric) matrix.
Definition: math_matrix_functions_common_impl.hpp:1025
ug::MatScaleAppend
void MatScaleAppend(matrix_t &mOut, typename matrix_t::value_type s, const matrix_t &m)
scales a matrix_t and adds to result to a second matrix
Definition: math_matrix_functions_common_impl.hpp:329
ug::MatHouseholder
void MatHouseholder(matrix_t &mOut, const vector_t &orthoVec)
Definition: math_matrix_functions_common_impl.hpp:926
ug::MatDivide
void MatDivide(matrix_t &mOut, const matrix_t &m, typename matrix_t::value_type s)
Devide a matrix by a scalar (componentwise)
Definition: math_matrix_functions_common_impl.hpp:825
math_matrix.h
math_matrix_functions_common_impl.hpp
ug
the ug namespace
value_type
T value_type
Definition: sparsematrix_interface.h:2