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 // Generalized-Inverse of Matrix
407 
420 template<size_t N, size_t M, typename T>
421 inline typename MathMatrix<N,M,T>::value_type
422 GeneralizedInverse(MathMatrix<N,M,T>& mOut, const MathMatrix<M,N,T>& m);
424 
426 // Trace of Matrix
428 
430 
434 template <typename T>
435 inline typename MathMatrix<1,1,T>::value_type
436 Trace(const MathMatrix<1,1,T>& m);
437 
438 template <typename T>
439 inline typename MathMatrix<2,2,T>::value_type
440 Trace(const MathMatrix<2,2,T>& m);
441 
442 template <typename T>
443 inline typename MathMatrix<3,3,T>::value_type
444 Trace(const MathMatrix<3,3,T>& m);
446 
448 // Scalar operations for Matrices
450 
452 template <typename matrix_t>
453 inline void
454 MatSet(matrix_t& mInOut, typename matrix_t::value_type s);
455 
457 template <typename matrix_t>
458 inline void
459 MatDiagSet(matrix_t& mInOut, typename matrix_t::value_type s);
460 
462 template <typename matrix_t>
463 inline void
464 MatAdd(matrix_t& mOut, const matrix_t& m, typename matrix_t::value_type s);
465 
467 template <typename matrix_t>
468 inline void
469 MatSubtract(matrix_t& mOut, const matrix_t& m, typename matrix_t::value_type s);
470 
472 template <typename matrix_t>
473 inline void
474 MatDivide(matrix_t& mOut, const matrix_t& m, typename matrix_t::value_type s);
475 
477 template <typename matrix_t>
478 inline void
479 MatMultiply(matrix_t& mOut, const matrix_t& m, typename matrix_t::value_type s);
480 
482 template <typename matrix_t>
483 inline void
484 MatIdentity(matrix_t& mOut);
485 
487 
489 template <typename matrix_t>
490 inline void
491 MatRotationX(matrix_t& mOut, typename matrix_t::value_type rads);
492 
494 
496 template <typename matrix_t>
497 inline void
498 MatRotationY(matrix_t& mOut, typename matrix_t::value_type rads);
499 
501 
503 template <typename matrix_t>
504 inline void
505 MatRotationZ(matrix_t& mOut, typename matrix_t::value_type rads);
506 
510 template <typename matrix_t>
511 inline void
512 MatRotationYawPitchRoll(matrix_t& mOut,
513  typename matrix_t::value_type yaw,
514  typename matrix_t::value_type pitch,
515  typename matrix_t::value_type roll);
516 
521 
522 template <typename matrix_t, typename vector_t>
523 inline void
524 MatHouseholder(matrix_t& mOut, const vector_t& orthoVec);
525 
527 // Norms for Matrices
529 
530 template <typename matrix_t>
531 inline typename matrix_t::value_type
532 MatFrobeniusNormSq(matrix_t& m);
533 
534 template <typename matrix_t>
535 inline typename matrix_t::value_type
536 MatFrobeniusNorm(matrix_t& m);
537 
538 template <typename matrix_t>
539 inline typename matrix_t::value_type
540 MatOneNorm(matrix_t& m);
541 
542 template <typename matrix_t>
543 inline typename matrix_t::value_type
544 MatInftyNorm(matrix_t& m);
545 
546 template <typename matrix_t>
547 inline typename matrix_t::value_type
548 MatMaxNorm(matrix_t& m);
549 
551 template <size_t N, size_t M, typename T>
552 inline typename MathMatrix<N,M,T>::value_type
553 MaxAbsEigenvalue(const MathMatrix<M,N,T>& m);
554 
556 template <size_t N, size_t M, typename T>
557 inline typename MathMatrix<N,M,T>::value_type
559 
560 
561 // end group math_matrix
563 
564 } //end of namespace
565 
566 // include a general, but not very fast implementation of the declared methods above.
568 
569 #endif /* __H__UG__COMMON__MATH_MATRIX_FUNCTIONS__ */
A class for fixed size, dense matrices.
Definition: math_matrix.h:52
T value_type
Definition: math_matrix.h:65
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
matrix_t::value_type MatDeviatorTrace(const matrix_t &m, matrix_t &dev)
Definition: math_matrix_functions_common_impl.hpp:295
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
matrix_t::value_type MatContraction(const matrix_t &m1, const matrix_t &m2)
Definition: math_matrix_functions_common_impl.hpp:275
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:679
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
MathMatrix< N, M, T >::value_type MinAbsEigenvalue(const MathMatrix< M, N, T > &m)
Computes minimum eigenvalue of a (symmetric) matrix.
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:873
void Transpose(MathMatrix< N, M, T > &mOut, const MathMatrix< M, N, T > &m)
transpose a matrix
Definition: math_matrix_functions_common_impl.hpp:345
MathMatrix< 1, 1, T >::value_type Trace(const MathMatrix< 1, 1, T > &m)
Trace of a Matrix.
Definition: math_matrix_functions_common_impl.hpp:769
matrix_t::value_type MatInftyNorm(matrix_t &m)
Definition: math_matrix_functions_common_impl.hpp:1006
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
MathMatrix< N, M, T >::value_type GeneralizedInverse(MathMatrix< N, M, T > &mOut, const MathMatrix< M, N, T > &m)
Definition: math_matrix_functions_common_impl.hpp:751
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
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
void MatIdentity(matrix_t &mOut)
Fills the matrix with the identity matrix.
Definition: math_matrix_functions_common_impl.hpp:865
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:794
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
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:806
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:903
matrix_t::value_type MatOneNorm(matrix_t &m)
Definition: math_matrix_functions_common_impl.hpp:988
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:888
matrix_t::value_type MatFrobeniusNormSq(matrix_t &m)
Definition: math_matrix_functions_common_impl.hpp:966
matrix_t::value_type MatMaxNorm(matrix_t &m)
Definition: math_matrix_functions_common_impl.hpp:1024
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
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
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
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
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:919
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:715
matrix_t::value_type MatFrobeniusNorm(matrix_t &m)
Definition: math_matrix_functions_common_impl.hpp:981
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:622
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
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
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:560
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
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:1041
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
void MatHouseholder(matrix_t &mOut, const vector_t &orthoVec)
Definition: math_matrix_functions_common_impl.hpp:942
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:841
the ug namespace
T value_type
Definition: sparsematrix_interface.h:2