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 following httk.core.coerce_view() semantics — the exact backend is retained behind view presentations (use httk.core.unview() on the result for a plain value); 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 propagates coercion failures. 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(p, q)

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

best_rational_in_interval(low, high)

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

fraction_from_continued_fraction(cf)

Reconstruct a fractions.Fraction from continued-fraction terms.

string_to_val_and_delta(arg[, min_accuracy])

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

any_to_fraction(arg[, min_accuracy])

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

integer_sqrt(n)

Return the integer square root of n.

sqrt(x[, prec, limit, digits, rounding, ...])

Return the square root of x.

cos(x[, prec, limit, degrees, digits, rounding, ...])

Return the cosine of x (radians unless degrees is True). See the module docstring for

sin(x[, prec, limit, degrees, digits, rounding, ...])

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

tan(x[, degrees, prec, limit, digits, rounding, ...])

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

exp(x[, prec, limit, digits, rounding, ...])

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

log(x[, base, prec, limit, digits, rounding, ...])

Return the logarithm of x to base (natural log when base is None). See the module

log10(x[, prec, limit, digits, rounding, ...])

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

asin(x[, degrees, prec, limit, digits, rounding, ...])

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

acos(x[, degrees, prec, limit, digits, rounding, ...])

Return the arc cosine of x (radians, or degrees if degrees). See the module docstring

atan(x[, degrees, prec, limit, digits, rounding, ...])

Return the arc tangent of x (radians, or degrees if degrees). See the module docstring

atan2(y, x[, degrees, prec, limit, digits, rounding, ...])

Return the arc tangent of y/x with math.atan2() quadrant conventions (radians, or

pi([prec, limit, digits, rounding, max_refinements])

Return pi.

Module Contents

httk.core.exactmath.default_accuracy[source]
httk.core.exactmath.get_continued_fraction(p, q)[source]

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

Parameters:

  • p (int) – Numerator of the rational value.

  • q (int) – Denominator used for the rational value and continued-fraction steps.

Yield:

The next continued-fraction term.

httk.core.exactmath.best_rational_in_interval(low, high)[source]

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

Parameters:

  • low (Any) – Lower endpoint of the interval.

  • high (Any) – Upper endpoint of the interval.

Returns:

The rational in the interval with the smallest denominator.

Return type:

fractions.Fraction

httk.core.exactmath.fraction_from_continued_fraction(cf)[source]

Reconstruct a fractions.Fraction from continued-fraction terms.

Parameters:

cf (list[int]) – Continued-fraction terms in order.

Returns:

The reconstructed rational value.

Return type:

fractions.Fraction

httk.core.exactmath.string_to_val_and_delta(arg, min_accuracy=fractions.Fraction(1, 10000))[source]

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).

Parameters:

  • arg (str) – Numeric text, including a decimal, fraction, scientific notation, or uncertainty notation.

  • min_accuracy (fractions.Fraction | None) – Upper bound for inferred uncertainty, or None to disable inference.

Returns:

The central value and its absolute uncertainty.

Return type:

tuple[fractions.Fraction, fractions.Fraction]

httk.core.exactmath.any_to_fraction(arg, min_accuracy=fractions.Fraction(1, 10000))[source]

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

Strings are parsed for uncertainty via string_to_val_and_delta(). 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 min_accuracy to None to convert strings exactly.

Parameters:

  • arg (Any) – Value accepted by the fractions.Fraction constructor.

  • min_accuracy (fractions.Fraction | None) – Minimum assumed accuracy for string input, or None for exact conversion.

Returns:

The converted rational value.

Return type:

fractions.Fraction

httk.core.exactmath.integer_sqrt(n)[source]

Return the integer square root of n.

Parameters:

n (int) – Non-negative integer whose square root is required.

Returns:

The floor of the exact square root.

Return type:

int

httk.core.exactmath.sqrt(x, prec=default_accuracy, limit=True, digits=None, rounding='half_even', max_refinements=None, exact=False, *, coerce=None)[source]

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: scalar input yields an exact SurdScalar, while vector input yields a SurdVector. Both are squarefree-radical results 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.

