User Manual 3.3 Matrices - Historique des versions

Admin le 27 février 2018 à 10:55

2018-02-27T10:55:55Z

← Version précédente		Version du 27 février 2018 à 10:55
Ligne 1 :		Ligne 1 :
			__NOTOC__

	== Introduction ==		== Introduction ==
	=== Scope ===		=== Scope ===

Admin le 27 février 2018 à 10:54

2018-02-27T10:54:23Z

← Version précédente		Version du 27 février 2018 à 10:54
Ligne 396 :		Ligne 396 :
	== [[File:lightBulb.png]] Tips & Tricks ==		== [[File:lightBulb.png]] Tips & Tricks ==
	None as of now.		None as of now.

			[[Category:User_Manual_3.3_Mathematics]]

Admin : /* The UDDecompositionImpl class */

2018-02-27T10:52:20Z

The UDDecompositionImpl class

← Version précédente		Version du 27 février 2018 à 10:52
Ligne 335 :		Ligne 335 :
	with		with

	'''*matrix '''= matrix to factorize,		*'''matrix '''= matrix to factorize,
	~~'''~~'''relativeSymmetryThreshold **= threshold above which off-diagonal elements are considered too different and matrix not symmetric,		**'''relativeSymmetryThreshold = threshold above which off-diagonal elements are considered too different and matrix not symmetric,
	~~'''~~'''absolutePositivityThreshold **= threshold below which diagonal elements are considered null and matrix not positive definite		**'''absolutePositivityThreshold = threshold below which diagonal elements are considered null and matrix not positive definite

	* basic constructor :		* basic constructor :
Ligne 344 :		Ligne 344 :
	with		with

	'''*matrix''' = matrix to factorize with relativeSymmetryThreshold = DEFAULT_RELATIVE_SYMMETRY_THRESHOLD (1.0e-15) and absolutePositivityThreshold = DEFAULT_ABSOLUTE_POSITIVITY_THRESHOLD (0.0)		*'''matrix''' = matrix to factorize with relativeSymmetryThreshold = DEFAULT_RELATIVE_SYMMETRY_THRESHOLD (1.0e-15) and absolutePositivityThreshold = DEFAULT_ABSOLUTE_POSITIVITY_THRESHOLD (0.0)

	The following methods are available in it :		The following methods are available in it :

Admin : /* Contents */

2018-02-27T10:49:19Z

Contents

← Version précédente		Version du 27 février 2018 à 10:49
Ligne 79 :		Ligne 79 :
	The most relevant interfaces related to matrices are listed here :		The most relevant interfaces related to matrices are listed here :

	\|=Interface\|=~~Summary~~\|=Javadoc		{\| class="wikitable"
	\|'''Vector<S extends Space>'''\|This interface represents a generic vector in a vectorial space or a point in an affine space.\|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/Vector.html ...]		\|-
	\|'''RealMatrix'''\|Interface defining a real-valued matrix with basic algebraic operations.\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/RealMatrix.html ...]		! scope="col"\| Interface
	\|'''UDDecomposition'''\|An interface to classes that implement an algorithm to calculate the UD-decomposition of a real matrix.\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/UDDecomposition.html ...]		! scope="col"\| Summary
			! scope="col"\| Javadoc
			\|-
			\|'''Vector<S extends Space>'''
			\|This interface represents a generic vector in a vectorial space or a point in an affine space.
			\|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/Vector.html ...]
			\|-
			\|'''RealMatrix'''
			\|Interface defining a real-valued matrix with basic algebraic operations.
			\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/RealMatrix.html ...]
			\|-
			\|'''UDDecomposition'''
			\|An interface to classes that implement an algorithm to calculate the UD-decomposition of a real matrix.
			\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/UDDecomposition.html ...]
			\|}

	=== Classes ===		=== Classes ===
	The most relevant classes related to matrices are listed here :		The most relevant classes related to matrices are listed here :

	\|=Class\|=~~Summary~~\|=Javadoc		{\| class="wikitable"
	\|'''Vector3D'''\|This class implements vectors in a three-dimensional space.\|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/euclidean/threed/Vector3D.html ...]		\|-
	\|'''Matrix3D'''\|This is a real 3x3 matrix designed to be used in geometric calculations. It is compatible with the Vector3D type.\|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/euclidean/threed/Matrix3D.html ...]		! scope="col"\| Class
	\|'''Array2DRowRealMatrix'''\|Implementation of RealMatrix using a double[][] array to store entries and LU decomposition to support linear system solution and inverse.\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/Array2DRowRealMatrix.html ...]		! scope="col"\| Summary
	\|'''UDDecompositionImpl'''\|Calculates the UD decomposition of a matrix.\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/UDDecompositionImpl.html ...]		! scope="col"\| Javadoc
	\|'''SymmetricMatrix''' \| Implementation of a symmetric matrix, implementing AbstractRealMatrix using a double[] array to store entries : storage convention is symmetric conventional full storage.\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/SymmetricMatrix.html ...]		\|-
	\|'''DiagonalMatrix''' \| Implementation of a diagonal matrix.\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/DiagonalMatrix.html ...]		\|'''Vector3D'''
			\|This class implements vectors in a three-dimensional space.
			\|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/euclidean/threed/Vector3D.html ...]
			\|-
			\|'''Matrix3D'''
			\|This is a real 3x3 matrix designed to be used in geometric calculations. It is compatible with the Vector3D type.
			\|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/euclidean/threed/Matrix3D.html ...]
			\|-
			\|'''Array2DRowRealMatrix'''
			\|Implementation of RealMatrix using a double[][] array to store entries and LU decomposition to support linear system solution and inverse.
			\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/Array2DRowRealMatrix.html ...]
			\|-
			\|'''UDDecompositionImpl'''
			\|Calculates the UD decomposition of a matrix.
			\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/UDDecompositionImpl.html ...]
			\|-
			\|'''SymmetricMatrix'''
			\| Implementation of a symmetric matrix, implementing AbstractRealMatrix using a double[] array to store entries : storage convention is symmetric conventional full storage.
			\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/SymmetricMatrix.html ...]
			\|-
			\|'''DiagonalMatrix'''
			\| Implementation of a diagonal matrix.
			\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/DiagonalMatrix.html ...]
			\|}

	=== Matrix3D and Vector3D ===		=== Matrix3D and Vector3D ===

