User Manual 3.3 Double Comparisons - Historique des versions

Admin le 27 février 2018 à 10:03

2018-02-27T10:03:53Z

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

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

Admin : /* Using the Comparators class */

2018-02-27T10:02:44Z

Using the Comparators class

← Version précédente		Version du 27 février 2018 à 10:02
Ligne 97 :		Ligne 97 :
	These comparisons are relative and use an epsilon value. Each method is duplicated, so the choice is given to use the default epsilon (''Comparators.DOUBLE_COMPARISON_EPSILON'') or any other value, by adding it to the method’s signature.		These comparisons are relative and use an epsilon value. Each method is duplicated, so the choice is given to use the default epsilon (''Comparators.DOUBLE_COMPARISON_EPSILON'') or any other value, by adding it to the method’s signature.

	To respect the'''IEEE Standard 754''', a “NaN” is considered different to any other double, including “NaN” itself, and the positive and negative infinite values are considered only equal to themselves (see behaviour examples).		To respect the '''IEEE Standard 754''', a “NaN” is considered different to any other double, including “NaN” itself, and the positive and negative infinite values are considered only equal to themselves (see behaviour examples).

	==== Examples of "equals" method behaviour (using default epsilon) : ====		==== Examples of "equals" method behaviour (using default epsilon) : ====

Admin : /* Classes */

2018-02-27T10:00:44Z

Classes

← Version précédente		Version du 27 février 2018 à 10:00
Ligne 51 :		Ligne 51 :
	The only class is <code>fr.cnes.sirius.patrius.utils.Comparators</code>.		The only class is <code>fr.cnes.sirius.patrius.utils.Comparators</code>.

	\|=Class\|=~~Summary~~\|=Javadoc		{\| class="wikitable"
	\|'''Comparators'''\|Static comparison methods for real numbers\|[{{JavaDoc3.3}}/fr/cnes/sirius/patrius/utils/Comparators.html ...]		\|-
			! scope="col"\| Class
			! scope="col"\| Summary
			! scope="col"\| Javadoc
			\|-
			\|'''Comparators'''
			\|Static comparison methods for real numbers
			\|[{{JavaDoc3.3}}/fr/cnes/sirius/patrius/utils/Comparators.html ...]
			\|}

	=== The Comparators class ===		=== The Comparators class ===

Admin le 27 février 2018 à 09:58

2018-02-27T09:58:59Z

