mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/readers/grib2/portable_math.py

@@ -0,0 +1,501 @@
+"""Trigonometry that answers the same on every machine, computed here rather than asked of C.
+
+Why this module exists
+----------------------
+IEEE-754 requires addition, subtraction, multiplication, division and square root to be
+correctly rounded: two conforming machines given the same doubles hand back the same double,
+bit for bit.  It requires nothing of the kind for sine, cosine, tangent, logarithm, arc tangent
+or raising to a fractional power.  Every C library approximates those its own way, and two of
+them may differ in the last place with neither of them wrong.
+
+That is not a theoretical difference here.  The flagship weather model declares both of its
+standard parallels at 38.5 degrees, so the whole cone constant of its projection is one sine::
+
+    math.sin(math.radians(38.5))
+
+    glibc on x86_64     0x1.3eba3d0b47a0ep-1
+    macOS on arm64      0x1.3eba3d0b47a0fp-1
+
+One unit in the last place.  Carried through the projection it moved the reported latitude of a
+grid cell over Chicago from ``41.87656533464987`` to ``41.87656533464984``, which moved the
+digest of a known-good sample, which failed the sample gate on one architecture and passed it on
+the other.  A dataset this harness builds is meant to be reproducible from its recipe and its
+bytes; a coordinate that also depends on which C library the machine was built against is not
+that, and it fails in the quiet way: the number verifies, it plots, and it disagrees with the
+same number computed next door.
+
+What this module guarantees, and what it does not
+-------------------------------------------------
+**Guaranteed: one float64 argument produces one float64 answer, the same on every machine.**
+Every step between them is a decimal operation the decimal arithmetic specification requires to
+be correctly rounded -- add, subtract, multiply, divide, square root -- carried at a fixed
+precision, in a fixed order, from constants this module computes for itself.  Nothing on that
+path is left to the machine.
+
+**Not claimed: correct rounding.**  Each series below stops when a further term no longer moves
+the running total at fifty significant digits, and the result is rounded to float64 once, at the
+end.  Claiming correct rounding would need a proof that no true value here lands within
+10^-33 of the midpoint between two doubles, and no such proof is offered.  What is offered is
+that whatever answer comes out, the same answer comes out everywhere, which is the property a
+reproducible receipt actually needs.
+
+**Accuracy is graded rather than asserted.**  The tests compare every function here against the
+platform's own C library across the range this Reader uses, and against the identities that
+relate them.  Beyond that, the projection built on this module is compared against the
+publisher's own declared grid corner on every message read -- so an error here does not wait for
+a test to be noticed, it stops a decode.
+
+What is not computed in decimal, and why
+----------------------------------------
+``PI``, ``radians`` and ``degrees`` are exact float64 work: a constant, and one multiplication
+by a factor derived with one correctly rounded division.  They live here so the projection has a
+single place to reach for its arithmetic, not because they were ever in doubt.  A correctly
+rounded multiplication is a correctly rounded multiplication everywhere, and running them
+through decimal would cost time to buy nothing.
+
+The method, in the order the code runs it
+-----------------------------------------
+1. The float64 argument converts to ``Decimal`` exactly.  A binary64 value is a terminating
+   decimal, so this step loses nothing and invents nothing.
+2. The argument is reduced to the interval where its series converges quickly: sine and cosine
+   modulo a quarter turn, the logarithm to a mantissa near one, the exponential modulo the
+   logarithm of ten, the arc tangent by repeated halving.  Reduction uses constants carried to
+   seventy-five digits so the subtraction that does it cannot lose the digits that matter.
+3. The reduced argument goes into a plain series, summed until a term no longer changes the
+   total at the working precision.
+4. The result is rounded to float64 exactly once, on the way out.
+
+The constants
+-------------
+``pi`` comes from Machin's formula, ``pi = 16 atan(1/5) - 4 atan(1/239)``; the natural
+logarithms of two and ten come from the ``atanh`` series.  They are computed at import from
+those formulae rather than pasted in as digits, so there is no transcription to get wrong.  The
+tests compare their leading digits against published values, which is the check a pasted
+constant would have needed anyway.
+
+Import discipline: ``decimal`` and nothing else, ever.  A module whose entire purpose is to
+stop depending on the machine's arithmetic has no business importing anything that might.
+"""
+
+from __future__ import annotations
+
+import decimal
+from decimal import Decimal
+
+__all__ = [
+    "CONSTANT_DIGITS",
+    "PI",
+    "WORKING_DIGITS",
+    "atan",
+    "atan2",
+    "cos",
+    "degrees",
+    "hypot",
+    "log",
+    "power",
+    "radians",
+    "sin",
+    "tan",
+]
+
+# Fifty digits to work in, seventy-five to reduce with.  A float64 needs seventeen to be written
+# down exactly, so the working precision carries thirty-three digits of headroom over what the
+# answer can express, and the reduction carries twenty-five more than that so the cancelling
+# subtraction inside it cannot eat the digits the series then works from.
+WORKING_DIGITS = 50
+CONSTANT_DIGITS = 75
+
+# The reduction subtracts a multiple of a constant known to CONSTANT_DIGITS digits, so a very
+# large argument would spend that headroom on its integer part.  Nothing on this Reader's path
+# reaches an angle of a thousand million radians -- every one of them is bounded by half a turn
+# or by a latitude -- so the bound is stated and enforced rather than assumed.
+_LARGEST_REDUCIBLE_ANGLE = Decimal(10) ** 10
+
+
+def _context(digits: int) -> decimal.Context:
+    """A context that decides everything: precision, rounding, range, and what is fatal.
+
+    Constructed rather than inherited.  A caller who has set a precision of five digits and
+    rounding towards zero must not be able to change this module's answer, and a caller's flags
+    must not be disturbed by having called it, so every function here runs inside one of these
+    and never inside whatever context it was called from.
+    """
+
+    return decimal.Context(
+        prec=digits,
+        rounding=decimal.ROUND_HALF_EVEN,
+        Emin=-999999999,
+        Emax=999999999,
+        capitals=1,
+        clamp=0,
+        flags=[],
+        # An operation with no answer, and a division by zero, are faults to raise rather than
+        # quiet NaNs to propagate.  Overflow is deliberately not fatal: it becomes an infinity,
+        # which is what float64 arithmetic would have produced at the same point.
+        traps=[decimal.InvalidOperation, decimal.DivisionByZero],
+    )
+
+
+_WORKING = _context(WORKING_DIGITS)
+_REDUCING = _context(CONSTANT_DIGITS)
+
+
+# --- The constants, computed from their own formulae ----------------------------------------
+
+
+def _arc_tangent_of_reciprocal(whole: int) -> Decimal:
+    """``atan(1/whole)`` by its alternating series, for whole numbers of two and up.
+
+    Used only to build pi, where the two reciprocals are a fifth and a two hundred and
+    thirty-ninth and the series converges in a few dozen terms.
+    """
+
+    x = Decimal(1) / Decimal(whole)
+    square = x * x
+    signed = x
+    total = x
+    term = 1
+    while True:
+        signed = -signed * square
+        addend = signed / (2 * term + 1)
+        if total + addend == total:
+            return total
+        total += addend
+        term += 1
+
+
+def _logarithm_series(mantissa: Decimal) -> Decimal:
+    """``log(mantissa)`` by the ``atanh`` series, for a mantissa the caller has already reduced.
+
+    ``log(m) = 2 (z + z^3/3 + z^5/5 + ...)`` with ``z = (m - 1) / (m + 1)``.  Every caller here
+    hands over a mantissa between the square roots of a half and of two, where ``|z|`` is under
+    0.18 and the series settles in about forty terms.
+    """
+
+    z = (mantissa - 1) / (mantissa + 1)
+    square = z * z
+    power_of_z = z
+    total = z
+    term = 1
+    while True:
+        power_of_z = power_of_z * square
+        addend = power_of_z / (2 * term + 1)
+        if total + addend == total:
+            return 2 * total
+        total += addend
+        term += 1
+
+
+with decimal.localcontext(_REDUCING):
+    _PI = 16 * _arc_tangent_of_reciprocal(5) - 4 * _arc_tangent_of_reciprocal(239)
+    _HALF_PI = _PI / 2
+    _LOG_TWO = _logarithm_series(Decimal(2))
+    # ten is eight times a quarter more than one, so the logarithm of ten is three logarithms of
+    # two plus one more series, all of them reduced enough to converge quickly.
+    _LOG_TEN = 3 * _LOG_TWO + _logarithm_series(Decimal("1.25"))
+    _ROOT_TWO = Decimal(2).sqrt()
+
+#: Pi as a float64.  Equal to ``math.pi``, and the tests assert that it is: this module computes
+#: the constant it needs rather than importing one, and the agreement is the evidence that both
+#: are the correctly rounded double.
+PI = float(_PI)
+
+#: One degree in radians, and one radian in degrees.  Each is a single IEEE-754 division of two
+#: doubles, which every conforming machine rounds the same way, so a conversion is one exactly
+#: reproducible multiplication.
+_DEGREES_TO_RADIANS = PI / 180.0
+_RADIANS_TO_DEGREES = 180.0 / PI
+
+# The arc tangent series is halved down to here before it is summed.  Below a twentieth the
+# terms fall by a factor of four hundred each time and thirty of them are more than enough.
+_ARC_TANGENT_THRESHOLD = Decimal("0.05")
+
+
+# --- What a caller may hand in ---------------------------------------------------------------
+
+
+def _argument(value: float, function: str) -> Decimal:
+    """One argument, exactly, or a refusal that names the function and what arrived.
+
+    A bool is a whole number to Python and an argument nobody meant to pass here, so it is
+    turned away with everything else that is not a real number.
+    """
+
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise TypeError(f"{function} takes a real number, not {value!r}")
+    number = Decimal(value)
+    if not number.is_finite():
+        raise ValueError(f"{function} takes a finite number, not {value!r}")
+    return number
+
+
+# --- Sine, cosine and tangent ----------------------------------------------------------------
+
+
+def _quarter_turns(angle: Decimal) -> tuple[int, Decimal]:
+    """An angle as a whole number of quarter turns and a remainder of at most an eighth turn.
+
+    The remainder is what the series are given, and it is computed at the reducing precision so
+    that the subtraction -- which cancels almost everything when the angle is near a quarter
+    turn -- still leaves fifty good digits behind.
+    """
+
+    if abs(angle) > _LARGEST_REDUCIBLE_ANGLE:
+        raise ValueError(
+            f"an angle of {angle} radians is larger than the {_LARGEST_REDUCIBLE_ANGLE} this "
+            f"module reduces exactly; every angle on this Reader's path is bounded by half a "
+            f"turn and this one is not one of them"
+        )
+    with decimal.localcontext(_REDUCING):
+        turns = (angle / _HALF_PI).to_integral_value(rounding=decimal.ROUND_HALF_EVEN)
+        remainder = angle - turns * _HALF_PI
+    return int(turns) % 4, +remainder
+
+
+def _sine_series(remainder: Decimal) -> Decimal:
+    """``sin`` of an angle already reduced to an eighth of a turn or less."""
+
+    square = remainder * remainder
+    term = remainder
+    total = remainder
+    index = 1
+    while True:
+        term = -term * square / ((2 * index) * (2 * index + 1))
+        if total + term == total:
+            return total
+        total += term
+        index += 1
+
+
+def _cosine_series(remainder: Decimal) -> Decimal:
+    """``cos`` of an angle already reduced to an eighth of a turn or less."""
+
+    square = remainder * remainder
+    term = Decimal(1)
+    total = Decimal(1)
+    index = 1
+    while True:
+        term = -term * square / ((2 * index - 1) * (2 * index))
+        if total + term == total:
+            return total
+        total += term
+        index += 1
+
+
+def _sine(angle: Decimal) -> Decimal:
+    quarter, remainder = _quarter_turns(angle)
+    if quarter == 0:
+        return _sine_series(remainder)
+    if quarter == 1:
+        return _cosine_series(remainder)
+    if quarter == 2:
+        return -_sine_series(remainder)
+    return -_cosine_series(remainder)
+
+
+def _cosine(angle: Decimal) -> Decimal:
+    quarter, remainder = _quarter_turns(angle)
+    if quarter == 0:
+        return _cosine_series(remainder)
+    if quarter == 1:
+        return -_sine_series(remainder)
+    if quarter == 2:
+        return -_cosine_series(remainder)
+    return _sine_series(remainder)
+
+
+def sin(x: float) -> float:
+    """The sine of an angle in radians."""
+
+    with decimal.localcontext(_WORKING):
+        return float(_sine(_argument(x, "sin")))
+
+
+def cos(x: float) -> float:
+    """The cosine of an angle in radians."""
+
+    with decimal.localcontext(_WORKING):
+        return float(_cosine(_argument(x, "cos")))
+
+
+def tan(x: float) -> float:
+    """The tangent of an angle in radians, as the quotient of the two computed above.
+
+    The quarter-turn reduction leaves the cosine of a remainder no larger than an eighth of a
+    turn, which is never nearer to zero than about 0.707, so the divisor here is zero only if the
+    reduction itself changed.  The guard is for that day rather than for any argument.
+    """
+
+    with decimal.localcontext(_WORKING):
+        angle = _argument(x, "tan")
+        divisor = _cosine(angle)
+        if divisor == 0:
+            raise ValueError(f"tan has no value at {x!r}, where the cosine is exactly zero")
+        return float(_sine(angle) / divisor)
+
+
+# --- Logarithm, exponential and a fractional power -------------------------------------------
+
+
+def _logarithm(number: Decimal) -> Decimal:
+    """The natural logarithm, reduced to a mantissa the series converges quickly on.
+
+    A decimal already carries its own power of ten, so the first reduction is free: shift it out
+    and the mantissa is between one and ten.  Halving at most three more times brings it between
+    the square roots of a half and of two.  Each halving is exact -- a mantissa that came from a
+    float64 has seventeen digits and there are fifty to hold it -- so nothing is lost getting
+    there.
+    """
+
+    exponent = number.adjusted()
+    mantissa = number.scaleb(Decimal(-exponent))
+    halvings = 0
+    while mantissa >= _ROOT_TWO:
+        mantissa = mantissa / 2
+        halvings += 1
+    return exponent * _LOG_TEN + halvings * _LOG_TWO + _logarithm_series(mantissa)
+
+
+def _exponential(power_of_e: Decimal) -> Decimal:
+    """``e`` to a power, reduced modulo the logarithm of ten so the scaling back is exact.
+
+    Reducing by ten rather than by two is deliberate: a decimal scales by powers of ten for
+    nothing, so the last step of this function moves an exponent rather than performing a
+    multiplication that would have to be rounded.
+    """
+
+    with decimal.localcontext(_REDUCING):
+        scale = int((power_of_e / _LOG_TEN).to_integral_value(rounding=decimal.ROUND_HALF_EVEN))
+        remainder = +(power_of_e - scale * _LOG_TEN)
+    term = Decimal(1)
+    total = Decimal(1)
+    index = 1
+    while True:
+        term = term * remainder / index
+        if total + term == total:
+            return total.scaleb(Decimal(scale))
+        total += term
+        index += 1
+
+
+def log(x: float) -> float:
+    """The natural logarithm of a positive number."""
+
+    with decimal.localcontext(_WORKING):
+        number = _argument(x, "log")
+        if number <= 0:
+            raise ValueError(f"log takes a positive number, not {x!r}")
+        return float(_logarithm(number))
+
+
+def power(base: float, exponent: float) -> float:
+    """A positive base raised to any power, as ``exp(exponent * log(base))``.
+
+    Written as one function rather than left to ``**`` because the operator on two floats is the
+    C library's ``pow``, which is exactly the kind of call this module exists to remove.  The
+    base is required to be positive: every use of it here raises a tangent or a radius, both of
+    which are checked positive by their caller before they arrive.
+    """
+
+    with decimal.localcontext(_WORKING):
+        bottom = _argument(base, "power")
+        top = _argument(exponent, "power")
+        if bottom <= 0:
+            raise ValueError(f"power takes a positive base, not {base!r}")
+        if top == 0 or bottom == 1:
+            return 1.0
+        return float(_exponential(_logarithm(bottom) * top))
+
+
+# --- Arc tangent, in one and in two arguments ------------------------------------------------
+
+
+def _arc_tangent_series(x: Decimal) -> Decimal:
+    """``atan`` of an argument the caller has already halved down below a twentieth."""
+
+    square = x * x
+    signed = x
+    total = x
+    index = 1
+    while True:
+        signed = -signed * square
+        addend = signed / (2 * index + 1)
+        if total + addend == total:
+            return total
+        total += addend
+        index += 1
+
+
+def _arc_tangent(x: Decimal) -> Decimal:
+    """The arc tangent, by reciprocal above one and by repeated halving below it.
+
+    ``atan(x) = 2 atan(x / (1 + sqrt(1 + x^2)))`` is the halving identity, and four or five of
+    them carry any argument in the unit interval below the series threshold.
+    """
+
+    if x < 0:
+        return -_arc_tangent(-x)
+    if x > 1:
+        return _HALF_PI - _arc_tangent(1 / x)
+    halvings = 0
+    while x > _ARC_TANGENT_THRESHOLD:
+        x = x / (1 + (1 + x * x).sqrt())
+        halvings += 1
+    return (2**halvings) * _arc_tangent_series(x)
+
+
+def atan(x: float) -> float:
+    """The arc tangent of a number, in radians, between minus and plus a quarter turn."""
+
+    with decimal.localcontext(_WORKING):
+        return float(_arc_tangent(_argument(x, "atan")))
+
+
+def atan2(y: float, x: float) -> float:
+    """The angle of the point ``(x, y)`` from the positive x axis, in radians.
+
+    Signed zeros are not distinguished: a zero is a zero here, so ``atan2(0.0, -1.0)`` is half a
+    turn and never minus half a turn.  The one caller in this Reader guards against both
+    arguments being zero before it calls, because a point at the apex of the cone has every
+    longitude and is refused there by name rather than answered here by convention.
+    """
+
+    with decimal.localcontext(_WORKING):
+        across = _argument(x, "atan2")
+        up = _argument(y, "atan2")
+        if across == 0:
+            if up == 0:
+                return 0.0
+            return float(_HALF_PI if up > 0 else -_HALF_PI)
+        angle = _arc_tangent(up / across)
+        if across > 0:
+            return float(angle)
+        return float(angle + _PI if up >= 0 else angle - _PI)
+
+
+# --- The rest: exact float64 work, kept here so the projection has one place to look ---------
+
+
+def hypot(x: float, y: float) -> float:
+    """The length of the hypotenuse, from a square root the specification rounds correctly."""
+
+    with decimal.localcontext(_WORKING):
+        across = _argument(x, "hypot")
+        up = _argument(y, "hypot")
+        return float((across * across + up * up).sqrt())
+
+
+def radians(degrees_of_arc: float) -> float:
+    """Degrees to radians: one multiplication, correctly rounded on every machine."""
+
+    if isinstance(degrees_of_arc, bool) or not isinstance(degrees_of_arc, (int, float)):
+        raise TypeError(f"radians takes a real number, not {degrees_of_arc!r}")
+    return degrees_of_arc * _DEGREES_TO_RADIANS
+
+
+def degrees(radians_of_arc: float) -> float:
+    """Radians to degrees: one multiplication, correctly rounded on every machine."""
+
+    if isinstance(radians_of_arc, bool) or not isinstance(radians_of_arc, (int, float)):
+        raise TypeError(f"degrees takes a real number, not {radians_of_arc!r}")
+    return radians_of_arc * _RADIANS_TO_DEGREES