Proposal: Math Lib is missing some APIs.

[kuzminrobin]

(This is the original proposal text. See the updated version of this proposal below)

I propose (to the Q# API Design Review Board) to add to the Q# API the following missing calls to support the Math library.

    @Inline()
    function NAN() : Double {
        body intrinsic;
    }

    @Inline()
    function IsNan(d: Double) : Bool {
        body intrinsic;
    }

    @Inline()
    function INFINITY() : Double {
        body intrinsic;
    }

    @Inline()
    function IsInf(d: Double) : Bool {
        body intrinsic;
    }

    @Inline()
    function IsNegativeInfinity(d : Double) : Bool {
        body intrinsic;
    }

Currently they are needed to implement the Log() math function.
More details:
Discussion
Possible Implementation

[bamarsha]

I think these don't have to be intrinsic, right?

function NaN() : Double {
    return 0.0 / 0.0;
}

function IsNaN(d : Double) : Bool {
    return d != d;
}

function Infinity() : Double {
    return 1.0 / 0.0;
}

function IsInfinity(d : Double) : Bool {
    // Or remove this function in favor of directly using "d == Infinity()".
    return d == Infinity();
}

function IsNegativeInfinity(d : Double) : Bool {
    // Or remove this function in favor of directly using "d == -Infinity()".
    return d == -Infinity();
}

[cgranade]

As a clarification, which namespace would you propose for these new callables? It seems like Microsoft.Quantum.Math may be the best bet, since these callables concern classical math operations similar to existing functions and operations in that namespace.

[kuzminrobin]

@SamarSha, looks like you are right ;-)
However I'm not sure if negative infinity is the same as -(positive infinity). It needs to be double-checked against the corresponding floating point standard.

[kuzminrobin]

@cgranade, I agree, Microsoft.Quantum.Math looks a good place.

[bamarsha]

I think you could define negative infinity as -1.0 / 0.0 in that case.

[kuzminrobin]

@SamarSha, I like the ideas in both your of posts!

[cgranade]

I'd suggest going with IsInfinite for the name of the function to check against infinity and having it check against positive and negative infinity. In part, that makes for a nice complement with checking that a number is finite:

namespace Microsoft.Quantum.Math {
    function IsInfinite(d : Double) : Bool {
        return d == 1.0 / 0.0 or d == -1.0 / 0.0;
    }

    function IsFinite(d : Double) : Bool {
        return not IsInfinite(d) and not IsNaN(d);
    }
}

namespace Microsoft.Quantum.Diagnostics {
    function FiniteFact(d : Double, message : String) : Unit {
        Fact(IsFinite(d), message);
    }
}

Positive and negative infinities can still be discriminated by checking d > 0.0 and d < 0.0, so no expressive power is lost. This also more closely matches existing scientific computing APIs like np.isinf, 's isinf, or even MATLAB's isinf, all of which check against positive and negative infinity in precisely the same way.

[cgranade]

@kuzminrobin: The API review for March is coming up in a few days, it would be good to get this in to that review cycle. Would you be willing to update your proposal to include the namespace, and the feedback from me and @samarsh, so that we can get it added to the discussion? Thank you!

[kuzminrobin]

Based on the feedback/discussion, the updated version of the proposal is below:

namespace Microsoft.Quantum.Math {
    function NaN() : Double {
        return 0.0 / 0.0;
    }

    function IsNaN(d : Double) : Bool {
        return d != d;
    }

    
    function IsInfinite(d : Double) : Bool {
        return d == 1.0 / 0.0 or d == -1.0 / 0.0;
        // Positive and negative infinities can still be 
        // discriminated by checking `d > 0.0` and `d < 0.0`.
    }

    function IsFinite(d : Double) : Bool {
        return not IsInfinite(d) and not IsNaN(d);
    }
}

namespace Microsoft.Quantum.Diagnostics {
    function FiniteFact(d : Double, message : String) : Unit {
        Fact(IsFinite(d), message);
    }
}