Parameters:

  • x (httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike) – Scalar or vector value whose square root is required.

  • prec (fractions.Fraction) – Maximum absolute error requested for Fraction-mode approximation.

  • limit (bool) – Whether to constrain the approximation’s denominator using prec.

  • digits (int | None) – Significant digits for Decimal mode, or None for Fraction mode unless x is Decimal.

  • rounding (str) – Decimal rounding mode: "half_even" or "down".

  • max_refinements (int | None) – Maximum Decimal refinements, or None for the normal adaptive limit.

  • exact (bool) – Whether to return an exact squarefree-radical result.

  • coerce (Any) – Optional output view or value type; "natural" disables presentation coercion.

Returns:

The square root in the selected output domain, preserving vector shape.

Raises:

ValueError – If the input is negative, exact input is not rational, or Decimal-mode parameters are invalid.

Return type:

Any

httk.core.exactmath.cos(x, prec=default_accuracy, limit=True, degrees=False, digits=None, rounding='half_even', max_refinements=None, exact=False, *, coerce=None)[source]

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")).

Parameters:

  • x (httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike) – Scalar or vector angle.

  • prec (fractions.Fraction) – Maximum absolute error requested for Fraction-mode approximation.

  • limit (bool) – Whether to constrain the approximation’s denominator using prec.

  • degrees (bool) – Whether to interpret the angle in degrees instead of radians.

  • digits (int | None) – Significant digits for Decimal mode, or None for Fraction mode unless x is Decimal.

  • rounding (str) – Decimal rounding mode: "half_even" or "down".

  • max_refinements (int | None) – Maximum Decimal refinements, or None for the normal adaptive limit.

  • exact (bool) – Whether to return the exact supported degree-mode surd result.

  • coerce (Any) – Optional output view or value type; "natural" disables presentation coercion.

Returns:

The cosine in the selected output domain, preserving vector shape.

Raises:

ValueError – If exact mode is not degree mode, the angle is unsupported, or Decimal-mode parameters are invalid.

Return type:

Any

httk.core.exactmath.sin(x, prec=default_accuracy, limit=True, degrees=False, digits=None, rounding='half_even', max_refinements=None, exact=False, *, coerce=None)[source]

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

Parameters:

  • x (httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike) – Scalar or vector angle.

  • prec (fractions.Fraction) – Maximum absolute error requested for Fraction-mode approximation.

  • limit (bool) – Whether to constrain the approximation’s denominator using prec.

  • degrees (bool) – Whether to interpret the angle in degrees instead of radians.

  • digits (int | None) – Significant digits for Decimal mode, or None for Fraction mode unless x is Decimal.

  • rounding (str) – Decimal rounding mode: "half_even" or "down".

  • max_refinements (int | None) – Maximum Decimal refinements, or None for the normal adaptive limit.

  • exact (bool) – Whether to return the exact supported degree-mode surd result.

  • coerce (Any) – Optional output view or value type; "natural" disables presentation coercion.

Returns:

The sine in the selected output domain, preserving vector shape.

Raises:

ValueError – If exact mode is not degree mode, the angle is unsupported, or Decimal-mode parameters are invalid.

Return type:

Any

httk.core.exactmath.tan(x, degrees=False, prec=default_accuracy, limit=True, digits=None, rounding='half_even', max_refinements=None, exact=False, *, coerce=None)[source]

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

Parameters:

  • x (httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike) – Scalar or vector angle.

  • degrees (bool) – Whether to interpret the angle in degrees instead of radians.

  • prec (fractions.Fraction) – Maximum absolute error requested for Fraction-mode approximation.

  • limit (bool) – Whether to constrain the approximation’s denominator using prec.

  • digits (int | None) – Significant digits for Decimal mode, or None for Fraction mode unless x is Decimal.

  • rounding (str) – Decimal rounding mode: "half_even" or "down".

  • max_refinements (int | None) – Maximum Decimal refinements, or None for the normal adaptive limit.

  • exact (bool) – Whether to return the exact supported degree-mode surd result.

  • coerce (Any) – Optional output view or value type; "natural" disables presentation coercion.

