httk.core.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. All scalar functions also accept ScalarLike and VectorLike inputs. Vectors are mapped elementwise and retain their shape. The optional keyword-only coerce= presents the natural result through a requested view or value type; coerce="natural" returns the pre-presentation result unchanged. By default, presentation is view-neutral and best-effort: ordinary inputs are presented in the input type family, while strings, bools, and Backend inputs retain the natural result. Explicit coercion is strict. exact=True keeps its exact SurdScalar/SurdVector result unless an explicit coerce= is supplied.

The default presentation therefore returns an int for an integral integer result, an exact Fraction for non-integral integer results, a float for float inputs (and explicit coerce=float is lossy), nested lists for list inputs, native tuple views for tuple inputs, and float64 numpy views for numpy inputs. Numpy view values are lossy, but the exact result remains recoverable with unwrap(). Decimal inputs or digits= select the Decimal domain. Fraction inputs remain Fractions. Surd inputs are embedded back into the Surd family when the natural result is rational.

The exact-symbolic domain is selected by exact=True on sqrt and degree-mode trigonometric functions. It returns exact squarefree-radical values (or exact inverse angles), with no approximation. Exact trigonometry is available only for the complete surd-cosine angle set: multiples of 15 and 36 degrees; unsupported values raise ValueError. Exact inverse trigonometry accepts surd values and returns exact degree Fractions.

When a genuinely irrational SurdScalar is used by ordinary Fraction-mode functions, it is reduced to the deterministic Fraction hub at the active Decimal context precision plus three guard digits. Exact symbolic operations preserve the surd and never use that lossy 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. 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.

The implementation uses the standard-library fractions.

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(→ Any)	Return the cosine of x (radians unless degrees is True). See the module docstring for
sin(→ Any)	Return the sine of x (radians unless degrees is True). See the module docstring for the
tan(→ Any)	Return the tangent of x. See the module docstring for the type-preservation rule.
exp(→ Any)	Return e raised to the power x. See the module docstring for the type-preservation rule.
log(→ Any)	Return the logarithm of x to base (natural log when base is None). See the module
log10(→ Any)	Return the base-10 logarithm of x. See the module docstring for the type-preservation rule.
asin(→ Any)	Return the arc sine of x (radians, or degrees if degrees). See the module docstring for
acos(→ Any)	Return the arc cosine of x (radians, or degrees if degrees). See the module docstring
atan(→ Any)	Return the arc tangent of x (radians, or degrees if degrees). See the module docstring
atan2(→ Any)	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.exactmath.default_accuracy

httk.core.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.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.exactmath.fraction_from_continued_fraction(cf: list[int]) → fractions.Fraction

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

httk.core.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.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.exactmath.integer_sqrt(n: int) → int

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

httk.core.exactmath.sqrt(x: httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None, exact: bool = False, *, coerce: Any = None) → 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.exactmath.cos(x: httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike, prec: fractions.Fraction = default_accuracy, limit: bool = True, degrees: bool = False, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None, exact: bool = False, *, coerce: Any = None) → Any

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.exactmath.sin(x: httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike, prec: fractions.Fraction = default_accuracy, limit: bool = True, degrees: bool = False, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None, exact: bool = False, *, coerce: Any = None) → Any

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

httk.core.exactmath.tan(x: httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike, degrees: bool = False, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None, exact: bool = False, *, coerce: Any = None) → Any

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

httk.core.exactmath.exp(x: httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None, *, coerce: Any = None) → Any

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

httk.core.exactmath.log(x: httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike, base: httk.core.vectors.scalar_like.ScalarLike | None = None, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None, *, coerce: Any = None) → Any

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.exactmath.log10(x: httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None, *, coerce: Any = None) → Any

Return the base-10 logarithm of x. See the module docstring for the type-preservation rule. max_refinements is honored and is forwarded to the logarithm implementation.

httk.core.exactmath.asin(x: httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike, degrees: bool = False, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None, exact: bool = False, *, coerce: Any = None) → Any

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

httk.core.exactmath.acos(x: httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike, degrees: bool = False, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None, exact: bool = False, *, coerce: Any = None) → Any

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

httk.core.exactmath.atan(x: httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike, degrees: bool = False, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None, exact: bool = False, *, coerce: Any = None) → Any

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

httk.core.exactmath.atan2(y: httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike, x: httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike, degrees: bool = False, prec: fractions.Fraction = default_accuracy, limit: bool = True, digits: int | None = None, rounding: str = 'half_even', max_refinements: int | None = None, exact: bool = False, *, coerce: Any = None) → Any

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). Vector inputs are mapped elementwise; a scalar argument is broadcast across the vector.

httk.core.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.