httk.core.vectors.numeric
=========================

.. py:module:: httk.core.vectors.numeric

.. autoapi-nested-parse::

   The *numeric* presentation of vectors: plain numpy numbers for callers who just want floats.

   Where the backend/view family (see :mod:`httk.core.vectors.vector_view`) lets the same tensor be
   seen as the exact :class:`~httk.core.vectors.fracvector.FracVector`, an exact
   :class:`~httk.core.vectors.surdvector.SurdVector`, a nested ``tuple``, or a
   :class:`numpy.ndarray`, the **numeric** concept is a convenience presentation one level above that:
   it is for users who do not care which representation carries the numbers and simply want plain
   numpy floats to compute with.

   The numeric presentation is **numpy-backed**, so a caller always knows the concrete type it gets:
   :func:`to_numeric` returns a base-class ``float64`` :class:`numpy.ndarray` for a tensor and a plain
   :class:`float` for a scalar — never a view subclass, never a 0-d array. :data:`NumericVector` is the
   generic name for what comes out.

   numpy is an optional dependency of *httk-core* (the ``httk-core[numpy]`` extra). :func:`to_numeric`
   therefore **requires numpy** and raises :class:`ImportError` when it is not installed. The scalar
   helper :func:`to_numeric_scalar` is the exception: converting a single value to a ``float`` needs no
   numpy, so it works unconditionally and never raises for a missing numpy.

   Use the numeric helpers when you just want numpy numbers; reach for a specific view
   (:class:`~httk.core.vectors.vector_numpy_view.VectorNumpyView`,
   :class:`~httk.core.vectors.vector_native_view.VectorNativeView`) when you need control over the exact
   container type, dtype, or leaf codec.



Attributes
----------

.. autoapisummary::

   httk.core.vectors.numeric.NumericVector


Functions
---------

.. autoapisummary::

   httk.core.vectors.numeric.numpy_available
   httk.core.vectors.numeric.to_numeric_scalar
   httk.core.vectors.numeric.to_numeric


Module Contents
---------------

.. 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_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: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.