Struct RnsRational 

pub struct RnsRational {
    pub numer: RnsInt,
    pub denom: RnsInt,
    pub channels: Channels,
    /* private fields */
}

An exact rational number represented over RNS channels.

The canonical value is held as a reduced BigInt pair (p, q) so that precision is never capped by the channel capacity — essential for the arbitrary-precision rationals produced at Level 3. The numer/denom RnsInt fields are the RNS view of that value (exact while the value fits inside the channel capacity), kept for the lower-level channel-dispatch machinery.

Fields

numer: RnsInt

RNS view of the numerator.

denom: RnsInt

RNS view of the denominator.

channels: Channels

Implementations

impl RnsRational

pub fn new(p: BigInt, q: BigInt, channels: Channels) -> Self

Build from a p/q pair, normalizing the sign and reducing by the GCD.

Panics if q == 0.

pub fn from_fraction(p: i64, q: i64, channels: Channels) -> Self

Convenience constructor from machine integers.

Examples found in repository

examples/float_comparison.rs (line 32)

fn main() {
    let ch = Channels::standard(32);
    println!("== adele-ring :: exact vs f64 ==\n");
    println!(
        "{:<16} | {:<10} | {:<22} | {:<12} | ULPs",
        "expression", "exact", "f64 result", "abs error"
    );
    println!("{}", "-".repeat(78));

    // 0.1 + 0.2 = 3/10
    let exact = RnsRational::from_fraction(1, 10, ch.clone())
        .add(&RnsRational::from_fraction(1, 5, ch.clone()));
    row("0.1 + 0.2", &exact.display(), 0.1 + 0.2, exact.to_f64());

    // 1/3 * 3 = 1
    let one = RnsRational::from_fraction(1, 3, ch.clone()).mul(&RnsRational::from_int(3, ch.clone()));
    row("1/3 * 3", &one.display(), (1.0 / 3.0) * 3.0, one.to_f64());

    // sqrt(2) * sqrt(2) = 2  (drops to Integer through the tower)
    let s2 = TowerValue::Algebraic(AlgebraicNumber::sqrt(2, ch.clone()));
    let two = s2.mul(&s2);
    let naive = 2f64.sqrt() * 2f64.sqrt();
    row("sqrt2 * sqrt2", "2", naive, two.to_f64().unwrap());

    // sin(pi) = 0  (exact identity; f64 gives ~1.2e-16)
    let sin_pi = TowerValue::Symbolic(SymbolicExpr::Pi).sin();
    row("sin(pi)", "0", std::f64::consts::PI.sin(), sin_pi.to_f64().unwrap());

    // 1/7 * 7 = 1
    let one7 = RnsRational::from_fraction(1, 7, ch.clone()).mul(&RnsRational::from_int(7, ch));
    row("1/7 * 7", &one7.display(), (1.0 / 7.0) * 7.0, one7.to_f64());

    println!("\nEvery `exact` column is bit-for-bit correct; the f64 column drifts.");
}

examples/engineering.rs (line 9)

fn main() {
    let ch = Channels::standard(32);
    let f = |p: i64, q: i64| RnsRational::from_fraction(p, q, ch.clone());

    println!("== adele-ring :: exact engineering arithmetic ==\n");

    // Stacked plate thicknesses in inches: 3/8 + 1/4 + 5/16.
    let stack = f(3, 8).add(&f(1, 4)).add(&f(5, 16));
    println!("3/8 + 1/4 + 5/16 in   = {} in   (= {:.6} in)", stack, stack.to_f64());

    // Safety factor 1/1.5 = 2/3 exactly.
    let safety = f(1, 1).div(&f(3, 2));
    println!("1 / 1.5               = {}        (= {:.6})", safety, safety.to_f64());

    // Load ratio: 47 kips / 70 kips — stays exact through combination checks.
    let load_ratio = f(47, 70);
    let with_margin = load_ratio.add(&f(1, 10)); // add a 0.1 utilization margin
    println!(
        "47/70 + 1/10          = {}    (= {:.6})",
        with_margin,
        with_margin.to_f64()
    );

    // AISC-style web area: t_w * d  =  (5/16) * (24/1) in^2.
    let t_w = f(5, 16);
    let d = f(24, 1);
    let web_area = t_w.mul(&d);
    println!("(5/16) * 24           = {} in^2   (= {:.6} in^2)", web_area, web_area.to_f64());

    println!("\n-- base awareness --");
    for (p, q) in [(1, 6), (1, 8), (47, 70)] {
        let r = f(p, q);
        println!(
            "{p}/{q}: natural base = {}, terminates in base 10 = {}, period in base 10 = {}",
            r.natural_base(),
            r.exact_in_base(10),
            r.termination_period_in_base(10)
        );
    }

    // Demonstrate the classic float failure that adele-ring avoids.
    let exact = f(1, 10).add(&f(1, 5)); // 0.1 + 0.2
    let naive = 0.1_f64 + 0.2_f64;
    println!("\n0.1 + 0.2 exact       = {}   (f64 gives {:.17})", exact, naive);
    assert_eq!(exact, f(3, 10));
}

