zenith-float 1.0.2

Arbitrary-precision software floating-point arithmetic on integer limbs.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# zenith-float

Arbitrary-precision software floating-point numbers in Rust, plus software IEEE-754 binary32/binary64 (`Ieee32` / `Ieee64`) and 1-D arrays. Current release: **1.0.2**. First stable release: **1.0.0** on [crates.io](https://crates.io/crates/zenith-float).

All arithmetic runs on integer limbs. The library does not use hardware floating-point registers for calculations. Construct `ExactNum` from integers or from binary, octal, decimal, or hexadecimal strings; construct IEEE widths from integer bit patterns (`from_bits`).

The library can work without `std` if a memory allocator is available.

Besides the usual `+ − × ÷` and the elementary functions (`sqrt`, `exp`, `exp2`, `exp10`, `ln`, trig, hyperbolic), the public API includes `hypot`, `atan2`, `log1p`, `expm1`, `rem_pi`, specials (`erf`, `gamma`, `bessel_j`, Jacobi `sn`/`cn`/`dn`), IEEE split (`frexp`, `ldexp`, `logb`), extra constants (√2, φ, γ), `cexpr!` for complex expressions, and `SharedConsts` for sharing a constant cache across threads.

License: MIT OR Apache-2.0. See [CONTRIBUTING.md](CONTRIBUTING.md) if you want to report a bug or send a patch.

## Crate layout

- `zenith-float` — public crate: `ExactNum`, `Ieee32`/`Ieee64`, arrays, `expr!`, `cexpr!`, constants, rounding.
- `zenith-float-num` — numeric kernel (you normally depend on `zenith-float` only).
- `zenith-float-macro` — `expr!` / `cexpr!` procedural macros.

## Documentation

- [Capabilities](doc/ZENITH_FLOAT_CAPABILITIES.md) — what the crate does and does not do
- [Getting started](doc/GETTING_STARTED.md)
- [Help](doc/HELP.md) — recipes, mistakes, FAQ
- [Library](doc/LIBRARY.md) — public API
- [`expr!` rounding](doc/EXPR.md)
- [Precision](doc/PRECISION.md)
- [Reproducibility](doc/REPRODUCIBILITY.md)
- [Contributing](CONTRIBUTING.md)
- rustdoc: <https://docs.rs/zenith-float>

## Features

| Feature | Default | Purpose |
| --- | --- | --- |
| `std` | yes | Formatting, `FromStr`, serde (when enabled) |
| `random` | no | `ExactNum::random_normal` for tests and fuzzing |
| `serde` | no | Serialize/deserialize as a decimal string or integer (`std` required) |
| `mpfr-tests` | no | Optional MPFR comparison tests (Linux x86_64, needs `rug`) |

`std` is on by default (formatting and `FromStr`):

```toml
[dependencies]
zenith-float = "1.0"
```

`no_std` (allocator required):

```toml
[dependencies]
zenith-float = { version = "1.0", default-features = false }
```

## Rounding

- `ExactNum` methods that take a rounding mode other than `RoundingMode::None` round the result to the requested precision.
- `RoundingMode::None` skips that final rounding and may keep extra bits.
- `expr!` raises working precision to compensate cancellation. It does **not** itself perform correct rounding; the completion of a rounding loop in finite time depends on the expression.
- Overflow of the configured exponent range becomes `±Inf`. Allocation and invalid arguments become `NaN`; `ExactNum::err()` returns the associated `Error`.
- Subnormals, `NaN`, and infinities are software values, not hardware floating-point registers.

## Example

```rust
use zenith_float::Consts;
use zenith_float::RoundingMode;
use zenith_float::ctx::Context;
use zenith_float::expr;

let mut ctx = Context::new(
    1024,
    RoundingMode::ToEven,
    Consts::new().expect("Constants cache initialized"),
    -10000,
    10000,
);

let pi = expr!(6 * atan(1 / sqrt(3)), &mut ctx);
let pi_lib = ctx.const_pi();
assert_eq!(pi.cmp(&pi_lib), Some(0));
```

Set the smallest exponent range that still holds your results. Internal working precision can grow with the exponent.

## Tests

From this directory:

```bash
bash scripts/ci.sh
```

Debug tests must finish in 10 minutes and the MPFR gate in 30 minutes (`CI_DEBUG_SECS` / `CI_MPFR_SECS`). Replay a random failure with `ZENITH_TEST_SEED=<seed> cargo test <name> -- --test-threads=1` (the seed is printed on panic).

That runs the default workspace tests, `std`-only tests, and tests with `random` and `serde` enabled. On Linux x86_64 the script also runs MPFR goldens in release:

```bash
cargo test -p zenith-float-num --features mpfr-tests -- --test-threads=1
```

Benchmarks (Criterion, release profile, deterministic fixtures):

```bash
./scripts/bench.sh              # quick smoke
./scripts/bench.sh --full       # full samples + HTML report under target/criterion/
./scripts/bench-compare.sh      # run benches, compare to doc/bench-baselines.tsv
./scripts/bench-compare.sh --update   # refresh the TSV baseline after intentional changes
cargo bench -p zenith-float-num --bench transcendentals -- ln/1024
cargo bench -p zenith-float-num --bench arithmetic -- mul_fft   # FFT-scale mul (slow)
```

Regression baselines live in `doc/bench-baselines.tsv` (tab-separated). `REGRESSION_PCT` defaults to 15.

Cross-library comparison (bigfloat-bench compatible workloads, TSV output):

```bash
./scripts/compare-bench.sh --quick    # zenith vs astro @ 132 bits, core tasks → doc/compare-results.tsv
./scripts/compare-bench.sh --full       # 132 / 1000 / 10000 bits, full task matrix
./scripts/compare-bench.sh --dashu    # include dashu-float (FBig)
```