Returns:

The tangent in the selected output domain, preserving vector shape.

Raises:

ValueError – If exact mode is not degree mode, the angle is unsupported, tangent is undefined, or Decimal-mode parameters are invalid.

Return type:

Any

httk.core.exactmath.exp(x, prec=default_accuracy, limit=True, digits=None, rounding='half_even', max_refinements=None, *, coerce=None)[source]

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

Parameters:

  • x (httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike) – Scalar or vector exponent.

  • prec (fractions.Fraction) – Maximum absolute error requested for Fraction-mode approximation.

  • limit (bool) – Whether to constrain the approximation’s denominator using prec.

  • digits (int | None) – Significant digits for Decimal mode, or None for Fraction mode unless x is Decimal.

  • rounding (str) – Decimal rounding mode: "half_even" or "down".

  • max_refinements (int | None) – Maximum Decimal refinements, or None for the normal adaptive limit.

  • coerce (Any) – Optional output view or value type; "natural" disables presentation coercion.

Returns:

The exponential in the selected output domain, preserving vector shape.

Raises:

ValueError – If Decimal-mode parameters are invalid.

Return type:

Any

httk.core.exactmath.log(x, base=None, prec=default_accuracy, limit=True, digits=None, rounding='half_even', max_refinements=None, *, coerce=None)[source]

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.

Parameters:

  • x (httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike) – Scalar or vector value whose logarithm is required.

  • base (httk.core.vectors.scalar_like.ScalarLike | None) – Logarithm base, or None for the natural logarithm.

  • prec (fractions.Fraction) – Maximum absolute error requested for Fraction-mode approximation.

  • limit (bool) – Whether to constrain the approximation’s denominator using prec.

  • digits (int | None) – Significant digits for Decimal mode, or None for Fraction mode unless an input is Decimal.

  • rounding (str) – Decimal rounding mode: "half_even" or "down".

  • max_refinements (int | None) – Maximum Decimal refinements, or None for the normal adaptive limit.

  • coerce (Any) – Optional output view or value type; "natural" disables presentation coercion.

Returns:

The logarithm in the selected output domain, preserving vector shape.

Raises:

ValueError – If the logarithm domain or Decimal-mode parameters are invalid.

Return type:

Any

httk.core.exactmath.log10(x, prec=default_accuracy, limit=True, digits=None, rounding='half_even', max_refinements=None, *, coerce=None)[source]

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.

Parameters:

  • x (httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike) – Scalar or vector value whose base-10 logarithm is required.

  • prec (fractions.Fraction) – Maximum absolute error requested for Fraction-mode approximation.

  • limit (bool) – Whether to constrain the approximation’s denominator using prec.

  • digits (int | None) – Significant digits for Decimal mode, or None for Fraction mode unless x is Decimal.

  • rounding (str) – Decimal rounding mode: "half_even" or "down".

  • max_refinements (int | None) – Maximum Decimal refinements, or None for the normal adaptive limit.

  • coerce (Any) – Optional output view or value type; "natural" disables presentation coercion.

Returns:

The base-10 logarithm in the selected output domain, preserving vector shape.

Raises:

ValueError – If the logarithm domain or Decimal-mode parameters are invalid.

Return type:

Any

httk.core.exactmath.asin(x, degrees=False, prec=default_accuracy, limit=True, digits=None, rounding='half_even', max_refinements=None, exact=False, *, coerce=None)[source]

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

Parameters:

  • x (httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike) – Scalar or vector value whose inverse sine is required.

  • degrees (bool) – Whether to return the angle in degrees instead of radians.

  • prec (fractions.Fraction) – Maximum absolute error requested for Fraction-mode approximation.

  • limit (bool) – Whether to constrain the approximation’s denominator using prec.

  • digits (int | None) – Significant digits for Decimal mode, or None for Fraction mode unless x is Decimal.

  • rounding (str) – Decimal rounding mode: "half_even" or "down".

  • max_refinements (int | None) – Maximum Decimal refinements, or None for the normal adaptive limit.

  • exact (bool) – Whether to return the exact supported degree-mode angle.

  • coerce (Any) – Optional output view or value type; "natural" disables presentation coercion.

