Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,3 +56,22 @@ void main()

See [the benchmark subpackage](benchmarks/README.md) for selectable statistical
benchmarks and their command-line runner.

#### Extreme numerical tests

Gamma inverse-CDF tests with very large shapes run by default with a DMD
frontend version of 2.113 or newer, including corresponding LDC and GDC
versions. Phobos fixed the large-shape performance issue in DMD 2.112.1
([issue 10920](https://github.com/dlang/phobos/issues/10920)), but `__VERSION__`
does not distinguish 2.112.0 from 2.112.1. The automatic gate therefore starts
conservatively at 2.113. Phobos versions without the fix can take an
impractically long time on these inputs.

To run them on 2.112.1, or opt in regardless of frontend version, run:

```sh
dub test --build=unittest-extreme-numerics
```

This opt-in build is separate from `unittest-slow-numerics` and is not run
by the routine CI matrix.
9 changes: 9 additions & 0 deletions dub.sdl
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,15 @@ buildType "unittest-slow-numerics" {
dflags "-lowmem" platform="dmd"
dflags "-lowmem" platform="ldc"
}
// Opt into extreme-shape tests even on older Phobos versions. Their lower
// incomplete-gamma power series can make these cases exceptionally slow.
// This build is intentionally not part of the routine CI matrix.
buildType "unittest-extreme-numerics" {
buildOptions "unittests" "debugMode" "debugInfo"
versions "mir_stat_test" "mir_stat_test_extreme_numerics"
dflags "-lowmem" platform="dmd"
dflags "-lowmem" platform="ldc"
}
buildType "docs-check" {
buildOptions "syntaxOnly" "warningsAsErrors"
dflags "-Dddocs"
Expand Down
118 changes: 106 additions & 12 deletions source/mir/stat/distribution/cauchy.d
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,11 @@ T cauchyPDF(T)(const T x)
{
import mir.math.constant: M_1_PI;

return T(M_1_PI) / (1 + x * x);
const T square = x * x;
if (square == T.infinity)
// 1/x^2 is negligible here, but the density can still be subnormal.
return (T(M_1_PI) / x) / x;
return T(M_1_PI) / (1 + square);
}

/++
Expand Down Expand Up @@ -192,6 +196,9 @@ unittest
/++
Computes the Cauchy inverse cumulative distribution function (InvCDF).

Uses reciprocal tangents in the tails so small probabilities are not lost
by subtracting one half.

Params:
p = value to evaluate InvCDF

Expand All @@ -205,16 +212,13 @@ T cauchyInvCDF(T)(const T p)
in (p <= 1, "p must be less than or equal to 1")
{
import mir.math.constant: PI;
import mir.math.common: fabs;
import std.math.trigonometry: tan;

if (p > 0 && p < 1) {
return tan(T(PI) * (p - 0.5));
} else if (p == 0) {
return -T.infinity;
} else if (p == 1) {
return T.infinity;
}
assert(0, "Should not be here");
const T centered = p - T(0.5);
if (fabs(centered) <= T(0.25))
return tan(T(PI) * centered);
return cauchyInvCDF(p, T(0), T(1));
}

/++
Expand All @@ -232,7 +236,31 @@ T cauchyInvCDF(T)(const T p, const T location, const T scale)
in (p <= 1, "p must be less than or equal to 1")
in (scale > 0, "scale must be greater than zero")
{
return location + scale * cauchyInvCDF(p);
import mir.math.constant: PI, M_1_PI;
import std.math.trigonometry: tan;

if (p >= T(0.25) && p <= T(0.75))
return location + scale * tan(T(PI) * (p - T(0.5)));
if (p == 0)
return -T.infinity;
if (p == 1)
return T.infinity;
if (p > 0 && p < 1)
{
if (p < T.min_normal)
{
// Avoid rounding pi*p to a subnormal before taking its inverse.
// cot(pi*p) = 1/(pi*p) to far better than working precision here.
const T ratio = scale / p;
const T tail = ratio < T.infinity ? ratio * T(M_1_PI)
: (scale * T(M_1_PI)) / p;
return location - tail;
}
if (p < T(0.25))
return location - scale / tan(T(PI) * p);
return location + scale / tan(T(PI) * (1 - p));
}
assert(0, "Should not be here");
}

///
Expand Down Expand Up @@ -274,10 +302,13 @@ See_also:
T cauchyLPDF(T)(const T x)
if (isFloatingPoint!T)
{
import mir.math.common: log;
import mir.math.common: log, fabs;
import mir.stat.constant: LOGPI;

return -T(LOGPI) - log(1 + x * x);
const T square = x * x;
if (square == T.infinity)
return -T(LOGPI) - 2 * log(fabs(x));
return -T(LOGPI) - log(1 + square);
}

/++
Expand Down Expand Up @@ -323,3 +354,66 @@ unittest
cauchyLPDF(2.0, 1, 2).shouldApprox == log(0.127324);
cauchyLPDF(3.0, 1, 2).shouldApprox == log(0.07957747);
}

// Extreme tails retain densities and logarithms when squaring overflows.
version(mir_stat_test)
@safe pure nothrow @nogc
unittest
{
import std.meta: AliasSeq;
import std.math: ldexp, nextUp;
import mir.math.common: approxEqual, log;
import mir.math.constant: M_1_PI;
import mir.stat.constant: LOGPI;

static foreach (T; AliasSeq!(float, double, real))
{{
const T x = ldexp(T(1), T.max_exp / 2);
// 1/x^2 is negligible; evaluating the divisions separately is safe.
const T expected = (T(M_1_PI) / x) / x;
assert(expected > 0);
foreach (v; [x, -x])
{
assert(approxEqual(cauchyPDF(v), expected, 8 * T.epsilon, 2 * nextUp(T(0))));
assert(approxEqual(cauchyLPDF(v), -T(LOGPI) - 2 * log(x), 8 * T.epsilon, T(0)));
}
}}
}

// Extreme probabilities retain tail and scaled quantiles.
version(mir_stat_test)
@safe pure nothrow @nogc
unittest
{
import std.meta: AliasSeq;
import std.math: ldexp, nextUp, nextDown;
import mir.math.common: approxEqual;
import mir.math.constant: M_1_PI;

static foreach (T; AliasSeq!(float, double, real))
{{
const T p = T.epsilon * T.epsilon;
assert(approxEqual(cauchyInvCDF(p), -T(M_1_PI) / p, 8 * T.epsilon, T(0)));
const T upper = nextDown(T(1));
assert(approxEqual(cauchyInvCDF(upper), T(M_1_PI) / (1 - upper), 8 * T.epsilon, T(0)));
const T tiny = nextUp(T(0));
assert(approxEqual(cauchyInvCDF(tiny, T(0), tiny), -T(M_1_PI), 8 * T.epsilon, T(0)));
// scale/p overflows, but division by pi leaves a finite result.
const T scaledTail = ldexp(T(M_1_PI), T.max_exp);
assert(approxEqual(cauchyInvCDF(T.min_normal / 2, T(0), T(2)),
-scaledTail, 8 * T.epsilon, T(0)));
// The normal-probability tail path also preserves small scales.
assert(approxEqual(cauchyInvCDF(T.min_normal, T(0), T.min_normal),
-T(M_1_PI), 8 * T.epsilon, T(0)));
assert(cauchyInvCDF(T(0)) == -T.infinity);
assert(cauchyInvCDF(T(1)) == T.infinity);
assert(cauchyInvCDF(T(.5)) == 0);
foreach (cutoff; [T(.25), T(.75)])
{
const T at = cauchyInvCDF(cutoff);
assert(approxEqual(at, cutoff == T(.25) ? T(-1) : T(1), 8 * T.epsilon, T(0)));
assert(approxEqual(cauchyInvCDF(nextDown(cutoff)), at, 8 * T.epsilon, T(0)));
assert(approxEqual(cauchyInvCDF(nextUp(cutoff)), at, 8 * T.epsilon, T(0)));
}
}}
}
Loading
Loading