Added getAddendum() to CalculusFieldElement interface.

Fixes #349
Hipparchus-Math · Aug 21, 2024 · 0d309eb · 0d309eb
1 parent a44d874
commit 0d309eb
Show file tree

Hide file tree

Showing 47 changed files with 290 additions and 46 deletions.
diff --git a/hipparchus-clustering/pom.xml b/hipparchus-clustering/pom.xml
@@ -23,7 +23,7 @@
   <parent>
     <groupId>org.hipparchus</groupId>
     <artifactId>hipparchus</artifactId>
-    <version>3.2-SNAPSHOT</version>
+    <version>4.0-SNAPSHOT</version>
     <relativePath>../hipparchus-parent</relativePath>
   </parent>
 

diff --git a/hipparchus-clustering/src/changes/changes.xml b/hipparchus-clustering/src/changes/changes.xml
@@ -49,7 +49,7 @@ If the output is not quite correct, check for invisible trailing spaces!
     <title>Hipparchus Clustering Release Notes</title>
   </properties>
   <body>
-    <release version="3.2" date="TBD" description="TBD">
+    <release version="4.0" date="TBD" description="TBD">
       <action dev="vincent" type="update" issue="issues/285">
         Migrated tests from JUnit 4 to JUnit 5
       </action>

diff --git a/hipparchus-core/pom.xml b/hipparchus-core/pom.xml
@@ -23,7 +23,7 @@
   <parent>
     <groupId>org.hipparchus</groupId>
     <artifactId>hipparchus</artifactId>
-    <version>3.2-SNAPSHOT</version>
+    <version>4.0-SNAPSHOT</version>
     <relativePath>../hipparchus-parent</relativePath>
   </parent>
 

diff --git a/hipparchus-core/src/changes/changes.xml b/hipparchus-core/src/changes/changes.xml
@@ -49,7 +49,10 @@ If the output is not quite correct, check for invisible trailing spaces!
     <title>Hipparchus Core Release Notes</title>
   </properties>
   <body>
-    <release version="3.2" date="TBD" description="TBD">
+    <release version="4.0" date="TBD" description="TBD">
+      <action dev="luc" type="update" issue="issues/349">
+        Added getAddendum() to CalculusFieldElement interface.
+      </action>
       <action dev="luc" type="update" issue="issues/346">
         Added getLocalizedString(baseName, key, locale) with default implementation
         to Localizable interface

