Admin : Page créée avec « NOTOC == Introduction == === Scope === This section describes PATRIUS handling of low-level math frameworks. A low-level math framework provides simple math operations... »

2019-01-14T14:59:56Z

Page créée avec « __NOTOC__ == Introduction == === Scope === This section describes PATRIUS handling of low-level math frameworks. A low-level math framework provides simple math operations... »

Nouvelle page

__NOTOC__
== Introduction ==
=== Scope ===
This section describes PATRIUS handling of low-level math frameworks.
A low-level math framework provides simple math operations such as sin, cos, exp, etc. Before PATRIUS 4.2, the only existing framework is <code>FastMath</code>.
Since version 4.2, the notion of math framework has been generalized and the user can use various framework:
* FastMath
* JAFAMA 2.1.0 FastMath
* JAFAMA 2.1.0 StrictFastMath
* Its own defined framework

JAFAMA is a fast open-source Math library. To be usable in PATRIUS, a dependency to JAFAMA 2.1.0 has been added in PATRIUS pom.xml file.

=== Javadoc ===
The math framework classes are available in the package <code>fr.cnes.sirius.patrius.math.framework</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.2}}/fr/cnes/sirius/patrius/math/framework/package-summary.html Package fr.cnes.sirius.patrius.math.framework]
|}

=== Links ===
One of the framework available is JAFAMA. JAFAMA is an open-source library under Apache 2.0 licence.
More information can be found at https://github.com/jeffhain/jafama

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

=== Package Overview ===

== Features Description ==

=== Features ===

A low-level Math framework is a class implementing all the original <code>FastMath</code> functions (sin, exp, min, atan, etc.).
All low-level Math framework should implement the <code>MathLibrary</code> interface.
Currently there are three implementations of the MathLibrary interface:
* <code>FastMathWrapper</code> which is a wrapper for FastMath static class.
* <code>JafamaFastMathWrapper</code> which is a wrapper for JAFAMA FastMath static class.
* <code>JafamaStrictFastMathWrapper</code> which is a wrapper for JAFAMA StrictFastMath static class.
The user can also define its own low-level Math framework by providing its own implementation of the <code>MathLibrary</code> interface.

Then in order to use the chosen low-level Math framework, the user must use the static class <code>MathLib</code>:
* By first defining the Math framework to use with methods <code>MathLib.setMathLibrary()</code> if different from FastMath.
* By then using the MathLib functions like the FastMath functions: <code>MathLib.sin(...)</code>
Note: by default, FastMath is set as the low-level Math library.
Note 2: inner PATRIUS functions call MathLib which by default call FastMath. Hence there is strictly no numerical differences between use of PATRIUS 4.2 or older versions of PATRIUS.

When the user defines a low-level math framework then all PATRIUS operations are performed using this framework.

=== Performances of available Math framework ===

==== Computation times ====

Here are displayed computation time gains with using JAFAMA library (reference: FastMath).

{| class="wikitable"
|-
! scope="col"| Item
! scope="col"| Jafama FastMath
! scope="col"| Jafama StrictFastMath
|-
|'''Numerical propagation'''
| <center>≈ -10%</center>
| <center>≈ -10%</center>
|-
|'''Analytical propagation'''
| <center>≈ -30%</center>
| <center>≈ -30%</center>
|-
|'''Attitude computation'''
| <center>≈ -10%</center>
| <center>≈ -10%</center>
|}

Note: these are averaged orders of magnitude and may vary from one case to another.

==== Accuracy ====

As stated in JAFAMA website, relative accuracy of operations is 1E-15 (no regression would required a relative accuracy better than 1E-16). As a result, use of PATRIUS with JAFAMA will lead to slightly different results. This will not occur on all operations.

Here are displayed absolute/relative error for standard PATRIUS uses with using JAFAMA library (reference: FastMath).