Returns:

The inverse sine in the selected output domain, preserving vector shape.

Raises:

ValueError – If exact mode is not degree mode, the angle is unsupported, or Decimal-mode parameters are invalid.

Return type:

Any

httk.core.exactmath.acos(x, degrees=False, prec=default_accuracy, limit=True, digits=None, rounding='half_even', max_refinements=None, exact=False, *, coerce=None)[source]

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

Parameters:

  • x (httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike) – Scalar or vector value whose inverse cosine is required.

  • degrees (bool) – Whether to return the angle in degrees instead of radians.

  • prec (fractions.Fraction) – Maximum absolute error requested for Fraction-mode approximation.

  • limit (bool) – Whether to constrain the approximation’s denominator using prec.

  • digits (int | None) – Significant digits for Decimal mode, or None for Fraction mode unless x is Decimal.

  • rounding (str) – Decimal rounding mode: "half_even" or "down".

  • max_refinements (int | None) – Maximum Decimal refinements, or None for the normal adaptive limit.

  • exact (bool) – Whether to return the exact supported degree-mode angle.

  • coerce (Any) – Optional output view or value type; "natural" disables presentation coercion.

Returns:

The inverse cosine in the selected output domain, preserving vector shape.

Raises:

ValueError – If exact mode is not degree mode, the angle is unsupported, or Decimal-mode parameters are invalid.

Return type:

Any

httk.core.exactmath.atan(x, degrees=False, prec=default_accuracy, limit=True, digits=None, rounding='half_even', max_refinements=None, exact=False, *, coerce=None)[source]

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

Parameters:

  • x (httk.core.vectors.scalar_like.ScalarLike | httk.core.vectors.vector_like.VectorLike) – Scalar or vector value whose inverse tangent is required.

  • degrees (bool) – Whether to return the angle in degrees instead of radians.

  • prec (fractions.Fraction) – Maximum absolute error requested for Fraction-mode approximation.

  • limit (bool) – Whether to constrain the approximation’s denominator using prec.

  • digits (int | None) – Significant digits for Decimal mode, or None for Fraction mode unless x is Decimal.

  • rounding (str) – Decimal rounding mode: "half_even" or "down".

  • max_refinements (int | None) – Maximum Decimal refinements, or None for the normal adaptive limit.

  • exact (bool) – Whether to return the exact supported degree-mode angle.

  • coerce (Any) – Optional output view or value type; "natural" disables presentation coercion.

Returns:

The inverse tangent in the selected output domain, preserving vector shape.

Raises:

ValueError – If exact mode is not degree mode, the angle is unsupported, or Decimal-mode parameters are invalid.

Return type:

Any

httk.core.exactmath.atan2(y, x, degrees=False, prec=default_accuracy, limit=True, digits=None, rounding='half_even', max_refinements=None, exact=False, *, coerce=None)[source]

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.

Parameters:
Returns:

The quadrant-aware angle in the selected output domain, preserving vector shape.

Raises:

ValueError – If exact mode is not degree mode, the angle is unsupported, or Decimal-mode parameters are invalid.

Return type:

Any

httk.core.exactmath.pi(prec=default_accuracy, limit=True, digits=None, rounding='half_even', max_refinements=None)[source]

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.

Parameters:

  • prec (fractions.Fraction) – Maximum absolute error requested for the Fraction approximation.

  • limit (bool) – Whether to constrain the approximation’s denominator using prec.

  • digits (int | None) – Significant digits for Decimal mode, or None for Fraction mode.

  • rounding (str) – Decimal rounding mode: "half_even" or "down".

  • max_refinements (int | None) – Maximum Decimal refinements, or None for the normal adaptive limit.

Returns:

Pi in the Fraction or Decimal domain selected by digits.

Raises:

ValueError – If Decimal-mode parameters are invalid.

Return type:

fractions.Fraction | decimal.Decimal