diff --git a/hipparchus-core/src/main/java/org/hipparchus/CalculusFieldElement.java b/hipparchus-core/src/main/java/org/hipparchus/CalculusFieldElement.java
@@ -36,6 +36,26 @@
  */
 public interface CalculusFieldElement<T extends FieldElement<T>> extends FieldElement<T> {
 
+    /** Get the addendum to the real value of the number.
+     * <p>
+     * The addendum is considered to be the part that when added back to
+     * the {@link #getReal() real part} recovers the instance. This means
+     * that when {@code e.getReal()} is finite (i.e. neither infinite
+     * nor NaN), then {@code e.getAddendum().add(e.getReal())} is {@code e}
+     * and {@code e.subtract(e.getReal())} is {@code e.getAddendum()}.
+     * Beware that for non-finite numbers, these two equalities may not hold.
+     * The first equality (with the addition), always holds even for infinity
+     * and NaNs if the real part is independent of the addendum (this is the
+     * case for all derivatives types, as well as for complex and Dfp, but it
+     * is not the case for Tuple and FieldTuple). The second equality (with
+     * the subtraction), generally doesn't hold for non-finite numbers, because
+     * the subtraction generates NaNs.
+     * </p>
+     * @return real value
+     * @since 4.0
+     */
+    T getAddendum();
+
     /** Get the Archimedes constant π.
      * <p>
      * Archimedes constant is the ratio of a circle's circumference to its diameter.

diff --git a/...rchus-core/src/main/java/org/hipparchus/analysis/differentiation/DerivativeStructure.java b/...rchus-core/src/main/java/org/hipparchus/analysis/differentiation/DerivativeStructure.java
@@ -155,6 +155,14 @@ void setDerivativeComponent(final int index, final double value) {
         return data[index];
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public DerivativeStructure getAddendum() {
+        final double[] addendum = data.clone();
+        addendum[0] = 0;
+        return new DerivativeStructure(factory, addendum);
+    }
+
     /** Get the value part of the derivative structure.
      * @return value part of the derivative structure
      * @see #getPartialDerivative(int...)

diff --git a/...-core/src/main/java/org/hipparchus/analysis/differentiation/FieldDerivativeStructure.java b/...-core/src/main/java/org/hipparchus/analysis/differentiation/FieldDerivativeStructure.java
@@ -25,6 +25,8 @@
 import org.hipparchus.util.MathArrays;
 import org.hipparchus.util.MathUtils;
 
+import java.util.Arrays;
+
 /** Class representing both the value and the differentials of a function.
  * <p>This class is similar to {@link DerivativeStructure} except function
  * parameters and value can be any {@link CalculusFieldElement}.</p>
@@ -89,14 +91,14 @@ public FDSFactory<T> getFactory() {
         return factory;
     }
 
-    @Override
     /** {@inheritDoc} */
+    @Override
     public int getFreeParameters() {
         return getFactory().getCompiler().getFreeParameters();
     }
 
-    @Override
     /** {@inheritDoc} */
+    @Override
     public int getOrder() {
         return getFactory().getCompiler().getOrder();
     }
@@ -131,6 +133,14 @@ T getDerivativeComponent(final int index) {
         return data[index];
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public FieldDerivativeStructure<T> getAddendum() {
+        final T[] addendum = data.clone();
+        addendum[0] = addendum[0].getField().getZero();
+        return new FieldDerivativeStructure<>(factory, addendum);
+    }
+
     /** Get the value part of the derivative structure.
      * @return value part of the derivative structure
      * @see #getPartialDerivative(int...)
@@ -1301,4 +1311,41 @@ public FieldDerivativeStructure<T> getPi() {
         return factory.getDerivativeField().getPi();
     }
 
+    /**
+     * Test for the equality of two derivative structures.
+     * <p>
+     * Derivative structures are considered equal if they have the same number
+     * of free parameters, the same derivation order, and the same derivatives.
+     * </p>
+     * @param other Object to test for equality to this
+     * @return true if two derivative structures are equal
+     */
+    @Override
+    public boolean equals(Object other) {
+
+        if (this == other) {
+            return true;
+        }
+
+        if (other instanceof FieldDerivativeStructure &&
+            ((FieldDerivativeStructure<?>) other).getField().equals(getField())) {
+            final FieldDerivativeStructure<T> rhs = (FieldDerivativeStructure<T>) other;
+            return (getFreeParameters() == rhs.getFreeParameters()) &&
+                   (getOrder() == rhs.getOrder()) &&
+                   MathArrays.equals(data, rhs.data);
+        }
+
+        return false;
+
+    }
+
+    /**
+     * Get a hashCode for the derivative structure.
+     * @return a hash code value for this object
+     */
+    @Override
+    public int hashCode() {
+        return 227 + 229 * getFreeParameters() + 233 * getOrder() + 239 * Arrays.hashCode(data);
+    }
+
 }
diff --git a/hipparchus-core/src/main/java/org/hipparchus/analysis/differentiation/FieldGradient.java b/hipparchus-core/src/main/java/org/hipparchus/analysis/differentiation/FieldGradient.java
@@ -149,6 +149,12 @@ public FieldGradient<T> withValue(final T v) {
         return new FieldGradient<>(v, grad);
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public FieldGradient<T> getAddendum() {
+        return new FieldGradient<>(value.getField().getZero(), grad);
+    }
+
     /** Get the value part of the function.
      * @return value part of the value of the function
      */

diff --git a/...ore/src/main/java/org/hipparchus/analysis/differentiation/FieldUnivariateDerivative1.java b/...ore/src/main/java/org/hipparchus/analysis/differentiation/FieldUnivariateDerivative1.java
@@ -101,6 +101,12 @@ public FieldUnivariateDerivative1<T> withValue(final T value) {
         return new FieldUnivariateDerivative1<>(value, f1);
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public FieldUnivariateDerivative1<T> getAddendum() {
+        return new FieldUnivariateDerivative1<>(f0.getField().getZero(), f1);
+    }
+
     /** Get the value part of the univariate derivative.
      * @return value part of the univariate derivative
      */

diff --git a/...ore/src/main/java/org/hipparchus/analysis/differentiation/FieldUnivariateDerivative2.java b/...ore/src/main/java/org/hipparchus/analysis/differentiation/FieldUnivariateDerivative2.java
@@ -108,6 +108,12 @@ public FieldUnivariateDerivative2<T> withValue(final T value) {
         return new FieldUnivariateDerivative2<>(value, f1, f2);
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public FieldUnivariateDerivative2<T> getAddendum() {
+        return new FieldUnivariateDerivative2<>(f0.getField().getZero(), f1, f2);
+    }
+
     /** Get the value part of the univariate derivative.
      * @return value part of the univariate derivative
      */

diff --git a/hipparchus-core/src/main/java/org/hipparchus/analysis/differentiation/Gradient.java b/hipparchus-core/src/main/java/org/hipparchus/analysis/differentiation/Gradient.java
@@ -141,6 +141,12 @@ public Gradient withValue(final double v) {
         return new Gradient(v, grad);
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public Gradient getAddendum() {
+        return new Gradient(0, grad);
+    }
+
     /** Get the value part of the function.
      * @return value part of the value of the function
      */

diff --git a/hipparchus-core/src/main/java/org/hipparchus/analysis/differentiation/SparseGradient.java b/hipparchus-core/src/main/java/org/hipparchus/analysis/differentiation/SparseGradient.java
@@ -148,6 +148,12 @@ public double getDerivative(final int index) {
         return (out == null) ? 0.0 : out;
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public SparseGradient getAddendum() {
+        return new SparseGradient(0, derivatives);
+    }
+
     /**
      * Get the value of the function.
      * @return value of the function.

diff --git a/...hus-core/src/main/java/org/hipparchus/analysis/differentiation/UnivariateDerivative1.java b/...hus-core/src/main/java/org/hipparchus/analysis/differentiation/UnivariateDerivative1.java
@@ -97,6 +97,12 @@ public UnivariateDerivative1 withValue(final double value) {
         return new UnivariateDerivative1(value, f1);
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public UnivariateDerivative1 getAddendum() {
+        return new UnivariateDerivative1(0, f1);
+    }
+
     /** {@inheritDoc} */
     @Override
     public double getValue() {

diff --git a/...hus-core/src/main/java/org/hipparchus/analysis/differentiation/UnivariateDerivative2.java b/...hus-core/src/main/java/org/hipparchus/analysis/differentiation/UnivariateDerivative2.java
@@ -105,6 +105,12 @@ public UnivariateDerivative2 withValue(final double value) {
         return new UnivariateDerivative2(value, f1, f2);
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public UnivariateDerivative2 getAddendum() {
+        return new UnivariateDerivative2(0, f1, f2);
+    }
+
     /** {@inheritDoc} */
     @Override
     public double getValue() {

diff --git a/hipparchus-core/src/main/java/org/hipparchus/complex/Complex.java b/hipparchus-core/src/main/java/org/hipparchus/complex/Complex.java
@@ -506,6 +506,12 @@ public double getReal() {
         return real;
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public Complex getAddendum() {
+        return new Complex(0, imaginary);
+    }
+
     /**
      * Access the real part.
      *
@@ -825,7 +831,7 @@ public Complex atan() {
      * <pre>
      *  Examples:
      *  <code>
-     *   cos(1 &plusmn; INFINITY i) = 1 \u2213 INFINITY i
+     *   cos(1 &plusmn; INFINITY i) = 1 ∓ INFINITY i
      *   cos(&plusmn;INFINITY + i) = NaN + NaN i
      *   cos(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i
      *  </code>

diff --git a/hipparchus-core/src/main/java/org/hipparchus/complex/FieldComplex.java b/hipparchus-core/src/main/java/org/hipparchus/complex/FieldComplex.java
@@ -580,6 +580,12 @@ public double getReal() {
         return real.getReal();
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public FieldComplex<T> getAddendum() {
+        return new FieldComplex<>(real.getAddendum(), imaginary);
+    }
+
     /**
      * Access the real part.
      *
@@ -933,7 +939,7 @@ public FieldComplex<T> atan() {
      * <pre>
      *  Examples:
      *  <code>
-     *   cos(1 &plusmn; INFINITY i) = 1 \u2213 INFINITY i
+     *   cos(1 &plusmn; INFINITY i) = 1 ∓ INFINITY i
      *   cos(&plusmn;INFINITY + i) = NaN + NaN i
      *   cos(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i
      *  </code>

diff --git a/hipparchus-core/src/main/java/org/hipparchus/dfp/Dfp.java b/hipparchus-core/src/main/java/org/hipparchus/dfp/Dfp.java
@@ -312,7 +312,7 @@ protected Dfp(final DfpField field, double x) {
         }
 
         Dfp xdfp = new Dfp(field, mantissa);
-        xdfp = xdfp.divide(new Dfp(field, 4503599627370496l)).add(field.getOne());  // Divide by 2^52, then add one
+        xdfp = xdfp.divide(new Dfp(field, 4503599627370496L)).add(field.getOne());  // Divide by 2^52, then add one
         xdfp = xdfp.multiply(DfpMath.pow(field.getTwo(), exponent));
 
         if ((bits & 0x8000000000000000L) != 0) {
@@ -1285,7 +1285,7 @@ protected Dfp trunc(final DfpField.RoundingMode rmode) {
                         result = result.add(a);
                     }
 
-                    /** If exactly equal to 1/2 and odd then increment */
+                    // If exactly equal to 1/2 and odd then increment
                     if (a.equals(half) && result.exp > 0 && (result.mant[mant.length-result.exp]&1) != 0) {
                         a = newInstance(getOne());
                         a.sign = sign;
@@ -2632,7 +2632,7 @@ public double toDouble() {
         }
 
 
-        y = y.multiply(newInstance(4503599627370496l)).rint();
+        y = y.multiply(newInstance(4503599627370496L)).rint();
         String str = y.toString();
         str = str.substring(0, str.length()-1);
         long mantissa = Long.parseLong(str);
@@ -2685,6 +2685,12 @@ public double getReal() {
         return toDouble();
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public Dfp getAddendum() {
+        return isFinite() ? subtract(getReal()) : getZero();
+    }
+
     /** {@inheritDoc}
      */
     @Override

diff --git a/hipparchus-core/src/main/java/org/hipparchus/util/Binary64.java b/hipparchus-core/src/main/java/org/hipparchus/util/Binary64.java
@@ -347,6 +347,12 @@ public double getReal() {
         return value;
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public Binary64 getAddendum() {
+        return Binary64.ZERO;
+    }
+
     /** {@inheritDoc} */
     @Override
     public Binary64 add(final double a) {

diff --git a/hipparchus-core/src/main/java/org/hipparchus/util/FieldTuple.java b/hipparchus-core/src/main/java/org/hipparchus/util/FieldTuple.java
@@ -185,6 +185,17 @@ public double getReal() {
         return values[0].getReal();
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public FieldTuple<T> getAddendum() {
+        final T[] addendum = values.clone();
+        addendum[0] = addendum[0].getField().getZero();
+        for (int i = 1; i < addendum.length; ++i) {
+            addendum[i] = addendum[i].subtract(values[0]);
+        }
+        return new FieldTuple<>(field, addendum);
+    }
+
     /** {@inheritDoc} */
     @Override
     public FieldTuple<T> add(final double a) {