Admin : /* Introduction */

2018-02-27T10:46:31Z

Introduction

← Version précédente		Version du 27 février 2018 à 10:46
Ligne 11 :		Ligne 11 :
	=== Javadoc ===		=== Javadoc ===
	The relevant packages are documented here :		The relevant packages are documented here :
	\|=Library\|=Javadoc
	\| Commons Math\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/package-summary.html Package org.apache.commons.math3.linear]		{\| class="wikitable"
	\| Commons Math\|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/euclidean/threed/package-summary.html Package org.apache.commons.math3.geometry.euclidean.threed]		\|-
	\| Commons Math addons\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/package-summary.html Package org.apache.commons.math3.linear]		! scope="col"\| Library
	\| Commons Math addons\|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/euclidean/threed/package-summary.html Package org.apache.commons.math3.geometry.euclidean.threed]		! scope="col"\| Javadoc
			\|-
			\| Commons Math
			\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/package-summary.html Package org.apache.commons.math3.linear]
			\|-
			\| Commons Math
			\|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/euclidean/threed/package-summary.html Package org.apache.commons.math3.geometry.euclidean.threed]
			\|-
			\| Commons Math addons
			\|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/package-summary.html Package org.apache.commons.math3.linear]
			\|-
			\| Commons Math addons
			\|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/euclidean/threed/package-summary.html Package org.apache.commons.math3.geometry.euclidean.threed]
			\|}


	=== Links ===		=== Links ===

Admin : Admin a déplacé la page Matrices vers User Manual 3.3 Matrices sans laisser de redirection

2018-02-27T10:37:09Z

Admin a déplacé la page Matrices vers User Manual 3.3 Matrices sans laisser de redirection

← Version précédente		Version du 27 février 2018 à 10:37
(Aucune différence)

Admin : 1 révision importée

2018-02-27T10:36:36Z

1 révision importée

← Version précédente		Version du 27 février 2018 à 10:36
(Aucune différence)

Admin le 27 février 2018 à 10:36

2018-02-27T10:36:34Z

Nouvelle page

== Introduction ==
=== Scope ===
This section will focus on the following aspects :

* Matrix3D and Vector3D
* Generic Matrices
* UD Decomposition

=== Javadoc ===
The relevant packages are documented here :
|=Library|=Javadoc
| Commons Math|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/package-summary.html Package org.apache.commons.math3.linear]
| Commons Math|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/euclidean/threed/package-summary.html Package org.apache.commons.math3.geometry.euclidean.threed]
| Commons Math addons|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/package-summary.html Package org.apache.commons.math3.linear]
| Commons Math addons|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/euclidean/threed/package-summary.html Package org.apache.commons.math3.geometry.euclidean.threed]

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Packages Overview ===
The matrices functionality can be found in the following commons-math packages :

