:mod:`heat.array_api._array_object` =================================== .. py:module:: heat.array_api._array_object Module Contents --------------- .. py:class:: Array DNDarray object for the array API namespace. This is a wrapper around ``heat.DNDarray`` that restricts the usage to only those things that are required by the array API namespace. Note, attributes on this object that start with a single underscore are not part of the API specification and should only be used internally. This object should not be constructed directly. Rather, use one of the creation functions, such as ``asarray``. .. attribute:: _array :annotation: :heat.DNDarray .. role:: raw-html(raw) :format: html .. method:: _new(x, /) Initializes the array API Array object. Functions outside of the array_api submodule should not use this method. Use one of the creation functions instead, such as ``asarray``. :param x: Underlying ``DNDarray`` :type x: DNDarray .. method:: __str__(/) -> str Computes a printable representation of the Array. .. method:: __repr__(/) -> str Computes a printable representation of the Array. .. method:: __len__() -> int The length of the Array. .. method:: _check_allowed_dtypes(other: Union[bool, int, float, Array], dtype_category: str, op: str) -> Array Helper function for operators to only allow specific input dtypes Use like other = self._check_allowed_dtypes(other, 'numeric', '__add__') if other is NotImplemented: return other .. method:: _promote_scalar(scalar) Returns a promoted version of a Python scalar appropriate for use with operations on self. This may raise a ``TypeError`` when the scalar type is incompatible with the dtype of self. .. method:: _normalize_two_args(x1, x2) -> Tuple[Array, Array] Normalize inputs to two arg functions to fix type promotion rules Heat deviates from the spec type promotion rules in cases where one argument is 0-dimensional and the other is not. For example: >>> import heat as ht >>> a = ht.array([1.0], dtype=ht.float32) >>> b = ht.array(1.0, dtype=ht.float64) >>> ht.add(a, b) # The spec says this should be float64 DNDarray([2.], dtype=ht.float32, device=cpu:0, split=None) To fix this, we add a dimension to the 0-dimension array before passing it through. This works because a dimension would be added anyway from broadcasting, so the resulting shape is the same, but this prevents Heat from not promoting the dtype. .. method:: _validate_index(key) Validate an index according to the array API. The array API specification only requires a subset of indices that are supported by Heat. This function will reject any index that is allowed by Heat but not required by the array API specification. This function raises IndexError if the index ``key`` is invalid. .. method:: __abs__(/) -> Array Calculates the absolute value for each element of an array instance (i.e., the element-wise result has the same magnitude as the respective element but has positive sign). .. method:: __add__(other: Union[int, float, Array], /) -> Array Calculates the sum for each element of an array instance with the respective element of the array ``other``. :param other: Addend array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __and__(other: Union[int, bool, Array], /) -> Array Evaluates ``self_i & other_i`` for each element of an array instance with the respective element of the array ``other``. :param other: Other array. Must have an integer or boolean data type. :type other: Union[int, bool, Array] .. method:: __array_namespace__(/, *, api_version: Optional[str] = None) -> Any Returns an object that has all the array API functions on it. :param api_version: string representing the version of the array API specification to be returned, in ``'YYYY.MM'`` form. If it is ``None`` (default), it returns the namespace corresponding to latest version of the array API specification. :type api_version: Optional[str] .. method:: __bool__(/) -> bool Converts a zero-dimensional boolean array to a Python ``bool`` object. .. method:: __dlpack__(/, *, stream: Optional[Union[int, Any]] = None) -> heat.array_api._typing.PyCapsule Exports the array for consumption by ``from_dlpack()`` as a DLPack capsule. :param stream: For CUDA and ROCm, a Python integer representing a pointer to a stream, on devices that support streams. :type stream: Optional[Union[int, Any]] .. method:: __dlpack_device__(/) -> Tuple[enum.Enum, int] Returns device type and device ID in DLPack format. Meant for use within ``from_dlpack()``. .. method:: __eq__(other: Union[int, float, bool, Array], /) -> Array Computes the truth value of ``self_i == other_i`` for each element of an array instance with the respective element of the array ``other``. :param other: Other array. :type other: Union[int, float, bool, Array] .. method:: __float__(/) -> float Converts a zero-dimensional floating-point array to a Python ``float`` object. .. method:: __floordiv__(other: Union[int, float, Array], /) -> Array Evaluates ``self_i // other_i`` for each element of an array instance with the respective element of the array ``other``. :param other: Other array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __ge__(other: Union[int, float, Array], /) -> Array Computes the truth value of ``self_i >= other_i`` for each element of an array instance with the respective element of the array ``other``. :param other: Other array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __getitem__(key: Union[int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], Ellipsis], Array], /) -> Array Returns ``self[key]``. :param key: Index key :type key: Union[int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], ...], Array] .. method:: __gt__(other: Union[int, float, Array], /) -> Array Computes the truth value of ``self_i > other_i`` for each element of an array instance with the respective element of the array ``other``. :param other: Other array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __index__(/) -> int Converts a zero-dimensional integer array to a Python ``int`` object. .. method:: __int__(/) -> int Converts a zero-dimensional integer array to a Python ``int`` object. .. method:: __invert__(/) -> Array Evaluates ``~self_i`` for each element of an array instance. .. method:: __le__(other: Union[int, float, Array], /) -> Array Computes the truth value of ``self_i <= other_i`` for each element of an array instance with the respective element of the array ``other``. :param other: Other array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __lshift__(other: Union[int, Array], /) -> Array Evaluates ``self_i << other_i`` for each element of an array instance with the respective element of the array ``other``. :param other: Other array. Must have an integer data type. Each element must be greater than or equal to ``0``. :type other: Union[int, Array] .. method:: __lt__(other: Union[int, float, Array], /) -> Array Computes the truth value of ``self_i < other_i`` for each element of an array instance with the respective element of the array ``other``. :param other: Other array. Must have a numeric data type. :type other: Union[int, Array] .. method:: __matmul__(other: Array, /) -> Array Computes the matrix product. :param other: Other array. Must have a numeric data type and at least one dimension. :type other: Array .. method:: __mod__(other: Union[int, float, Array], /) -> Array Evaluates ``self_i % other_i`` for each element of an array instance with the respective element of the array ``other``. :param other: Other array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __mul__(other: Union[int, float, Array], /) -> Array Calculates the product for each element of an array instance with the respective element of the array ``other``. :param other: Other array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __ne__(other: Union[int, float, bool, Array], /) -> Array Computes the truth value of ``self_i != other_i`` for each element of an array instance with the respective element of the array ``other``. :param other: Other array. :type other: Union[int, float, bool, Array] .. method:: __neg__(/) -> Array Evaluates ``-self_i`` for each element of an array instance. .. method:: __or__(other: Union[int, bool, Array], /) -> Array Evaluates ``self_i | other_i`` for each element of an array instance with the respective element of the array ``other``. :param other: Other array. Must have an integer or boolean data type. :type other: Union[int, bool, Array] .. method:: __pos__(/) -> Array Evaluates ``+self_i`` for each element of an array instance. .. method:: __pow__(other: Union[int, float, Array], /) -> Array Calculates an approximation of exponentiation by raising each element (the base) of an array instance to the power of ``other_i`` (the exponent), where ``other_i`` is the corresponding element of the array ``other``. :param other: Other array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __rshift__(other: Union[int, Array], /) -> Array Evaluates ``self_i >> other_i`` for each element of an array instance with the respective element of the array ``other``. :param other: Other array. Must have an integer data type. Each element must be greater than or equal to ``0``. :type other: Union[int, Array] .. method:: __setitem__(key: Union[int, slice, ellipsis, Tuple[Union[int, slice, ellipsis], Ellipsis], Array], value: Union[int, float, bool, Array], /) -> None Sets ``self[key]`` to ``value``. .. method:: __sub__(other: Union[int, float, Array], /) -> Array Calculates the difference for each element of an array instance with the respective element of the array ``other``. :param other: Subtrahend array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __truediv__(other: Union[int, float, Array], /) -> Array Evaluates ``self_i / other_i`` for each element of an array instance with the respective element of the array ``other``. :param other: Subtrahend array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __xor__(other: Union[int, bool, Array], /) -> Array Evaluates ``self_i ^ other_i`` for each element of an array instance with the respective element of the array ``other``. :param other: Subtrahend array. Must have an integer or boolean data type. :type other: Union[int, bool, Array] .. method:: __radd__(other: Union[int, float, Array], /) -> Array Reflected version of ``__add__``. :param other: Addend array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __rfloordiv__(other: Union[int, float, Array], /) -> Array Reflected version of ``__floordiv__``. :param other: Other array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __rmod__(other: Union[int, float, Array], /) -> Array Reflected version of ``__rmod__``. .. method:: __rmul__(other: Union[int, float, Array], /) -> Array Reflected version of ``__mul__``. :param other: Other array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __rpow__(other: Union[int, float, Array], /) -> Array Reflected version of ``__rpow__``. :param other: Other array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __rsub__(other: Union[int, float, Array], /) -> Array Reflected version of ``__sub__``. :param other: Subtrahend array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: __rtruediv__(other: Union[float, Array], /) -> Array Reflected version of ``__truediv__``. :param other: Subtrahend array. Must have a numeric data type. :type other: Union[int, float, Array] .. method:: to_device(device: heat.array_api._typing.Device, /, stream: Optional[Union[int, Any]] = None) -> Array Copy the array from the device on which it currently resides to the specified ``device``. :param device: A ``Device`` object. :type device: Device :param stream: Stream object to use during copy. :type stream: Optional[Union[int, Any]]