User Manual 4.14 Math frameworks

User Manual 4.14 Math frameworks

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 FastMath. Since version 4.2, the notion of math framework has been generalized and the user can use various framework:

• FastMath
• Math
• StrictMath
• JAFAMA 2.3.1 FastMath
• JAFAMA 2.3.1 StrictFastMath
• An implementation corresponding for each function to fastest implementations among all above libraries.
• Its own defined framework

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

The math framework classes are available in the package fr.cnes.sirius.patrius.math.framework.

Library	Javadoc
Patrius	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.

Features Description

Features

A low-level Math framework is a class implementing all the original FastMath functions (sin, exp, min, atan, etc.). All low-level Math framework should implement the MathLibrary interface. Currently there are three implementations of the MathLibrary interface:

• FastMathWrapper which is a wrapper for FastMath static class.
• MathWrapper which is a wrapper for Math static class.
• StrictMathWrapper which is a wrapper for StrictMath static class.
• JafamaFastMathWrapper which is a wrapper for JAFAMA FastMath static class.
• JafamaStrictFastMathWrapper which is a wrapper for JAFAMA StrictFastMath static class.
• FastestMathLibWrapper 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 MathLibrary interface.

Then in order to use the chosen low-level Math framework, the user must use the static class MathLib:

• By first defining the Math framework to use with methods MathLib.setMathLibrary() if different from FastMath.
• By then using the MathLib functions like the FastMath functions: MathLib.sin(...)

Notes:

• by default, FastMath is set as the low-level Math library.
• 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.
• MathLib has function sinAndCos which allows the computation of sine and cosine of a value in one single operation. If using Jafama, the computational cost is reduced by about 30%. There is no impact if using another framework.

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

Item	Jafama FastMath	Jafama StrictFastMath
Numerical propagation	≈ -10%	≈ -10%
Analytical propagation	≈ -30%	≈ -30%
Attitude computation	≈ -10%	≈ -10%

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

Item	Jafama FastMath	Jafama StrictFastMath
Framework functions	<1E-15 rel.	<1E-15 rel.
Low-level space mechanics functions	<1E-15 rel.	<1E-15 rel.
LEO propagation on 24h	<1E-6m	<1E-6m
GEO propagation on 24h	<1E-5m	<1E-5m
GTO propagation on 24h	<1E-6m	<1E-6m

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

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

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:

final double y = FastMath.sin(x);

• Still use FastMath through the use of MathLib

final double y = MathLib.sin(x);

Note: by default, MathLib calls FastMath.

Intermediate user

This user wants to use another Math framework (here FastMath from JAFAMA):

MathLib.setMathLibrary(MathLibraryType.JAFAMA_FASTMATH);
final double y = MathLib.sin(x);

Advanced user

This user wants to use his own math framework:

final MathLibrary myOwnFramework = new MathLibrary() {
    public double sin(final double x) {
        return ...;
    }
    ...
}
MathLib.setMathLibrary(myOwnFramework);
final double y = MathLib.sin(x);

Contents

Interfaces

The library defines the following interfaces related to math frameworks:

Interface	Summary	Javadoc
MathLibrary	Interface for low-level Math framework	...

Classes

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

Class	Summary	Javadoc
MathLib	Static class for generic low-level math functions use	...
MathLibraryType	Enumeration for currently available Math framework in PATRIUS	...
FastMathWrapper	Wrapper of FastMath class implementing MathLibrary interface	...
MathWrapper	Wrapper of Math class implementing MathLibrary interface	...
StrictMathWrapper	Wrapper of StrictMath class implementing MathLibrary interface	...
JafamaFastMathWrapper	Wrapper of Jafama FastMath class implementing MathLibrary interface	...
JafamaStrictFastMathWrapper	Wrapper of Jafama StrictFastMath class implementing MathLibrary interface	...
FastestMathLibWrapper	Implementation wrapping the fastest implementation among Math, FastMath, StrictMath and Jafama for each function	...
FastMath	Original class from PATRIUS providing low-level math functions	...