pub fn from_int(n: i64, channels: Channels) -> Self

An integer rational n/1.

Examples found in repository

examples/float_comparison.rs (line 37)

fn main() {
    let ch = Channels::standard(32);
    println!("== adele-ring :: exact vs f64 ==\n");
    println!(
        "{:<16} | {:<10} | {:<22} | {:<12} | ULPs",
        "expression", "exact", "f64 result", "abs error"
    );
    println!("{}", "-".repeat(78));

    // 0.1 + 0.2 = 3/10
    let exact = RnsRational::from_fraction(1, 10, ch.clone())
        .add(&RnsRational::from_fraction(1, 5, ch.clone()));
    row("0.1 + 0.2", &exact.display(), 0.1 + 0.2, exact.to_f64());

    // 1/3 * 3 = 1
    let one = RnsRational::from_fraction(1, 3, ch.clone()).mul(&RnsRational::from_int(3, ch.clone()));
    row("1/3 * 3", &one.display(), (1.0 / 3.0) * 3.0, one.to_f64());

    // sqrt(2) * sqrt(2) = 2  (drops to Integer through the tower)
    let s2 = TowerValue::Algebraic(AlgebraicNumber::sqrt(2, ch.clone()));
    let two = s2.mul(&s2);
    let naive = 2f64.sqrt() * 2f64.sqrt();
    row("sqrt2 * sqrt2", "2", naive, two.to_f64().unwrap());

    // sin(pi) = 0  (exact identity; f64 gives ~1.2e-16)
    let sin_pi = TowerValue::Symbolic(SymbolicExpr::Pi).sin();
    row("sin(pi)", "0", std::f64::consts::PI.sin(), sin_pi.to_f64().unwrap());

    // 1/7 * 7 = 1
    let one7 = RnsRational::from_fraction(1, 7, ch.clone()).mul(&RnsRational::from_int(7, ch));
    row("1/7 * 7", &one7.display(), (1.0 / 7.0) * 7.0, one7.to_f64());

    println!("\nEvery `exact` column is bit-for-bit correct; the f64 column drifts.");
}

pub fn zero(channels: Channels) -> Self

Zero.

pub fn to_pair(&self) -> (BigInt, BigInt)

The reduced (p, q) pair as BigInts (exact, never capacity-bounded).

pub fn is_zero(&self) -> bool

true iff the value is zero.

pub fn is_integer(&self) -> bool

true iff the denominator is 1 (the value is an integer).

pub fn add(&self, other: &Self) -> Self

p1/q1 + p2/q2 = (p1·q2 + p2·q1) / (q1·q2).

Examples found in repository

examples/float_comparison.rs (line 33)

