Arbitrary-precision numbers for Mojo¶

First program¶

After installing the package or a checkout, run this program from the directory containing pixi.toml. From a checkout:

pixi run --locked mojo run -I src docs/examples/quickstart.mojo

With the apn_mojo package installed, save it as quickstart.mojo and run pixi run mojo run quickstart.mojo, without -I src.

"""Exact integers and fractions, Floats of any precision and Complex numbers."""

from apn_mojo import ArithmeticContext, Complex, Float, FloatFormat, Integer, Rational, sqrt


def main() raises:
    # Integers and Rationals are exact: they grow instead of overflowing or rounding.
    print("2 ** 100 =", Integer(2) ** 100)
    print("1/3 + 1/6 =", Rational(1, 3) + Rational(1, 6))
    # A Float has the precision you choose and rounds each result once.
    var precise = ArithmeticContext(format=FloatFormat(256))
    var root = sqrt(Float(2, context=precise))
    print("sqrt(2) =", root.to_string(10, digits=60))
    # Decimal text is exact; a native Float64 brings its binary rounding error along.
    print("0.1 from text =", Float("0.1", context=precise).to_string(10, digits=60))
    print("0.1 as Float64 =", Float(Float64(0.1), context=precise).to_string(10, digits=60))
    # Complex numbers round each component once.
    var z = Complex("1+2j") * Complex("3-4j")
    print("(1+2j)(3-4j) =", String(z.real().to_integer_exact()) + "+" + String(z.imag().to_integer_exact()) + "j")
    var w = sqrt(Complex(-4))
    print("sqrt(-4) =", String(w.real().to_integer_exact()) + "+" + String(w.imag().to_integer_exact()) + "j")

2 ** 100 = 1267650600228229401496703205376
1/3 + 1/6 = 1/2
sqrt(2) = 1.41421356237309504880168872420969807856967187537694807317668
0.1 from text = 0.100000000000000000000000000000000000000000000000000000000000
0.1 as Float64 = 0.100000000000000005551115123125782702118158340454101562500000
(1+2j)(3-4j) = 11+2j
sqrt(-4) = 0+2j

The integers and fractions in this example stay exact as their storage grows. The Float calculation uses 256 bits of precision, so sqrt(2) returns the correctly rounded 256-bit approximation. Each operation has this rounding guarantee; a sequence of operations can still accumulate error.

Supply decimal values as text to avoid rounding them through a native float first. Rational("0.1") is exactly one tenth; Float("0.1") rounds one tenth to a binary approximation. Importing Float64(0.1) starts with the approximation already stored in the native float.

Number families¶

Integer and rational arithmetic stays exact: Integer + Rational returns a Rational. Mixing with a Float produces a rounded result. Named functions such as add and sqrt accept a context when the selected number family needs one. See the family references for accepted operands and return types.

Batches, mapping and reductions¶

Batch[T] holds Integer, Rational, Float, Complex, Ball, or ComplexBall values. Copies and slices keep their values when the original changes. Integer, rational, float, and complex batches provide arithmetic operators, comparisons, reductions, and JSON. Ball batches support NumPy-style functions such as batch.add and batch.exp, and mapping with vmap or lift. Real Ball batches support min and max; both ball families support cumsum and cumprod, but have no arithmetic operators or batch JSON. ExactComplex is a scalar type, with no batch support.

This example applies a scalar function to a batch, then reduces its results:

"""A first batch calculation with an explicit precision and a reduction."""

from apn_mojo import ArithmeticContext, Batch, FloatFormat, Integer, batch


def main() raises:
    var values = Batch[Integer]([1, 4, 9, 16])
    var context = ArithmeticContext(format=FloatFormat(256))
    var roots = batch.sqrt(values, context=context)
    print("roots:", roots)
    print("sum:", batch.sum(roots, context=context))

roots: [1.0, 2.0, 3.0, 4.0]
sum: 10.0

With vmap[f], you can apply library functions or your own scalar functions across batch arguments. lift[f] builds on binary functions for integers, rationals, floats, complex numbers, and balls. Large supported operations can use a worker pool; short runs and some mapping signatures run on the caller thread. The batch reference describes those rules.

For floating-point and complex totals, sum and dot keep intermediates exact and round only the final result. The reduction reference also covers explicit rounding orders, axes, contexts, and custom folds.

Find your starting point¶

See support and limitations for supported platforms and library boundaries.