Hipparchus-Math · maisonobe · Dec 28, 2025 · Dec 28, 2025 · Dec 28, 2025
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>4.1-SNAPSHOT</version>
+    <version>5.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,6 +49,8 @@ If the output is not quite correct, check for invisible trailing spaces!
     <title>Hipparchus Clustering Release Notes</title>
   </properties>
   <body>
+    <release version="5.0" date="TBD" description="TBD.">
+    </release>
     <release version="4.0.2" date="2025-09-08" description="This is a patch release.">
       <action dev="bryan" type="update">
         No changes directly in this module. However, lower level Hipparchus modules did change,

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>4.1-SNAPSHOT</version>
+    <version>5.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,6 +49,11 @@ If the output is not quite correct, check for invisible trailing spaces!
     <title>Hipparchus Core Release Notes</title>
   </properties>
   <body>
+    <release version="5.0" date="TBD" description="TBD.">
+      <action dev="luc" type="add" issue="issues/439">
+        Added Field.isSmall to help convergence checks in Field iterative algorithms.
+      </action>
+    </release>
     <release version="4.1" date="TBD" description="TBD">
       <action dev="krys06" type="add" issue="issues/355">
         Added evaluation of bicubic and tricubic interpolation functions with CalculusFieldElement

diff --git a/hipparchus-core/src/main/java/org/hipparchus/CalculusFieldElement.java b/hipparchus-core/src/main/java/org/hipparchus/CalculusFieldElement.java
@@ -598,6 +598,20 @@ default double norm() {
         return abs().getReal();
     }
 
+    /** Check if instance is small with respect to reference.
+     * <p>
+     * This check is mainly intended for checking convergence of iterative
+     * algorithms. The idea is that {@code this + base} is <em>close enough</em>
+     * to {@code base}, using a relative threshold. The default implementation
+     * uses only the relative threshold with respect to he {@link #getReal()} part.
+     * </p>
+     * @return true if instance is small with respect to reference
+     * @since 5.0
+     */
+    default boolean isSmall(final T base, final double relativeThreshold) {
+        return FastMath.abs(getReal()) <= FastMath.abs(base.getReal() * relativeThreshold);
+    }
+
     /** absolute value.
      * @return abs(this)
      */

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
@@ -24,6 +24,7 @@
 import java.io.Serializable;
 
 import org.hipparchus.Field;
+import org.hipparchus.exception.LocalizedCoreFormats;
 import org.hipparchus.exception.MathIllegalArgumentException;
 import org.hipparchus.exception.MathRuntimeException;
 import org.hipparchus.util.FastMath;
