User Manual 4.3 Math frameworks - Historique des versions

Admin : bo

2019-05-16T15:21:30Z

← Version précédente		Version du 16 mai 2019 à 15:21
Ligne 45 :		Ligne 45 :
	Currently there are three implementations of the MathLibrary interface:		Currently there are three implementations of the MathLibrary interface:
	* <code>FastMathWrapper</code> which is a wrapper for FastMath static class.		* <code>FastMathWrapper</code> which is a wrapper for FastMath static class.
			* <code>MathWrapper</code> which is a wrapper for Math static class.
			* <code>StrictMathWrapper</code> which is a wrapper for StrictMath static class.
	* <code>JafamaFastMathWrapper</code> which is a wrapper for JAFAMA 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.		* <code>JafamaStrictFastMathWrapper</code> which is a wrapper for JAFAMA StrictFastMath static class.
			* <code>FastestMathLibWrapper</code> which is a wrapper for fastest math library among the listed above. Fastest functions are mainly Jafama FastMath functions except for simple functions (abs, ceil, floor, round, etc.) for which FastMath or StrictMath are faster.
	The user can also define its own low-level Math framework by providing its own implementation of the <code>MathLibrary</code> interface.		The user can also define its own low-level Math framework by providing its own implementation of the <code>MathLibrary</code> interface.

Ligne 122 :		Ligne 125 :
	* 1 single JAFAMA operation leads to a relative accuracy of 1E-15 or better		* 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		* 1 propagation over 24 h (with millions calls to JAFAMA) leads to a relative accuracy of 1E-12

			Warning: Except for StrictMath, PATRIUS does not guarantee implementations of various JVM will return the exact same result.

	== Getting Started ==		== Getting Started ==
Ligne 192 :		Ligne 197 :
	\|Wrapper of FastMath class implementing MathLibrary interface		\|Wrapper of FastMath class implementing MathLibrary interface
	\|[{{JavaDoc4.3}}/fr/cnes/sirius/patrius/math/framework/FastMathWrapper.html ...]		\|[{{JavaDoc4.3}}/fr/cnes/sirius/patrius/math/framework/FastMathWrapper.html ...]
			\|-
			\|'''MathWrapper'''
			\|Wrapper of Math class implementing MathLibrary interface
			\|[{{JavaDoc4.3}}/fr/cnes/sirius/patrius/math/framework/MathWrapper.html ...]
			\|-
			\|'''StrictMathWrapper'''
			\|Wrapper of StrictMath class implementing MathLibrary interface
			\|[{{JavaDoc4.3}}/fr/cnes/sirius/patrius/math/framework/StrictMathWrapper.html ...]
	\|-		\|-
	\|'''JafamaFastMathWrapper'''		\|'''JafamaFastMathWrapper'''
Ligne 200 :		Ligne 213 :
	\|Wrapper of Jafama StrictFastMath class implementing MathLibrary interface		\|Wrapper of Jafama StrictFastMath class implementing MathLibrary interface
	\|[{{JavaDoc4.3}}/fr/cnes/sirius/patrius/math/framework/JafamaStrictFastMathWrapper.html ...]		\|[{{JavaDoc4.3}}/fr/cnes/sirius/patrius/math/framework/JafamaStrictFastMathWrapper.html ...]
			\|-
			\|'''FastestMathLibWrapper'''
			\|Implementation wrapping the fastest implementation among Math, FastMath, StrictMath and Jafama for each function
			\|[{{JavaDoc4.3}}/fr/cnes/sirius/patrius/math/framework/FastestMathLibWrapper.html ...]
	\|-		\|-
	\|'''FastMath'''		\|'''FastMath'''

Admin le 16 mai 2019 à 15:14

2019-05-16T15:14:22Z

← Version précédente		Version du 16 mai 2019 à 15:14
Ligne 6 :		Ligne 6 :
	Since version 4.2, the notion of math framework has been generalized and the user can use various framework:		Since version 4.2, the notion of math framework has been generalized and the user can use various framework:
	* FastMath		* FastMath
			* Math
			* StrictMath
	* JAFAMA 2.3.1 FastMath		* JAFAMA 2.3.1 FastMath
	* JAFAMA 2.3.1 StrictFastMath		* JAFAMA 2.3.1 StrictFastMath
			* An implementation corresponding for each function to fastest implementations among all above libraries.
	* Its own defined framework		* 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.		JAFAMA is a fast open-source Math library. To be usable in PATRIUS, a dependency to JAFAMA 2.3.1 has been added in PATRIUS pom.xml file.

	=== Javadoc ===		=== Javadoc ===

Admin le 16 mai 2019 à 15:12

2019-05-16T15:12:38Z

← Version précédente		Version du 16 mai 2019 à 15:12
Ligne 6 :		Ligne 6 :
	Since version 4.2, the notion of math framework has been generalized and the user can use various framework:		Since version 4.2, the notion of math framework has been generalized and the user can use various framework:
	* FastMath		* FastMath
	* JAFAMA 2.1.0 FastMath		* JAFAMA 2.3.1 FastMath
	* JAFAMA 2.1.0 StrictFastMath		* JAFAMA 2.3.1 StrictFastMath
	* Its own defined framework		* Its own defined framework

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-05-15T12:34:16Z

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.3}}/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.3}}/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.3}}/fr/cnes/sirius/patrius/math/MathLib.html ...]
|-
|'''MathLibraryType'''
|Enumeration for currently available Math framework in PATRIUS
|[{{JavaDoc4.3}}/fr/cnes/sirius/patrius/math/framework/MathLibraryType.html ...]
|-
|'''FastMathWrapper'''
|Wrapper of FastMath class implementing MathLibrary interface
|[{{JavaDoc4.3}}/fr/cnes/sirius/patrius/math/framework/FastMathWrapper.html ...]
|-
|'''JafamaFastMathWrapper'''
|Wrapper of Jafama FastMath class implementing MathLibrary interface
|[{{JavaDoc4.3}}/fr/cnes/sirius/patrius/math/framework/JafamaFastMathWrapper.html ...]
|-
|'''JafamaStrictFastMathWrapper'''
|Wrapper of Jafama StrictFastMath class implementing MathLibrary interface
|[{{JavaDoc4.3}}/fr/cnes/sirius/patrius/math/framework/JafamaStrictFastMathWrapper.html ...]
|-
|'''FastMath'''
|Original class from PATRIUS providing low-level math functions
|[{{JavaDoc4.3}}/fr/cnes/sirius/patrius/math/FastMath.html ...]
|}

[[Category:User_Manual_4.3_Mathematics]]

User Manual 4.3 Math frameworks - Historique des versions

Admin : bo

Admin le 16 mai 2019 à 15:14

Admin le 16 mai 2019 à 15:12

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 : bo

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