Crate astro_float

Astro-float (astronomically large floating point numbers) is a library that implements arbitrary precision floating point numbers.

Introduction

Numbers

The number is defined by the data type BigFloat. Each finite number consists of an array of words representing the mantissa, exponent, and sign. BigFloat can also be Inf (positive infinity), -Inf (negative infinity) or NaN (not-a-number).

BigFloat creation operations take bit precision as an argument. Precision is always rounded up to the nearest word. For example, if you specify a precision of 1 bit, then it will be converted to 64 bits when one word has a size of 64 bits. If you specify a precision of 65 bits, the resulting precision will be 128 bits (2 words), and so on.

Most operations take the rounding mode as an argument. The operation will typically internally result in a number with more precision than necessary. Before the result is returned to the user, the result is rounded according to the rounding mode and reduced to the expected precision.

The result of an operation is marked as inexact if some of the bits were rounded when producing the result, or if any of the operation’s arguments were marked as inexact. The information about exactness is used to achieve correct rounding.

BigFloat can be parsed from a string and formatted into a string using binary, octal, decimal, or hexadecimal representation.

Numbers can be subnormal. Usually any number is normalized: the most significant bit of the mantissa is set to 1. If the result of the operation has the smallest possible exponent, then normalization cannot be performed, and some significant bits of the mantissa may become 0. This allows for a more gradual transition to zero.

Error handling

In case of an error, such as memory allocation error, BigFloat takes the value NaN. BigFloat::err() can be used to get the associated error in this situation.

Constants

Constants such as pi or the Euler number have arbitrary precision and are evaluated lazily and then cached in the constants cache. Some functions expect constants cache as parameter.

Correctness

Results of all arithmetic operations, mathematical functions, radix conversion, and constant values are correctly rounded (a correctly rounded number is a number that is identical to a number computed to infinite precision and then rounded, reflecting no information loss during rounding).

Examples

The example below computes value of Pi with precision 1024 rounded to the nearest even number using expr! macro. Macro simplifies syntax and takes care of the error.

use astro_float::Consts;
use astro_float::RoundingMode;
use astro_float::ctx::Context;
use astro_float::expr;

// Create a context with precision 1024, rounding to the nearest even,
// and exponent range from -100000 to 100000.
let mut ctx = Context::new(1024, RoundingMode::ToEven,
    Consts::new().expect("Constants cache initialized"),
    -100000, 100000);

// Compute pi: pi = 6*arctan(1/sqrt(3))
let pi = expr!(6 * atan(1 / sqrt(3)), &mut ctx);

// Use library's constant value for verifying the result.
let pi_lib = ctx.const_pi();

// Compare computed constant with library's constant
assert_eq!(pi.cmp(&pi_lib), Some(0));

// Print using decimal radix.
println!("{}", pi);

// output: 3.14159265358979323846264338327950288419716939937510582097494459230781640628620899862803482534211706798214808651328230664709384460955058223172535940812848111745028410270193852110555964462294895493038196442881097566593344612847564823378678316527120190914564856692346034861045432664821339360726024914127372458699748e+0

The example below computes value of Pi with precision 1024 rounded to the nearest even number using BigFloat directly. We will take care of the error in this case.

use astro_float::BigFloat;
use astro_float::Consts;
use astro_float::RoundingMode;

// Precision with some space for error.
let p = 1024 + 8;

// The results of computations will not be rounded.
// That will be more performant, even though it may give an incorrectly rounded result.
let rm = RoundingMode::None;

// Initialize mathematical constants cache
let mut cc = Consts::new().expect("An error occured when initializing constants");

// Compute pi: pi = 6*arctan(1/sqrt(3))
let six = BigFloat::from_word(6, 1);
let three = BigFloat::from_word(3, p);

let n = three.sqrt(p, rm);
let n = n.reciprocal(p, rm);
let n = n.atan(p, rm, &mut cc);
let mut pi = six.mul(&n, p, rm);

// Reduce precision to 1024 and round to the nearest even number.
pi.set_precision(1024, RoundingMode::ToEven).expect("Precision updated");

// Use library's constant for verifying the result
let pi_lib = cc.pi(1024, RoundingMode::ToEven);

// Compare computed constant with library's constant
assert_eq!(pi.cmp(&pi_lib), Some(0));

// Print using decimal radix.
println!("{}", pi);

// output: 3.14159265358979323846264338327950288419716939937510582097494459230781640628620899862803482534211706798214808651328230664709384460955058223172535940812848111745028410270193852110555964462294895493038196442881097566593344612847564823378678316527120190914564856692346034861045432664821339360726024914127372458699748e+0

Performance recommendations

When small error is acceptable because of rounding it is recommended to do all computations with RoundingMode::None, and use BigFloat::set_precision or BigFloat::round with a specific rounding mode just once for the final result.

no_std

The library can work without the standard library provided there is a memory allocator. The standard library dependency is activated by the feature std. The feature std is active by default and must be excluded when specifying dependency, e.g.:

[dependencies]
astro-float = { version = "0.9.2", default-features = false }

Modules

• ctx
  Context is used in expressions returning BigFloat.

Macros

• expr
  Computes an expression with the specified precision and rounding mode.

Structs

• BigFloat
  A floating point number of arbitrary precision.
• Consts
  Constants cache contains arbitrary-precision mathematical constants.

Enums

• Error
  Possible errors.
• Radix
  Radix.
• RoundingMode
  Rounding modes.
• Sign
  Sign.

Constants

• EXPONENT_BIT_SIZE
  The size of exponent type in bits.
• EXPONENT_MAX
  Maximum exponent value.
• EXPONENT_MIN
  Minimum exponent value.
• INF_NEG
  Negative infinity.
• INF_POS
  Positive infinity.
• NAN
  Not a number.
• WORD_BASE
  Base of words.
• WORD_BIT_SIZE
  Size of a word in bits.
• WORD_MAX
  Maximum value of a word.
• WORD_SIGNIFICANT_BIT
  Word with the most significant bit set.

Traits

• FromExt
  A trait for conversion with additional arguments.

Type Aliases

• Exponent
  An exponent.
• Word
  A word.