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.

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 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 — what the crate does and does not do
• Getting started
• Help — recipes, mistakes, FAQ
• Library — public API
• expr! rounding
• Precision
• Reproducibility
• Contributing
• rustdoc: https://docs.rs/zenith-float

Features

std is on by default (formatting and FromStr):

[dependencies]
zenith-float = "1.0"

no_std (allocator required):

[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

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 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:

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

Benchmarks (Criterion, release profile, deterministic fixtures):

./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):

./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)