fn main() {
    let ch = Channels::standard(32);
    println!("== adele-ring :: exact vs f64 ==\n");
    println!(
        "{:<16} | {:<10} | {:<22} | {:<12} | ULPs",
        "expression", "exact", "f64 result", "abs error"
    );
    println!("{}", "-".repeat(78));

    // 0.1 + 0.2 = 3/10
    let exact = RnsRational::from_fraction(1, 10, ch.clone())
        .add(&RnsRational::from_fraction(1, 5, ch.clone()));
    row("0.1 + 0.2", &exact.display(), 0.1 + 0.2, exact.to_f64());

    // 1/3 * 3 = 1
    let one = RnsRational::from_fraction(1, 3, ch.clone()).mul(&RnsRational::from_int(3, ch.clone()));
    row("1/3 * 3", &one.display(), (1.0 / 3.0) * 3.0, one.to_f64());

    // sqrt(2) * sqrt(2) = 2  (drops to Integer through the tower)
    let s2 = TowerValue::Algebraic(AlgebraicNumber::sqrt(2, ch.clone()));
    let two = s2.mul(&s2);
    let naive = 2f64.sqrt() * 2f64.sqrt();
    row("sqrt2 * sqrt2", "2", naive, two.to_f64().unwrap());

    // sin(pi) = 0  (exact identity; f64 gives ~1.2e-16)
    let sin_pi = TowerValue::Symbolic(SymbolicExpr::Pi).sin();
    row("sin(pi)", "0", std::f64::consts::PI.sin(), sin_pi.to_f64().unwrap());

    // 1/7 * 7 = 1
    let one7 = RnsRational::from_fraction(1, 7, ch.clone()).mul(&RnsRational::from_int(7, ch));
    row("1/7 * 7", &one7.display(), (1.0 / 7.0) * 7.0, one7.to_f64());

    println!("\nEvery `exact` column is bit-for-bit correct; the f64 column drifts.");
}

examples/engineering.rs (line 14)

fn main() {
    let ch = Channels::standard(32);
    let f = |p: i64, q: i64| RnsRational::from_fraction(p, q, ch.clone());

    println!("== adele-ring :: exact engineering arithmetic ==\n");

    // Stacked plate thicknesses in inches: 3/8 + 1/4 + 5/16.
    let stack = f(3, 8).add(&f(1, 4)).add(&f(5, 16));
    println!("3/8 + 1/4 + 5/16 in   = {} in   (= {:.6} in)", stack, stack.to_f64());

    // Safety factor 1/1.5 = 2/3 exactly.
    let safety = f(1, 1).div(&f(3, 2));
    println!("1 / 1.5               = {}        (= {:.6})", safety, safety.to_f64());

    // Load ratio: 47 kips / 70 kips — stays exact through combination checks.
    let load_ratio = f(47, 70);
    let with_margin = load_ratio.add(&f(1, 10)); // add a 0.1 utilization margin
    println!(
        "47/70 + 1/10          = {}    (= {:.6})",
        with_margin,
        with_margin.to_f64()
    );

    // AISC-style web area: t_w * d  =  (5/16) * (24/1) in^2.
    let t_w = f(5, 16);
    let d = f(24, 1);
    let web_area = t_w.mul(&d);
    println!("(5/16) * 24           = {} in^2   (= {:.6} in^2)", web_area, web_area.to_f64());

    println!("\n-- base awareness --");
    for (p, q) in [(1, 6), (1, 8), (47, 70)] {
        let r = f(p, q);
        println!(
            "{p}/{q}: natural base = {}, terminates in base 10 = {}, period in base 10 = {}",
            r.natural_base(),
            r.exact_in_base(10),
            r.termination_period_in_base(10)
        );
    }

    // Demonstrate the classic float failure that adele-ring avoids.
    let exact = f(1, 10).add(&f(1, 5)); // 0.1 + 0.2
    let naive = 0.1_f64 + 0.2_f64;
    println!("\n0.1 + 0.2 exact       = {}   (f64 gives {:.17})", exact, naive);
    assert_eq!(exact, f(3, 10));
}

pub fn sub(&self, other: &Self) -> Self

Subtraction.

pub fn mul(&self, other: &Self) -> Self

Multiplication.

Examples found in repository

examples/float_comparison.rs (line 37)