@@ -1102,6 +1103,20 @@ public DerivativeStructure getPi() {
         return factory.getDerivativeField().getPi();
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean isSmall(final DerivativeStructure base, final double relativeThreshold) {
+        if (data.length != base.data.length) {
+            throw new MathIllegalArgumentException(LocalizedCoreFormats.DIMENSIONS_MISMATCH,
+                                                   data.length, base.data.length);
+        }
+        boolean ok = true;
+        for (int i = 0; i < data.length && ok; ++i) {
+            ok = FastMath.abs(data[i]) <= FastMath.abs(base.data[i] * relativeThreshold);
+        }
+        return ok;
+    }
+
     /**
      * Test for the equality of two derivative structures.
      * <p>

diff --git a/...-core/src/main/java/org/hipparchus/analysis/differentiation/FieldDerivativeStructure.java b/...-core/src/main/java/org/hipparchus/analysis/differentiation/FieldDerivativeStructure.java
@@ -18,6 +18,7 @@
 
 import org.hipparchus.CalculusFieldElement;
 import org.hipparchus.Field;
+import org.hipparchus.exception.LocalizedCoreFormats;
 import org.hipparchus.exception.MathIllegalArgumentException;
 import org.hipparchus.exception.MathRuntimeException;
 import org.hipparchus.util.FieldSinCos;
@@ -1321,6 +1322,20 @@ public FieldDerivativeStructure<T> getPi() {
         return factory.getDerivativeField().getPi();
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean isSmall(final FieldDerivativeStructure<T> base, final double relativeThreshold) {
+        if (data.length != base.data.length) {
+            throw new MathIllegalArgumentException(LocalizedCoreFormats.DIMENSIONS_MISMATCH,
+                                                   data.length, base.data.length);
+        }
+        boolean ok = true;
+        for (int i = 0; i < data.length && ok; ++i) {
+            ok = data[i].isSmall(base.data[i], relativeThreshold);
+        }
+        return ok;
+    }
+
     /**
      * Test for the equality of two derivative structures.
      * <p>

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
@@ -904,6 +904,20 @@ public FieldGradient<T> getPi() {
         return new FieldGradient<>(getValueField().getZero().getPi(), getFreeParameters());
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean isSmall(final FieldGradient<T> base, final double relativeThreshold) {
+        if (grad.length != base.grad.length) {
+            throw new MathIllegalArgumentException(LocalizedCoreFormats.DIMENSIONS_MISMATCH,
+                                                   grad.length, base.grad.length);
+        }
+        boolean ok = value.isSmall(base.value, relativeThreshold);
+        for (int i = 0; i < grad.length && ok; ++i) {
+            ok = grad[i].isSmall(base.grad[i], relativeThreshold);
+        }
+        return ok;
+    }
+
     /** Test for the equality of two univariate derivatives.
      * <p>
      * univariate derivatives are considered equal if they have the same derivatives.

diff --git a/...ore/src/main/java/org/hipparchus/analysis/differentiation/FieldUnivariateDerivative1.java b/...ore/src/main/java/org/hipparchus/analysis/differentiation/FieldUnivariateDerivative1.java
@@ -675,6 +675,13 @@ public FieldUnivariateDerivative1<T> getPi() {
         return new FieldUnivariateDerivative1<>(zero.getPi(), zero);
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean isSmall(final FieldUnivariateDerivative1<T> base, final double relativeThreshold) {
+        return f0.isSmall(base.f0, relativeThreshold) &&
+               f1.isSmall(base.f1, relativeThreshold);
+    }
+
     /** Test for the equality of two univariate derivatives.
      * <p>
      * univariate derivatives are considered equal if they have the same derivatives.

diff --git a/...ore/src/main/java/org/hipparchus/analysis/differentiation/FieldUnivariateDerivative2.java b/...ore/src/main/java/org/hipparchus/analysis/differentiation/FieldUnivariateDerivative2.java
@@ -1002,6 +1002,14 @@ public FieldUnivariateDerivative2<T> getPi() {
         return new FieldUnivariateDerivative2<>(zero.getPi(), zero, zero);
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean isSmall(final FieldUnivariateDerivative2<T> base, final double relativeThreshold) {
+        return f0.isSmall(base.f0, relativeThreshold) &&
+               f1.isSmall(base.f1, relativeThreshold) &&
+               f2.isSmall(base.f2, relativeThreshold);
+    }
+
     /** Test for the equality of two univariate derivatives.
      * <p>
      * univariate derivatives are considered equal if they have the same derivatives.

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
@@ -733,6 +733,20 @@ public Gradient stackVariable() {
         return new Gradient(gradient, this.getValue());
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean isSmall(final Gradient base, final double relativeThreshold) {
+        if (grad.length != base.grad.length) {
+            throw new MathIllegalArgumentException(LocalizedCoreFormats.DIMENSIONS_MISMATCH,
+                                                   grad.length, base.grad.length);
+        }
+        boolean ok = FastMath.abs(value) <= FastMath.abs(base.value * relativeThreshold);
+        for (int i = 0; i < grad.length && ok; ++i) {
+            ok = FastMath.abs(grad[i]) <= FastMath.abs(base.grad[i] * relativeThreshold);
+        }
+        return ok;
+    }
+
     /** Test for the equality of two univariate derivatives.
      * <p>
      * univariate derivatives are considered equal if they have the same derivatives.

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
@@ -769,6 +769,17 @@ public SparseGradient getPi() {
         return new SparseGradient(FastMath.PI, null);
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean isSmall(final SparseGradient base, final double relativeThreshold) {
+        boolean ok = FastMath.abs(value) <= FastMath.abs(base.value * relativeThreshold);
+        for (final Map.Entry<Integer, Double> entry : derivatives.entrySet()) {
+            ok &= FastMath.abs(entry.getValue()) <=
+                  FastMath.abs(base.getDerivative(entry.getKey()) * relativeThreshold);
+        }
+        return ok;
+    }
+
     /**
      * Test for the equality of two sparse gradients.
      * <p>

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
@@ -506,6 +506,13 @@ public UnivariateDerivative1 getPi() {
         return PI;
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean isSmall(final UnivariateDerivative1 base, final double relativeThreshold) {
+        return FastMath.abs(f0) <= FastMath.abs(base.f0 * relativeThreshold) &&
+               FastMath.abs(f1) <= FastMath.abs(base.f1 * relativeThreshold);
+    }
+
     /** Test for the equality of two univariate derivatives.
      * <p>
      * univariate derivatives are considered equal if they have the same derivatives.

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
@@ -785,6 +785,14 @@ public UnivariateDerivative2 getPi() {
         return PI;
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean isSmall(final UnivariateDerivative2 base, final double relativeThreshold) {
+        return FastMath.abs(f0) <= FastMath.abs(base.f0 * relativeThreshold) &&
+               FastMath.abs(f1) <= FastMath.abs(base.f1 * relativeThreshold) &&
+               FastMath.abs(f2) <= FastMath.abs(base.f2 * relativeThreshold);
+    }
+
     /** Test for the equality of two univariate derivatives.
      * <p>
      * univariate derivatives are considered equal if they have the same derivatives.

diff --git a/hipparchus-core/src/main/java/org/hipparchus/complex/Complex.java b/hipparchus-core/src/main/java/org/hipparchus/complex/Complex.java
@@ -1885,6 +1885,13 @@ public Complex toRadians() {
         return createComplex(FastMath.toRadians(getRealPart()), FastMath.toRadians(getImaginaryPart()));
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean isSmall(final Complex base, final double relativeThreshold) {
+        return FastMath.abs(getRealPart())      <= FastMath.abs(base.getRealPart()      * relativeThreshold) &&
+               FastMath.abs(getImaginaryPart()) <= FastMath.abs(base.getImaginaryPart() * relativeThreshold);
+    }
+
     /** {@inheritDoc}
      * <p>
      * Comparison us performed using real ordering as the primary sort order and

diff --git a/hipparchus-core/src/main/java/org/hipparchus/complex/FieldComplex.java b/hipparchus-core/src/main/java/org/hipparchus/complex/FieldComplex.java
@@ -1997,4 +1997,11 @@ public FieldComplex<T> getPi() {
         return getPi(getPartsField());
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean isSmall(final FieldComplex<T> base, final double relativeThreshold) {
+        return getRealPart().isSmall(base.getRealPart(), relativeThreshold) &&
+               getImaginaryPart().isSmall(base.getImaginaryPart(), relativeThreshold);
+    }
+
 }
diff --git a/hipparchus-core/src/main/java/org/hipparchus/util/FieldTuple.java b/hipparchus-core/src/main/java/org/hipparchus/util/FieldTuple.java
@@ -20,6 +20,7 @@
 
 import org.hipparchus.CalculusFieldElement;
 import org.hipparchus.Field;
+import org.hipparchus.exception.LocalizedCoreFormats;
 import org.hipparchus.exception.MathIllegalArgumentException;
 
 /**
@@ -784,6 +785,20 @@ public FieldTuple<T> getPi() {
         return result;
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean isSmall(final FieldTuple<T> base, final double relativeThreshold) {
+        if (values.length != base.values.length) {
+            throw new MathIllegalArgumentException(LocalizedCoreFormats.DIMENSIONS_MISMATCH,
+                                                   values.length, base.values.length);
+        }
+        boolean ok = true;
+        for (int i = 0; i < values.length && ok; ++i) {
+            ok = values[i].isSmall(base.values[i], relativeThreshold);
+        }
+        return ok;
+    }
+
     /** Field for {link FieldTuple} instances.
      * @param <T> the type of the field elements
      */

diff --git a/hipparchus-core/src/main/java/org/hipparchus/util/Tuple.java b/hipparchus-core/src/main/java/org/hipparchus/util/Tuple.java
@@ -20,6 +20,7 @@
 
 import org.hipparchus.CalculusFieldElement;
 import org.hipparchus.Field;
+import org.hipparchus.exception.LocalizedCoreFormats;
 import org.hipparchus.exception.MathIllegalArgumentException;
 
 /**
@@ -787,6 +788,20 @@ public Tuple getPi() {
         return result;
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean isSmall(final Tuple base, final double relativeThreshold) {
+        if (values.length != base.values.length) {
+            throw new MathIllegalArgumentException(LocalizedCoreFormats.DIMENSIONS_MISMATCH,
+                                                   values.length, base.values.length);
+        }
+        boolean ok = true;
+        for (int i = 0; i < values.length && ok; ++i) {
+            ok = FastMath.abs(values[i]) <= FastMath.abs(base.values[i] * relativeThreshold);
+        }
+        return ok;
+    }
+
     /** Field for {link Tuple} instances.
      */
     private static class TupleField implements Field<Tuple> {