{| class="wikitable"
|-
! scope="col"| Item
! scope="col"| Jafama FastMath
! scope="col"| Jafama StrictFastMath
|-
|'''Framework functions'''
| <center><1E-15 rel.</center>
| <center><1E-15 rel.</center>
|-
|'''Low-level space mechanics functions'''
| <center><1E-15 rel.</center>
| <center><1E-15 rel.</center>
|-
|'''LEO propagation on 24h'''
| <center><1E-6m</center>
| <center><1E-6m</center>
|-
|'''GEO propagation on 24h'''
| <center><1E-5m</center>
| <center><1E-5m</center>
|-
|'''GTO propagation on 24h'''
| <center><1E-6m</center>
| <center><1E-6m</center>
|}

Roughly, an absolute accuracy on position of 1E-6m for LEO orbits means a relative accuracy of 1E-12.

The accuracy (with respect to FastMath) is directly correlated to the number of used JAFAMA operations. To get an idea of what accuracy to expect:
* 1 single JAFAMA operation leads to a relative accuracy of 1E-15 or better
* 1 propagation over 24 h (with millions calls to JAFAMA) leads to a relative accuracy of 1E-12

== Getting Started ==

In the following section are defined potential use of Math framework.

=== Simple user ===

This user does not want to change anything with PATRIUS 4.2 upgrade. He has two options:
* Continue to use FastMath and do nothing in particular:
<syntaxhighlight lang="java">final double y = FastMath.sin(x);</syntaxhighlight>
* Still use FastMath through the use of MathLib
<syntaxhighlight lang="java">final double y = MathLib.sin(x);</syntaxhighlight>
Note: by default, MathLib calls FastMath.

=== Intermediate user ===

This user wants to use another Math framework (here FastMath from JAFAMA):
<syntaxhighlight lang="java">
MathLib.setMathLibrary(MathLibraryType.JAFAMA_FASTMATH);
final double y = MathLib.sin(x);
</syntaxhighlight>

=== Advanced user ===

This user wants to use his own math framework:
<syntaxhighlight lang="java">final MathLibrary myOwnFramework = new MathLibrary() {
public double sin(final double x) {
return ...;
}
...
}
MathLib.setMathLibrary(myOwnFramework);
final double y = MathLib.sin(x);
</syntaxhighlight>

== Contents ==
=== Interfaces ===
The library defines the following interfaces related to math frameworks:

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''MathLibrary'''
|Interface for low-level Math framework
|[{{JavaDoc4.2}}/fr/cnes/sirius/patrius/math/framework/MathLibrary.html ...]
|}

=== Classes ===
The library defines the following classes related to low-level Math frameworks:

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''MathLib'''
|Static class for generic low-level math functions use
|[{{JavaDoc4.2}}/fr/cnes/sirius/patrius/math/MathLib.html ...]
|-
|'''MathLibraryType'''
|Enumeration for currently available Math framework in PATRIUS
|[{{JavaDoc4.2}}/fr/cnes/sirius/patrius/math/framework/MathLibraryType.html ...]
|-
|'''FastMathWrapper'''
|Wrapper of FastMath class implementing MathLibrary interface
|[{{JavaDoc4.2}}/fr/cnes/sirius/patrius/math/framework/FastMathWrapper.html ...]
|-
|'''JafamaFastMathWrapper'''
|Wrapper of Jafama FastMath class implementing MathLibrary interface
|[{{JavaDoc4.2}}/fr/cnes/sirius/patrius/math/framework/JafamaFastMathWrapper.html ...]
|-
|'''JafamaStrictFastMathWrapper'''
|Wrapper of Jafama StrictFastMath class implementing MathLibrary interface
|[{{JavaDoc4.2}}/fr/cnes/sirius/patrius/math/framework/JafamaStrictFastMathWrapper.html ...]
|-
|'''FastMath'''
|Original class from PATRIUS providing low-level math functions
|[{{JavaDoc4.2}}/fr/cnes/sirius/patrius/math/FastMath.html ...]
|}

[[Category:User_Manual_4.2_Mathematics]]

User Manual 4.2 Math frameworks - Historique des versions

Admin : Page créée avec « __NOTOC__ == Introduction == === Scope === This section describes PATRIUS handling of low-level math frameworks. A low-level math framework provides simple math operations... »

Admin : Page créée avec « NOTOC == Introduction == === Scope === This section describes PATRIUS handling of low-level math frameworks. A low-level math framework provides simple math operations... »