fn main() {
    let ch = Channels::standard(32);
    println!("== adele-ring :: exact vs f64 ==\n");
    println!(
        "{:<16} | {:<10} | {:<22} | {:<12} | ULPs",
        "expression", "exact", "f64 result", "abs error"
    );
    println!("{}", "-".repeat(78));

    // 0.1 + 0.2 = 3/10
    let exact = RnsRational::from_fraction(1, 10, ch.clone())
        .add(&RnsRational::from_fraction(1, 5, ch.clone()));
    row("0.1 + 0.2", &exact.display(), 0.1 + 0.2, exact.to_f64());

    // 1/3 * 3 = 1
    let one = RnsRational::from_fraction(1, 3, ch.clone()).mul(&RnsRational::from_int(3, ch.clone()));
    row("1/3 * 3", &one.display(), (1.0 / 3.0) * 3.0, one.to_f64());

    // sqrt(2) * sqrt(2) = 2  (drops to Integer through the tower)
    let s2 = TowerValue::Algebraic(AlgebraicNumber::sqrt(2, ch.clone()));
    let two = s2.mul(&s2);
    let naive = 2f64.sqrt() * 2f64.sqrt();
    row("sqrt2 * sqrt2", "2", naive, two.to_f64().unwrap());

    // sin(pi) = 0  (exact identity; f64 gives ~1.2e-16)
    let sin_pi = TowerValue::Symbolic(SymbolicExpr::Pi).sin();
    row("sin(pi)", "0", std::f64::consts::PI.sin(), sin_pi.to_f64().unwrap());

    // 1/7 * 7 = 1
    let one7 = RnsRational::from_fraction(1, 7, ch.clone()).mul(&RnsRational::from_int(7, ch));
    row("1/7 * 7", &one7.display(), (1.0 / 7.0) * 7.0, one7.to_f64());

    println!("\nEvery `exact` column is bit-for-bit correct; the f64 column drifts.");
}

examples/engineering.rs (line 33)

fn main() {
    let ch = Channels::standard(32);
    let f = |p: i64, q: i64| RnsRational::from_fraction(p, q, ch.clone());

    println!("== adele-ring :: exact engineering arithmetic ==\n");

    // Stacked plate thicknesses in inches: 3/8 + 1/4 + 5/16.
    let stack = f(3, 8).add(&f(1, 4)).add(&f(5, 16));
    println!("3/8 + 1/4 + 5/16 in   = {} in   (= {:.6} in)", stack, stack.to_f64());

    // Safety factor 1/1.5 = 2/3 exactly.
    let safety = f(1, 1).div(&f(3, 2));
    println!("1 / 1.5               = {}        (= {:.6})", safety, safety.to_f64());

    // Load ratio: 47 kips / 70 kips — stays exact through combination checks.
    let load_ratio = f(47, 70);
    let with_margin = load_ratio.add(&f(1, 10)); // add a 0.1 utilization margin
    println!(
        "47/70 + 1/10          = {}    (= {:.6})",
        with_margin,
        with_margin.to_f64()
    );

    // AISC-style web area: t_w * d  =  (5/16) * (24/1) in^2.
    let t_w = f(5, 16);
    let d = f(24, 1);
    let web_area = t_w.mul(&d);
    println!("(5/16) * 24           = {} in^2   (= {:.6} in^2)", web_area, web_area.to_f64());

    println!("\n-- base awareness --");
    for (p, q) in [(1, 6), (1, 8), (47, 70)] {
        let r = f(p, q);
        println!(
            "{p}/{q}: natural base = {}, terminates in base 10 = {}, period in base 10 = {}",
            r.natural_base(),
            r.exact_in_base(10),
            r.termination_period_in_base(10)
        );
    }

    // Demonstrate the classic float failure that adele-ring avoids.
    let exact = f(1, 10).add(&f(1, 5)); // 0.1 + 0.2
    let naive = 0.1_f64 + 0.2_f64;
    println!("\n0.1 + 0.2 exact       = {}   (f64 gives {:.17})", exact, naive);
    assert_eq!(exact, f(3, 10));
}

pub fn div(&self, other: &Self) -> Self

Division. Panics if other is zero.

Examples found in repository

examples/engineering.rs (line 18)

