httk.core.vectors ================= .. py:module:: httk.core.vectors .. autoapi-nested-parse:: Exact-rational vectors (:class:`FracVector`/:class:`FracScalar`/:class:`~httk.core.vectors.mutablefracvector.MutableFracVector`) and the Vector backend/view family that lets the same tensor data be viewed as the exact representation, plain nested sequences, or (optionally) numpy arrays. The exact-math helpers live in :mod:`httk.core.exactmath` (type-preserving exact transcendentals on Fraction and Decimal) and :mod:`httk.core.vectors.vectormath` (functional math wrappers). Submodules ---------- .. toctree:: :maxdepth: 1 /reference/autoapi/httk/core/vectors/fracvector/index /reference/autoapi/httk/core/vectors/leaf_codecs/index /reference/autoapi/httk/core/vectors/mutablefracvector/index /reference/autoapi/httk/core/vectors/numeric/index /reference/autoapi/httk/core/vectors/scalar_like/index /reference/autoapi/httk/core/vectors/surdvector/index /reference/autoapi/httk/core/vectors/vector_api/index /reference/autoapi/httk/core/vectors/vector_backend/index /reference/autoapi/httk/core/vectors/vector_frac_view/index /reference/autoapi/httk/core/vectors/vector_like/index /reference/autoapi/httk/core/vectors/vector_native_backend/index /reference/autoapi/httk/core/vectors/vector_native_view/index /reference/autoapi/httk/core/vectors/vector_numpy_backend/index /reference/autoapi/httk/core/vectors/vector_numpy_view/index /reference/autoapi/httk/core/vectors/vector_surd_view/index /reference/autoapi/httk/core/vectors/vector_view/index /reference/autoapi/httk/core/vectors/vectormath/index Attributes ---------- .. autoapisummary:: httk.core.vectors.NumericVector httk.core.vectors.ScalarLike httk.core.vectors.VectorLike Classes ------- .. autoapisummary:: httk.core.vectors.FracScalar httk.core.vectors.FracVector httk.core.vectors.LeafCodec httk.core.vectors.MutableFracVector httk.core.vectors.SurdScalar httk.core.vectors.SurdVector httk.core.vectors.VectorAPI httk.core.vectors.VectorBackend httk.core.vectors.VectorFracView httk.core.vectors.VectorNativeBackend httk.core.vectors.VectorNativeView httk.core.vectors.VectorSurdView httk.core.vectors.VectorView Functions --------- .. autoapisummary:: httk.core.vectors.known_leaf_codecs httk.core.vectors.register_leaf_codec httk.core.vectors.numpy_available httk.core.vectors.to_numeric httk.core.vectors.to_numeric_scalar Package Contents ---------------- .. py:class:: FracScalar(value, *, denom = None, simplify = False, chain = False, min_accuracy = fractions.Fraction(1, 10000)) Bases: :py:obj:`FracVector` Represents the fractional number ``nom/denom``. This is a subclass of FracVector with the purpose of making it clear when a scalar fracvector is needed/used. Convert a value into a FracScalar. ``FracScalar(something)`` where ``something`` may be any object that can be used in the constructor of the Python Fraction class (also works with strings!). For signature compatibility with the :class:`~httk.core.vectors.fracvector.FracVector` constructor, this accepts but ignores ``chain`` and ``min_accuracy``, and converts strings exactly via the Fraction constructor. :param value: The scalar value or values to convert. :param denom: An optional additional denominator. :param simplify: Whether to reduce the resulting denominator. :param chain: An accepted compatibility parameter; it does not affect scalar creation. :param min_accuracy: An accepted compatibility parameter; scalar strings are exact. .. py:class:: FracVector(values, *, denom = None, simplify = False, chain = False, min_accuracy = fractions.Fraction(1, 10000)) Bases: :py:obj:`FracVectorBase`, :py:obj:`httk.core.vectors.vector_backend.VectorBackend` Immutable exact-rational vector that is also its own vector backend. .. py:property:: fractions :type: httk.core.vectors.vector_api.Fractions Return this vector in the exact nested Fraction interchange format. .. py:class:: LeafCodec A leaf codec: a documented conversion of one exact :class:`fractions.Fraction` leaf into a presentation leaf. A codec is an orthogonal layer beside the vector backends: given a value already reduced to the canonical Fraction hub, it produces the requested element type. Its :attr:`from_fraction` documents both its exactness contract (when the result is exact) and its default conversion (what it does when an exact result is impossible); on data it never raises. :param name: The canonical name used to select the codec. :param from_fraction: The conversion operation applied to each exact hub leaf. :param check_options: The option-validation operation. .. py:attribute:: name :type: str Canonical codec name (e.g. ``"int"``); also how an explicit ``leaf=`` hint selects it. .. py:attribute:: from_fraction :type: collections.abc.Callable[..., Any] Convert ``(value: fractions.Fraction, **options) -> leaf`` from the canonical Fraction hub. .. py:attribute:: check_options :type: collections.abc.Callable[[dict[str, Any]], None] Validate an options mapping eagerly, raising :class:`ValueError` on any invalid option. .. py:function:: known_leaf_codecs() Return the registered leaf-codec names in registration order. :return: The registered codec names. .. py:function:: register_leaf_codec(codec) Register or replace a codec under its :attr:`~LeafCodec.name`. :param codec: The codec to register. .. py:class:: MutableFracVector(values, *, denom = None, simplify = False, chain = False, min_accuracy = fractions.Fraction(1, 10000)) Bases: :py:obj:`httk.core.vectors.fracvector.FracVectorBase` Same as :class:`~httk.core.vectors.fracvector.FracVector`, only this version allows assignment of elements, e.g.:: mfracvec[2, 7] = 5 and, e.g.:: mfracvec[:, 7] = [1, 2, 3, 4] Other than this, the FracVector methods exist and do the same, i.e., they return *copies* of the fracvector, rather than modifying it. :param values: A rational value-like to convert, such as nested sequences or scalars. :param denom: An optional additional common denominator. :param simplify: Whether to reduce the resulting denominator. :param chain: Whether to flatten the outermost nested sequence. :param min_accuracy: Minimum accuracy for decimal values, or ``None`` for exact conversion. Methods with ``set_*`` prefixes perform mutating operations, e.g.:: A.set_T() replaces A with its own transpose, whereas:: A.T() just returns a new MutableFracVector that is the transpose of A, leaving A unmodified. .. py:attribute:: nested_map :type: ClassVar[collections.abc.Callable[..., Any]] .. py:attribute:: nested_inmap :type: ClassVar[collections.abc.Callable[..., Any]] .. py:attribute:: nested_map_fractions :type: ClassVar[collections.abc.Callable[..., Any]] .. py:attribute:: noms :type: Any .. py:method:: validate() Return whether the vector's stored list structure is valid. .. py:method:: invalidate() Internal method to call when the MutableFracVector is changed in such a way that cached properties are invalidated (e.g., ``_dim``). :return: None. .. py:method:: set_negative() Change the MutableFracVector inline into its own negative: ``self -> -self``. .. py:method:: set_T() Change the MutableFracVector inline into its own transpose: ``self -> self.T``. .. py:method:: set_inv() Change the MutableFracVector inline into its own inverse: ``self -> self^-1``. :return: The inverse scalar when ``self`` is scalar; otherwise ``None`` after mutation. .. py:method:: set_simplify() Change the MutableFracVector; reduces any common factor between the denominator and all nominators. .. py:method:: set_set_denominator(resolution = 1000000000) Change the MutableFracVector; reduces resolution. :param resolution: The new denominator; each element becomes the closest numerical approximation using this denominator. .. py:method:: set_normalize() Add/remove an integer +/-N to each element to place it in the range [0, 1). .. py:method:: set_normalize_half() Add/remove an integer +/-N to each element to place it in the range [-1/2, 1/2). This is useful to find the shortest vector C between two points A, B in a space with periodic boundary conditions [0, 1):: C = (A - B).normalize_half() .. py:type:: NumericVector :canonical: float | numpy.ndarray .. py:function:: numpy_available() Return whether the optional numpy dependency is available for the numeric helpers. This reads the vectors package's ``_numpy_available`` flag freshly on each call (the flag set when :mod:`httk.core.vectors` conditionally imports/registers the numpy backend), so tests may monkeypatch ``httk.core.vectors._numpy_available`` to exercise the numpy-absent path. :return: ``True`` when numpy is available, otherwise ``False``. .. py:function:: to_numeric(obj) Present ``obj`` as plain numpy numbers: a :class:`numpy.ndarray` for a tensor, a ``float`` for a scalar. A tensor becomes a base-class ``float64`` :class:`numpy.ndarray` (never a view subclass) via :class:`~httk.core.vectors.vector_numpy_view.VectorNumpyView`; a **scalar** input (shape ``()``) returns a plain :class:`float` via :func:`to_numeric_scalar` (never a 0-d array). The numeric presentation is numpy-backed, so this **always requires numpy**: it raises :class:`ImportError` (naming the ``httk-core[numpy]`` extra) when numpy is not installed, uniformly, so the contract is predictable regardless of the input shape. Use :func:`to_numeric_scalar` directly for a single float without a numpy requirement. :param obj: The vector-like value to present numerically. :return: The converted scalar or tensor value. :raises ImportError: If numpy is unavailable. :raises TypeError: If the value cannot be converted to the numeric presentation. .. py:function:: to_numeric_scalar(obj) Convert a single scalar value to a plain :class:`float`, deterministically. A :class:`~httk.core.vectors.surdvector.SurdScalar` (or scalar :class:`~httk.core.vectors.surdvector.SurdVector`) and a scalar :class:`~httk.core.vectors.fracvector.FracVector` render through their own exact ``to_float()``; a :class:`~fractions.Fraction`, ``int``, ``float``, or numeric ``str`` render via :func:`~httk.core.exactmath.any_to_fraction`. A non-scalar shape raises :class:`TypeError`. Unlike :func:`to_numeric`, this needs **no numpy**: a plain ``float`` conversion has no numpy dependency, so it works unconditionally and never raises for a missing numpy. :param obj: The scalar value to convert. :return: The converted scalar value. :raises TypeError: If ``obj`` is not scalar or cannot be converted to a scalar float. .. py:type:: ScalarLike :canonical: int | float | str | fractions.Fraction | decimal.Decimal | fracvector.FracScalar | surdvector.SurdScalar .. py:class:: SurdScalar(value, dim = None) Bases: :py:obj:`SurdVector` A scalar :class:`SurdVector` (shape ``()``): a single field element :math:`\sum_r q_r\sqrt r`. Adds the scalar-only operations — the field inverse, exact sign and ordering, and Decimal rendering — that need a single value rather than a tensor. :param value: A rational scalar/nested sequence accepted by :class:`~httk.core.vectors.fracvector.FracVector`, or an existing SurdVector or SurdScalar, returned unchanged. .. py:method:: inverse() Return the multiplicative inverse ``1/self`` (raises :class:`ZeroDivisionError` on zero). :return: The exact multiplicative inverse. .. py:method:: sign() Return the exact sign of the value: ``-1``, ``0`` or ``1``. For an irrational value the sign is decided by refining rational lower/upper bounds on each ``sqrt(r)`` (from :func:`~httk.core.exactmath.integer_sqrt` at increasing precision) and summing the weighted intervals until the total interval excludes zero — which always happens in finitely many steps because a nonzero surd is bounded away from zero. :return: ``-1``, ``0``, or ``1`` according to the exact sign. .. py:method:: cos_degrees(q) :classmethod: Return ``cos(q degrees)`` as an exact :class:`SurdScalar`, or None when it is not a surd. The value lies in the squarefree-radical field precisely when the angle, reduced modulo 360, is a **multiple of 15 or of 36 degrees** — e.g. :math:`\cos 30° = \tfrac{\sqrt3}2`, :math:`\cos 15° = \tfrac{\sqrt6+\sqrt2}4`, :math:`\cos 36° = \tfrac{1+\sqrt5}4`. ``q`` may be an int, :class:`~fractions.Fraction`, or numeric string (parsed via :func:`~httk.core.exactmath.any_to_fraction`). That list is **complete**: :math:`\cos(2\pi a/b)` lies in a field generated by square roots of rationals iff the Galois group :math:`(\mathbb{Z}/b)^\times/\{\pm1\}` of :math:`\mathbb{Q}(\cos 2\pi/b)` has exponent at most 2, which holds exactly for :math:`b \in \{1,2,3,4,5,6,8,10,12,24\}` — the rational-degree angles that are multiples of 15° or 36°. (Niven's theorem is the rational-value special case of this classification.) A ``None`` result is therefore a proof that the exact cosine lies outside :math:`\mathbb{Q}[\sqrt n]` — use :func:`~httk.core.exactmath.cos` with ``degrees=True`` for a deterministic rational approximation in that case. :param q: The angle in degrees. :return: The exact cosine, or ``None`` outside the surd field. .. py:method:: sin_degrees(q) :classmethod: Return ``sin(q degrees)`` as an exact :class:`SurdScalar`, or ``None`` when the value lies outside the supported surd field (when ``90 - q`` is not in the exact surd-cosine set). Computed as ``cos(90 - q)`` degrees, so exactness follows the same classification as :meth:`cos_degrees` applied to ``90 - q``: exact when ``90 - q`` is a multiple of 15 or 36 degrees, and ``None`` otherwise (a proof that the exact sine is outside the field). For example, ``sin(54°)`` is exact because it is ``cos(36°)``. :param q: The angle in degrees. :return: The exact sine, or ``None`` outside the surd field. .. py:method:: acos_degrees() Return the exact ``arccos`` of this value in **degrees** over :math:`[0, 180]`, or None. This is the reverse table lookup: the result is an exact rational number of degrees precisely when the value equals the cosine of a multiple of 15° or 36° (the complete set of rational-degree angles with surd cosines — see :meth:`cos_degrees`), decided by exact surd equality; otherwise None (the exact angle is then irrational in degrees). Raises :class:`ValueError` — decided exactly via :meth:`sign` — when the value lies outside :math:`[-1, 1]`. :return: The exact angle in degrees, or ``None`` when not represented by the table. .. py:method:: to_float(prec = fractions.Fraction(1, 10**30)) Return the value as a float via a high-precision exact rational approximation. :param prec: The maximum approximation error. :return: The value as a float. .. py:method:: to_decimal(digits = None, rounding = 'half_even', max_refinements = None) Render the value as a correctly-rounded :class:`decimal.Decimal`. Reuses the exact-math module's Ziv refinement loop (``_to_decimal``): a rational value renders exactly (its finite expansion when it fits, else quantized), and an irrational surd — never on a rational rounding boundary — is rendered by refining the rational approximation until the rounding is determined. ``digits`` (significant digits; default: the active decimal context precision), ``rounding`` (``"half_even"``/``"down"``) and ``max_refinements`` match :func:`~httk.core.exactmath.sqrt` in Decimal mode. :param digits: The number of significant decimal digits, or the active context precision when omitted. :param rounding: The decimal rounding mode. :param max_refinements: The maximum number of approximation refinements. :return: The correctly rounded decimal value. .. py:class:: SurdVector(value, dim = None) Bases: :py:obj:`httk.core.vectors.vector_backend.VectorBackend` An *immutable* exact tensor over the squarefree-radical field :math:`\mathbb{Q}[\sqrt n : n\ \text{squarefree}]`. A SurdVector is a map ``{squarefree radicand -> FracVector coefficient}`` (all coefficients sharing one ``dim``); radicand ``1`` is the rational part. It is stored **canonically** — coefficients simplified, all-zero coefficients dropped — so the representation is unique and equality/zero-detection are exact. Like :class:`~httk.core.vectors.fracvector.FracVector` it is immutable and hashable. See the module docstring for the field facts, the fractional-vs-Cartesian motivation, and the magnitude-vs-linear-structure purpose boundary. :param value: An existing SurdVector or SurdScalar, returned unchanged; a rational scalar/nested sequence accepted by :class:`~httk.core.vectors.fracvector.FracVector` (which becomes the radicand-1 component); or a ``{squarefree radicand -> FracVector coefficient}`` mapping in canonical component form (as emitted by ``repr()``). Non-squarefree radicands are not folded here — use :meth:`from_radicand_map` for that. :param dim: The shared coefficient shape, used only with the mapping form; inferred from the coefficients when omitted, and required to pin the shape of an all-zero (empty) mapping. .. py:method:: from_radicand_map(mapping) :classmethod: Compose a SurdVector from a ``{radicand -> coefficient}`` mapping. Radicands are positive integers and need not be squarefree — each is normalized via ``square_part`` (``sqrt(radicand) = s*sqrt(r)``) and the coefficients (FracVector-like, all of one shape) folded together canonically. :param mapping: Radicands mapped to their coefficient tensors. :return: The canonical SurdVector representation. .. py:method:: sqrt_of(q) :classmethod: Return the exact square root of a nonnegative rational ``q`` as a :class:`SurdScalar`. The result is a plain rational when ``q`` is a perfect square (e.g. ``sqrt_of(4/9) == 2/3``) and otherwise a single-radical surd (``sqrt_of(8) == 2*sqrt(2)``). ``sqrt(p/q)`` is normalized as ``sqrt(p*q)/q`` so the stored radicand is always a positive squarefree integer (``sqrt_of(1/2) == sqrt(2)/2``). Raises :class:`ValueError` on a negative argument — there is no exact square root of a surd (no nested radicals), only of a rational. :param q: A nonnegative rational value. :return: Its exact square root. .. py:method:: zero(dim = ()) :classmethod: The zero SurdVector of shape ``dim`` (a :class:`SurdScalar` for the default ``()``). :param dim: The shape of the zero tensor. :return: The zero SurdVector or SurdScalar. .. py:method:: one() :classmethod: The scalar ``1``. .. py:property:: dim :type: tuple[int, ...] The shape tuple, as for :attr:`~httk.core.vectors.fracvector.FracVectorBase.dim`. .. py:property:: is_rational :type: bool True iff the value is purely rational (only the radicand-1 term is present). .. py:method:: is_zero() True iff the value is exactly zero (empty canonical form). .. py:property:: radicands :type: tuple[int, ...] The sorted squarefree radicands present in the canonical form. .. py:method:: coefficient(radicand) Return the FracVector coefficient of ``sqrt(radicand)`` (a zero tensor when absent). :param radicand: The radicand whose coefficient to retrieve. :return: The coefficient, or a zero tensor when absent. .. py:method:: T() Return the transpose, transposing each radicand's coefficient tensor. :return: The transposed tensor. .. py:method:: dot(other) Return the vector dot product of two 1-D SurdVectors (``sum a_i b_i``). :param other: The other 1-D SurdVector. :return: The exact scalar dot product. .. py:method:: lengthsqr() Return the squared length ``A * A^T`` as a :class:`SurdScalar`. :return: The exact squared length. .. py:method:: length() Return the exact length ``sqrt(lengthsqr)`` as a :class:`SurdScalar`. Exact precisely when ``lengthsqr`` is rational — which canonical arithmetic guarantees for a difference of Cartesian sites under a rational metric (the crystallographic case). When ``lengthsqr`` is itself irrational the length would be a nested radical (``sqrt(a + b*sqrt(c))``), which is outside the field, so this raises :class:`ValueError`. :return: The exact length when the squared length is rational. .. py:method:: det() Return the determinant of a 3x3 SurdVector as a :class:`SurdScalar`. :return: The exact determinant. .. py:method:: inv() Return the inverse of a 3x3 SurdVector via the adjugate and the scalar field inverse. :return: The exact inverse matrix. .. py:method:: to_fractions_approx(prec = fractions.Fraction(1, 10**30)) A deterministic nested list of :class:`fractions.Fraction` within ``prec`` of the true value. Exact (not merely within ``prec``) whenever the value is rational. This is the ``compute(prec)``-shaped rational approximation reused by the Decimal rendering. :param prec: The maximum elementwise approximation error. :return: Nested rational approximations of the values. .. py:method:: to_floats(prec = fractions.Fraction(1, 10**30)) Return a nested list of floats via a high-precision exact rational approximation. :param prec: The maximum elementwise approximation error. :return: Nested floating-point approximations of the values. .. py:property:: fractions :type: httk.core.vectors.vector_api.Fractions Return the exact or deterministic rational hub representation. .. py:property:: fractions_exact :type: bool Return whether the Fraction interchange is exact for this surd. .. py:class:: VectorAPI Bases: :py:obj:`abc.ABC` Abstract base class for the canonical vector interface. It declares the ``fractions`` accessor (a nested tuple of :class:`fractions.Fraction`, or a bare Fraction for a scalar) that every vector backend produces from its own native representation and every vector view builds its presentation from, together with the ``dim`` shape tuple. The interchange is exact when :attr:`fractions_exact` is True; members such as irrational surds whose hub is a deterministic approximation report False, and exact construction paths refuse them. This is the single interchange format; there is no pairwise conversion between backends. On top of the two abstract accessors it provides the guaranteed float renderings :meth:`to_floats` and :meth:`to_float`, derived from the ``fractions`` hub — so *whatever* object the family hands you, ``.to_floats()`` works. (The exact value types :class:`~httk.core.vectors.fracvector.FracVector` and :class:`~httk.core.vectors.surdvector.SurdVector` honor the same contract with their own implementations, while the numpy backend adds a dtype-guarded fast path with the hub as fallback. Surd values render floats at fixed high precision independent of the decimal context, unlike the hub's context-precision reduction. .. py:property:: fractions :type: Fractions :abstractmethod: Return the Fraction interchange representation. .. py:property:: fractions_exact :type: bool Return whether ``fractions`` reproduces this value exactly. Members whose Fraction interchange may be a deterministic approximation override this property with ``False``; exact construction paths must refuse those members. .. py:property:: dim :type: tuple[int, ...] :abstractmethod: Return the tensor shape as a tuple of dimensions. .. py:method:: to_floats() Return the value as nested lists of floats. The value as (possibly nested) plain lists of ``float`` — a bare ``float`` for a scalar. Derived from the ``fractions`` hub; when :attr:`fractions_exact` is False, the result is the member's deterministic approximation. Nested lists match the ``numpy.ndarray.tolist()`` convention and are directly JSON-serializable. :return: The rendered value. .. py:method:: to_float() Return the scalar value as a plain ``float``. Raises :class:`TypeError` on a non-scalar. :return: The rendered scalar value. :raises TypeError: If the value is not scalar. .. py:class:: VectorBackend(backend, **hints) Bases: :py:obj:`httk.core.views.Backend`\ [\ :py:obj:`VectorBackend`\ ], :py:obj:`httk.core.vectors.vector_api.VectorAPI` Abstract base class for all backends of vector (tensor) data. Concrete backends carry a native representation (an exact FracVector, plain nested sequences, or a numpy array) and produce the canonical exactness-preserving ``fractions`` interchange declared by :class:`~httk.core.vectors.vector_api.VectorAPI` from it. Concrete subclasses select the accepted input and optional dispatch hints in their ``_backend_adopt`` hooks. .. py:attribute:: backend_classes :type: ClassVar[list[type[httk.core.views.Backend[Any]]]] .. py:class:: VectorFracView(obj, **hints) Bases: :py:obj:`httk.core.vectors.vector_view.VectorView`, :py:obj:`httk.core.vectors.fracvector.FracVector` A view presenting an underlying vector backend as an exact :class:`~httk.core.vectors.fracvector.FracVector`. This view is a genuine FracVector, so it can be passed anywhere a FracVector is accepted, and it exposes the full exact-rational algebra (``det``/``inv``/``*``/...). It is built lazily on first access — adopting a frac backend's FracVector directly, otherwise converting from the backend's exact ``fractions`` interchange — so the round-trip is exactness-preserving for the frac and native backends. (numpy values are binary rationals, so a numpy source round-trips to the exact float64 rational, not necessarily the original decimal fraction.) Because inherited FracVector algebra builds its results with the low-level ``self.__class__._of(noms, denom)`` constructor, results built that way are plain (backend-less) FracVector values presented through this class. :param obj: The source value to present. :param \**hints: Backend-selection and view-conversion hints. .. py:property:: fractions_exact :type: bool Return whether this view's Fraction interchange is exact. .. py:property:: noms :type: httk.core.vectors.fracvector.Noms Return the materialized numerator data. .. py:property:: denom :type: int Return the materialized common denominator. .. py:method:: unwrap() Return the underlying unwrapped vector, or this value when no backend remains. .. py:method:: unview() Return a plain FracVector containing this view's presented data. .. py:type:: VectorLike :canonical: vector_backend.VectorBackend | vector_view.VectorView | fracvector.FracVector | surdvector.SurdVector | tuple[Any, ...] | list[Any] | 'numpy.ndarray' .. py:class:: VectorNativeBackend(obj, **hints) Bases: :py:obj:`httk.core.vectors.vector_backend.VectorBackend` Backend for a vector backed by plain nested sequences. The native representation is a (possibly nested) rectangular list or tuple whose leaves are ``int``, ``float``, :class:`decimal.Decimal`, :class:`fractions.Fraction`, or ``str``. Conversion into the exact ``fractions`` interchange goes through :class:`~httk.core.vectors.fracvector.FracVector`, so string-uncertainty parsing (e.g. ``"0.33342(10)"``) works here too. ``unwrap`` returns the original raw object. :param obj: The rectangular source data to wrap. :param \**hints: Optional backend-selection hints. .. py:property:: native :type: Any The original nested list/tuple this backend wraps, leaves untouched. This is the same object returned by :meth:`unwrap`, exposed as a named accessor so the native view can present a natively-held vector's leaves *verbatim* (its preserve-original default) without reaching into private state. .. py:property:: fractions :type: httk.core.vectors.vector_api.Fractions Return the native value in the exact Fraction interchange format. .. py:property:: dim :type: tuple[int, ...] Return the native value's shape. .. py:method:: unwrap() Return the original nested list or tuple. .. py:class:: VectorNativeView(obj, **hints) Bases: :py:obj:`httk.core.vectors.vector_view.VectorView`, :py:obj:`tuple` A view presenting an underlying vector backend as nested tuples, with a selectable *leaf codec*. The leaf codec is the element-domain axis (see :mod:`httk.core.vectors.leaf_codecs`); it is chosen with the ``leaf=`` hint plus any codec options (``rounding=``, ``digits=``, ...). There are three modes: - **preserve-original** (``leaf=None``, and the source is natively-held data): the backend's original nested leaves are presented *verbatim* — the same objects, only containers tuple-ized (``Decimal``\\ s in, the same ``Decimal``\\ s out). - **exact default** (``leaf=None``, source crossing from a frac/numpy backend): the ``"exact"`` codec — ``int`` when integral, else :class:`fractions.Fraction`, never a float. - **explicit codec** (``leaf="int"``/``"float"``/``"decimal"``/``"fraction"``/...): every element is converted from the backend's exact ``fractions`` interchange through that codec. The codec name and its options are validated eagerly at construction (an unknown codec name or invalid option raises :class:`ValueError`); a codec never raises on the *data* — a value it cannot represent exactly takes the codec's documented default conversion, because the backend keeps the exact original. A scalar source is presented as a single-element tuple. :param obj: The source value to present. :param \**hints: Backend-selection, leaf-codec, and codec-option hints. .. py:method:: unwrap() Return the underlying unwrapped vector. .. py:method:: unview() Return a plain tuple containing the presented leaves. .. py:class:: VectorSurdView(obj, **hints) Bases: :py:obj:`httk.core.vectors.vector_view.VectorView`, :py:obj:`httk.core.vectors.surdvector.SurdVector` A view presenting an underlying vector backend as an exact :class:`~httk.core.vectors.surdvector.SurdVector`. This view is a genuine SurdVector, so it exposes the full exact surd algebra (``det``/``inv``/``*``/``length``/``...). It is built lazily on first access, following the immutable-subclass pattern of :class:`~httk.core.vectors.vector_frac_view.VectorFracView`: from a surd backend it adopts the exact SurdVector directly, and from a frac/native/numpy backend it embeds the backend's exact rational ``fractions`` at radicand 1 — exactly, since every rational is a surd. (numpy values are binary rationals, so a numpy source embeds the exact float64 rational, not necessarily the original decimal fraction — the same caveat as :class:`~httk.core.vectors.vector_frac_view.VectorFracView`.) :param obj: The source value to present. :param \**hints: Backend-selection and view-conversion hints. .. py:property:: fractions_exact :type: bool Return whether this view's Fraction interchange is exact. .. py:method:: unwrap() Return the underlying unwrapped vector, or this value when no backend remains. .. py:method:: unview() Return a plain SurdVector containing this view's presented data. .. py:class:: VectorView Bases: :py:obj:`httk.core.views.View`\ [\ :py:obj:`httk.core.vectors.vector_backend.VectorBackend`\ ] Abstract base class for all views of vector (tensor) data. Concrete views present a backend through a specific container or leaf domain while retaining access to the underlying backend.