* <code>org.apache.commons.math3.geometry.euclidean.threed</code> for Vector3D, Matrix3D
* <code>org.apache.commons.math3.linear</code> for RealMatrix, AbstractRealMatrix, Array2DRowRealMatrix, UDDecomposition, UDDecompositionImpl ...

[[File:PATRIMOINESIRIUSDiagrammeMUmatricesgeneriques.png]]

== Features Description ==
=== The Matrix3D class ===
The Matrix3D is a real matrix designed to be used in geometric calculations. It belongs to the package org.apache.commons.math.geometry.euclidean.threed. The Matrix3D is compatible with the Vector3D type, unlike the matrices implemented in the package "linear".

=== Generic real matrices ===
The library also provides generic representations of real matrices, of any size.

The RealMatrix interface presents the following services :

* usual operations (adding, multiplying)
* extraction of submatrices
* symmetry and antisymmetry tests
* orthogonality tests
* diagonality tests
* invertibility tests

The Array2DRowRealMatrix is one available implementation for generic real matrices.

=== UD decomposition feature ===
The library can compute the UD decomposition of a matrix.

The UD-decomposition of the matrix A is a set of three matrices such that A = UxDxU^^t^^ with :

* U is an upper triangular matrix,
* D is a diagonal matrix,
* U^^t^^ is the transpose of U.

== Getting Started ==
{{specialInclusion prefix=$theme_sub section="GettingStarted"/}}

== Contents ==
=== Interfaces ===
The most relevant interfaces related to matrices are listed here :

|=Interface|=Summary|=Javadoc
|'''Vector<S extends Space>'''|This interface represents a generic vector in a vectorial space or a point in an affine space.|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/Vector.html ...]
|'''RealMatrix'''|Interface defining a real-valued matrix with basic algebraic operations.|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/RealMatrix.html ...]
|'''UDDecomposition'''|An interface to classes that implement an algorithm to calculate the UD-decomposition of a real matrix.|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/UDDecomposition.html ...]

=== Classes ===
The most relevant classes related to matrices are listed here :

|=Class|=Summary|=Javadoc
|'''Vector3D'''|This class implements vectors in a three-dimensional space.|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/euclidean/threed/Vector3D.html ...]
|'''Matrix3D'''|This is a real 3x3 matrix designed to be used in geometric calculations. It is compatible with the Vector3D type.|[{{JavaDoc3.3}}/org/apache/commons/math3/geometry/euclidean/threed/Matrix3D.html ...]
|'''Array2DRowRealMatrix'''|Implementation of RealMatrix using a double[][] array to store entries and LU decomposition to support linear system solution and inverse.|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/Array2DRowRealMatrix.html ...]
|'''UDDecompositionImpl'''|Calculates the UD decomposition of a matrix.|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/UDDecompositionImpl.html ...]
|'''SymmetricMatrix''' | Implementation of a symmetric matrix, implementing AbstractRealMatrix using a double[] array to store entries : storage convention is symmetric conventional full storage.|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/SymmetricMatrix.html ...]
|'''DiagonalMatrix''' | Implementation of a diagonal matrix.|[{{JavaDoc3.3}}/org/apache/commons/math3/linear/DiagonalMatrix.html ...]

=== Matrix3D and Vector3D ===
==== The Matrix3D class ====

A Matrix3D instance be constructed from doubles :

<syntaxhighlight lang="java">
double[][] data = { {1d,2d,3d}, {2d,5d,3d}, {1d,0d,8d} };

Matrix3D matrix3d = new Matrix3D(data);
</syntaxhighlight>

Or from a RealMatrix :

<syntaxhighlight lang="java">
Array2DRowRealMatrix matrixCM = new Array2DRowRealMatrix(data);

Matrix3D matrix3D = new Matrix3D(matrixCM);
</syntaxhighlight>

If the RealMatrix or data dimensions are not 3x3, a MathIllegalArgumentException is thrown.

Some basic methods are available in it :

* Matrix3D / Matrix3D addition

<syntaxhighlight lang="java">
Matrix3D matrix3d_result = matrix3d_1.add(matrix3d_2);
</syntaxhighlight>

* Matrix3D / Matrix3D subtraction

<syntaxhighlight lang="java">
Matrix3D matrix3d_result = matrix3d_1.subtract(matrix3d_2);
</syntaxhighlight>

* Matrix3D / Matrix3D multiplication