fn main() {
    let ch = Channels::standard(32);
    let f = |p: i64, q: i64| RnsRational::from_fraction(p, q, ch.clone());

    println!("== adele-ring :: exact engineering arithmetic ==\n");

    // Stacked plate thicknesses in inches: 3/8 + 1/4 + 5/16.
    let stack = f(3, 8).add(&f(1, 4)).add(&f(5, 16));
    println!("3/8 + 1/4 + 5/16 in   = {} in   (= {:.6} in)", stack, stack.to_f64());

    // Safety factor 1/1.5 = 2/3 exactly.
    let safety = f(1, 1).div(&f(3, 2));
    println!("1 / 1.5               = {}        (= {:.6})", safety, safety.to_f64());

    // Load ratio: 47 kips / 70 kips — stays exact through combination checks.
    let load_ratio = f(47, 70);
    let with_margin = load_ratio.add(&f(1, 10)); // add a 0.1 utilization margin
    println!(
        "47/70 + 1/10          = {}    (= {:.6})",
        with_margin,
        with_margin.to_f64()
    );

    // AISC-style web area: t_w * d  =  (5/16) * (24/1) in^2.
    let t_w = f(5, 16);
    let d = f(24, 1);
    let web_area = t_w.mul(&d);
    println!("(5/16) * 24           = {} in^2   (= {:.6} in^2)", web_area, web_area.to_f64());

    println!("\n-- base awareness --");
    for (p, q) in [(1, 6), (1, 8), (47, 70)] {
        let r = f(p, q);
        println!(
            "{p}/{q}: natural base = {}, terminates in base 10 = {}, period in base 10 = {}",
            r.natural_base(),
            r.exact_in_base(10),
            r.termination_period_in_base(10)
        );
    }

    // Demonstrate the classic float failure that adele-ring avoids.
    let exact = f(1, 10).add(&f(1, 5)); // 0.1 + 0.2
    let naive = 0.1_f64 + 0.2_f64;
    println!("\n0.1 + 0.2 exact       = {}   (f64 gives {:.17})", exact, naive);
    assert_eq!(exact, f(3, 10));
}

pub fn neg(&self) -> Self

Additive inverse.

pub fn recip(&self) -> Self

Multiplicative inverse. Panics if zero.

pub fn denom_prime_signature(&self) -> Vec<u64>

The distinct primes appearing in the reduced denominator.

pub fn exact_in_base(&self, base: u64) -> bool

true iff this fraction has a terminating expansion in base, i.e. every prime in the denominator divides base.

Examples found in repository

examples/engineering.rs (line 42)

fn main() {
    let ch = Channels::standard(32);
    let f = |p: i64, q: i64| RnsRational::from_fraction(p, q, ch.clone());

    println!("== adele-ring :: exact engineering arithmetic ==\n");

    // Stacked plate thicknesses in inches: 3/8 + 1/4 + 5/16.
    let stack = f(3, 8).add(&f(1, 4)).add(&f(5, 16));
    println!("3/8 + 1/4 + 5/16 in   = {} in   (= {:.6} in)", stack, stack.to_f64());

    // Safety factor 1/1.5 = 2/3 exactly.
    let safety = f(1, 1).div(&f(3, 2));
    println!("1 / 1.5               = {}        (= {:.6})", safety, safety.to_f64());

    // Load ratio: 47 kips / 70 kips — stays exact through combination checks.
    let load_ratio = f(47, 70);
    let with_margin = load_ratio.add(&f(1, 10)); // add a 0.1 utilization margin
    println!(
        "47/70 + 1/10          = {}    (= {:.6})",
        with_margin,
        with_margin.to_f64()
    );

    // AISC-style web area: t_w * d  =  (5/16) * (24/1) in^2.
    let t_w = f(5, 16);
    let d = f(24, 1);
    let web_area = t_w.mul(&d);
    println!("(5/16) * 24           = {} in^2   (= {:.6} in^2)", web_area, web_area.to_f64());

    println!("\n-- base awareness --");
    for (p, q) in [(1, 6), (1, 8), (47, 70)] {
        let r = f(p, q);
        println!(
            "{p}/{q}: natural base = {}, terminates in base 10 = {}, period in base 10 = {}",
            r.natural_base(),
            r.exact_in_base(10),
            r.termination_period_in_base(10)
        );
    }

    // Demonstrate the classic float failure that adele-ring avoids.
    let exact = f(1, 10).add(&f(1, 5)); // 0.1 + 0.2
    let naive = 0.1_f64 + 0.2_f64;
    println!("\n0.1 + 0.2 exact       = {}   (f64 gives {:.17})", exact, naive);
    assert_eq!(exact, f(3, 10));
}

