Float

Symbolica documentation for getting started, symbolic expressions, numerical evaluation, pattern matching, and APIs in Python and Rust.

`Float`

Float()

An immutable real number with arbitrary binary precision.

Notes

Values use binary floating-point arithmetic, so decimal fractions need not be exact. Arithmetic tracks accuracy and may change the result’s precision. Native numeric operands are converted at this Float’s precision; existing Float operands keep their own precision. Increasing precision does not recover lost digits. Operations return new values; Float is unhashable.

Supports arithmetic and real comparisons with Float, int, float and Decimal. Addition, subtraction, multiplication and division with complex operands return ComplexFloat. Use float(x), int(x), to_decimal() or as_integer_ratio() for explicit conversion. str(x) displays significant digits; repr(x) preserves value and precision. Formatting accepts Decimal-style specifications.

Examples

from symbolica import Float
x = Float("1.25", decimal_digits=80)
x.precision
266
x.as_integer_ratio()
(5, 4)
str(x + 2)
'3.25'
Float.from_ratio(1, 3, precision=200).to_decimal(10)
Decimal('0.3333333333')
Float.pi(decimal_digits=60).sin().is_finite()
True

Attributes

Name	Description
`imag`	Zero as a Float at this value’s precision.
`precision`	The working precision in bits
`real`	The real part as a Float with the same value and precision.

`imag`

Float.imag: Float

Zero as a Float at this value’s precision.

`precision`

Float.precision: int

The working precision in bits. Read-only; use with_precision() to return a rounded copy.

`real`

Float.real: Float

The real part as a Float with the same value and precision.

Methods