<syntaxhighlight lang="java">
Matrix3D matrix3d_result = matrix3d_1.multiply(matrix3d_2);
</syntaxhighlight>

* Matrix3D / Vector3D multiplication

<syntaxhighlight lang="java">
Vector3D vector3d_result = matrix3d.multiply(vector3d);
</syntaxhighlight>

* Matrix3D / double multiplication

<syntaxhighlight lang="java">
Matrix3D matrix3d_result = matrix3d.multiply(2.0);
</syntaxhighlight>

* transposition

<syntaxhighlight lang="java">
Matrix3D transposed_matrix3d = matrix3d.transpose();
</syntaxhighlight>

* transposition and Matrix3D / Vector3D multiplication

<syntaxhighlight lang="java">
Vector3D vector3d_result = matrix3d.transposeAndMultiply(vector3d);
</syntaxhighlight>

* test : orthogonal matrix ? Uses the same-named function in AbstractRealMatrix : same principle, same use.

* getRealMatrix : returns an Array2dRowRealMatrix with the same data in it

<syntaxhighlight lang="java">
RealMatrix realmatrix = matrix3d.getRealMatrix();
</syntaxhighlight>

* toString : creates a string containing all the values.

<code> final Matrix3D matrix = new Matrix3D(testData);</code>
returns <code>"Matrix3D{{1.0,2.0,3.0},{2.0,5.0,3.0},{1.0,0.0,8.0}}"</code>

==== Links between "linear" and "geometry" ====

The packages "linear" and "geometry" both contains classes to represent vectors and matrices, but without any compatibility (for example, the "multiply" methods availables in the generic real matrices only accept the objects from the "linear" package).

To make possible the operations using both types of vectors and matrices, a constructor and a getter are added to the Vector3D and Matrix3D classes.

The constructor creates the object from a similar one (containing the same data) from the "linear" package.

For vectors :

<syntaxhighlight lang="java">
ArrayRealVector realVector = new ArrayRealVector(data);
Vector3D vector3D = new Vector3D(realVector);
</syntaxhighlight>

For matrices, the operation is described in the previous paragraph.

This construction works only if the generic real vectors and matrices dimensions are right (3 for the vectors and 3x3 for the matrices).

The getters are : "getRealMatrix()" in the Matrix3D class and "getRealVector()" in the Vector3D class. They return the generic objects containing identical data.

=== Generic matrices ===
==== The AbstractRealMatrix class ====

===== Symmetry and antisymmetry tests =====

The RealMatrix interface and the AbstractRealMatrix abstract class contain the two methods isSymmetric and isAntisymmetric to test if a real matrix is symmetric or antisymmetric:

<syntaxhighlight lang="java">
Array2DRowRealMatrix sym = new Array2DRowRealMatrix(symmetricData);

boolean isSymmetric = sym.isSymmetric() ;
</syntaxhighlight>

The returned boolean is TRUE if the matrix is symmetric. The equality test made on each value uses the MathUtils.equalsWithRelativeTolerance method, with an algorithm using a relative threshold described in the “Doubles Values Comparisons” paragraph of the SUM.

isAntisymmetric needs a threshold given by the user for the comparisons the zero of the diagonal values. This threshold can be taken as MathUtils.DOUBLES_COMPARISON_EPSILON for standard cases.

But if the matrix contains values closer to zero than this epsilon (1.0e-14), the user shall define their own threshold.

For the rest of the values tested (other than the diagonal), the same method as in isSymmetric is used.

<syntaxhighlight lang="java">
Array2DRowRealMatrix antisym = new Array2DRowRealMatrix(antisymmetricData);

boolean isAntisymmetric = antisym.isAntisymmetric(Precision.DOUBLE_COMPARISON_EPSILON) ;
</syntaxhighlight>

The returned boolean is TRUE if the matrix is antisymmetric.

===== Orthogonal test =====

In order to know if a real matrix is orthogonal, one can use the method isOrthogonal(), this method checks if the column vectors form an orthonormal set :

<syntaxhighlight lang="java">
double[][] orthogonalMatrix = {{ 8.0 / 9.0, 1.0 / 9.0,-4.0 / 9.0 },
{-4.0 / 9.0, 4.0 / 9.0, -7.0 / 9.0 },
{ 1.0 / 9.0, 8.0 / 9.0, 4.0 / 9.0 }};
RealMatrix matrix = new Array2DRowRealMatrix(orthogonalMatrix);
matrix.isOrthogonal(Precision.EPSILON, Precision.EPSILON));
</syntaxhighlight>