pub fn natural_base(&self) -> u64

Minimal base for an exact (terminating) representation = radical(denom).

Examples found in repository

examples/engineering.rs (line 41)

fn main() {
    let ch = Channels::standard(32);
    let f = |p: i64, q: i64| RnsRational::from_fraction(p, q, ch.clone());

    println!("== adele-ring :: exact engineering arithmetic ==\n");

    // Stacked plate thicknesses in inches: 3/8 + 1/4 + 5/16.
    let stack = f(3, 8).add(&f(1, 4)).add(&f(5, 16));
    println!("3/8 + 1/4 + 5/16 in   = {} in   (= {:.6} in)", stack, stack.to_f64());

    // Safety factor 1/1.5 = 2/3 exactly.
    let safety = f(1, 1).div(&f(3, 2));
    println!("1 / 1.5               = {}        (= {:.6})", safety, safety.to_f64());

    // Load ratio: 47 kips / 70 kips — stays exact through combination checks.
    let load_ratio = f(47, 70);
    let with_margin = load_ratio.add(&f(1, 10)); // add a 0.1 utilization margin
    println!(
        "47/70 + 1/10          = {}    (= {:.6})",
        with_margin,
        with_margin.to_f64()
    );

    // AISC-style web area: t_w * d  =  (5/16) * (24/1) in^2.
    let t_w = f(5, 16);
    let d = f(24, 1);
    let web_area = t_w.mul(&d);
    println!("(5/16) * 24           = {} in^2   (= {:.6} in^2)", web_area, web_area.to_f64());

    println!("\n-- base awareness --");
    for (p, q) in [(1, 6), (1, 8), (47, 70)] {
        let r = f(p, q);
        println!(
            "{p}/{q}: natural base = {}, terminates in base 10 = {}, period in base 10 = {}",
            r.natural_base(),
            r.exact_in_base(10),
            r.termination_period_in_base(10)
        );
    }

    // Demonstrate the classic float failure that adele-ring avoids.
    let exact = f(1, 10).add(&f(1, 5)); // 0.1 + 0.2
    let naive = 0.1_f64 + 0.2_f64;
    println!("\n0.1 + 0.2 exact       = {}   (f64 gives {:.17})", exact, naive);
    assert_eq!(exact, f(3, 10));
}

pub fn termination_period_in_base(&self, base: u64) -> u64

Repeating period in base: 0 if it terminates, else the period length.

Examples found in repository

examples/engineering.rs (line 43)

fn main() {
    let ch = Channels::standard(32);
    let f = |p: i64, q: i64| RnsRational::from_fraction(p, q, ch.clone());

    println!("== adele-ring :: exact engineering arithmetic ==\n");

    // Stacked plate thicknesses in inches: 3/8 + 1/4 + 5/16.
    let stack = f(3, 8).add(&f(1, 4)).add(&f(5, 16));
    println!("3/8 + 1/4 + 5/16 in   = {} in   (= {:.6} in)", stack, stack.to_f64());

    // Safety factor 1/1.5 = 2/3 exactly.
    let safety = f(1, 1).div(&f(3, 2));
    println!("1 / 1.5               = {}        (= {:.6})", safety, safety.to_f64());

    // Load ratio: 47 kips / 70 kips — stays exact through combination checks.
    let load_ratio = f(47, 70);
    let with_margin = load_ratio.add(&f(1, 10)); // add a 0.1 utilization margin
    println!(
        "47/70 + 1/10          = {}    (= {:.6})",
        with_margin,
        with_margin.to_f64()
    );

    // AISC-style web area: t_w * d  =  (5/16) * (24/1) in^2.
    let t_w = f(5, 16);
    let d = f(24, 1);
    let web_area = t_w.mul(&d);
    println!("(5/16) * 24           = {} in^2   (= {:.6} in^2)", web_area, web_area.to_f64());

    println!("\n-- base awareness --");
    for (p, q) in [(1, 6), (1, 8), (47, 70)] {
        let r = f(p, q);
        println!(
            "{p}/{q}: natural base = {}, terminates in base 10 = {}, period in base 10 = {}",
            r.natural_base(),
            r.exact_in_base(10),
            r.termination_period_in_base(10)
        );
    }

    // Demonstrate the classic float failure that adele-ring avoids.
    let exact = f(1, 10).add(&f(1, 5)); // 0.1 + 0.2
    let naive = 0.1_f64 + 0.2_f64;
    println!("\n0.1 + 0.2 exact       = {}   (f64 gives {:.17})", exact, naive);
    assert_eq!(exact, f(3, 10));
}

