httk.core.vectors.exactmath

Exact math on rationals and decimals: type-preserving transcendentals.

This module provides the transcendental and helper functions used by FracVector. Every value is computed with 100% exact integer/rational arithmetic, so results are platform-independent and deterministic by construction — no floating point is used anywhere in the computation.

Two output domains are supported, selected by a single documented rule:

The result is a decimal.Decimal iff any numeric input is a Decimal OR digits= is passed; Fraction/int/str inputs otherwise get today’s exact Fraction behavior with prec/limit semantics.

One function additionally offers an exact-symbolic domain: sqrt() with exact=True overrides the output-domain rule and returns the exact SurdScalar square root (an element of the squarefree-radical field \(\mathbb{Q}[\sqrt n]\)), with no approximation.

In the Fraction domain each function returns a rational (fractions.Fraction) approximation to a target precision prec (the error bound), with limit controlling the result denominator — exactly as before. In the Decimal domain the same rational algorithms drive Ziv’s adaptive strategy to produce a correctly rounded Decimal to digits significant digits (default: the active decimal.getcontext() precision, matching stdlib Decimal’s own model) under rounding ("half_even" = correctly rounded, "down" = correct truncation toward zero). A Decimal input is converted to a Fraction exactly (fractions.Fraction accepts a Decimal), so the rational core is identical in both domains; this gives deterministic cos/sin/atan2/… for Decimals, which the stdlib decimal module does not offer.

Note: a possible future performance follow-up is to soft-import the third-party cfractions accelerator in place of the standard-library fractions; the legacy code did so, but on Python 3.12 the standard library is used unconditionally.

Attributes

default_accuracy

Functions