Name	Description
`__abs__`	Return the magnitude as a real Float.
`__add__`	Return self + other with accuracy tracking; complex operands produce ComplexFloat.
`__bool__`	Return False for zero and True otherwise, including NaN.
`__copy__`	Return a copy preserving the value and precision.
`__deepcopy__`	Return a copy preserving the value and precision.
`__eq__`	Compare numeric values exactly across compatible scalar types; NaN is unequal to every value.
`__float__`	Convert to a native binary64 float, potentially losing precision or overflowing to infinity.
`__format__`	Format with a Decimal-style specification
`__ge__`	Return self >= other using numeric comparison
`__gt__`	Return self > other using numeric comparison
`__int__`	Convert to a Python integer by truncating toward zero
`__le__`	Return self <= other using numeric comparison
`__lt__`	Return self < other using numeric comparison
`__mul__`	Return self * other with accuracy tracking; complex operands produce ComplexFloat.
`__ne__`	Return the negation of numeric equality, including True for NaN.
`__neg__`	Return the additive inverse.
`__new__`	Construct an immutable real number with arbitrary binary precision.
`__pos__`	Return a copy of this value.
`__pow__`	Raise to an integer or real numeric exponent
`__radd__`	Return other + self with accuracy tracking; complex operands produce ComplexFloat.
`__repr__`	Return a constructor expression that preserves the value and its precision.
`__rmul__`	Return other * self with accuracy tracking; complex operands produce ComplexFloat.
`__rsub__`	Return other - self with accuracy tracking; complex operands produce ComplexFloat.
`__rtruediv__`	Return other / self with accuracy tracking; complex operands produce ComplexFloat
`__str__`	Return a decimal display using significant digits appropriate to the precision.
`__sub__`	Return self - other with accuracy tracking; complex operands produce ComplexFloat.
`__truediv__`	Return self / other with accuracy tracking; complex operands produce ComplexFloat
`_repr_html_`	Return HTML with the same significant digits as str(self).
`_repr_latex_`	Return LaTeX with the same significant digits as str(self), using powers of ten for scientific notation.
`_repr_pretty_`	Write the same significant digits as str(self) to a notebook pretty printer.
`acos`	Return the inverse cosine in radians, in [0, pi]
`acosh`	Return the nonnegative inverse hyperbolic cosine
`as_integer_ratio`	Return the exact (numerator, denominator) of the stored binary value
`asin`	Return the inverse sine in radians, in [-pi/2, pi/2]
`asinh`	Return the inverse hyperbolic sine.
`atan`	Return the inverse tangent in radians, in [-pi/2, pi/2].
`atan2`	Return the quadrant-aware angle atan2(self, x) in radians in [-pi, pi]
`atanh`	Return the inverse hyperbolic tangent
`conj`	Alias for conjugate().
`conjugate`	Return a copy with the same value and precision.
`cos`	Return the cosine, with the argument in radians.
`cosh`	Return the hyperbolic cosine with accuracy tracking.
`csch`	Return the reciprocal hyperbolic sine, retaining accuracy near zero and at infinity.
`e`	Construct Euler’s number e with precision in bits or decimal_digits (default: 53 bits).
`euler`	Construct the Euler-Mascheroni constant with precision in bits or decimal_digits (default: 53 bits).
`euler_gamma`	Alias for euler(), the Euler-Mascheroni constant; precision defaults to 53 bits.
`exp`	Return the exponential e**self with accuracy tracking.
`fixed_precision`	Return False: arithmetic dynamically tracks precision for these scalar types.
`from_i64`	Convert a signed 64-bit integer at this value’s precision
`from_ratio`	Construct numerator / denominator from two Python integers
`from_rational`	Convert numerator / denominator at this value’s precision
`from_usize`	Convert a nonnegative platform-sized integer at this value’s precision
`get_epsilon`	Return 2**(-precision) as a native float
`get_precision`	Return the working precision in bits; alias for the precision property.
`hypot`	Return sqrt(self2 + other2), avoiding unnecessary overflow and underflow.
`i`	Return None
`inv`	Return 1/self
`is_finite`	Return True for finite values, including zero; False for NaN and infinities.
`is_fully_zero`	Return whether the value is exactly zero.
`is_infinite`	Return whether the value is positive or negative infinity; False for NaN.
`is_nan`	Return whether the value is NaN (not a number).
`is_one`	Return whether the value equals one.
`is_zero`	Return whether the value is zero; signed zero also counts as zero.
`ln`	Return the natural logarithm
`log`	Alias for ln(), the natural logarithm (base e).
`log1p`	Return log(1+self), retaining small increments lost when adding one.
`mul_add`	Return self*a+b with accuracy tracking, rounding the multiplication and addition separately.
`nan`	Return NaN at this value’s precision.
`neg`	Return the additive inverse, equivalent to -self.
`new_one`	Construct one with precision in bits or decimal_digits (default: 53 bits)
`new_zero`	Construct zero with precision in bits or decimal_digits (default: 53 bits)
`norm`	Return the magnitude as a real Float, equivalent to abs(self).
`one`	Return one at this value’s precision.
`phi`	Construct the golden ratio (1+sqrt(5))/2 with precision in bits or decimal_digits (default: 53 bits).
`pi`	Construct pi with precision in bits or decimal_digits (default: 53 bits).
`pow`	Raise to an unsigned 64-bit integer exponent
`powf`	Raise to a real numeric exponent with accuracy tracking
`round_to_nearest_integer`	Return the nearest Python integer, rounding ties to even
`sample_unit`	Sample uniformly from [0, 1) using the full working precision
`sech`	Return the reciprocal hyperbolic cosine without overflowing an intermediate cosh.
`set_from`	Return a new value converted from other, with precision inferred as in the constructor.
`sin`	Return the sine, with the argument in radians.
`sinh`	Return the hyperbolic sine with accuracy tracking.
`sqrt`	Return the nonnegative square root
`tan`	Return the tangent, with the argument in radians.
`tanh`	Return the hyperbolic tangent with accuracy tracking.
`to_decimal`	Convert the stored binary value to Decimal
`to_f64`	Convert to a native binary64 float; alias for float(self)
`to_usize_clamped`	Round ties to even and clamp to [0, 2**pointer_bits-1]
`with_precision`	Return a copy rounded to a new working precision
`zero`	Return zero at this value’s precision.

`abs`

Float.__abs__() -> Float

Return the magnitude as a real Float.

`add`

Float.__add__(other: Float | int | float | Decimal) -> Float
Float.__add__(other: ComplexFloat | complex) -> ComplexFloat

Return self + other with accuracy tracking; complex operands produce ComplexFloat.

Parameters

other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

`bool`

Float.__bool__() -> bool

Return False for zero and True otherwise, including NaN.

`copy`

Float.__copy__() -> Float

Return a copy preserving the value and precision.

`deepcopy`

Float.__deepcopy__(memo: Any) -> Float

Return a copy preserving the value and precision.

Parameters