pub fn to_f64(&self) -> f64

Lossy f64 approximation.

Computed via bit-shift scaling so it stays finite even when the numerator and denominator are far too large to fit in an f64 individually.

Examples found in repository

examples/float_comparison.rs (line 34)

fn main() {
    let ch = Channels::standard(32);
    println!("== adele-ring :: exact vs f64 ==\n");
    println!(
        "{:<16} | {:<10} | {:<22} | {:<12} | ULPs",
        "expression", "exact", "f64 result", "abs error"
    );
    println!("{}", "-".repeat(78));

    // 0.1 + 0.2 = 3/10
    let exact = RnsRational::from_fraction(1, 10, ch.clone())
        .add(&RnsRational::from_fraction(1, 5, ch.clone()));
    row("0.1 + 0.2", &exact.display(), 0.1 + 0.2, exact.to_f64());

    // 1/3 * 3 = 1
    let one = RnsRational::from_fraction(1, 3, ch.clone()).mul(&RnsRational::from_int(3, ch.clone()));
    row("1/3 * 3", &one.display(), (1.0 / 3.0) * 3.0, one.to_f64());

    // sqrt(2) * sqrt(2) = 2  (drops to Integer through the tower)
    let s2 = TowerValue::Algebraic(AlgebraicNumber::sqrt(2, ch.clone()));
    let two = s2.mul(&s2);
    let naive = 2f64.sqrt() * 2f64.sqrt();
    row("sqrt2 * sqrt2", "2", naive, two.to_f64().unwrap());

    // sin(pi) = 0  (exact identity; f64 gives ~1.2e-16)
    let sin_pi = TowerValue::Symbolic(SymbolicExpr::Pi).sin();
    row("sin(pi)", "0", std::f64::consts::PI.sin(), sin_pi.to_f64().unwrap());

    // 1/7 * 7 = 1
    let one7 = RnsRational::from_fraction(1, 7, ch.clone()).mul(&RnsRational::from_int(7, ch));
    row("1/7 * 7", &one7.display(), (1.0 / 7.0) * 7.0, one7.to_f64());

    println!("\nEvery `exact` column is bit-for-bit correct; the f64 column drifts.");
}

examples/engineering.rs (line 15)

