Skip to content

README.md

Latest commit

 

History

History
69 lines (51 loc) · 2.61 KB

README.md

File metadata and controls

69 lines (51 loc) · 2.61 KB
Raw

Rational

Rational is the exact arithmetic base for hyperreal.

Representation

Rational stores:

  • a num::bigint::Sign
  • a non-negative BigUint numerator
  • a non-zero BigUint denominator

Zero is canonicalized as NoSign, numerator 0, denominator 1. Non-zero values are reduced when constructors or operations require canonical form.

Module map

  • mod.rs: public module export.
  • arithmetic.rs: representation, constructors, arithmetic, reduction, structural predicates, exact product sums, and tests.
  • convert.rs: primitive integer and floating-point conversions.
  • parse.rs: exact text parsing for integers, decimals, and fractions.

API expectations

  • Rational::new builds exact integers.
  • Rational::fraction validates the denominator and reduces exactly.
  • finite f32/f64 imports decode the IEEE-754 value exactly, including values like 0.3 that are not decimal 3/10.
  • NaN and infinities are rejected.
  • text decimals and fractions parse as exact rationals; scientific notation is not the exact text format.
  • -0.0 imports as canonical rational zero, so IEEE signed zero is not preserved.

Performance expectations

The hot path avoids generic BigInt work where the representation already has the needed facts:

  • signs are stored separately from magnitudes
  • dyadic denominators reduce by shifts instead of full GCDs
  • exact dot products and signed product sums build shared denominators and reduce once at the end
  • product-sum signs are computed once and reused across reducer stages
  • all-zero and single-term sums exit before denominator construction

These optimizations support the higher-level Real and hyperlattice matrix/vector kernels, where repeated rational reduction can dominate runtime.

Numerical explosion controls

Rational is the first line of defense against exact-value growth:

  • canonical zero and separate sign storage keep common identities small
  • finite float imports become exact dyadics, preserving shift-only denominator reduction where possible
  • shared-denominator dot products and signed product sums accumulate related terms before the final reduction
  • all-zero and single-term exits avoid building denominators that will be discarded immediately
  • reducers should use already-known signs, zero checks, and denominator facts instead of re-querying scalar properties inside hot accumulation loops

Error expectations

Rational reports divide-by-zero construction or inversion through Problem. Ordinary arithmetic on valid rationals is exact and total except for operations that explicitly require a non-zero denominator or divisor.