Of course, because a matrix usually results from several operations which can introduce numerical errors, one has to give 2 thresholds under which the matrix is considered to be orthogonal. These thresholds concern the normality and the orthogonality of the column vectors of the matrix.

===== Diagonal test =====

In order to know if a real matrix is diagonal, one can use the method isDiagonal() :

<syntaxhighlight lang="java">
double[][] diagonalMatrix = {{ 4.0, 0.0, 0.0, 0.0 },
{ 0.0,-1.0, 0.0, 0.0 },
{ 0.0, 0.0, 5.0, 0.0 },
{0.0, 0.0, 0.0, 9.0 }};
RealMatrix matrix = new Array2DRowRealMatrix(diagonalMatrix);
matrix.isDiagonal(Precision.EPSILON);
</syntaxhighlight>

Of course, because a matrix usually results from several operations which can introduce numerical errors, one has to give a threshold under which the non diagonal elements are considered to be zero ie the matrix is considered to be diagonal.

===== Invertible test =====

In order to know if a real matrix is invertible, one can use the method isInvertible(), this method checks if the n column vectors form a basis of Rn :

<syntaxhighlight lang="java">
double[][] nonSingularMatrix = {{ 4.0, 2.0,-1.5, 2.0 },
{ 6.0, 8.0, 2.1, 2.5 },
{ 2.0, 1.0,-0.75, 1.0 },
{-1.0, 0.0, 0.0, -0.5 }};
RealMatrix matrix = new Array2DRowRealMatrix(nonSingularMatrix);
matrix.isInvertible(Precision.EPSILON);
</syntaxhighlight>

Of course, because a matrix usually results from several operations which can introduce numerical errors, one has to give a threshold under which the column vectors are considered linearly dependant.

=== UD decomposition ===
==== The UDDecompositionImpl class ====

The UDDecompositionImpl class is the one performing the UD-decomposition of a matrix.

The UD-decomposition of matrix A is a set of three matrices such that A = UxDxU^^t^^ with :

* U is an upper triangular matrix,
* D is a diagonal matrix,
* U^^t^^ is the transpose of U.

If the RealMatrix A is not square, a NonSquareMatrixException is thrown.
If the RealMatrix A is not symmetric, a NonSymmetricMatrixException is thrown.
If the RealMatrix A is not positive definite, a NonPositiveDefiniteMatrixException is thrown.

Two constructors are available :

* default constructor :
<code>UDDecompositionImpl(matrix,relativeSymmetryThreshold,absolutePositivityThreshold)</code>

with

'''*matrix '''= matrix to factorize,
''''''relativeSymmetryThreshold **= threshold above which off-diagonal elements are considered too different and matrix not symmetric,
''''''absolutePositivityThreshold **= threshold below which diagonal elements are considered null and matrix not positive definite

* basic constructor :
<code>UDDecompositionImpl(matrix)</code>

with

'''*matrix''' = matrix to factorize with relativeSymmetryThreshold = DEFAULT_RELATIVE_SYMMETRY_THRESHOLD (1.0e-15) and absolutePositivityThreshold = DEFAULT_ABSOLUTE_POSITIVITY_THRESHOLD (0.0)

The following methods are available in it :

<syntaxhighlight lang="java">
final UDDecomposition udut = new UDDecompositionImpl(matrix);
</syntaxhighlight>

* get the U matrix

<syntaxhighlight lang="java">
RealMatrix Umatrix = udut.getU();
</syntaxhighlight>

* get the D matrix

<syntaxhighlight lang="java">
RealMatrix Dmatrix = udut.getD();
</syntaxhighlight>

* get the U^^t^^ matrix

<syntaxhighlight lang="java">
RealMatrix UTmatrix = udut.getUT();
</syntaxhighlight>

* get the determinant

<syntaxhighlight lang="java">
double d = udut.getDeterminant();
</syntaxhighlight>

* get the solver based on the UD decomposition

<syntaxhighlight lang="java">
DecompositionSolver s = udut.getSolver();
</syntaxhighlight>

== Tutorials ==
=== Tutorial 1 ===
{{specialInclusion prefix=$theme_sub section="Tuto1"/}}

=== Tutorial 2 ===
{{specialInclusion prefix=$theme_sub section="Tuto2"/}}

== [[File:lightBulb.png]] Tips & Tricks ==
None as of now.

User Manual 3.3 Matrices - Historique des versions

Admin le 27 février 2018 à 10:55

Admin le 27 février 2018 à 10:54

Admin : /* The UDDecompositionImpl class */

Admin : /* Contents */

Admin : /* Introduction */