memo (dict) Memo dictionary supplied by copy.deepcopy.

`eq`

Float.__eq__(other: object) -> bool

Compare numeric values exactly across compatible scalar types; NaN is unequal to every value.

Parameters

other (object) Value to compare numerically. Compatible numeric types compare by value; unsupported types are not equal.

`float`

Float.__float__() -> float

Convert to a native binary64 float, potentially losing precision or overflowing to infinity.

`format`

Float.__format__(spec: str) -> str

Format with a Decimal-style specification. An empty specification uses str(self).

Parameters

spec (str) Decimal-style format specification, such as “.12f”. An empty string uses str(self).

`ge`

Float.__ge__(other: Float | int | float | Decimal) -> bool

Return self >= other using numeric comparison. Comparisons with NaN return False.

Parameters

other (Float, int, float or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

`gt`

Float.__gt__(other: Float | int | float | Decimal) -> bool

Return self > other using numeric comparison. Comparisons with NaN return False.

Parameters

other (Float, int, float or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

`int`

Float.__int__() -> int

Convert to a Python integer by truncating toward zero. NaN and infinity cannot be converted.

`le`

Float.__le__(other: Float | int | float | Decimal) -> bool

Return self <= other using numeric comparison. Comparisons with NaN return False.

Parameters

other (Float, int, float or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

`lt`

Float.__lt__(other: Float | int | float | Decimal) -> bool

Return self < other using numeric comparison. Comparisons with NaN return False.

Parameters

other (Float, int, float or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

`mul`

Float.__mul__(other: Float | int | float | Decimal) -> Float
Float.__mul__(other: ComplexFloat | complex) -> ComplexFloat

Return self * other with accuracy tracking; complex operands produce ComplexFloat.

Parameters

other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

`ne`

Float.__ne__(other: object) -> bool

Return the negation of numeric equality, including True for NaN.

Parameters

other (object) Value to compare numerically. Compatible numeric types compare by value; unsupported types are not equal.

`neg`

Float.__neg__() -> Float

Return the additive inverse.

`new`

Float.__new__(
    value: Float | int | float | str | Decimal | None = None,
    *,
    precision: int | None = None,
    decimal_digits: int | None = None,
) -> Float

Construct an immutable real number with arbitrary binary precision.

Parameters

value (Float, int, float, str, Decimal, optional) Initial value; omitted or None means zero. Strings and Decimal values are rounded directly to the requested binary precision. For decimal input, use a string such as “0.1”.
precision (int, optional) Working precision in bits. Mutually exclusive with decimal_digits.
decimal_digits (int, optional) Decimal working precision, converted to ceil(decimal_digits * log2(10)) bits.

Notes

Without a precision option, Float inputs retain their precision, native floats use 53 bits, and strings, integers and Decimal inputs infer precision from their significant decimal digits, with a minimum of 53 bits. Unsupported input types raise TypeError; malformed strings, invalid precision, or supplying both precision options raise ValueError. Negative or out-of-range integer precision arguments raise OverflowError.

`pos`

Float.__pos__() -> Float

Return a copy of this value.

`pow`

Float.__pow__(exponent: Float | int | float | Decimal, modulo: None = None) -> Float

Raise to an integer or real numeric exponent. Negative integer powers are supported; zero to a negative power raises ZeroDivisionError. Modular powers are unsupported.

Parameters

exponent (Float, int, float or Decimal) Numeric exponent. Use ** for signed integer powers.
modulo (None, optional) Must be None. Three-argument modular exponentiation is unsupported.

`radd`

Float.__radd__(other: Float | int | float | Decimal) -> Float
Float.__radd__(other: ComplexFloat | complex) -> ComplexFloat

Return other + self with accuracy tracking; complex operands produce ComplexFloat.

Parameters

other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

`repr`

Float.__repr__() -> str

Return a constructor expression that preserves the value and its precision.

`rmul`

Float.__rmul__(other: Float | int | float | Decimal) -> Float
Float.__rmul__(other: ComplexFloat | complex) -> ComplexFloat

Return other * self with accuracy tracking; complex operands produce ComplexFloat.

Parameters

other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

`rsub`

Float.__rsub__(other: Float | int | float | Decimal) -> Float
Float.__rsub__(other: ComplexFloat | complex) -> ComplexFloat

Return other - self with accuracy tracking; complex operands produce ComplexFloat.

Parameters

other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

`rtruediv`

Float.__rtruediv__(other: Float | int | float | Decimal) -> Float
Float.__rtruediv__(other: ComplexFloat | complex) -> ComplexFloat

Return other / self with accuracy tracking; complex operands produce ComplexFloat. A zero divisor raises ZeroDivisionError.

Parameters

other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

`str`

Float.__str__() -> str

Return a decimal display using significant digits appropriate to the precision.

`sub`

Float.__sub__(other: Float | int | float | Decimal) -> Float
Float.__sub__(other: ComplexFloat | complex) -> ComplexFloat

Return self - other with accuracy tracking; complex operands produce ComplexFloat.

Parameters

other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

`truediv`

Float.__truediv__(other: Float | int | float | Decimal) -> Float
Float.__truediv__(other: ComplexFloat | complex) -> ComplexFloat

Return self / other with accuracy tracking; complex operands produce ComplexFloat. A zero divisor raises ZeroDivisionError.

Parameters

other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

`_repr_html_`

Float._repr_html_() -> str

Return HTML with the same significant digits as str(self).

`_repr_latex_`

Float._repr_latex_() -> str

Return LaTeX with the same significant digits as str(self), using powers of ten for scientific notation.

`_repr_pretty_`

Float._repr_pretty_(pretty: Any, cycle: bool) -> None

Write the same significant digits as str(self) to a notebook pretty printer.

Parameters

pretty (object) Pretty printer providing a text(string) method.
cycle (bool) Whether the printer detected a reference cycle; prints … if True.

`acos`

Float.acos() -> Float

Return the inverse cosine in radians, in [0, pi]. Inputs outside [-1, 1] yield NaN.

`acosh`

Float.acosh() -> Float

Return the nonnegative inverse hyperbolic cosine. Inputs below one yield NaN.

`as_integer_ratio`

Float.as_integer_ratio() -> tuple[int, int]

Return the exact (numerator, denominator) of the stored binary value.

Both entries are Python integers and the denominator is positive. This describes the stored value, which may approximate the original decimal input. NaN and infinity raise ValueError.

Examples

Float("1.25").as_integer_ratio()
(5, 4)

`asin`

Float.asin() -> Float

Return the inverse sine in radians, in [-pi/2, pi/2]. Inputs outside [-1, 1] yield NaN.

`asinh`

Float.asinh() -> Float

Return the inverse hyperbolic sine.

`atan`

Float.atan() -> Float

Return the inverse tangent in radians, in [-pi/2, pi/2].

`atan2`

Float.atan2(x: Float | int | float | Decimal) -> Float

Return the quadrant-aware angle atan2(self, x) in radians in [-pi, pi]. Accepts real numeric operands and preserves signed-zero quadrant conventions.

Parameters

x (Float, int, float or Decimal) Horizontal coordinate; self is the vertical coordinate in atan2(self, x).

`atanh`

Float.atanh() -> Float

Return the inverse hyperbolic tangent. Inputs outside [-1, 1] yield NaN; +/-1 yield signed infinity.

`conj`

Float.conj() -> Float

Alias for conjugate().

`conjugate`

Float.conjugate() -> Float

Return a copy with the same value and precision.

`cos`

Float.cos() -> Float

Return the cosine, with the argument in radians.

`cosh`

Float.cosh() -> Float

Return the hyperbolic cosine with accuracy tracking.

`csch`

Float.csch() -> Float

Return the reciprocal hyperbolic sine, retaining accuracy near zero and at infinity.

`e`

Float.e(*, precision: int | None = None, decimal_digits: int | None = None) -> Float

Construct Euler’s number e with precision in bits or decimal_digits (default: 53 bits).

Parameters

precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits.
decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits.

`euler`

Float.euler(*, precision: int | None = None, decimal_digits: int | None = None) -> Float

Construct the Euler-Mascheroni constant with precision in bits or decimal_digits (default: 53 bits).

Parameters

precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits.
decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits.

`euler_gamma`

Float.euler_gamma(*, precision: int | None = None, decimal_digits: int | None = None) -> Float

Alias for euler(), the Euler-Mascheroni constant; precision defaults to 53 bits.

Parameters

precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits.
decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits.

`exp`

Float.exp() -> Float

Return the exponential e**self with accuracy tracking.

`fixed_precision`

Float.fixed_precision() -> bool

Return False: arithmetic dynamically tracks precision for these scalar types.

`from_i64`

Float.from_i64(value: int) -> Float

Convert a signed 64-bit integer at this value’s precision. Out-of-range inputs raise OverflowError.

Parameters

value (int) Integer in [-263, 263-1] to convert.

`from_ratio`

Float.from_ratio(
    numerator: int,
    denominator: int,
    *,
    precision: int | None = None,
    decimal_digits: int | None = None,
) -> Float

Construct numerator / denominator from two Python integers.

Specify precision in bits or decimal_digits, never both; the default is 53 bits. The rational is rounded directly without conversion through a native float. A zero denominator raises ZeroDivisionError.

Parameters

numerator (int) Numerator of the rational value; accepts arbitrary-sized Python integers.
denominator (int) Nonzero denominator of the rational value; either sign is accepted.
precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits.
decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits.

Examples

Float.from_ratio(1, 8, precision=100).to_decimal()
Decimal('0.125')

`from_rational`

Float.from_rational(numerator: int, denominator: int) -> Float

Convert numerator / denominator at this value’s precision. Both inputs must be Python integers; zero denominator raises ZeroDivisionError.

Parameters

numerator (int) Numerator of the rational value; accepts arbitrary-sized Python integers.
denominator (int) Nonzero denominator of the rational value; either sign is accepted.

`from_usize`

Float.from_usize(value: int) -> Float

Convert a nonnegative platform-sized integer at this value’s precision. Out-of-range inputs raise OverflowError.

Parameters

value (int) Integer in [0, 2**pointer_bits-1] to convert.

`get_epsilon`

Float.get_epsilon() -> float

Return 2**(-precision) as a native float. Very high precision can underflow to zero.

`get_precision`

Float.get_precision() -> int

Return the working precision in bits; alias for the precision property.

`hypot`

Float.hypot(other: Float | int | float | Decimal) -> Float

Return sqrt(self2 + other2), avoiding unnecessary overflow and underflow.

Parameters

other (Float, int, float, Decimal) Second coordinate. Native numbers use this value’s precision; existing arbitrary-precision scalars retain their precision.

`i`

Float.i() -> Float | None

Return None. Construct the imaginary unit with ComplexFloat.i().

`inv`

Float.inv() -> Float

Return 1/self. Zero raises ZeroDivisionError.

`is_finite`

Float.is_finite() -> bool

Return True for finite values, including zero; False for NaN and infinities.

`is_fully_zero`

Float.is_fully_zero() -> bool

Return whether the value is exactly zero.

`is_infinite`

Float.is_infinite() -> bool

Return whether the value is positive or negative infinity; False for NaN.

`is_nan`

Float.is_nan() -> bool

Return whether the value is NaN (not a number).

`is_one`

Float.is_one() -> bool

Return whether the value equals one.

`is_zero`

Float.is_zero() -> bool

Return whether the value is zero; signed zero also counts as zero.

`ln`

Float.ln() -> Float

Return the natural logarithm. Zero yields negative infinity; negative inputs yield NaN.

`log`

Float.log() -> Float

Alias for ln(), the natural logarithm (base e).

`log1p`

Float.log1p() -> Float

Return log(1+self), retaining small increments lost when adding one.

`mul_add`

Float.mul_add(a: Float | int | float | Decimal, b: Float | int | float | Decimal) -> Float

Return self*a+b with accuracy tracking, rounding the multiplication and addition separately.

Parameters

a (Float, int, float or Decimal) Multiplier in self*a+b.
b (Float, int, float or Decimal) Addend in self*a+b.

`nan`

Float.nan() -> Float

Return NaN at this value’s precision.

`neg`

Float.neg() -> Float

Return the additive inverse, equivalent to -self.

`new_one`

Float.new_one(*, precision: int | None = None, decimal_digits: int | None = None) -> Float

Construct one with precision in bits or decimal_digits (default: 53 bits). Use one() to retain instance precision.

Parameters

precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits.
decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits.

`new_zero`

Float.new_zero(*, precision: int | None = None, decimal_digits: int | None = None) -> Float

Construct zero with precision in bits or decimal_digits (default: 53 bits). Use zero() to retain instance precision.

Parameters

precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits.
decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits.

`norm`

Float.norm() -> Float

Return the magnitude as a real Float, equivalent to abs(self).

`one`

Float.one() -> Float

Return one at this value’s precision.

`phi`

Float.phi(*, precision: int | None = None, decimal_digits: int | None = None) -> Float

Construct the golden ratio (1+sqrt(5))/2 with precision in bits or decimal_digits (default: 53 bits).

Parameters

precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits.
decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits.

`pi`

Float.pi(*, precision: int | None = None, decimal_digits: int | None = None) -> Float

Construct pi with precision in bits or decimal_digits (default: 53 bits).

Parameters

precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits.
decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits.

`pow`

Float.pow(exponent: int) -> Float

Raise to an unsigned 64-bit integer exponent. Negative or out-of-range exponents raise OverflowError; use ** for signed integer powers.

Parameters

exponent (int) Unsigned exponent in [0, 2**64-1]; zero returns one, including for a zero base.

`powf`

Float.powf(exponent: Float | int | float | Decimal) -> Float

Raise to a real numeric exponent with accuracy tracking. Zero to a negative power raises ZeroDivisionError; non-real results yield NaN.

Parameters

exponent (Float, int, float or Decimal) Numeric exponent. Use ** for signed integer powers.

`round_to_nearest_integer`

Float.round_to_nearest_integer() -> int

Return the nearest Python integer, rounding ties to even. NaN and infinity raise ValueError.

`sample_unit`

Float.sample_unit(rng: Any = None) -> Float

Sample uniformly from [0, 1) using the full working precision.

rng must supply getrandbits(bits); omitted or None uses Python’s random module. Pass random.Random(seed) for reproducibility.

Parameters

rng (object, optional) Random generator with a getrandbits(bits) method returning an integer in [0, 2**bits). Omitted or None uses Python’s random module; use random.Random(seed) for reproducible samples.

`sech`

Float.sech() -> Float

Return the reciprocal hyperbolic cosine without overflowing an intermediate cosh.

`set_from`

Float.set_from(other: Float | int | float | str | Decimal) -> Float

Return a new value converted from other, with precision inferred as in the constructor.

Parameters

other (Float, int, float, str or Decimal) Value to copy or convert using constructor precision inference.

`sin`

Float.sin() -> Float

Return the sine, with the argument in radians.

`sinh`

Float.sinh() -> Float

Return the hyperbolic sine with accuracy tracking.

`sqrt`

Float.sqrt() -> Float

Return the nonnegative square root. Negative real inputs yield NaN; use ComplexFloat for complex roots.

`tan`

Float.tan() -> Float

Return the tangent, with the argument in radians.

`tanh`

Float.tanh() -> Float

Return the hyperbolic tangent with accuracy tracking.

`to_decimal`

Float.to_decimal(digits: int | None = None) -> Decimal

Convert the stored binary value to Decimal.

With digits omitted, conversion is exact. A positive digits value rounds to that many significant decimal digits, using round-half-even. Neither mode depends on or modifies Python’s global decimal context. Preserves signed zero, NaN and infinity. Zero digits raises ValueError; negative or out-of-range integer digits raise OverflowError.

Parameters

digits (int, optional) Positive number of significant decimal digits per converted value. Omitted or None converts the stored binary value exactly; otherwise round half-even.

Examples

Float.from_ratio(1, 3, precision=100).to_decimal(digits=5)
Decimal('0.33333')

`to_f64`

Float.to_f64() -> float

Convert to a native binary64 float; alias for float(self). Precision can be lost and overflow yields infinity.

`to_usize_clamped`

Float.to_usize_clamped() -> int

Round ties to even and clamp to [0, 2**pointer_bits-1]. Negative values become zero, positive infinity becomes the maximum, and NaN raises ValueError.

`with_precision`

Float.with_precision(*, precision: int | None = None, decimal_digits: int | None = None) -> Float

Return a copy rounded to a new working precision.

Specify exactly one of precision (bits) or decimal_digits. Missing, invalid, or conflicting precision options raise ValueError; negative or out-of-range integer arguments raise OverflowError. Increasing precision cannot recover digits already lost. The original value is unchanged.

Parameters

precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. Exactly one precision option is required.
decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. Exactly one precision option is required.

`zero`

Float.zero() -> Float

Return zero at this value’s precision.