get_continued_fraction(→ collections.abc.Iterator[int])	Yield the terms of the continued fraction expansion of p/q.
best_rational_in_interval(→ fractions.Fraction)	Return the rational number with the smallest denominator lying in [low, high].
fraction_from_continued_fraction(→ fractions.Fraction)	Reconstruct a fractions.Fraction from a list of continued-fraction terms.
string_to_val_and_delta() → tuple[fractions.Fraction, ...)	Parse a numeric string into a central value and an uncertainty (delta).
any_to_fraction() → fractions.Fraction)	Convert an arbitrary numeric-like object into a fractions.Fraction.
integer_sqrt(→ int)	Return the integer square root of n (the floor of its exact square root).
sqrt(→ Any)	Return the square root of x.
cos(→ fractions.Fraction | decimal.Decimal)	Return the cosine of x (radians unless degrees is True). See the module docstring for
sin(→ fractions.Fraction | decimal.Decimal)	Return the sine of x (radians unless degrees is True). See the module docstring for the
tan(→ fractions.Fraction | decimal.Decimal)	Return the tangent of x. See the module docstring for the type-preservation rule.
exp(→ fractions.Fraction | decimal.Decimal)	Return e raised to the power x. See the module docstring for the type-preservation rule.
log(→ fractions.Fraction | decimal.Decimal)	Return the logarithm of x to base (natural log when base is None). See the module
log10(→ fractions.Fraction | decimal.Decimal)	Return the base-10 logarithm of x. See the module docstring for the type-preservation rule.
asin(→ fractions.Fraction | int | decimal.Decimal)	Return the arc sine of x (radians, or degrees if degrees). See the module docstring for
acos(→ fractions.Fraction | decimal.Decimal)	Return the arc cosine of x (radians, or degrees if degrees). See the module docstring
atan(→ fractions.Fraction | decimal.Decimal)	Return the arc tangent of x (radians, or degrees if degrees). See the module docstring
atan2(→ fractions.Fraction | decimal.Decimal)	Return the arc tangent of y/x with math.atan2() quadrant conventions (radians, or
pi(→ fractions.Fraction | decimal.Decimal)	Return pi.

Module Contents

httk.core.vectors.exactmath.default_accuracy

httk.core.vectors.exactmath.get_continued_fraction(p: int, q: int) → collections.abc.Iterator[int]

Yield the terms of the continued fraction expansion of p/q.

httk.core.vectors.exactmath.best_rational_in_interval(low: Any, high: Any) → fractions.Fraction

Return the rational number with the smallest denominator lying in [low, high].

httk.core.vectors.exactmath.fraction_from_continued_fraction(cf: list[int]) → fractions.Fraction

Reconstruct a fractions.Fraction from a list of continued-fraction terms.

httk.core.vectors.exactmath.string_to_val_and_delta(arg: str, min_accuracy: fractions.Fraction | None = fractions.Fraction(1, 10000)) → tuple[fractions.Fraction, fractions.Fraction]

Parse a numeric string into a central value and an uncertainty (delta).

Recognizes plain decimals, fractions ("2/3"), scientific notation, and explicit standard-deviation notation ("0.33342(10)"). When no explicit uncertainty is present and min_accuracy is not None, an uncertainty is inferred from the number of written digits (capped at min_accuracy).

httk.core.vectors.exactmath.any_to_fraction(arg: Any, min_accuracy: fractions.Fraction | None = fractions.Fraction(1, 10000)) → fractions.Fraction

Convert an arbitrary numeric-like object into a fractions.Fraction.

Parameters:

• arg – a number, string, Decimal, Fraction, or anything the Fraction constructor accepts. Strings are parsed for uncertainty via string_to_val_and_delta().

• min_accuracy – the minimum assumed accuracy for string input. With the default 1/10000, 0.33 is taken to mean 0.3300 (= 33/100), whereas 0.3333 is taken to mean 1/3. Set to None to convert strings exactly.

httk.core.vectors.exactmath.integer_sqrt(n: int) → int

Return the integer square root of n (the floor of its exact square root).

httk.core.vectors.exactmath.sqrt(x: Any, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None, exact: bool = False) → Any

Return the square root of x.

Fraction domain (Fraction/int/str input, no digits=): a rational approximation within prec (exact for perfect squares), limit controlling the denominator. Decimal domain (Decimal input or digits= given): the correctly-rounded Decimal to digits significant digits under rounding.

With exact=True the output-domain rule is overridden: the result is the exact SurdScalar square root of x — an element of the squarefree-radical field, with no approximation at all (sqrt(2, exact=True) squares back to exactly 2, sqrt(9/4, exact=True) is the rational 3/2). x must be a nonnegative rational; prec/limit/digits/rounding are ignored in this mode.

httk.core.vectors.exactmath.cos(x: Any, prec: fractions.Fraction = default_accuracy, limit: bool = True, degrees: bool = False, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None) → fractions.Fraction | decimal.Decimal

Return the cosine of x (radians unless degrees is True). See the module docstring for the type-preservation rule; Decimal mode renders the special-angle exact values exactly (e.g. cos(Decimal("60"), degrees=True) == Decimal("0.5")).

httk.core.vectors.exactmath.sin(x: Any, prec: fractions.Fraction = default_accuracy, limit: bool = True, degrees: bool = False, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None) → fractions.Fraction | decimal.Decimal

Return the sine of x (radians unless degrees is True). See the module docstring for the type-preservation rule.

httk.core.vectors.exactmath.tan(x: Any, degrees: bool = False, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None) → fractions.Fraction | decimal.Decimal

Return the tangent of x. See the module docstring for the type-preservation rule.

httk.core.vectors.exactmath.exp(x: Any, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None) → fractions.Fraction | decimal.Decimal

Return e raised to the power x. See the module docstring for the type-preservation rule.

httk.core.vectors.exactmath.log(x: Any, base: Any = None, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None) → fractions.Fraction | decimal.Decimal

Return the logarithm of x to base (natural log when base is None). See the module docstring for the type-preservation rule; a Decimal base also promotes the result.

httk.core.vectors.exactmath.log10(x: Any, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None) → fractions.Fraction | decimal.Decimal

Return the base-10 logarithm of x. See the module docstring for the type-preservation rule.

httk.core.vectors.exactmath.asin(x: Any, degrees: bool = False, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None) → fractions.Fraction | int | decimal.Decimal

Return the arc sine of x (radians, or degrees if degrees). See the module docstring for the type-preservation rule.

httk.core.vectors.exactmath.acos(x: Any, degrees: bool = False, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None) → fractions.Fraction | decimal.Decimal

Return the arc cosine of x (radians, or degrees if degrees). See the module docstring for the type-preservation rule.

httk.core.vectors.exactmath.atan(x: Any, degrees: bool = False, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None) → fractions.Fraction | decimal.Decimal

Return the arc tangent of x (radians, or degrees if degrees). See the module docstring for the type-preservation rule.

httk.core.vectors.exactmath.atan2(y: Any, x: Any, degrees: bool = False, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None) → fractions.Fraction | decimal.Decimal

Return the arc tangent of y/x with math.atan2() quadrant conventions (radians, or degrees if degrees). See the module docstring for the type-preservation rule; a Decimal in either argument promotes the result (atan2(Decimal, Fraction) returns a Decimal).

httk.core.vectors.exactmath.pi(prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None) → fractions.Fraction | decimal.Decimal

Return pi.

With no digits= the Fraction contract holds (a rational within prec, limit controlling the denominator); pi(digits=n) returns the correctly-rounded Decimal to n significant digits under rounding.