feat: add specialised inverse cdf implementation for geometric distribution

[nataziel]

closes #342

[nataziel]

@YeungOnion would you mind taking a look at this?

[YeungOnion]

Thanks for the ping and for contributing!

Would you be able to write a few tests, specifically for
small p (2e-16) with x near 1, maybe 1-1e-15? Just wanting to know if there should be a warning output for small p regarding an upper bound to k, and if so, at what range of p.

Since the domain of CDF is natural numbers but the type is u64, want to ensure the inversion property is upheld for the range of values in u64.

Does my request seem justified?

[codecov]

Codecov Report

Attention: Patch coverage is 80.00000% with 2 lines in your changes missing coverage. Please review.

Project coverage is 94.98%. Comparing base (8a45d47) to head (1a98f14).

Files with missing lines	Patch %	Lines
src/distribution/geometric.rs	80.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #343      +/-   ##
==========================================
- Coverage   94.99%   94.98%   -0.02%     
==========================================
  Files          61       61              
  Lines       13615    13625      +10     
==========================================
+ Hits        12934    12942       +8     
- Misses        681      683       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[YeungOnion]

Let me know if you need any clarity on the request.

[nataziel]

Request is fine, just need to find time to implement! Will try this weekend.

[nataziel]

Fixed a rustfmt error and added tests for branch coverage. Struggling with the small p tests because I'm not sure how to generate cases that generate pathological outputs

[OrionYeung]

Yeah, it's kind of tricky to ensure they're extreme. We can take a similar approach for upper bound of p as #155 (comment)

For IEEE, largest nontrivial success probability, p, is
$(1+m)\times 2^{-1}$ for largest m on [0,1), and float 64 would be exponent of 1022, positive and mantissa of (1<<53)-1

That should be 0x3fefffffffffffff if I did math right (playground). Then verify inversion via forward cdf then inverse cdf until forward evaluates to 1.

--

The other extremes of p you might want to check would be if the codomain of the float inverse cdf includes min(intmax, smallest int where forward cdf evaluates to 1), I'll call not reaching this value "early saturation". I'd expect a p near 0 and another near 1.

If the test fails somewhere on the interval, I'd include a warning and for the test, the most extreme value for regression testing. To find the most extreme you would likely have to search for the least extreme p where the expression saturates early.

If it doesn't fail, then I think you choose the most extreme value that's not degenerate for the forward cdf and check that it saturates correctly.

EDIT: math formatting, add a reference for max float less than 1.0

[YeungOnion]

Hey, did you need anything here? I totally fell off the radar, if you ran into issues, I can work on a test case.

I'll probably test include it as a separate pr to see if it even passed with the search implementation. It can be tricky to know if the test is even right for things like this.