Skip to content

Commit 9a5e148

Browse files
committed
doc: update readme to regard precision, open to updates
1 parent ea2ca01 commit 9a5e148

File tree

1 file changed

+30
-11
lines changed

1 file changed

+30
-11
lines changed

README.md

Lines changed: 30 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -61,14 +61,16 @@ Thanks for your help to improve the project!
6161
**No contribution is too small and all contributions are valued.**
6262

6363
Suggestions if you don't know where to start,
64+
- if you're an existing user, file an issue or feature request.
6465
- [documentation][docs-url] is a great place to start, as you'll be able to identify the value of existing documentation better than its authors.
6566
- tests are valuable in demonstrating correct behavior, you can review test coverage on the [CodeCov Report][codecov-url]
6667
- check out some of the issues marked [help wanted](https://github.com/statrs-dev/statrs/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).
67-
- look at features in other tools you'd like to see in statrs
68-
- Math.NET's
68+
- look at features you'd like to see in statrs
69+
- Math.NET
6970
- [Distributions](https://github.com/mathnet/mathnet-numerics/tree/master/src/Numerics/Distributions)
7071
- [Statistics](https://github.com/mathnet/mathnet-numerics/tree/master/src/Numerics/Statistics)
7172
- scipy.stats
73+
- KDE, see (issue #193)[https://github.com/statrs-dev/statrs/issues/193]
7274

7375
### How to contribute
7476

@@ -102,24 +104,41 @@ gh pr create --head <your_branch> # with GitHub's cli
102104

103105
Then submit a PR, preferably referencing the relevant issue, if it exists.
104106

107+
### Precision for contributors
108+
Take a look at the (Precision section)[#precision] to get a sense of what we have built in. Also take a look at tests and various assertions.
109+
If you'd like to improve precision, please also make existing tests more precise, perhaps up to the crate's default set in the `crate::prec` module or better.
110+
105111
### Commit messages
106112

107113
Please be explicit and and purposeful with commit messages.
108114
[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) encouraged.
109115

110-
#### Bad
116+
### Communication Expectations
111117

112-
```
113-
Modify test code
114-
```
118+
Please allow at least one week before pinging issues/pr's.
115119

116-
#### Good
120+
121+
## Precision
122+
Floating point is hard! We should try to not unintentionally misuse it. The below text is from the `approx` crate's README and contains useful links.
123+
> ## References
124+
> Floating point is hard! Thanks goes to these links for helping to make things a little easier to understand:
125+
>
126+
> [Comparing Floating Point Numbers, 2012 Edition](https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/)
127+
> [The Floating Point Guide - Comparison](http://floating-point-gui.de/errors/comparison/)
128+
> [What Every Computer Scientist Should Know About Floating-Point Arithmetic](https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html)
129+
130+
We have a set of approximation checks in the `prec` module that wrap those from the `approx` crate so that it's easier to have convey blanket precision expectations when appraising this crate. For granularity, one can search for where the options are set otherwise. If you use `rg`, you can run this below command from the crate root.
117131

118132
```
119-
test: Update statrs::distribution::Normal test_cdf
133+
$ rg --no-config '(?:abs_diff|relative|ulps)_eq\(.+?(?:epsilon|max_relative|ulps)\s?='
120134
```
121135

122-
### Communication Expectations
123-
124-
Please allow at least one week before pinging issues/pr's.
136+
Below uses $\oplus,\ominus,\otimes$ for floating point binary operation rounded to float.
137+
The approximation macros are enumerated below, we also have `assert_*` variants, often used in testing.
138+
- `abs_diff_eq(x, y[, epsilon = DEFAULT_EPS])`
139+
is $\textrm{float}|x \ominus y| < \epsilon$, which is `abs(x - y) < epsilon` and
140+
- `relative_eq(x, y[, epsilon = DEFAULT_EPS][, max_relative = DEFAULT_RELATIVE_ACC])`
141+
is `abs_diff < cmp::max(fabs(x), fabs(y)) * max_relative` where `abs_diff >= epsilon`
142+
- `ulps_eq(x, y[, epsilon = DEFAULT_EPS][, max_ulps = DEFAULT_ULPS])`
143+
"number of bits away" or "count of representible floats between".
125144

0 commit comments

Comments
 (0)