User Manual 4.3 Double Comparisons - Historique des versions

Admin le 28 mai 2019 à 09:04

2019-05-28T09:04:48Z

Admin : Contenu remplacé par « Category:User_Manual_4.3_Mathematics »

2019-05-28T07:42:45Z

Contenu remplacé par « Category:User_Manual_4.3_Mathematics »

← Version précédente		Version du 28 mai 2019 à 07:42
Ligne 1 :		Ligne 1 :
	~~__NOTOC__~~		[[Category:User_Manual_4.3_Mathematics]]
	~~== 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.math.interval</code>.~~

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

	~~=== Links ===~~
	~~Some elements about the “equals” comparators previously proposed in the “MathUtils” 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, [{{JavaDoc4.2}}/fr/cnes/sirius/patrius/math/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” 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.~~

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

	* '' IF x equals y in the Bruce Dawson’s way ''
	** ''=> 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~~

Admin le 15 mai 2019 à 12:38

2019-05-15T12:38:45Z

← Version précédente		Version du 15 mai 2019 à 12:38
Ligne 67 :		Ligne 67 :

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

Admin le 15 mai 2019 à 12:38

2019-05-15T12:38:28Z

← Version précédente		Version du 15 mai 2019 à 12:38
Ligne 65 :		Ligne 65 :

	Code examples :		Code examples :

			<syntaxhighlight lang="java">

Admin : Page créée avec « NOTOC == Introduction == === Scope === The « Comparators » class contains static methods to perform relative comparisons of doubles. === Javadoc === The Comparator... »

2019-05-15T12:38:01Z

Page créée avec « __NOTOC__ == Introduction == === Scope === The « Comparators » class contains static methods to perform relative comparisons of doubles. === Javadoc === The Comparator... »

Nouvelle page

__NOTOC__
== 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.math.interval</code>.

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

=== Links ===
Some elements about the “equals” comparators previously proposed in the “MathUtils” 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, [{{JavaDoc4.2}}/fr/cnes/sirius/patrius/math/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” 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.

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

* '' IF x equals y in the Bruce Dawson’s way ''
** ''=> 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 :

User Manual 4.3 Double Comparisons - Historique des versions

Admin le 28 mai 2019 à 09:04

Admin : Contenu remplacé par « Category:User_Manual_4.3_Mathematics »

Admin le 15 mai 2019 à 12:38

Admin le 15 mai 2019 à 12:38

Admin : Page créée avec « __NOTOC__ == Introduction == === Scope === The « Comparators » class contains static methods to perform relative comparisons of doubles. === Javadoc === The Comparator... »

Admin : Contenu remplacé par « Category:User_Manual_4.3_Mathematics »

Admin : Page créée avec « NOTOC == Introduction == === Scope === The « Comparators » class contains static methods to perform relative comparisons of doubles. === Javadoc === The Comparator... »