httk.core.exactmath =================== .. py:module:: httk.core.exactmath .. autoapi-nested-parse:: Exact math on rationals and decimals: type-preserving transcendentals. This module provides the transcendental and helper functions used by :class:`~httk.core.vectors.fracvector.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 (:class:`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 :func:`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 (:class:`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 :mod:`decimal` module does not offer. The implementation uses the standard-library :mod:`fractions`. Attributes ---------- .. autoapisummary:: httk.core.exactmath.default_accuracy Functions --------- .. autoapisummary:: httk.core.exactmath.get_continued_fraction httk.core.exactmath.best_rational_in_interval httk.core.exactmath.fraction_from_continued_fraction httk.core.exactmath.string_to_val_and_delta httk.core.exactmath.any_to_fraction httk.core.exactmath.integer_sqrt httk.core.exactmath.sqrt httk.core.exactmath.cos httk.core.exactmath.sin httk.core.exactmath.tan httk.core.exactmath.exp httk.core.exactmath.log httk.core.exactmath.log10 httk.core.exactmath.asin httk.core.exactmath.acos httk.core.exactmath.atan httk.core.exactmath.atan2 httk.core.exactmath.pi Module Contents --------------- .. py:data:: default_accuracy .. py:function:: get_continued_fraction(p: int, q: int) -> collections.abc.Iterator[int] Yield the terms of the continued fraction expansion of ``p/q``. .. py:function:: best_rational_in_interval(low: Any, high: Any) -> fractions.Fraction Return the rational number with the smallest denominator lying in ``[low, high]``. .. py:function:: fraction_from_continued_fraction(cf: list[int]) -> fractions.Fraction Reconstruct a :class:`fractions.Fraction` from a list of continued-fraction terms. .. py:function:: 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``). .. py:function:: any_to_fraction(arg: Any, min_accuracy: fractions.Fraction | None = fractions.Fraction(1, 10000)) -> fractions.Fraction Convert an arbitrary numeric-like object into a :class:`fractions.Fraction`. :param arg: a number, string, Decimal, Fraction, or anything the Fraction constructor accepts. Strings are parsed for uncertainty via :func:`string_to_val_and_delta`. :param 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. .. py:function:: integer_sqrt(n: int) -> int Return the integer square root of ``n`` (the floor of its exact square root). .. py:function:: 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** :class:`~httk.core.vectors.surdvector.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. .. py:function:: 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")``). .. py:function:: 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. .. py:function:: 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. .. py:function:: 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. .. py:function:: 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. .. py:function:: 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. .. py:function:: 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. .. py:function:: 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. .. py:function:: 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. .. py:function:: 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 :func:`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. .. py:function:: 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``.