Patrius - Contributions [fr]

Modèle:JavaDoc4.15

2025-02-10T14:57:36Z

Admin :

https://patrius.cnes.fr/images/upload/JavaDocs/V4.15

Catégorie:Tutorials 4.15

2025-01-16T13:47:38Z

Admin : Page créée avec « [https://github.com/CNES/patrius-tutorials/tree/patrius-4.15 Tutorials PATRIUS 4.15] The tutorials for PATRIUS v4.15 can now be found on the [https://github.com/CNES/pat... »

[https://github.com/CNES/patrius-tutorials/tree/patrius-4.15 Tutorials PATRIUS 4.15]

The tutorials for PATRIUS v4.15 can now be found on the [https://github.com/CNES/patrius-tutorials/tree/patrius-4.15 CNES' GitHub page]

Patrius Versions and Dependencies

2025-01-15T14:54:57Z

Admin : new

{| class="wikitable"
|-
|Version
|style="text-align:center;"|4.15
|style="text-align:center;"|4.14
|style="text-align:center;"|4.13
|style="text-align:center;"|4.12
|style="text-align:center;"|4.11
|style="text-align:center;"|4.10
|style="text-align:center;"|4.9
|style="text-align:center;"|4.8
|style="text-align:center;"|4.7
|style="text-align:center;"|4.6.1
|style="text-align:center;"|4.5.1
|style="text-align:center;"|4.4
|style="text-align:center;"|4.3
|style="text-align:center;"|4.2
|style="text-align:center;"|4.1.1
|style="text-align:center;"|4.0
|style="text-align:center;"|3.x
|-
|Disponibility
|style="text-align:center;"| from 22/11/2024
|style="text-align:center;"| from 23/08/2024
|style="text-align:center;"| from 19/12/2023
|style="text-align:center;"| from 23/05/2023
|style="text-align:center;"| from 03/11/2022
|style="text-align:center;"| from 30/05/2022
|style="text-align:center;"| from 20/10/2021
|style="text-align:center;"| from 04/06/2021
|style="text-align:center;"| from 02/04/2021
|style="text-align:center;"| from 13/08/2020
|style="text-align:center;"| from 30/10/2019
|style="text-align:center;"| from 15/06/2019
|style="text-align:center;"| from 17/01/2019
|style="text-align:center;"| from 16/10/2018
|style="text-align:center;"| from 22/01/2018
|style="text-align:center;"| -
|-
|Javadoc
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|style="text-align:center;"|yes
|-
|- style="vertical-align:top;"
|Dependencies
|style="text-align:center;"|Java 1.8 
|style="text-align:center;"|Java 1.8 
|style="text-align:center;"|Java 1.8 
|style="text-align:center;"|Java 1.8 
|style="text-align:center;"|Java 1.8 
|style="text-align:center;"|Java 1.8 
|style="text-align:center;"|Java 1.8 
|style="text-align:center;"|Java 1.8 
|style="text-align:center;"|Java 1.8 
|style="text-align:center;"|Java 1.8 
|style="text-align:center;"|Java 1.8 
|style="text-align:center;"|Java 1.7 
|style="text-align:center;"|Java 1.7 
|style="text-align:center;"|Java 1.6 
|style="text-align:center;"|Java 1.6 
|}

Patrius Versions and Dependencies

2025-01-15T14:54:46Z

Admin : new page

2023-12-19T16:11:57Z

Admin :

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

* Matrix3D and Vector3D
* Generic Matrices
* UD Decomposition

=== Javadoc ===
The relevant packages are documented here :

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
| Patrius
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/linear/package-summary.html Package fr.cnes.sirius.patrius.math.linear]
|-
| Patrius
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/package-summary.html Package fr.cnes.sirius.patrius.math.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 packages :

* <code>fr.cnes.sirius.patrius.math.geometry.euclidean.threed</code> for Vector3D, Matrix3D
* <code>fr.cnes.sirius.patrius.math.linear</code> for RealMatrix, AbstractRealMatrix, Array2DRowRealMatrix, UDDecomposition, UDDecompositionImpl ...

Please note that not all implementations are present in the following diagram for the sake of clarity.

[[File:PATRIMOINESIRIUSDiagrammeMUmatricesgeneriques.png]]

== Features Description ==
=== The Matrix3D class ===
The Matrix3D is a real matrix designed to be used in geometric calculations. The Matrix3D is compatible with the Vector3D type, unlike the matrices implemented in the package "linear".

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 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.

=== Decompositions ===

PATRIUS provides several ways for matrix decomposition. Interface for decomposition is <code>Decomposition</code>.
A decomposition provides a way to:
* Inverse a matrix
* Separate a matrix into a product of specific matrices (orthogonal, upper triangular, etc.) depending on the solver type.
Standard decomposition in PATRIUS are:
* <code>QRDecomposition</code>
* <code>LUDecomposition</code>
* <code>CholeskyDecomposition</code>
* <code>SingularValueDecomposition</code>
* <code>UDDecompositionImpl</code>
RealMatrix interface possesses a method to get its inverse. If not provided, by default a <code>LUDecomposition</code>is used.

==== Exemple with UD decomposition ====
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.

=== Symmetric matrices ===

Symmetric matrices are handled through the generic <code>SymmetricMatrix</code> interface.
An implementation is provided: <code>ArrayRowSymmetricMatrix</code>. This implementation optimally stores data in one single 1D-array.

== Getting Started ==

=== 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>

* minimum

<syntaxhighlight lang="java">
double min = matrix3d.getMin();
</syntaxhighlight>

* maximum

<syntaxhighlight lang="java">
double max = matrix3d.getMax();
</syntaxhighlight>

* absolute values

<syntaxhighlight lang="java">
RealMatrix abs_matrix3d = matrix3d.getAbs();
</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>

=== 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.

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>

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

{| class="wikitable"
|-
! scope="col"| Interface
! 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.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/geometry/Vector.html ...]
|-
|'''RealMatrix'''
|Interface defining a real-valued matrix with basic algebraic operations.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/linear/RealMatrix.html ...]
|-
|'''SymmetricMatrix'''
| Interface for symmetric matrices.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/linear/SymmetricMatrix.html ...]
|-
|'''SymmetricPositiveMatrix'''
| Interface for symmetric positive matrices.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/linear/SymmetricPositiveMatrix.html ...]
|-
|'''Decomposition'''
| Interface for matrices decompositions.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/linear/Decomposition.html ...]
|-
|'''DecompositionSolver'''
| Interface for matrices decompositions solvers. In particular thses solvers provides the inverse of a matrix.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/linear/DecompositionSolver.html ...]
|-
|'''UDDecomposition'''
|An interface to classes that implement an algorithm to calculate the UD-decomposition of a real matrix.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/linear/UDDecomposition.html ...]
|}

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

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''Vector3D'''
|This class implements vectors in a three-dimensional space.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/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.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/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.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/linear/Array2DRowRealMatrix.html ...]
|-
|'''ArrayRowSymmetricMatrix'''
| Implementation of a symmetric matrix, implementing AbstractRealMatrix using a double[] array to store entries : storage convention is symmetric conventional full storage.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/linear/ArrayRowSymmetricMatrix.html ...]
|-
|'''DiagonalMatrix'''
| Implementation of a diagonal matrix.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/linear/DiagonalMatrix.html ...]
|-
|'''QRDecomposition'''
|Calculates the QR decomposition of a matrix.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/linear/QRDecomposition.html ...]
|-
|'''LUDecomposition'''
|Calculates the LU decomposition of a matrix.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/linear/LUDecomposition.html ...]
|-
|'''CholeskyDecomposition'''
|Calculates the Cholesky decomposition of a matrix.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/linear/CholeskyDecomposition.html ...]
|-
|'''SingularValueDecomposition'''
|Calculates the SVD decomposition of a matrix.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/math/linear/SingularValueDecomposition.html ...]
|}

[[Category:User_Manual_4.13_Mathematics]]