What is a "semi-monotonic" function?

Question

In the java Math class, the outputs of some methods are described as "semi monotonic".

for example:

/** 
    Returns the base 10 logarithm of a {@code double} value.
    ...
    Results must be semi-monotonic.
 */

public static double log10(double a) {
    return StrictMath.log10(a);
}

I'm familiar with monotonic functions, but what does this mean?

Answer 1

@mrp directs us to the Math library documentation on this java-specific term, which explains that semi-monotonic is a notion describing how certain FP functions relate to an underlying mathematical function that is monotone:

semi-monotonic: whenever the mathematical function is non-decreasing, so is the floating-point approximation ...

---

Consider this pair of logarithm functions:

• StrictMath.log10
• Math.log10

The "strict" spec is:

Returns the base 10 logarithm of a double value. Special cases:

• If the argument is NaN or less than zero, then the result is NaN.
• If the argument is positive infinity, then the result is positive infinity.
• If the argument is positive zero or negative zero, then the result is negative infinity.
• If the argument is equal to 10n for integer n, then the result is n. In particular, if the argument is 1.0 (100), then the result is positive zero.

OTOH the Math spec copies that verbatim, and then weakens the contract on the return value by appending:

The computed result must be within 1 ulp of the exact result. Results must be semi-monotonic.

So an Intel FPU or other implementation method might possibly make significand's final bit a random boolean. But when using such a method within the JVM, the overall implementation must ensure that significand, including that final ulp, offers monotonic FP results. This is for consistency with the underlying mathematical function which is itself monotone.