← Version précédente		Version du 27 février 2018 à 09:58
Ligne 208 :		Ligne 208 :
	== [[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 Comparators class */

2018-02-27T09:58:12Z

The Comparators class

Voir les modifications

Admin : /* Introduction */

2018-02-27T09:52:59Z

Introduction

← Version précédente		Version du 27 février 2018 à 09:52
Ligne 7 :		Ligne 7 :
	=== Javadoc ===		=== Javadoc ===
	The Comparators class is available in the <code>package fr.cnes.sirius.patrius.utils</code>.		The Comparators class is available in the <code>package fr.cnes.sirius.patrius.utils</code>.
	\|=Library\|=Javadoc
	\|Patrius \|[{{JavaDoc3.3}}/fr/cnes/sirius/patrius/utils/package-summary.html Package fr.cnes.sirius.patrius.utils]		{\| class="wikitable"
			\|-
			! scope="col"\| Library
			! scope="col"\| Javadoc
			\|-
			\|Patrius
			\|[{{JavaDoc3.3}}/fr/cnes/sirius/patrius/utils/package-summary.html Package fr.cnes.sirius.patrius.utils]
			\|}


	=== Links ===		=== Links ===
	Some elements about the “equals” comparators previously proposed in the “MathUtils” COMMONS-MATH class are described in the document “Comparing floating point numbers” by Bruce Dawson : [http://www.cygnus-software.com/papers/comparingfloats/comparingfloats.htm http:~~/~~/www.cygnus-software.com/papers/comparingfloats/comparingfloats.htm].		Some elements about the “equals” comparators previously proposed in the “MathUtils” COMMONS-MATH class are described in the document “Comparing floating point numbers” by Bruce Dawson : [http://www.cygnus-software.com/papers/comparingfloats/comparingfloats.htm http://www.cygnus-software.com/papers/comparingfloats/comparingfloats.htm].

	=== Useful Documents ===		=== Useful Documents ===

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

2018-02-27T09:52:07Z

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

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

Admin : 1 révision importée

2018-02-27T09:51:35Z

1 révision importée

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

Admin le 27 février 2018 à 09:51

2018-02-27T09:51:35Z

Nouvelle page

== Introduction ==
=== Scope ===
The « Comparators » class contains static methods to perform relative comparisons of doubles.

=== Javadoc ===
The Comparators class is available in the <code>package fr.cnes.sirius.patrius.utils</code>.
|=Library|=Javadoc
|Patrius |[{{JavaDoc3.3}}/fr/cnes/sirius/patrius/utils/package-summary.html Package fr.cnes.sirius.patrius.utils]

=== Links ===
Some elements about the “equals” comparators previously proposed in the “MathUtils” COMMONS-MATH class are described in the document “Comparing floating point numbers” by Bruce Dawson : [http://www.cygnus-software.com/papers/comparingfloats/comparingfloats.htm http:~~/~~/www.cygnus-software.com/papers/comparingfloats/comparingfloats.htm].

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

=== Package Overview ===
The doubles comparison issue is adressed through a single utility class, [{{JavaDoc3.3}}/fr/cnes/sirius/patrius/utils/Comparators.html Comparators], in the fr.cnes.sirius.patrius.utils package.

== Features Description ==
=== Algorithms and espilon value ===
The need here is to compare two values with a known maximum relative difference.

The “equals” comparators previously proposed in the “MathUtils” COMMONS-MATH class are of two types :

* a simple absolute comparison using an epsilon
* a more complex one, described in the document “Comparing floating point numbers” by Bruce Dawson (see the Links paragraph)

This last comparison makes more sense to compare real values and takes into account the precision issues due to the double type. It works as well with any exponent (high values or close to zero…), but the relative difference accepted between two equal doubles is uncontrolled, between 2.5e-16 and 1.25e-16 for a maxUlps of 1 (difference between two consecutive doubles).

Here is proposed a new comparison method to control the maximum relative difference and still have a comparison that makes sense when computed.

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

== Contents ==
=== Interfaces ===
None as of now.

=== Classes ===
The only class is <code>fr.cnes.sirius.patrius.utils.Comparators</code>.

|=Class|=Summary|=Javadoc
|'''Comparators'''|Static comparison methods for real numbers|[{{JavaDoc3.3}}/fr/cnes/sirius/patrius/utils/Comparators.html ...]

=== The Comparators class ===
The new comparison method is implemented in the Comparators class. Its simplified algorithm is described below with pseudo-code.

''x and y are two doubles.''

(% style="list-style-type: square;" %)
* '' IF x equals y in the Bruce Dawson’s way (call made to the COMMONS-MATH method)''
''' ''=> Then the return is “TRUE” regardless to relative difference'''''
* '' ELSE ~:''
''' ''=> IF the absolute relative difference is lower than the epsilon, then the return is “TRUE”'''''
* ''ENDIF''

NB : the epsilon can be chosen by the user, eventually between 2.5e-16 and 1.25e-16 (min and max values for the relative difference in Bruce Dawson’s algorithm). In that case, the comparison becomes at worst uncontrolled and doesn’t make any sense : sometimes the epsilon will be used, sometimes not, without information to the user. If the chosen epsilon is lower than 1.25e-16, it becomes useless.

The default epsilon proposed is :

''Comparators.DOUBLE_COMPARISON_EPSILON'' = 1.0e-14

(two orders higher than the max relative difference between to consecutive doubles)

==== Using the Comparators class ====

The Comparators class provides the following static methods ''equal, lowerOrEqual, greaterOrEqual, lowerStrict, greaterStrict,'' for doubles comparison purposes.

Their returns are Booleans, in order to be used the same way as classical « > », « == »…

Code examples :

<syntaxhighlight lang="java">
if (Comparators.equals(x, y, eps)) { } // epsilon given by the user
if (Comparators.equals(x, y)) { } // default epsilon
if (Comparators.lowerOrEqual(x, y)) { } // default epsilon
</syntaxhighlight>

These comparisons are relative and use an epsilon value. Each method is duplicated, so the choice is given to use the default epsilon (''Comparators.DOUBLE_COMPARISON_EPSILON'') or any other value, by adding it to the method’s signature.

To respect the'''IEEE Standard 754''', a “NaN” is considered different to any other double, including “NaN” itself, and the positive and negative infinite values are considered only equal to themselves (see behaviour examples).

==== Examples of "equals" method behaviour (using default epsilon) : ====

|=(% colspan="2" %)X|=(% colspan="2" %)Y|= ~|X-Y~|/Y|=(% colspan="2" %)MathUtils.equals result|=(% colspan="2" %)Comparators.equals result
|(% colspan="2" %)0.0|(% colspan="2" %)1.0e-300|1.0|(% align="center" colspan="2" style="color: red;" %)'''false'''|(% align="center" colspan="2" style="color: red;" %)'''false'''
|(% colspan="2" %)1.25000000000000025|(% colspan="2" %)1.25| 2.0e-16|(% align="center" colspan="2" style="color: red;" %)'''false'''|(% align="center" colspan="2" style="color: rgb(51, 153, 102);" %)'''true'''
|(% colspan="2" %)1.0000000000000002|(% colspan="2" %)1.0| 2.0e-16|(% align="center" colspan="2" style="color: rgb(51, 153, 102);" %)'''true'''|(% align="center" colspan="2" style="color: rgb(51, 153, 102);" %)'''true'''
|(% colspan="2" %)1.0000000000000001e+300|(% colspan="2" %)1.0e+300| 1.0e-16|(% align="center" colspan="2" style="color: rgb(51, 153, 102);" %)'''true'''|(% align="center" colspan="2" style="color: rgb(51, 153, 102);" %)'''true'''
|(% colspan="2" %)1.0000000000000001e-300|(% colspan="2" %)1.0e-300| 1.0e-16|(% align="center" colspan="2" style="color: rgb(51, 153, 102);" %)'''true'''|(% align="center" colspan="2" style="color: rgb(51, 153, 102);" %)'''true'''
|(% colspan="2" %)1.000000000000001|(% colspan="2" %)1.0| 1.0e-15|(% align="center" colspan="2" style="color: red;" %)'''false'''|(% align="center" colspan="2" style="color: rgb(51, 153, 102);" %)'''true'''
|(% colspan="2" %)1.000000000000001e+300|(% colspan="2" %)1.0e+300| 1.0e-15|(% align="center" colspan="2" style="color: red;" %)'''false'''|(% align="center" colspan="2" style="color: rgb(51, 153, 102);" %)'''true'''
|(% colspan="2" %)1.000000000000001e-300|(% colspan="2" %)1.0e-300| 1.0e-15|(% align="center" colspan="2" style="color: red;" %)'''false'''|(% align="center" colspan="2" style="color: rgb(51, 153, 102);" %)'''true'''
|(% colspan="2" %)1.0000000000001|(% colspan="2" %)1.0|1.0e-13|(% align="center" colspan="2" style="color: red;" %)'''false'''|(% align="center" colspan="2" style="color: red;" %)'''false'''
|(% colspan="2" %)1.0000000000001e+300|(% colspan="2" %)1.0e+300| 1.0e-13|(% align="center" colspan="2" style="color: red;" %)'''false'''|(% align="center" colspan="2" style="color: red;" %)'''false'''
|(% colspan="2" %)1.0000000000001e-300|(% colspan="2" %)1.0e-300| 1.0e-13|(% align="center" colspan="2" style="color: red;" %)'''false'''|(% align="center" colspan="2" style="color: red;" %)'''false'''
|(% colspan="2" %)NaN|(% colspan="2" %)NaN| -|(% align="center" colspan="2" style="color: red;" %)'''false'''|(% align="center" colspan="2" style="color: red;" %)'''false'''
|(% colspan="2" %)NaN|(% colspan="2" %)Any other double|-|(% align="center" colspan="2" style="color: red;" %)'''false'''|(% align="center" colspan="2" style="color: red;" %)'''false'''
|(% colspan="2" %)POSITIVE_INFINITE|(% colspan="2" %)POSITIVE_INFINITE| -|(% align="center" colspan="2" style="color: rgb(51, 153, 102);" %)'''true'''|(% align="center" colspan="2" style="color: rgb(51, 153, 102);" %)'''true'''
|(% colspan="2" %)POSITIVE_INFINITE|(% colspan="2" %)Any other double| -|(% align="center" colspan="2" style="color: red;" %)'''false'''|(% align="center" colspan="2" style="color: red;" %)'''false'''

Notice the second and third lines : two pair of doubles with the same relative difference imply a “false” for the first, and a “true” for the second when computed with previous commons-math method.

Using a relative epsilon allows us to stay coherent in any case.

'''Beware :'''when realizing a comparison close to zero, you must think about the type of comparison needed. In order to perform comparison in the same way regardless to the exponents, our comparator considers a double with a very low exponent different to zero (first line of the example). In some cases, an absolute comparison with epsilon shall be needed (to compare the result of a computation to zero...).

== 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 Double Comparisons - Historique des versions

Admin le 27 février 2018 à 10:03

Admin : /* Using the Comparators class */

Admin : /* Classes */

Admin le 27 février 2018 à 09:58

Admin : /* The Comparators class */

Admin : /* Introduction */

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