rival/
lib.rs

1//! # Rival 3: Real Computation via Interval Arithmetic
2//!
3//! Rival is an advanced interval arithmetic library for
4//! arbitrary-precision computation of complex mathematical expressions.
5//! Its interval arithmetic is valid and attempts to be tight.
6//! Besides the standard intervals, Rival also supports boolean intervals,
7//! error intervals, and movability flags, as described in
8//! ["An Interval Arithmetic for Robust Error Estimation"](https://arxiv.org/abs/2107.05784).
9//!
10//! Rival is a part of the [Herbie project](https://herbie.uwplse.org),
11//! and is developed [on Github](https://github.com/herbie-fp/rival3).
12//!
13//! # Real Computation
14//!
15//! Rival is built to evaluate real-number expressions to
16//! correctly-rounded floating-point outputs. To do so, you first compile
17//! your real-number expression to a [`Machine`] via [`MachineBuilder`],
18//! and then apply that machine to specific inputs.
19//!
20//! ```no_run
21//! use rival::{Expr, MachineBuilder, Ival};
22//! use rug::Float;
23//!
24//! struct Fp64Disc;
25//! impl rival::Discretization for Fp64Disc {
26//!     fn target(&self) -> u32 { 53 }
27//!     fn convert(&self, _: usize, v: &Float) -> Float { Float::with_val(53, v) }
28//!     fn distance(&self, _: usize, lo: &Float, hi: &Float) -> usize { 0 }
29//! }
30//! impl Clone for Fp64Disc { fn clone(&self) -> Self { Fp64Disc } }
31//! 
32//! let expr = Expr::Sub(
33//!     Box::new(Expr::Sin(Box::new(Expr::Var("x".into())))),
34//!     Box::new(Expr::Sub(
35//!         Box::new(Expr::Var("x".into())),
36//!         Box::new(Expr::Div(
37//!             Box::new(Expr::Pow(
38//!                 Box::new(Expr::Var("x".into())),
39//!                 Box::new(Expr::Literal(Float::with_val(53, 3))),
40//!             )),
41//!             Box::new(Expr::Literal(Float::with_val(53, 6))),
42//!         )),
43//!     )),
44//! );
45//!
46//! let machine = MachineBuilder::new(Fp64Disc).build(vec![expr], vec!["x".into()]);
47//! ```
48//!
49//! Rival works by evaluating the expression with high-precision interval
50//! arithmetic, repeating the evaluation with ever-higher precision until
51//! a narrow-enough output interval is found.
52//!
53//! Detailed profiling information can be accessed via [`Execution`].
54//!
55//! Rival also exposes the underlying interval-arithmetic library:
56//!
57//! ```
58//! use rival::Ival;
59//!
60//! let x = Ival::from_lo_hi(
61//!     rug::Float::with_val(20, 2),
62//!     rug::Float::with_val(20, 3),
63//! );
64//! let mut result = Ival::zero(20);
65//! result.sqrt_assign(&x);
66//! ```
67//!
68//! Rival is fast, accurate, and sound. We believe it to be a
69//! state-of-the-art implementation, competitive with Sollya/MPFI,
70//! Calcium/Arb, and Mathematica.
71
72mod eval;
73mod interval;
74mod mpfr;
75
76pub use eval::ast::Expr;
77pub use eval::machine::{Discretization, Hint, Machine, MachineBuilder};
78pub use eval::profile::Execution;
79pub use eval::run::RivalError;
80pub use interval::{ErrorFlags, Ival};
rival/lib.rs

rival/
lib.rs