fn main() {
    let ch = Channels::standard(32);
    let f = |p: i64, q: i64| RnsRational::from_fraction(p, q, ch.clone());

    println!("== adele-ring :: exact engineering arithmetic ==\n");

    // Stacked plate thicknesses in inches: 3/8 + 1/4 + 5/16.
    let stack = f(3, 8).add(&f(1, 4)).add(&f(5, 16));
    println!("3/8 + 1/4 + 5/16 in   = {} in   (= {:.6} in)", stack, stack.to_f64());

    // Safety factor 1/1.5 = 2/3 exactly.
    let safety = f(1, 1).div(&f(3, 2));
    println!("1 / 1.5               = {}        (= {:.6})", safety, safety.to_f64());

    // Load ratio: 47 kips / 70 kips — stays exact through combination checks.
    let load_ratio = f(47, 70);
    let with_margin = load_ratio.add(&f(1, 10)); // add a 0.1 utilization margin
    println!(
        "47/70 + 1/10          = {}    (= {:.6})",
        with_margin,
        with_margin.to_f64()
    );

    // AISC-style web area: t_w * d  =  (5/16) * (24/1) in^2.
    let t_w = f(5, 16);
    let d = f(24, 1);
    let web_area = t_w.mul(&d);
    println!("(5/16) * 24           = {} in^2   (= {:.6} in^2)", web_area, web_area.to_f64());

    println!("\n-- base awareness --");
    for (p, q) in [(1, 6), (1, 8), (47, 70)] {
        let r = f(p, q);
        println!(
            "{p}/{q}: natural base = {}, terminates in base 10 = {}, period in base 10 = {}",
            r.natural_base(),
            r.exact_in_base(10),
            r.termination_period_in_base(10)
        );
    }

    // Demonstrate the classic float failure that adele-ring avoids.
    let exact = f(1, 10).add(&f(1, 5)); // 0.1 + 0.2
    let naive = 0.1_f64 + 0.2_f64;
    println!("\n0.1 + 0.2 exact       = {}   (f64 gives {:.17})", exact, naive);
    assert_eq!(exact, f(3, 10));
}

pub fn from_f64(x: f64, channels: Channels) -> Self

Exact dyadic rational equal to a finite f64.

pub fn to_f64_with_error(&self) -> (f64, RnsRational)

f64 approximation together with the exact representation error self - f64(self) as an RnsRational.

pub fn signum(&self) -> i32

Sign of the value: -1, 0, or +1.

pub fn abs(&self) -> Self

Absolute value.

pub fn midpoint(&self, other: &Self) -> Self

Midpoint (self + other) / 2.

pub fn display(&self) -> String

Human-readable form: "3/7", or just "5" when the denominator is 1.

Examples found in repository

examples/float_comparison.rs (line 34)

fn main() {
    let ch = Channels::standard(32);
    println!("== adele-ring :: exact vs f64 ==\n");
    println!(
        "{:<16} | {:<10} | {:<22} | {:<12} | ULPs",
        "expression", "exact", "f64 result", "abs error"
    );
    println!("{}", "-".repeat(78));

    // 0.1 + 0.2 = 3/10
    let exact = RnsRational::from_fraction(1, 10, ch.clone())
        .add(&RnsRational::from_fraction(1, 5, ch.clone()));
    row("0.1 + 0.2", &exact.display(), 0.1 + 0.2, exact.to_f64());

    // 1/3 * 3 = 1
    let one = RnsRational::from_fraction(1, 3, ch.clone()).mul(&RnsRational::from_int(3, ch.clone()));
    row("1/3 * 3", &one.display(), (1.0 / 3.0) * 3.0, one.to_f64());

    // sqrt(2) * sqrt(2) = 2  (drops to Integer through the tower)
    let s2 = TowerValue::Algebraic(AlgebraicNumber::sqrt(2, ch.clone()));
    let two = s2.mul(&s2);
    let naive = 2f64.sqrt() * 2f64.sqrt();
    row("sqrt2 * sqrt2", "2", naive, two.to_f64().unwrap());

    // sin(pi) = 0  (exact identity; f64 gives ~1.2e-16)
    let sin_pi = TowerValue::Symbolic(SymbolicExpr::Pi).sin();
    row("sin(pi)", "0", std::f64::consts::PI.sin(), sin_pi.to_f64().unwrap());

    // 1/7 * 7 = 1
    let one7 = RnsRational::from_fraction(1, 7, ch.clone()).mul(&RnsRational::from_int(7, ch));
    row("1/7 * 7", &one7.display(), (1.0 / 7.0) * 7.0, one7.to_f64());

    println!("\nEvery `exact` column is bit-for-bit correct; the f64 column drifts.");
}

Trait Implementations

impl Clone for RnsRational

fn clone(&self) -> RnsRational

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RnsRational

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for RnsRational

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for RnsRational

impl Ord for RnsRational

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for RnsRational

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for RnsRational

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.