:mod:`heat` =========== .. py:module:: heat .. autoapi-nested-parse:: add modules/namespaces to the heat namespace Subpackages ----------- .. toctree:: :titlesonly: :maxdepth: 3 array_api/index.rst classification/index.rst cluster/index.rst core/index.rst datasets/index.rst decomposition/index.rst fft/index.rst graph/index.rst naive_bayes/index.rst nn/index.rst optim/index.rst preprocessing/index.rst regression/index.rst sparse/index.rst spatial/index.rst testing/index.rst utils/index.rst Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 cli/index.rst Package Contents ---------------- .. py:class:: finfo Class describing machine limits (bit representation) of floating point types. :ivar bits: The number of bits occupied by the type. :vartype bits: int :ivar eps: The smallest representable positive number such that ``1.0 + eps != 1.0``. Type of ``eps`` is an appropriate floating point type. :vartype eps: float :ivar max: The largest representable number. :vartype max: float :ivar min: The smallest representable number, typically ``-max``. :vartype min: float :ivar tiny: The smallest positive usable number. Type of ``tiny`` is an appropriate floating point type. :vartype tiny: float :param dtype: Kind of floating point data-type about which to get information. :type dtype: datatype .. rubric:: Examples >>> import heat as ht >>> info = ht.types.finfo(ht.float32) >>> info.bits 32 >>> info.eps 1.1920928955078125e-07 .. role:: raw-html(raw) :format: html .. method:: _init(dtype: Type[datatype]) .. py:class:: iinfo Class describing machine limits (bit representation) of integer types. :ivar bits: The number of bits occupied by the type. :vartype bits: int :ivar max: The largest representable number. :vartype max: float :ivar min: The smallest representable number, typically ``-max``. :vartype min: float :param dtype: Kind of floating point data-type about which to get information. :type dtype: datatype .. rubric:: Examples >>> import heat as ht >>> info = ht.types.iinfo(ht.int32) >>> info.bits 32 .. role:: raw-html(raw) :format: html .. method:: _init(dtype: Type[datatype]) .. data:: __version__ :annotation: :str = '1.8.0' The combined version string, consisting out of major, minor, micro and possibly extension. .. function:: add(t1: Union[heat.core.dndarray.DNDarray, float], t2: Union[heat.core.dndarray.DNDarray, float], /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Element-wise addition of values from two operands, commutative. Takes the first and second operand (scalar or :class:`~heat.core.dndarray.DNDarray`) whose elements are to be added as argument and returns a ``DNDarray`` containing the results of element-wise addition of ``t1`` and ``t2``. :param t1: The first operand involved in the addition :type t1: DNDarray or scalar :param t2: The second operand involved in the addition :type t2: DNDarray or scalar :param out: The output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the added value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> import heat as ht >>> ht.add(1.0, 4.0) DNDarray(5., dtype=ht.float32, device=cpu:0, split=None) >>> T1 = ht.float32([[1, 2], [3, 4]]) >>> T2 = ht.float32([[2, 2], [2, 2]]) >>> ht.add(T1, T2) DNDarray([[3., 4.], [5., 6.]], dtype=ht.float32, device=cpu:0, split=None) >>> s = 2.0 >>> ht.add(T1, s) DNDarray([[3., 4.], [5., 6.]], dtype=ht.float32, device=cpu:0, split=None) .. function:: bitwise_and(t1: Union[heat.core.dndarray.DNDarray, float], t2: Union[heat.core.dndarray.DNDarray, float], /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Compute the bitwise AND of two :class:`~heat.core.dndarray.DNDarray` ``t1`` and ``t2`` element-wise. Only integer and boolean types are handled. If ``t1.shape!=t2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output) :param t1: The first operand involved in the operation :type t1: DNDarray or scalar :param t2: The second operand involved in the operation :type t2: DNDarray or scalar :param out: The output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the added value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> ht.bitwise_and(13, 17) DNDarray(1, dtype=ht.int64, device=cpu:0, split=None) >>> ht.bitwise_and(14, 13) DNDarray(12, dtype=ht.int64, device=cpu:0, split=None) >>> ht.bitwise_and(ht.array([14, 3]), 13) DNDarray([12, 1], dtype=ht.int64, device=cpu:0, split=None) >>> ht.bitwise_and(ht.array([11, 7]), ht.array([4, 25])) DNDarray([0, 1], dtype=ht.int64, device=cpu:0, split=None) >>> ht.bitwise_and(ht.array([2, 5, 255]), ht.array([3, 14, 16])) DNDarray([ 2, 4, 16], dtype=ht.int64, device=cpu:0, split=None) >>> ht.bitwise_and(ht.array([True, True]), ht.array([False, True])) DNDarray([False, True], dtype=ht.bool, device=cpu:0, split=None) .. data:: bitwise_not Alias for :py:func:`invert` .. function:: bitwise_or(t1: Union[heat.core.dndarray.DNDarray, float], t2: Union[heat.core.dndarray.DNDarray, float], /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Compute the bit-wise OR of two :class:`~heat.core.dndarray.DNDarray` ``t1`` and ``t2`` element-wise. Only integer and boolean types are handled. If ``t1.shape!=t2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output) :param t1: The first operand involved in the operation :type t1: DNDarray or scalar :param t2: The second operand involved in the operation :type t2: DNDarray or scalar :param out: The output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the added value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> ht.bitwise_or(13, 16) DNDarray(29, dtype=ht.int64, device=cpu:0, split=None) >>> ht.bitwise_or(32, 2) DNDarray(34, dtype=ht.int64, device=cpu:0, split=None) >>> ht.bitwise_or(ht.array([33, 4]), 1) DNDarray([33, 5], dtype=ht.int64, device=cpu:0, split=None) >>> ht.bitwise_or(ht.array([33, 4]), ht.array([1, 2])) DNDarray([33, 6], dtype=ht.int64, device=cpu:0, split=None) >>> ht.bitwise_or(ht.array([2, 5, 255]), ht.array([4, 4, 4])) DNDarray([ 6, 5, 255], dtype=ht.int64, device=cpu:0, split=None) >>> ht.bitwise_or(ht.array([2, 5, 255, 2147483647], dtype=ht.int32), ht.array([4, 4, 4, 2147483647], dtype=ht.int32)) DNDarray([ 6, 5, 255, 2147483647], dtype=ht.int32, device=cpu:0, split=None) >>> ht.bitwise_or(ht.array([True, True]), ht.array([False, True])) DNDarray([True, True], dtype=ht.bool, device=cpu:0, split=None) .. function:: bitwise_xor(t1: Union[heat.core.dndarray.DNDarray, float], t2: Union[heat.core.dndarray.DNDarray, float], /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Compute the bit-wise XOR of two arrays ``t1`` and ``t2`` element-wise. Only integer and boolean types are handled. If ``x1.shape!=x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). :param t1: The first operand involved in the operation :type t1: DNDarray or scalar :param t2: The second operand involved in the operation :type t2: DNDarray or scalar :param out: The output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the added value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> ht.bitwise_xor(13, 17) DNDarray(28, dtype=ht.int64, device=cpu:0, split=None) >>> ht.bitwise_xor(31, 5) DNDarray(26, dtype=ht.int64, device=cpu:0, split=None) >>> ht.bitwise_xor(ht.array([31, 3]), 5) DNDarray([26, 6], dtype=ht.int64, device=cpu:0, split=None) >>> ht.bitwise_xor(ht.array([31, 3]), ht.array([5, 6])) DNDarray([26, 5], dtype=ht.int64, device=cpu:0, split=None) >>> ht.bitwise_xor(ht.array([True, True]), ht.array([False, True])) DNDarray([ True, False], dtype=ht.bool, device=cpu:0, split=None) .. function:: copysign(a: heat.core.dndarray.DNDarray, b: Union[heat.core.dndarray.DNDarray, float, int], /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Create a new floating-point tensor with the magnitude of 'a' and the sign of 'b', element-wise :param a: The input array :type a: DNDarray :param b: value(s) whose signbit(s) are applied to the magnitudes in 'a' :type b: DNDarray or Number :param out: The output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the divided value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> ht.copysign(ht.array([3, 2, -8, -2, 4]), 1) DNDarray([3, 2, 8, 2, 4], dtype=ht.int64, device=cpu:0, split=None) >>> ht.copysign(ht.array([3.0, 2.0, -8.0, -2.0, 4.0]), ht.array([1.0, -1.0, 1.0, -1.0, 1.0])) DNDarray([ 3., -2., 8., -2., 4.], dtype=ht.float32, device=cpu:0, split=None) .. function:: cumprod(a: heat.core.dndarray.DNDarray, axis: int, dtype: heat.core.types.datatype = None, out=None) -> heat.core.dndarray.DNDarray Return the cumulative product of elements along a given axis. :param a: Input array. :type a: DNDarray :param axis: Axis along which the cumulative product is computed. :type axis: int :param dtype: Type of the returned array, as well as of the accumulator in which the elements are multiplied. If ``dtype`` is not specified, it defaults to the datatype of ``a``, unless ``a`` has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used instead. :type dtype: datatype, optional :param out: Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type of the resulting values will be cast if necessary. :type out: DNDarray, optional .. rubric:: Examples >>> a = ht.full((3, 3), 2) >>> ht.cumprod(a, 0) DNDarray([[2., 2., 2.], [4., 4., 4.], [8., 8., 8.]], dtype=ht.float32, device=cpu:0, split=None) .. data:: cumproduct Alias for :py:func:`cumprod` .. function:: cumsum(a: heat.core.dndarray.DNDarray, axis: int, dtype: heat.core.types.datatype = None, out=None) -> heat.core.dndarray.DNDarray Return the cumulative sum of the elements along a given axis. :param a: Input array. :type a: DNDarray :param axis: Axis along which the cumulative sum is computed. :type axis: int :param dtype: Type of the returned array and of the accumulator in which the elements are summed. If ``dtype`` is not specified, it defaults to the datatype of ``a``, unless ``a`` has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used. :type dtype: datatype, optional :param out: Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary. :type out: DNDarray, optional .. rubric:: Examples >>> a = ht.ones((3, 3)) >>> ht.cumsum(a, 0) DNDarray([[1., 1., 1.], [2., 2., 2.], [3., 3., 3.]], dtype=ht.float32, device=cpu:0, split=None) .. function:: diff(a: heat.core.dndarray.DNDarray, n: int = 1, axis: int = -1, prepend: Union[int, float, heat.core.dndarray.DNDarray] = None, append: Union[int, float, heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Calculate the n-th discrete difference along the given axis. The first difference is given by ``out[i]=a[i+1]-a[i]`` along the given axis, higher differences are calculated by using diff recursively. The shape of the output is the same as ``a`` except along axis where the dimension is smaller by ``n``. The datatype of the output is the same as the datatype of the difference between any two elements of ``a``. The split does not change. The output array is balanced. :param a: Input array :type a: DNDarray :param n: The number of times values are differenced. If zero, the input is returned as-is. ``n=2`` is equivalent to ``diff(diff(a))`` :type n: int, optional :param axis: The axis along which the difference is taken, default is the last axis. :type axis: int, optional :param prepend: Value to prepend along axis prior to performing the difference. Scalar values are expanded to arrays with length 1 in the direction of axis and the shape of the input array in along all other axes. Otherwise the dimension and shape must match a except along axis. :type prepend: Union[int, float, DNDarray] :param append: Values to append along axis prior to performing the difference. Scalar values are expanded to arrays with length 1 in the direction of axis and the shape of the input array in along all other axes. Otherwise the dimension and shape must match a except along axis. :type append: Union[int, float, DNDarray] .. function:: div(t1: Union[heat.core.dndarray.DNDarray, float], t2: Union[heat.core.dndarray.DNDarray, float], /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Element-wise true division of values of operand ``t1`` by values of operands ``t2`` (i.e ``t1/t2``). Operation is not commutative. :param t1: The first operand whose values are divided. :type t1: DNDarray or scalar :param t2: The second operand by whose values is divided. :type t2: DNDarray or scalar :param out: The output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the divided value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Example >>> ht.div(2.0, 2.0) DNDarray(1., dtype=ht.float32, device=cpu:0, split=None) >>> T1 = ht.float32([[1, 2], [3, 4]]) >>> T2 = ht.float32([[2, 2], [2, 2]]) >>> ht.div(T1, T2) DNDarray([[0.5000, 1.0000], [1.5000, 2.0000]], dtype=ht.float32, device=cpu:0, split=None) >>> s = 2.0 >>> ht.div(s, T1) DNDarray([[2.0000, 1.0000], [0.6667, 0.5000]], dtype=ht.float32, device=cpu:0, split=None) .. data:: divide Alias for :py:func:`div` .. function:: divmod(t1: Union[heat.core.dndarray.DNDarray, float], t2: Union[heat.core.dndarray.DNDarray, float], out1: heat.core.dndarray.DNDarray = None, out2: heat.core.dndarray.DNDarray = None, /, out: Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] = (None, None), *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] Element-wise division remainder and quotient from an integer division of values of operand ``t1`` by values of operand ``t2`` (i.e. C Library function divmod). Result has the sign as the dividend ``t1``. Operation is not commutative. :param t1: The first operand whose values are divided (may be floats) :type t1: DNDarray or scalar :param t2: The second operand by whose values is divided (may be floats) :type t2: DNDarray or scalar :param out1: The output array for the quotient. It must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. If provided, it must be of the same shape as the expected output. Only one of out1 and out can be provided. :type out1: DNDarray, optional :param out2: The output array for the remainder. It must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. If provided, it must be of the same shape as the expected output. Only one of out2 and out can be provided. :type out2: DNDarray, optional :param out: Tuple of two output arrays (quotient, remainder), respectively. Both must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. If provided, they must be of the same shape as the expected output. out1 and out2 cannot be used at the same time. :type out: tuple of two DNDarrays, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out1` array will be set to the quotient value and the `out2` array will be set to the remainder value. Elsewhere, the `out1` and `out2` arrays will retain their original value. If an uninitialized `out1` and `out2` array is created via the default `out1=None` and `out2=None`, locations within them where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out1` and `out2` arrays. :type where: DNDarray, optional .. rubric:: Examples >>> ht.divmod(2.0, 2.0) (DNDarray(1., dtype=ht.float32, device=cpu:0, split=None), DNDarray(0., dtype=ht.float32, device=cpu:0, split=None)) >>> T1 = ht.float32([[1, 2], [3, 4]]) >>> T2 = ht.float32([[2, 2], [2, 2]]) >>> ht.divmod(T1, T2) (DNDarray([[0., 1.], [1., 2.]], dtype=ht.float32, device=cpu:0, split=None), DNDarray([[1., 0.], [1., 0.]], dtype=ht.float32, device=cpu:0, split=None)) >>> s = 2.0 >>> ht.divmod(s, T1) (DNDarray([[2., 1.], [0., 0.]], dtype=ht.float32, device=cpu:0, split=None), DNDarray([[0., 0.], [2., 2.]], dtype=ht.float32, device=cpu:0, split=None)) .. function:: floordiv(t1: Union[heat.core.dndarray.DNDarray, float], t2: Union[heat.core.dndarray.DNDarray, float], /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Element-wise floor division of value(s) of operand ``t1`` by value(s) of operand ``t2`` (i.e. ``t1//t2``), not commutative. :param t1: The first operand whose values are divided :type t1: DNDarray or scalar :param t2: The second operand by whose values is divided :type t2: DNDarray or scalar :param out: The output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the divided value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> T1 = ht.float32([[1.7, 2.0], [1.9, 4.2]]) >>> ht.floordiv(T1, 1) DNDarray([[1., 2.], [1., 4.]], dtype=ht.float64, device=cpu:0, split=None) >>> T2 = ht.float32([1.5, 2.5]) >>> ht.floordiv(T1, T2) DNDarray([[1., 0.], [1., 1.]], dtype=ht.float32, device=cpu:0, split=None) .. data:: floor_divide Alias for :py:func:`floordiv` .. function:: fmod(t1: Union[heat.core.dndarray.DNDarray, float], t2: Union[heat.core.dndarray.DNDarray, float], /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Element-wise division remainder of values of operand ``t1`` by values of operand ``t2`` (i.e. C Library function fmod). Result has the sign as the dividend ``t1``. Operation is not commutative. :param t1: The first operand whose values are divided (may be floats) :type t1: DNDarray or scalar :param t2: The second operand by whose values is divided (may be floats) :type t2: DNDarray or scalar :param out: The output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. If provided, it must be of the same shape as the expected output. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the divided value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> ht.fmod(2.0, 2.0) DNDarray(0., dtype=ht.float32, device=cpu:0, split=None) >>> T1 = ht.float32([[1, 2], [3, 4]]) >>> T2 = ht.float32([[2, 2], [2, 2]]) >>> ht.fmod(T1, T2) DNDarray([[1., 0.], [1., 0.]], dtype=ht.float32, device=cpu:0, split=None) >>> s = 2.0 >>> ht.fmod(s, T1) DNDarray([[0., 0.], [2., 2.]], dtype=ht.float32, device=cpu:0, split=None) .. function:: gcd(a: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray, /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Returns the greatest common divisor of |a| and |b| element-wise. :param a: The first input array, must be of integer type :type a: DNDarray :param b: the second input array, must be of integer type :type b: DNDarray :param out: The output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the divided value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> import heat as ht >>> T1 = ht.int(ht.ones(3)) * 9 >>> T2 = ht.arange(3) + 1 >>> ht.gcd(T1, T2) DNDarray([1, 1, 3], dtype=ht.int32, device=cpu:0, split=None) .. function:: hypot(t1: heat.core.dndarray.DNDarray, t2: heat.core.dndarray.DNDarray, /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Given the 'legs' of a right triangle, return its hypotenuse. Equivalent to :math:`sqrt(a^2 + b^2)`, element-wise. :param t1: The first input array :type t1: DNDarray :param t2: the second input array :type t2: DNDarray :param out: The output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the divided value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> a = ht.array([2.0]) >>> b = ht.array([1.0, 3.0, 3.0]) >>> ht.hypot(a, b) DNDarray([2.2361, 3.6056, 3.6056], dtype=ht.float32, device=cpu:0, split=None) .. function:: invert(a: heat.core.dndarray.DNDarray, /, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Computes the bitwise NOT of the given input :class:`~heat.core.dndarray.DNDarray`. The input array must be of integral or Boolean types. For boolean arrays, it computes the logical NOT. Bitwise_not is an alias for invert. :param a: The input array to invert. Must be of integral or Boolean types :type a: DNDarray :param out: Alternative output array in which to place the result. It must have the same shape as the expected output. The dtype of the output will be the one of the input array, unless it is logical, in which case it will be casted to int8. If not provided or None, a freshly- allocated array is returned. :type out: DNDarray, optional .. rubric:: Examples >>> ht.invert(ht.array([13], dtype=ht.uint8)) DNDarray([242], dtype=ht.uint8, device=cpu:0, split=None) >>> ht.bitwise_not(ht.array([-1, -2, 3], dtype=ht.int8)) DNDarray([ 0, 1, -4], dtype=ht.int8, device=cpu:0, split=None) .. function:: lcm(a: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray, /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Returns the lowest common multiple of |a| and |b| element-wise. :param a: The first input (array), must be of integer type :type a: DNDarray or scalar :param b: the second input (array), must be of integer type :type b: DNDarray or scalar :param out: The output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the divided value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> a = ht.array([6, 12, 15]) >>> b = ht.array([3, 4, 5]) >>> ht.lcm(a, b) DNDarray([ 6, 12, 15], dtype=ht.int64, device=cpu:0, split=None) >>> s = 2 >>> ht.lcm(s, a) DNDarray([ 6, 12, 30], dtype=ht.int64, device=cpu:0, split=None) >>> ht.lcm(b, s) DNDarray([ 6, 4, 10], dtype=ht.int64, device=cpu:0, split=None) .. function:: left_shift(t1: heat.core.dndarray.DNDarray, t2: Union[heat.core.dndarray.DNDarray, float], /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Shift the bits of an integer to the left. :param t1: Input array :type t1: DNDarray :param t2: Integer number of zero bits to add :type t2: DNDarray or float :param out: Output array for the result. Must have the same shape as the expected output. The dtype of the output will be the one of the input array, unless it is logical, in which case it will be casted to int8. If not provided or None, a freshly-allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the shifted value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> ht.left_shift(ht.array([1, 2, 3]), 1) DNDarray([2, 4, 6], dtype=ht.int64, device=cpu:0, split=None) .. data:: mod Alias for :py:func:`remainder` .. function:: mul(t1: Union[heat.core.dndarray.DNDarray, float], t2: Union[heat.core.dndarray.DNDarray, float], /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Element-wise multiplication (NOT matrix multiplication) of values from two operands, commutative. Takes the first and second operand (scalar or :class:`~heat.core.dndarray.DNDarray`) whose elements are to be multiplied as argument. :param t1: The first operand involved in the multiplication :type t1: DNDarray or scalar :param t2: The second operand involved in the multiplication :type t2: DNDarray or scalar :param out: Output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided or None, a freshly-allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the multiplied value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> ht.mul(2.0, 4.0) DNDarray(8., dtype=ht.float32, device=cpu:0, split=None) >>> T1 = ht.float32([[1, 2], [3, 4]]) >>> s = 3.0 >>> ht.mul(T1, s) DNDarray([[ 3., 6.], [ 9., 12.]], dtype=ht.float32, device=cpu:0, split=None) >>> T2 = ht.float32([[2, 2], [2, 2]]) >>> ht.mul(T1, T2) DNDarray([[2., 4.], [6., 8.]], dtype=ht.float32, device=cpu:0, split=None) .. data:: multiply Alias for :py:func:`mul` .. function:: nan_to_num(a: heat.core.dndarray.DNDarray, nan: float = 0.0, posinf: float = None, neginf: float = None, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Replaces NaNs, positive infinity values, and negative infinity values in the input 'a' with the values specified by nan, posinf, and neginf, respectively. By default, NaNs are replaced with zero, positive infinity is replaced with the greatest finite value representable by input's dtype, and negative infinity is replaced with the least finite value representable by input's dtype. :param a: Input array. :type a: DNDarray :param nan: Value to be used to replace NaNs. Default value is 0.0. :type nan: float, optional :param posinf: Value to replace positive infinity values with. If None, positive infinity values are replaced with the greatest finite value of the input's dtype. Default value is None. :type posinf: float, optional :param neginf: Value to replace negative infinity values with. If None, negative infinity values are replaced with the greatest negative finite value of the input's dtype. Default value is None. :type neginf: float, optional :param out: Alternative output array in which to place the result. It must have the same shape as the expected output, but the datatype of the output values will be cast if necessary. :type out: DNDarray, optional .. rubric:: Examples >>> x = ht.array([float("nan"), float("inf"), -float("inf")]) >>> ht.nan_to_num(x) DNDarray([ 0.0000e+00, 3.4028e+38, -3.4028e+38], dtype=ht.float32, device=cpu:0, split=None) .. function:: nanprod(a: heat.core.dndarray.DNDarray, axis: Union[int, Tuple[int, Ellipsis]] = None, out: heat.core.dndarray.DNDarray = None, keepdims: bool = None) -> heat.core.dndarray.DNDarray Return the product of array elements over a given axis treating Not a Numbers (NaNs) as one. :param a: Input array. :type a: DNDarray :param axis: Axis or axes along which a product is performed. The default, ``axis=None``, will calculate the product of all the elements in the input array. If axis is negative it counts from the last to the first axis. If axis is a tuple of ints, a product is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before. :type axis: None or int or Tuple[int,...], optional :param out: Alternative output array in which to place the result. It must have the same shape as the expected output, but the datatype of the output values will be cast if necessary. :type out: DNDarray, optional :param keepdims: If this is set to ``True``, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array. :type keepdims: bool, optional .. rubric:: Examples >>> ht.nanprod(ht.array([4.0, ht.nan])) DNDarray(4., dtype=ht.float32, device=cpu:0, split=None) >>> ht.nanprod(ht.array([ [1.,ht.nan], [3.,4.]])) DNDarray(12., dtype=ht.float32, device=cpu:0, split=None) >>> ht.nanprod(ht.array([ [1.,ht.nan], [ht.nan,4.] ]), axis=1) DNDarray([ 1., 4.], dtype=ht.float32, device=cpu:0, split=None) .. function:: nansum(a: heat.core.dndarray.DNDarray, axis: Union[int, Tuple[int, Ellipsis]] = None, out: heat.core.dndarray.DNDarray = None, keepdims: bool = None) -> heat.core.dndarray.DNDarray Sum of array elements over a given axis treating Not a Numbers (NaNs) as zero. An array with the same shape as ``self.__array`` except for the specified axis which becomes one, e.g. ``a.shape=(1, 2, 3)`` => ``ht.ones((1, 2, 3)).sum(axis=1).shape=(1, 1, 3)`` :param a: Input array. :type a: DNDarray :param axis: Axis along which a sum is performed. The default, ``axis=None``, will sum all of the elements of the input array. If ``axis`` is negative it counts from the last to the first axis. If ``axis`` is a tuple of ints, a sum is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before. :type axis: None or int or Tuple[int,...], optional :param out: Alternative output array in which to place the result. It must have the same shape as the expected output, but the datatype of the output values will be cast if necessary. :type out: DNDarray, optional :param keepdims: If this is set to ``True``, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array. :type keepdims: bool, optional .. rubric:: Examples >>> ht.sum(ht.ones(2)) DNDarray(2., dtype=ht.float32, device=cpu:0, split=None) >>> ht.sum(ht.ones((3, 3))) DNDarray(9., dtype=ht.float32, device=cpu:0, split=None) >>> ht.sum(ht.ones((3, 3)).astype(ht.int)) DNDarray(9, dtype=ht.int64, device=cpu:0, split=None) >>> ht.sum(ht.ones((3, 2, 1)), axis=-3) DNDarray([[3.], [3.]], dtype=ht.float32, device=cpu:0, split=None) .. function:: neg(a: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Element-wise negation of `a`. :param a: The input array. :type a: DNDarray :param out: The output array. It must have a shape that the inputs broadcast to :type out: DNDarray, optional .. rubric:: Examples >>> ht.neg(ht.array([-1, 1])) DNDarray([ 1, -1], dtype=ht.int64, device=cpu:0, split=None) >>> -ht.array([-1.0, 1.0]) DNDarray([ 1., -1.], dtype=ht.float32, device=cpu:0, split=None) .. data:: negative Alias for :py:func:`neg` .. function:: pos(a: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Element-wise positive of `a`. :param a: The input array. :type a: DNDarray :param out: The output array. It must have a shape that the inputs broadcast to. :type out: DNDarray, optional .. rubric:: Notes Equivalent to a.copy(). .. rubric:: Examples >>> ht.pos(ht.array([-1, 1])) DNDarray([-1, 1], dtype=ht.int64, device=cpu:0, split=None) >>> +ht.array([-1.0, 1.0]) DNDarray([-1., 1.], dtype=ht.float32, device=cpu:0, split=None) .. data:: positive Alias for :py:func:`pos` .. function:: pow(t1: Union[heat.core.dndarray.DNDarray, float], t2: Union[heat.core.dndarray.DNDarray, float], /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Element-wise power function of values of operand ``t1`` to the power of values of operand ``t2`` (i.e ``t1**t2``). Operation is not commutative. :param t1: The first operand whose values represent the base :type t1: DNDarray or scalar :param t2: The second operand whose values represent the exponent :type t2: DNDarray or scalar :param out: Output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided or None, a freshly-allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the exponentiated value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> ht.pow(3.0, 2.0) DNDarray(9., dtype=ht.float32, device=cpu:0, split=None) >>> T1 = ht.float32([[1, 2], [3, 4]]) >>> T2 = ht.float32([[3, 3], [2, 2]]) >>> ht.pow(T1, T2) DNDarray([[ 1., 8.], [ 9., 16.]], dtype=ht.float32, device=cpu:0, split=None) >>> s = 3.0 >>> ht.pow(T1, s) DNDarray([[ 1., 8.], [27., 64.]], dtype=ht.float32, device=cpu:0, split=None) .. data:: power Alias for :py:func:`pow` .. function:: prod(a: heat.core.dndarray.DNDarray, axis: Union[int, Tuple[int, Ellipsis]] = None, out: heat.core.dndarray.DNDarray = None, keepdims: bool = None) -> heat.core.dndarray.DNDarray Return the product of array elements over a given axis in form of a DNDarray shaped as a but with the specified axis removed. :param a: Input array. :type a: DNDarray :param axis: Axis or axes along which a product is performed. The default, ``axis=None``, will calculate the product of all the elements in the input array. If axis is negative it counts from the last to the first axis. If axis is a tuple of ints, a product is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before. :type axis: None or int or Tuple[int,...], optional :param out: Alternative output array in which to place the result. It must have the same shape as the expected output, but the datatype of the output values will be cast if necessary. :type out: DNDarray, optional :param keepdims: If this is set to ``True``, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array. :type keepdims: bool, optional .. rubric:: Examples >>> ht.prod(ht.array([1.0, 2.0])) DNDarray(2., dtype=ht.float32, device=cpu:0, split=None) >>> ht.prod(ht.array([ [1.,2.], [3.,4.]])) DNDarray(24., dtype=ht.float32, device=cpu:0, split=None) >>> ht.prod(ht.array([ [1.,2.], [3.,4.] ]), axis=1) DNDarray([ 2., 12.], dtype=ht.float32, device=cpu:0, split=None) .. function:: remainder(t1: Union[heat.core.dndarray.DNDarray, float], t2: Union[heat.core.dndarray.DNDarray, float], /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Element-wise division remainder of values of operand ``t1`` by values of operand ``t2`` (i.e. ``t1%t2``). Result has the same sign as the divisor ``t2``. Operation is not commutative. :param t1: The first operand whose values are divided :type t1: DNDarray or scalar :param t2: The second operand by whose values is divided :type t2: DNDarray or scalar :param out: Output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided, a freshly allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the divided value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> ht.remainder(2, 2) DNDarray(0, dtype=ht.int64, device=cpu:0, split=None) >>> T1 = ht.int32([[1, 2], [3, 4]]) >>> T2 = ht.int32([[2, 2], [2, 2]]) >>> ht.remainder(T1, T2) DNDarray([[1, 0], [1, 0]], dtype=ht.int32, device=cpu:0, split=None) >>> s = 2 >>> ht.remainder(s, T1) DNDarray([[0, 0], [2, 2]], dtype=ht.int32, device=cpu:0, split=None) .. function:: right_shift(t1: Union[heat.core.dndarray.DNDarray, float], t2: Union[heat.core.dndarray.DNDarray, float], /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Shift the bits of an integer to the right. :param t1: Input array :type t1: DNDarray or scalar :param t2: Integer number of bits to remove :type t2: DNDarray or scalar :param out: Output array for the result. Must have the same shape as the expected output. The dtype of the output will be the one of the input array, unless it is logical, in which case it will be casted to int8. If not provided or None, a freshly-allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the shifted value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> ht.right_shift(ht.array([1, 2, 3]), 1) DNDarray([0, 1, 1], dtype=ht.int64, device=cpu:0, split=None) .. function:: sub(t1: Union[heat.core.dndarray.DNDarray, float], t2: Union[heat.core.dndarray.DNDarray, float], /, out: Optional[heat.core.dndarray.DNDarray] = None, *, where: Union[bool, heat.core.dndarray.DNDarray] = True) -> heat.core.dndarray.DNDarray Element-wise subtraction of values of operand ``t2`` from values of operands ``t1`` (i.e ``t1-t2``). Operation is not commutative. :param t1: The first operand from which values are subtracted :type t1: DNDarray or scalar :param t2: The second operand whose values are subtracted :type t2: DNDarray or scalar :param out: Output array. It must have a shape that the inputs broadcast to and matching split axis. If not provided or None, a freshly-allocated array is returned. :type out: DNDarray, optional :param where: Condition to broadcast over the inputs. At locations where the condition is True, the `out` array will be set to the subtracted value. Elsewhere, the `out` array will retain its original value. If an uninitialized `out` array is created via the default `out=None`, locations within it where the condition is False will remain uninitialized. If distributed, the split axis (after broadcasting if required) must match that of the `out` array. :type where: DNDarray, optional .. rubric:: Examples >>> ht.sub(4.0, 1.0) DNDarray(3., dtype=ht.float32, device=cpu:0, split=None) >>> T1 = ht.float32([[1, 2], [3, 4]]) >>> T2 = ht.float32([[2, 2], [2, 2]]) >>> ht.sub(T1, T2) DNDarray([[-1., 0.], [ 1., 2.]], dtype=ht.float32, device=cpu:0, split=None) >>> s = 2.0 >>> ht.sub(s, T1) DNDarray([[ 1., 0.], [-1., -2.]], dtype=ht.float32, device=cpu:0, split=None) .. data:: subtract Alias for :py:func:`sub` .. function:: sum(a: heat.core.dndarray.DNDarray, axis: Union[int, Tuple[int, Ellipsis]] = None, out: heat.core.dndarray.DNDarray = None, keepdims: bool = None) -> heat.core.dndarray.DNDarray Sum of array elements over a given axis. An array with the same shape as ``self.__array`` except for the specified axis which becomes one, e.g. ``a.shape=(1, 2, 3)`` => ``ht.ones((1, 2, 3)).sum(axis=1).shape=(1, 1, 3)`` :param a: Input array. :type a: DNDarray :param axis: Axis along which a sum is performed. The default, ``axis=None``, will sum all of the elements of the input array. If ``axis`` is negative it counts from the last to the first axis. If ``axis`` is a tuple of ints, a sum is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before. :type axis: None or int or Tuple[int,...], optional :param out: Alternative output array in which to place the result. It must have the same shape as the expected output, but the datatype of the output values will be cast if necessary. :type out: DNDarray, optional :param keepdims: If this is set to ``True``, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array. :type keepdims: bool, optional .. rubric:: Examples >>> ht.sum(ht.ones(2)) DNDarray(2., dtype=ht.float32, device=cpu:0, split=None) >>> ht.sum(ht.ones((3, 3))) DNDarray(9., dtype=ht.float32, device=cpu:0, split=None) >>> ht.sum(ht.ones((3, 3)).astype(ht.int)) DNDarray(9, dtype=ht.int64, device=cpu:0, split=None) >>> ht.sum(ht.ones((3, 2, 1)), axis=-3) DNDarray([[3.], [3.]], dtype=ht.float32, device=cpu:0, split=None) .. py:class:: DNDarray(array: torch.Tensor, gshape: Tuple[int, Ellipsis], dtype: heat.core.types.datatype, split: Union[int, None], device: heat.core.devices.Device, comm: Communication, balanced: bool) Distributed N-Dimensional array. The core element of HeAT. It is composed of PyTorch tensors local to each process. :param array: Local array elements :type array: torch.Tensor :param gshape: The global shape of the array :type gshape: Tuple[int,...] :param dtype: The datatype of the array :type dtype: datatype :param split: The axis on which the array is divided between processes :type split: int or None :param device: The device on which the local arrays are using (cpu or gpu) :type device: Device :param comm: The communications object for sending and receiving data :type comm: Communication :param balanced: Describes whether the data are evenly distributed across processes. If this information is not available (``self.balanced is None``), it can be gathered via the :func:`is_balanced()` method (requires communication). :type balanced: bool or None .. attribute:: __array .. attribute:: __gshape .. attribute:: __dtype .. attribute:: __split .. attribute:: __device .. attribute:: __comm .. attribute:: __balanced .. attribute:: __ishalo :annotation: = False .. attribute:: __halo_next :annotation: = None .. attribute:: __halo_prev :annotation: = None .. attribute:: __partitions_dict__ :annotation: = None .. attribute:: __lshape_map :annotation: = None .. role:: raw-html(raw) :format: html .. method:: __prephalo(start, end) -> torch.Tensor Extracts the halo indexed by start, end from ``self.array`` in the direction of ``self.split`` :param start: Start index of the halo extracted from ``self.array`` :type start: int :param end: End index of the halo extracted from ``self.array`` :type end: int .. method:: get_halo(halo_size: int, prev: bool = True, next: bool = True) Fetch halos of size ``halo_size`` from neighboring ranks and save them in ``self.halo_next/self.halo_prev``. :param halo_size: Size of the halo. :type halo_size: int :param prev: If True, fetch the halo from the previous rank. Default: True. :type prev: bool, optional :param next: If True, fetch the halo from the next rank. Default: True. :type next: bool, optional .. method:: __cat_halo() -> torch.Tensor Return local array concatenated to halos if they are available. .. method:: __array__() -> numpy.ndarray Returns a view of the process-local slice of the :class:`DNDarray` as a numpy ndarray, if the ``DNDarray`` resides on CPU. Otherwise, it returns a copy, on CPU, of the process-local slice of ``DNDarray`` as numpy ndarray. .. method:: __array_ufunc__(ufunc, method, *inputs, **kwargs) Override NumPy's universal functions. .. method:: __array_function__(func, types, args, kwargs) Augments NumPy's functions. .. method:: astype(dtype, copy=True) -> DNDarray Returns a casted version of this array. Casted array is a new array of the same shape but with given type of this array. If copy is ``True``, the same array is returned instead. :param dtype: Heat type to which the array is cast :type dtype: datatype :param copy: By default the operation returns a copy of this array. If copy is set to ``False`` the cast is performed in-place and this array is returned :type copy: bool, optional .. method:: balance_() -> DNDarray Function for balancing a :class:`DNDarray` between all nodes. To determine if this is needed use the :func:`is_balanced()` function. If the ``DNDarray`` is already balanced this function will do nothing. This function modifies the ``DNDarray`` itself and will not return anything. .. rubric:: Examples >>> a = ht.zeros((10, 2), split=0) >>> a[:, 0] = ht.arange(10) >>> b = a[3:] [0/2] tensor([[3., 0.], [1/2] tensor([[4., 0.], [5., 0.], [6., 0.]]) [2/2] tensor([[7., 0.], [8., 0.], [9., 0.]]) >>> b.balance_() >>> print(b.gshape, b.lshape) [0/2] (7, 2) (1, 2) [1/2] (7, 2) (3, 2) [2/2] (7, 2) (3, 2) >>> b [0/2] tensor([[3., 0.], [4., 0.], [5., 0.]]) [1/2] tensor([[6., 0.], [7., 0.]]) [2/2] tensor([[8., 0.], [9., 0.]]) >>> print(b.gshape, b.lshape) [0/2] (7, 2) (3, 2) [1/2] (7, 2) (2, 2) [2/2] (7, 2) (2, 2) .. method:: __bool__() -> bool Boolean scalar casting. .. method:: __cast(cast_function) -> Union[float, int] Implements a generic cast function for ``DNDarray`` objects. :param cast_function: The actual cast function, e.g. ``float`` or ``int`` :type cast_function: function :raises TypeError: If the ``DNDarray`` object cannot be converted into a scalar. .. method:: collect_(target_rank: Optional[int] = 0) -> None A method collecting a distributed DNDarray to one MPI rank, chosen by the `target_rank` variable. It is a specific case of the ``redistribute_`` method. :param target_rank: The rank to which the DNDarray will be collected. Default: 0. :type target_rank: int, optional :raises TypeError: If the target rank is not an integer. :raises ValueError: If the target rank is out of bounds. .. rubric:: Examples >>> st = ht.ones((50, 81, 67), split=2) >>> print(st.lshape) [0/2] (50, 81, 23) [1/2] (50, 81, 22) [2/2] (50, 81, 22) >>> st.collect_() >>> print(st.lshape) [0/2] (50, 81, 67) [1/2] (50, 81, 0) [2/2] (50, 81, 0) >>> st.collect_(1) >>> print(st.lshape) [0/2] (50, 81, 0) [1/2] (50, 81, 67) [2/2] (50, 81, 0) .. method:: __complex__() -> DNDarray Complex scalar casting. .. method:: counts_displs() -> Tuple[Tuple[int], Tuple[int]] Returns actual counts (number of items per process) and displacements (offsets) of the DNDarray. Does not assume load balance. .. method:: cpu() -> DNDarray Returns a copy of this object in main memory. If this object is already in main memory, then no copy is performed and the original object is returned. .. method:: create_lshape_map(force_check: bool = False) -> torch.Tensor Generate a 'map' of the lshapes of the data on all processes. Units are ``(process rank, lshape)`` :param force_check: if False (default) and the lshape map has already been created, use the previous result. Otherwise, create the lshape_map :type force_check: bool, optional .. method:: create_partition_interface() Create a partition interface in line with the DPPY proposal. This is subject to change. The intention of this to facilitate the usage of a general format for the referencing of distributed datasets. An example of the output and shape is shown below. __partitioned__ = { 'shape': (27, 3, 2), 'partition_tiling': (4, 1, 1), 'partitions': { (0, 0, 0): { 'start': (0, 0, 0), 'shape': (7, 3, 2), 'data': tensor([...], dtype=torch.int32), 'location': [0], 'dtype': torch.int32, 'device': 'cpu' }, (1, 0, 0): { 'start': (7, 0, 0), 'shape': (7, 3, 2), 'data': None, 'location': [1], 'dtype': torch.int32, 'device': 'cpu' }, (2, 0, 0): { 'start': (14, 0, 0), 'shape': (7, 3, 2), 'data': None, 'location': [2], 'dtype': torch.int32, 'device': 'cpu' }, (3, 0, 0): { 'start': (21, 0, 0), 'shape': (6, 3, 2), 'data': None, 'location': [3], 'dtype': torch.int32, 'device': 'cpu' } }, 'locals': [(rank, 0, 0)], 'get': lambda x: x, } :rtype: dictionary containing the partition interface as shown above. .. method:: __float__() -> DNDarray Float scalar casting. .. seealso:: :func:`~heat.core.manipulations.flatten` .. method:: fill_diagonal(value: float) -> DNDarray Fill the main diagonal of a 2D :class:`DNDarray`. This function modifies the input tensor in-place, and returns the input array. :param value: The value to be placed in the ``DNDarrays`` main diagonal :type value: float .. method:: __getitem__(key: Union[int, Tuple[int, Ellipsis], List[int, Ellipsis]]) -> DNDarray Global getter function for DNDarrays. Returns a new DNDarray composed of the elements of the original tensor selected by the indices given. This does *NOT* redistribute or rebalance the resulting tensor. If the selection of values is unbalanced then the resultant tensor is also unbalanced! To redistributed the ``DNDarray`` use :func:`balance()` (issue #187) :param key: Indices to get from the tensor. :type key: int, slice, Tuple[int,...], List[int,...] .. rubric:: Examples >>> a = ht.arange(10, split=0) (1/2) >>> tensor([0, 1, 2, 3, 4], dtype=torch.int32) (2/2) >>> tensor([5, 6, 7, 8, 9], dtype=torch.int32) >>> a[1:6] (1/2) >>> tensor([1, 2, 3, 4], dtype=torch.int32) (2/2) >>> tensor([5], dtype=torch.int32) >>> a = ht.zeros((4, 5), split=0) (1/2) >>> tensor([[0., 0., 0., 0., 0.], [0., 0., 0., 0., 0.]]) (2/2) >>> tensor([[0., 0., 0., 0., 0.], [0., 0., 0., 0., 0.]]) >>> a[1:4, 1] (1/2) >>> tensor([0.]) (2/2) >>> tensor([0., 0.]) .. method:: gpu() -> DNDarray Returns a copy of this object in GPU memory. If this object is already in GPU memory, then no copy is performed and the original object is returned. .. method:: __int__() -> DNDarray Integer scalar casting. .. method:: is_balanced(force_check: bool = False) -> bool Determine if ``self`` is balanced evenly (or as evenly as possible) across all nodes distributed evenly (or as evenly as possible) across all processes. This is equivalent to returning ``self.balanced``. If no information is available (``self.balanced = None``), the balanced status will be assessed via collective communication. :param force_check: If True, the balanced status of the ``DNDarray`` will be assessed via collective communication in any case. :type force_check: bool, optional .. method:: is_distributed() -> bool Determines whether the data of this ``DNDarray`` is distributed across multiple processes. .. method:: __key_is_singular(key: any, axis: int, self_proxy: torch.Tensor) -> bool .. method:: __key_adds_dimension(key: any, axis: int, self_proxy: torch.Tensor) -> bool .. method:: item() Returns the only element of a 1-element :class:`DNDarray`. Mirror of the pytorch command by the same name. If size of ``DNDarray`` is >1 element, then a ``ValueError`` is raised (by pytorch) .. rubric:: Examples >>> import heat as ht >>> x = ht.zeros((1)) >>> x.item() 0.0 .. method:: __len__() -> int The length of the ``DNDarray``, i.e. the number of items in the first dimension. .. method:: numpy() -> numpy.array Returns a copy of the :class:`DNDarray` as numpy ndarray. If the ``DNDarray`` resides on the GPU, the underlying data will be copied to the CPU first. If the ``DNDarray`` is distributed, an MPI Allgather operation will be performed before converting to np.ndarray, i.e. each MPI process will end up holding a copy of the entire array in memory. Make sure process memory is sufficient! .. rubric:: Examples >>> import heat as ht T1 = ht.random.randn((10,8)) T1.numpy() .. method:: _repr_pretty_(p, cycle) Pretty print for IPython. .. method:: __repr__() -> str Returns a printable representation of the passed DNDarray, targeting developers. .. method:: ravel() Flattens the ``DNDarray``. .. seealso:: :func:`~heat.core.manipulations.ravel` .. rubric:: Examples >>> a = ht.ones((2, 3), split=0) >>> b = a.ravel() >>> a[0, 0] = 4 >>> b DNDarray([4., 1., 1., 1., 1., 1.], dtype=ht.float32, device=cpu:0, split=0) .. method:: redistribute_(lshape_map: Optional[torch.Tensor] = None, target_map: Optional[torch.Tensor] = None) Redistributes the data of the :class:`DNDarray` *along the split axis* to match the given target map. This function does not modify the non-split dimensions of the ``DNDarray``. This is an abstraction and extension of the balance function. :param lshape_map: The current lshape of processes. Units are ``[rank, lshape]``. :type lshape_map: torch.Tensor, optional :param target_map: The desired distribution across the processes. Units are ``[rank, target lshape]``. Note: the only important parts of the target map are the values along the split axis, values which are not along this axis are there to mimic the shape of the ``lshape_map``. :type target_map: torch.Tensor, optional .. rubric:: Examples >>> st = ht.ones((50, 81, 67), split=2) >>> target_map = torch.zeros((st.comm.size, 3), dtype=torch.int64) >>> target_map[0, 2] = 67 >>> print(target_map) [0/2] tensor([[ 0, 0, 67], [0/2] [ 0, 0, 0], [0/2] [ 0, 0, 0]], dtype=torch.int32) [1/2] tensor([[ 0, 0, 67], [1/2] [ 0, 0, 0], [1/2] [ 0, 0, 0]], dtype=torch.int32) [2/2] tensor([[ 0, 0, 67], [2/2] [ 0, 0, 0], [2/2] [ 0, 0, 0]], dtype=torch.int32) >>> print(st.lshape) [0/2] (50, 81, 23) [1/2] (50, 81, 22) [2/2] (50, 81, 22) >>> st.redistribute_(target_map=target_map) >>> print(st.lshape) [0/2] (50, 81, 67) [1/2] (50, 81, 0) [2/2] (50, 81, 0) .. method:: __redistribute_shuffle(snd_pr: Union[int, torch.Tensor], send_amt: Union[int, torch.Tensor], rcv_pr: Union[int, torch.Tensor], snd_dtype: torch.dtype) Function to abstract the function used during redistribute for shuffling data between processes along the split axis :param snd_pr: Sending process :type snd_pr: int or torch.Tensor :param send_amt: Amount of data to be sent by the sending process :type send_amt: int or torch.Tensor :param rcv_pr: Receiving process :type rcv_pr: int or torch.Tensor :param snd_dtype: Torch type of the data in question :type snd_dtype: torch.dtype .. method:: resplit_(axis: int = None) In-place option for resplitting a :class:`DNDarray`. :param axis: The new split axis, ``None`` denotes gathering, an int will set the new split axis :type axis: int .. rubric:: Examples >>> a = ht.zeros( ... ( ... 4, ... 5, ... ), ... split=0, ... ) >>> a.lshape (0/2) (2, 5) (1/2) (2, 5) >>> ht.resplit_(a, None) >>> a.split None >>> a.lshape (0/2) (4, 5) (1/2) (4, 5) >>> a = ht.zeros( ... ( ... 4, ... 5, ... ), ... split=0, ... ) >>> a.lshape (0/2) (2, 5) (1/2) (2, 5) >>> ht.resplit_(a, 1) >>> a.split 1 >>> a.lshape (0/2) (4, 3) (1/2) (4, 2) .. method:: __setitem__(key: Union[int, Tuple[int, Ellipsis], List[int, Ellipsis]], value: Union[float, DNDarray, torch.Tensor]) Global item setter :param key: Index/indices to be set :type key: Union[int, Tuple[int,...], List[int,...]] :param value: Value to be set to the specified positions in the DNDarray (self) :type value: Union[float, DNDarray,torch.Tensor] .. rubric:: Notes If a ``DNDarray`` is given as the value to be set then the split axes are assumed to be equal. If they are not, PyTorch will raise an error when the values are attempted to be set on the local array .. rubric:: Examples >>> a = ht.zeros((4, 5), split=0) (1/2) >>> tensor([[0., 0., 0., 0., 0.], [0., 0., 0., 0., 0.]]) (2/2) >>> tensor([[0., 0., 0., 0., 0.], [0., 0., 0., 0., 0.]]) >>> a[1:4, 1] = 1 >>> a (1/2) >>> tensor([[0., 0., 0., 0., 0.], [0., 1., 0., 0., 0.]]) (2/2) >>> tensor([[0., 1., 0., 0., 0.], [0., 1., 0., 0., 0.]]) .. method:: __setter(key: Union[int, Tuple[int, Ellipsis], List[int, Ellipsis]], value: Union[float, DNDarray, torch.Tensor]) Utility function for checking ``value`` and forwarding to :func:``__setitem__`` :raises NotImplementedError: If the type of ``value`` ist not supported .. method:: __str__() -> str Computes a string representation of the passed ``DNDarray``. .. method:: tolist(keepsplit: bool = False) -> List Return a copy of the local array data as a (nested) Python list. For scalars, a standard Python number is returned. :param keepsplit: Whether the list should be returned locally or globally. :type keepsplit: bool .. rubric:: Examples >>> a = ht.array([[0, 1], [2, 3]]) >>> a.tolist() [[0, 1], [2, 3]] >>> a = ht.array([[0, 1], [2, 3]], split=0) >>> a.tolist() [[0, 1], [2, 3]] >>> a = ht.array([[0, 1], [2, 3]], split=1) >>> a.tolist(keepsplit=True) (1/2) [[0], [2]] (2/2) [[1], [3]] .. method:: __torch_function__(func, types, args=(), kwargs=None) Supports PyTorch's dispatch mechanism. .. method:: __torch_proxy__() -> torch.Tensor Return a 1-element `torch.Tensor` strided as the global `self` shape. Used internally for sanitation purposes. .. method:: __xitem_get_key_start_stop(rank: int, actives: list, key_st: int, key_sp: int, step: int, ends: torch.Tensor, og_key_st: int) -> Tuple[int, int] .. py:class:: BaseEstimator Abstract base class for all estimators, i.e. parametrized analysis algorithms, in Heat. Can be used as mixin. .. role:: raw-html(raw) :format: html .. method:: _parameter_names() -> List[str] Get the names of all parameters that can be set inside the constructor of the estimator. .. method:: get_params(deep: bool = True) -> Dict[str, object] Get parameters for this estimator. :param deep: If ``True``, will return the parameters for this estimator and contained sub-objects that are estimators. :type deep: bool, default: True .. method:: __repr__(indent: int = 1) -> str Returns a printable representation of the object. :param indent: Indicates the indentation for the top-level output. :type indent: int, default: 1 .. method:: set_params(**params: Dict[str, object]) -> BaseEstimator.set_params.self Set the parameters of this estimator. The method works on simple estimators as well as on nested objects (such as pipelines). The latter have to be nested dictionaries. :param \*\*params: Estimator parameters to bet set. :type \*\*params: dict[str, object] .. py:class:: ClassificationMixin Mixin for all classifiers in Heat. .. role:: raw-html(raw) :format: html .. method:: fit(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray) Fits the classification model. :param x: Training instances to train on. Shape = (n_samples, n_features) :type x: DNDarray :param y: Class values to fit. Shape = (n_samples, ) :type y: DNDarray .. method:: fit_predict(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Fits model and returns classes for each input sample Convenience method; equivalent to calling :func:`fit` followed by :func:`predict`. :param x: Input data to be predicted. Shape = (n_samples, n_features) :type x: DNDarray :param y: Class values to fit. Shape = (n_samples, ) :type y: DNDarray .. method:: predict(x: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Predicts the class labels for each sample. :param x: Values to predict the classes for. Shape = (n_samples, n_features) :type x: DNDarray .. py:class:: TransformMixin Mixin for all transformations in Heat. .. role:: raw-html(raw) :format: html .. method:: fit(x: heat.core.dndarray.DNDarray) Fits the transformation model. :param x: Training instances to train on. Shape = (n_samples, n_features) :type x: DNDarray .. method:: fit_transform(x: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Fits model and returns transformed data for each input sample Convenience method; equivalent to calling :func:`fit` followed by :func:`transform`. :param x: Input data to be transformed. Shape = (n_samples, n_features) :type x: DNDarray .. method:: transform(x: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Transforms the input data. :param x: Values to transform. Shape = (n_samples, n_features) :type x: DNDarray .. py:class:: ClusteringMixin Clustering mixin for all clusterers in Heat. .. role:: raw-html(raw) :format: html .. method:: fit(x: heat.core.dndarray.DNDarray) Computes the clustering. :param x: Training instances to cluster. Shape = (n_samples, n_features) :type x: DNDarray .. method:: fit_predict(x: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Compute clusters and returns the predicted cluster assignment for each sample. Returns index of the cluster each sample belongs to. Convenience method; equivalent to calling :func:`fit` followed by :func:`predict`. :param x: Input data to be clustered. Shape = (n_samples, n_features) :type x: DNDarray .. py:class:: RegressionMixin Mixin for all regression estimators in Heat. .. role:: raw-html(raw) :format: html .. method:: fit(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray) Fits the regression model. :param x: Training instances to train on. Shape = (n_samples, n_features) :type x: DNDarray :param y: Continuous values to fit. Shape = (n_samples,) :type y: DNDarray .. method:: fit_predict(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Fits model and returns regression predictions for each input sample Convenience method; equivalent to calling :func:`fit` followed by :func:`predict`. :param x: Input data to be predicted. Shape = (n_samples, n_features) :type x: DNDarray :param y: Continuous values to fit. Shape = (n_samples,) :type y: DNDarray .. method:: predict(x: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Predicts the continuous labels for each sample. :param x: Values to let the model predict. Shape = (n_samples, n_features) :type x: DNDarray .. function:: is_classifier(estimator: object) -> bool Return ``True`` if the given estimator is a classifier, ``False`` otherwise. :param estimator: Estimator object to test. :type estimator: object .. function:: is_transformer(estimator: object) -> bool Return ``True`` if the given estimator is a transformer, ``False`` otherwise. :param estimator: Estimator object to test. :type estimator: object .. function:: is_estimator(estimator: object) -> bool Return ``True`` if the given estimator is an estimator, ``False`` otherwise. :param estimator: Estimator object to test. :type estimator: object .. function:: is_clusterer(estimator: object) -> bool Return ``True`` if the given estimator is a clusterer, ``False`` otherwise. :param estimator: Estimator object to test. :type estimator: object .. function:: is_regressor(estimator: object) -> bool Return ``True`` if the given estimator is a regressor, ``False`` otherwise. :param estimator: Estimator object to test. :type estimator: object .. function:: sanitize_axis(shape: Tuple[int, Ellipsis], axis: Union[int, None, Tuple[int, Ellipsis]]) -> Union[int, None, Tuple[int, Ellipsis]] Checks conformity of an axis with respect to a given shape. The axis will be converted to its positive equivalent and is checked to be within bounds :param shape: Shape of an array :type shape: Tuple[int, ...] :param axis: The axis to be sanitized :type axis: ints or Tuple[int, ...] or None :raises ValueError: if the axis cannot be sanitized, i.e. out of bounds. :raises TypeError: if the axis is not integral. .. rubric:: Examples >>> import heat as ht >>> ht.core.stride_tricks.sanitize_axis((5, 4, 4), 1) 1 >>> ht.core.stride_tricks.sanitize_axis((5, 4, 4), -1) 2 >>> ht.core.stride_tricks.sanitize_axis((5, 4), (1,)) (1,) >>> ht.core.stride_tricks.sanitize_axis((5, 4), 1.0) Traceback (most recent call last): File "", line 1, in File "heat/heat/core/stride_tricks.py", line 99, in sanitize_axis raise TypeError("axis must be None or int or tuple, but was {}".format(type(axis))) TypeError: axis must be None or int or tuple, but was .. py:class:: MPIRequest(handle, sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any] = None, recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any] = None, tensor: torch.Tensor = None, permutation: Tuple[int, Ellipsis] = None) Represents a handle on a non-blocking operation :param handle: Handle for the mpi4py Communicator :type handle: MPI.Communicator :param sendbuf: The buffer for the data to be send :type sendbuf: DNDarray or torch.Tensor or Any :param recvbuf: The buffer to the receive data :type recvbuf: DNDarray or torch.Tensor or Any :param tensor: Internal Data :type tensor: torch.Tensor :param permutation: Permutation of the tensor axes :type permutation: Tuple[int,...] .. attribute:: handle .. attribute:: tensor :annotation: = None .. attribute:: recvbuf :annotation: = None .. attribute:: sendbuf :annotation: = None .. attribute:: permutation :annotation: = None .. role:: raw-html(raw) :format: html .. method:: Wait(status: mpi4py.MPI.Status = None) Waits for an MPI request to complete .. method:: __getattr__(name: str) -> Callable Default pass-through for the communicator methods. :param name: The name of the method to be called. :type name: str .. py:class:: Communication Base class for Communications (inteded for other backends) .. role:: raw-html(raw) :format: html .. method:: is_distributed() -> NotImplementedError Whether or not the Communication is distributed .. method:: chunk(shape, split) -> NotImplementedError Calculates the chunk of data that will be assigned to this compute node given a global data shape and a split axis. Returns ``(offset, local_shape, slices)``: the offset in the split dimension, the resulting local shape if the global input shape is chunked on the split axis and the chunk slices with respect to the given shape :param shape: The global shape of the data to be split :type shape: Tuple[int,...] :param split: The axis along which to chunk the data :type split: int .. py:class:: MPICommunication(handle=MPI.COMM_WORLD) Bases: :class:`Communication` Class encapsulating all MPI Communication :param handle: Handle for the mpi4py Communicator :type handle: MPI.Communicator .. attribute:: COUNT_LIMIT .. attribute:: __mpi_type_mappings .. attribute:: __mpi_dtype2ctype .. attribute:: handle .. role:: raw-html(raw) :format: html .. method:: is_distributed() -> bool Determines whether the communicator is distributed, i.e. handles more than one node. .. method:: chunk(shape: Tuple[int], split: int, rank: int = None, w_size: int = None, sparse: bool = False) -> Tuple[int, Tuple[int], Tuple[slice]] Calculates the chunk of data that will be assigned to this compute node given a global data shape and a split axis. Returns ``(offset, local_shape, slices)``: the offset in the split dimension, the resulting local shape if the global input shape is chunked on the split axis and the chunk slices with respect to the given shape :param shape: The global shape of the data to be split :type shape: Tuple[int,...] :param split: The axis along which to chunk the data :type split: int :param rank: Process for which the chunking is calculated for, defaults to ``self.rank``. Intended for creating chunk maps without communication :type rank: int, optional :param w_size: The MPI world size, defaults to ``self.size``. Intended for creating chunk maps without communication :type w_size: int, optional :param sparse: Specifies whether the array is a sparse matrix :type sparse: bool, optional .. method:: counts_displs_shape(shape: Tuple[int], axis: int) -> Tuple[Tuple[int], Tuple[int], Tuple[int]] Calculates the item counts, displacements and output shape for a variable sized all-to-all MPI-call (e.g. ``MPI_Alltoallv``). The passed shape is regularly chunk along the given axis and for all nodes. :param shape: The object for which to calculate the chunking. :type shape: Tuple[int,...] :param axis: The axis along which the chunking is performed. :type axis: int .. method:: mpi_type_of(dtype: torch.dtype) -> mpi4py.MPI.Datatype Determines the MPI Datatype from the torch dtype. :param dtype: PyTorch data type :type dtype: torch.dtype .. method:: _handle_large_count(mpi_type: mpi4py.MPI.Datatype, elements: int) -> Tuple[mpi4py.MPI.Datatype, int] Handles large counts for MPI data types by creating vector types to circumvent the MAX_INT limit on certain MPI implementations. :param mpi_type: The base MPI data type :type mpi_type: MPI.Datatype :param elements: The total number of elements to be sent :type elements: int :returns: A tuple containing the constructed MPI data type and the count (always 1 in this case) :rtype: Tuple[MPI.Datatype, int] :raises ValueError: If the tensor is too large to be handled .. rubric:: Notes Uses vector type to get around the MAX_INT limit on certain MPI implementations This is at the moment only applied when sending contiguous data, as the construction of data types to get around non-contiguous data naturally aliviates the problem to a certain extent. Thanks to: J. R. Hammond, A. Schäfer and R. Latham, "To INT_MAX... and Beyond! Exploring Large-Count Support in MPI," 2014 Workshop on Exascale MPI at Supercomputing Conference, New Orleans, LA, USA, 2014, pp. 1-8 .. method:: mpi_type_and_elements_of(obj: Union[heat.core.dndarray.DNDarray, torch.Tensor], counts: Optional[Tuple[int]], displs: Tuple[int], is_contiguous: Optional[bool]) -> Tuple[mpi4py.MPI.Datatype, Tuple[int, Ellipsis]] Determines the MPI data type and number of respective elements for the given tensor (:class:`~heat.core.dndarray.DNDarray` or ``torch.Tensor). In case the tensor is contiguous in memory, a native MPI data type can be used. Otherwise, a derived data type is automatically constructed using the storage information of the passed object. :param obj: The object for which to construct the MPI data type and number of elements :type obj: DNDarray or torch.Tensor :param counts: Optional counts arguments for variable MPI-calls (e.g. Alltoallv) :type counts: Tuple[ints,...], optional :param displs: Optional displacements arguments for variable MPI-calls (e.g. Alltoallv) :type displs: Tuple[ints,...], optional :param is_contiguous: Information on global contiguity of the memory-distributed object. If `None`, it will be set to local contiguity via ``torch.Tensor.is_contiguous()``. :type is_contiguous: bool :param # ToDo: :type # ToDo: The option to explicitely specify the counts and displacements to be send still needs propper implementation .. method:: as_mpi_memory(obj: torch.Tensor) -> mpi4py.MPI.memory Converts the passed ``torch.Tensor`` into an MPI compatible memory view. :param obj: The tensor to be converted into a MPI memory view. :type obj: torch.Tensor .. method:: as_buffer(obj: torch.Tensor, counts: Optional[Tuple[int]] = None, displs: Optional[Tuple[int]] = None, is_contiguous: Optional[bool] = None) -> List[Union[mpi4py.MPI.memory, Tuple[int, int], mpi4py.MPI.Datatype]] Converts a passed ``torch.Tensor`` into a memory buffer object with associated number of elements and MPI data type. :param obj: The object to be converted into a buffer representation. :type obj: torch.Tensor :param counts: Optional counts arguments for variable MPI-calls (e.g. Alltoallv) :type counts: Tuple[int,...], optional :param displs: Optional displacements arguments for variable MPI-calls (e.g. Alltoallv) :type displs: Tuple[int,...], optional :param is_contiguous: Optional information on global contiguity of the memory-distributed object. :type is_contiguous: bool, optional .. method:: _moveToCompDevice(x: torch.Tensor, func: Callable | None) -> torch.Tensor Moves the torch tensor to the relevant device, in case the function is not compatible with the MPI+GPU library. .. method:: alltoall_sendbuffer(obj: torch.Tensor) -> List[Union[mpi4py.MPI.memory, Tuple[int, int], mpi4py.MPI.Datatype]] Converts a passed ``torch.Tensor`` into a memory buffer object with associated number of elements and MPI data type. XXX: might not work for all MPI stacks. Might require multiple type commits or so :param obj: The object to be transformed into a custom MPI datatype :type obj: torch.Tensor .. method:: alltoall_recvbuffer(obj: torch.Tensor) -> List[Union[mpi4py.MPI.memory, Tuple[int, int], mpi4py.MPI.Datatype]] Converts a passed ``torch.Tensor`` into a memory buffer object with associated number of elements and MPI data type. XXX: might not work for all MPI stacks. Might require multiple type commits or so :param obj: The object to be transformed into a custom MPI datatype :type obj: torch.Tensor .. method:: Free() -> None Free a communicator. .. method:: Split(color: int = 0, key: int = 0) -> MPICommunication Split communicator by color and key. :param color: Determines the new communicator for a process. :type color: int, optional :param key: Ordering within the new communicator. :type key: int, optional .. method:: Irecv(buf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], source: int = MPI.ANY_SOURCE, tag: int = MPI.ANY_TAG) -> MPIRequest Nonblocking receive :param buf: Buffer address where to place the received message :type buf: Union[DNDarray, torch.Tensor, Any] :param source: Rank of source process, that send the message :type source: int, optional :param tag: A Tag to identify the message :type tag: int, optional .. method:: Recv(buf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], source: int = MPI.ANY_SOURCE, tag: int = MPI.ANY_TAG, status: mpi4py.MPI.Status = None) Blocking receive :param buf: Buffer address where to place the received message :type buf: Union[DNDarray, torch.Tensor, Any] :param source: Rank of the source process, that send the message :type source: int, optional :param tag: A Tag to identify the message :type tag: int, optional :param status: Details on the communication :type status: MPI.Status, optional .. method:: __send_like(func: Callable, buf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], dest: int, tag: int) -> Tuple[Optional[Union[heat.core.dndarray.DNDarray, torch.Tensor]]] Generic function for sending a message to process with rank "dest" :param func: The respective MPI sending function :type func: Callable :param buf: Buffer address of the message to be send :type buf: Union[DNDarray, torch.Tensor, Any] :param dest: Rank of the destination process, that receives the message :type dest: int, optional :param tag: A Tag to identify the message :type tag: int, optional .. method:: Bsend(buf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], dest: int, tag: int = 0) Blocking buffered send :param buf: Buffer address of the message to be send :type buf: Union[DNDarray, torch.Tensor, Any] :param dest: Index of the destination process, that receives the message :type dest: int, optional :param tag: A Tag to identify the message :type tag: int, optional .. method:: Ibsend(buf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], dest: int, tag: int = 0) -> MPIRequest Nonblocking buffered send :param buf: Buffer address of the message to be send :type buf: Union[DNDarray, torch.Tensor, Any] :param dest: Rank of the destination process, that receives the message :type dest: int, optional :param tag: A Tag to identify the message :type tag: int, optional .. method:: Irsend(buf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], dest: int, tag: int = 0) -> MPIRequest Nonblocking ready send :param buf: Buffer address of the message to be send :type buf: Union[DNDarray, torch.Tensor, Any] :param dest: Rank of the destination process, that receives the message :type dest: int, optional :param tag: A Tag to identify the message :type tag: int, optional .. method:: Isend(buf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], dest: int, tag: int = 0) -> MPIRequest Nonblocking send :param buf: Buffer address of the message to be send :type buf: Union[DNDarray, torch.Tensor, Any] :param dest: Rank of the destination process, that receives the message :type dest: int, optional :param tag: A Tag to identify the message :type tag: int, optional .. method:: Issend(buf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], dest: int, tag: int = 0) -> MPIRequest Nonblocking synchronous send :param buf: Buffer address of the message to be send :type buf: Union[DNDarray, torch.Tensor, Any] :param dest: Rank of the destination process, that receives the message :type dest: int, optional :param tag: A Tag to identify the message :type tag: int, optional .. method:: Rsend(buf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], dest: int, tag: int = 0) Blocking ready send :param buf: Buffer address of the message to be send :type buf: Union[DNDarray, torch.Tensor, Any] :param dest: Rank of the destination process, that receives the message :type dest: int, optional :param tag: A Tag to identify the message :type tag: int, optional .. method:: Ssend(buf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], dest: int, tag: int = 0) Blocking synchronous send :param buf: Buffer address of the message to be send :type buf: Union[DNDarray, torch.Tensor, Any] :param dest: Rank of the destination process, that receives the message :type dest: int, optional :param tag: A Tag to identify the message :type tag: int, optional .. method:: Send(buf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], dest: int, tag: int = 0) Blocking send :param buf: Buffer address of the message to be send :type buf: Union[DNDarray, torch.Tensor, Any] :param dest: Rank of the destination process, that receives the message :type dest: int, optional :param tag: A Tag to identify the message :type tag: int, optional .. method:: __broadcast_like(func: Callable, buf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], root: int) -> Tuple[Optional[heat.core.dndarray.DNDarray, torch.Tensor]] Generic function for broadcasting a message from the process with rank "root" to all other processes of the communicator :param func: The respective MPI broadcast function :type func: Callable :param buf: Buffer address of the message to be broadcasted :type buf: Union[DNDarray, torch.Tensor, Any] :param root: Rank of the root process, that broadcasts the message :type root: int .. method:: Bcast(buf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], root: int = 0) -> None Blocking Broadcast :param buf: Buffer address of the message to be broadcasted :type buf: Union[DNDarray, torch.Tensor, Any] :param root: Rank of the root process, that broadcasts the message :type root: int .. method:: Ibcast(buf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], root: int = 0) -> MPIRequest Nonblocking Broadcast :param buf: Buffer address of the message to be broadcasted :type buf: Union[DNDarray, torch.Tensor, Any] :param root: Rank of the root process, that broadcasts the message :type root: int .. method:: __derived_op(tensor: torch.Tensor, datatype: mpi4py.MPI.Datatype, operation: mpi4py.MPI.Op) -> Callable[[mpi4py.MPI.memory, mpi4py.MPI.memory, mpi4py.MPI.Datatype], None] .. method:: _minmax_op(dtype: torch.dtype, total_count: int, shape: Tuple[int], stride: Tuple[int], offset: int = 0) -> Callable[[mpi4py.MPI.memory, mpi4py.MPI.memory, mpi4py.MPI.Datatype], None] Create an MPI.Op for elementwise min/max combine of a packed buffer [mins; maxs]. :param dtype: torch.dtype of underlying elements :type dtype: torch.dtype :param total_count: Number of elements per mins OR per max (so recv buffer has 2*total_count elements) :type total_count: int :param shape: Shape of the packed buffer that the MPI callback will operate on. This describes the logical shape of the concatenated buffer [mins; maxs] :type shape: Tuple[int] :param stride: Stride (in elements) of the packed buffer's storage, matching the layout :type stride: Tuple[int] :param offset: Storage offset (if needed), default 0 :type offset: int, optional .. method:: __reduce_like(func: Callable, sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], op: mpi4py.MPI.Op, *args: Any, **kwargs: Any) -> Tuple[Optional[heat.core.dndarray.DNDarray, torch.Tensor]] Generic function for reduction operations. :param func: The respective MPI reduction operation :type func: Callable :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result of the reduction :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param op: Operation to apply during the reduction. :type op: MPI.Op :param \*args: Additional positional arguments to be passed to the function :type \*args: Any :param \*\*kwargs: Additional keyword arguments to be passed to the function :type \*\*kwargs: Any .. method:: Allreduce(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], op: mpi4py.MPI.Op = MPI.SUM) Combines values from all processes and distributes the result back to all processes :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result of the reduction :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param op: The operation to perform upon reduction :type op: MPI.Op .. method:: Exscan(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], op: mpi4py.MPI.Op = MPI.SUM) Computes the exclusive scan (partial reductions) of data on a collection of processes :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result of the reduction :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param op: The operation to perform upon reduction :type op: MPI.Op .. method:: Iallreduce(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], op: mpi4py.MPI.Op = MPI.SUM) -> MPIRequest Nonblocking allreduce reducing values on all processes to a single value :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result of the reduction :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param op: The operation to perform upon reduction :type op: MPI.Op .. method:: Iexscan(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], op: mpi4py.MPI.Op = MPI.SUM) -> MPIRequest Nonblocking Exscan :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result of the reduction :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param op: The operation to perform upon reduction :type op: MPI.Op .. method:: Iscan(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], op: mpi4py.MPI.Op = MPI.SUM) -> MPIRequest Nonblocking Scan :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result of the reduction :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param op: The operation to perform upon reduction :type op: MPI.Op .. method:: Ireduce(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], op: mpi4py.MPI.Op = MPI.SUM, root: int = 0) -> MPIRequest Nonblocking reduction operation :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result of the reduction :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param op: The operation to perform upon reduction :type op: MPI.Op :param root: Rank of the root process :type root: int .. method:: Reduce(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], op: mpi4py.MPI.Op = MPI.SUM, root: int = 0) Reduce values from all processes to a single value on process "root" :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result of the reduction :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param op: The operation to perform upon reduction :type op: MPI.Op :param root: Rank of the root process :type root: int .. method:: Scan(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], op: mpi4py.MPI.Op = MPI.SUM) Computes the scan (partial reductions) of data on a collection of processes in a nonblocking way :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result of the reduction :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param op: The operation to perform upon reduction :type op: MPI.Op .. method:: __allgather_like(func: Callable, sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], axis: int, **kwargs) Generic function for allgather operations. :param func: Type of MPI Allgather function (i.e. allgather, allgatherv, iallgather) :type func: Callable :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param axis: Concatenation axis: The axis along which ``sendbuf`` is packed and along which ``recvbuf`` puts together individual chunks :type axis: int :param \*\*kwargs: Extra arguments to be passed to the function. .. method:: Allgather(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recv_axis: int = 0) Gathers data from all tasks and distribute the combined data to all tasks :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param recv_axis: Concatenation axis: The axis along which ``sendbuf`` is packed and along which ``recvbuf`` puts together individual chunks :type recv_axis: int .. method:: Allgatherv(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recv_axis: int = 0) v-call of Allgather: Each process may contribute a different amount of data. :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param recv_axis: Concatenation axis: The axis along which ``sendbuf`` is packed and along which ``recvbuf`` puts together individual chunks :type recv_axis: int .. method:: Iallgather(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recv_axis: int = 0) -> MPIRequest Nonblocking Allgather. :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param recv_axis: Concatenation axis: The axis along which ``sendbuf`` is packed and along which ``recvbuf`` puts together individual chunks :type recv_axis: int .. method:: Iallgatherv(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recv_axis: int = 0) Nonblocking v-call of Allgather: Each process may contribute a different amount of data. :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param recv_axis: Concatenation axis: The axis along which ``sendbuf`` is packed and along which ``recvbuf`` puts together individual chunks :type recv_axis: int .. method:: __alltoall_like(func: Callable, sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], send_axis: int, recv_axis: int, **kwargs) Generic function for alltoall operations. :param func: Specific alltoall function :type func: Callable :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param send_axis: Future split axis, along which data blocks will be created that will be send to individual ranks - if ``send_axis==recv_axis``, an error will be thrown - if ``send_axis`` or ``recv_axis`` are ``None``, an error will be thrown :type send_axis: int :param recv_axis: Prior split axis, along which blocks are received from the individual ranks :type recv_axis: int :param \*\*kwargs: Extra arguments to be passed to the function. .. method:: Alltoall(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], send_axis: int = 0, recv_axis: int = None) All processes send data to all processes: The jth block sent from process i is received by process j and is placed in the ith block of recvbuf. :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param send_axis: Future split axis, along which data blocks will be created that will be send to individual ranks - if ``send_axis==recv_axis``, an error will be thrown - if ``send_axis`` or ``recv_axis`` are ``None``, an error will be thrown :type send_axis: int :param recv_axis: Prior split axis, along which blocks are received from the individual ranks :type recv_axis: int .. method:: Alltoallv(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], send_axis: int = 0, recv_axis: int = None) v-call of Alltoall: All processes send different amount of data to, and receive different amount of data from, all processes :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param send_axis: Future split axis, along which data blocks will be created that will be send to individual ranks - if ``send_axis==recv_axis``, an error will be thrown - if ``send_axis`` or ``recv_axis`` are ``None``, an error will be thrown :type send_axis: int :param recv_axis: Prior split axis, along which blocks are received from the individual ranks :type recv_axis: int .. method:: Alltoallw(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any]) Generalized All-to-All communication allowing different counts, displacements and datatypes for each partner. See MPI standard for more information. :param sendbuf: Buffer address of the send message. The buffer is expected to be a tuple of the form (buffer, (counts, displacements), subarray_params_list), where subarray_params_list is a list of tuples of the form (lshape, subsizes, substarts). :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result. The buffer is expected to be a tuple of the form (buffer, (counts, displacements), subarray_params_list), where subarray_params_list is a list of tuples of the form (lshape, subsizes, substarts). :type recvbuf: Union[DNDarray, torch.Tensor, Any] .. method:: _create_recursive_vectortype(datatype: mpi4py.MPI.Datatype, tensor_stride: Tuple[int], subarray_sizes: List[int], start: List[int]) -> mpi4py.MPI.Datatype Create a recursive vector to handle non-contiguous tensor data. The created datatype will be a recursively defined vector datatype that will enable the collection of non-contiguous tensor data in the specified subarray sizes. :param datatype: The base datatype to create the recursive vector datatype from. :type datatype: MPI.Datatype :param tensor_stride: A list of tensor strides for each dimension. :type tensor_stride: Tuple[int] :param subarray_sizes: A list of subarray sizes for each dimension. :type subarray_sizes: List[int] :param start: Index of the first element of the subarray in the original array. :type start: List[int] .. rubric:: Notes This function creates a recursive vector datatype by defining vectors out of the previous datatype with specified strides and sizes. The extent (size of the data type in bytes) of the new datatype is set to the extent of the basic datatype to allow interweaving of data. .. rubric:: Examples >>> datatype = MPI.INT >>> tensor_stride = [1, 2, 3] >>> subarray_sizes = [4, 5, 6] >>> recursive_vectortype = create_recursive_vectortype( ... datatype, tensor_stride, subarray_sizes ... ) .. method:: Ialltoall(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], send_axis: int = 0, recv_axis: int = None) -> MPIRequest Nonblocking Alltoall :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param send_axis: Future split axis, along which data blocks will be created that will be send to individual ranks - if ``send_axis==recv_axis``, an error will be thrown - if ``send_axis`` or ``recv_axis`` are ``None``, an error will be thrown :type send_axis: int :param recv_axis: Prior split axis, along which blocks are received from the individual ranks :type recv_axis: int .. method:: Ialltoallv(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], send_axis: int = 0, recv_axis: int = None) -> MPIRequest Nonblocking v-call of Alltoall: All processes send different amount of data to, and receive different amount of data from, all processes :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param send_axis: Future split axis, along which data blocks will be created that will be send to individual ranks - if ``send_axis==recv_axis``, an error will be thrown - if ``send_axis`` or ``recv_axis`` are ``None``, an error will be thrown :type send_axis: int :param recv_axis: Prior split axis, along which blocks are received from the individual ranks :type recv_axis: int .. method:: __gather_like(func: Callable, sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], send_axis: int, recv_axis: int, send_factor: int = 1, recv_factor: int = 1, **kwargs) Generic function for gather operations. :param func: Type of MPI Scatter/Gather function :type func: Callable :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param send_axis: The axis along which ``sendbuf`` is packed :type send_axis: int :param recv_axis: The axis along which ``recvbuf`` is packed :type recv_axis: int :param send_factor: Number of elements to be scattered (vor non-v-calls) :type send_factor: int :param recv_factor: Number of elements to be gathered (vor non-v-calls) :type recv_factor: int :param \*\*kwargs: Extra arguments to be passed to the function. .. method:: Gather(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], root: int = 0, axis: int = 0, recv_axis: int = None) Gathers together values from a group of processes :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param root: Rank of receiving process :type root: int :param axis: The axis along which ``sendbuf`` is packed :type axis: int :param recv_axis: The axis along which ``recvbuf`` is packed :type recv_axis: int .. method:: Gatherv(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], root: int = 0, axis: int = 0, recv_axis: int = None) v-call for Gather: All processes send different amount of data :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param root: Rank of receiving process :type root: int :param axis: The axis along which ``sendbuf`` is packed :type axis: int :param recv_axis: The axis along which ``recvbuf`` is packed :type recv_axis: int .. method:: Igather(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], root: int = 0, axis: int = 0, recv_axis: int = None) -> MPIRequest Non-blocking Gather :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param root: Rank of receiving process :type root: int :param axis: The axis along which ``sendbuf`` is packed :type axis: int :param recv_axis: The axis along which ``recvbuf`` is packed :type recv_axis: int .. method:: Igatherv(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], root: int = 0, axis: int = 0, recv_axis: int = None) -> MPIRequest Non-blocking v-call for Gather: All processes send different amount of data :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param root: Rank of receiving process :type root: int :param axis: The axis along which ``sendbuf`` is packed :type axis: int :param recv_axis: The axis along which ``recvbuf`` is packed :type recv_axis: int .. method:: __scatter_like(func: Callable, sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], send_axis: int, recv_axis: int, send_factor: int = 1, recv_factor: int = 1, **kwargs) Generic function for scatter operations. :param func: Type of MPI Scatter/Gather function :type func: Callable :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param send_axis: The axis along which ``sendbuf`` is packed :type send_axis: int :param recv_axis: The axis along which ``recvbuf`` is packed :type recv_axis: int :param send_factor: Number of elements to be scattered (vor non-v-calls) :type send_factor: int :param recv_factor: Number of elements to be gathered (vor non-v-calls) :type recv_factor: int :param \*\*kwargs: Extra arguments to be passed to the function. .. method:: Iscatter(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], root: int = 0, axis: int = 0, recv_axis: int = None) -> MPIRequest Non-blocking Scatter :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param root: Rank of sending process :type root: int :param axis: The axis along which ``sendbuf`` is packed :type axis: int :param recv_axis: The axis along which ``recvbuf`` is packed :type recv_axis: int .. method:: Iscatterv(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], root: int = 0, axis: int = 0, recv_axis: int = None) -> MPIRequest Non-blocking v-call for Scatter: Sends different amounts of data to different processes :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param root: Rank of sending process :type root: int :param axis: The axis along which ``sendbuf`` is packed :type axis: int :param recv_axis: The axis along which ``recvbuf`` is packed :type recv_axis: int .. method:: Scatter(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], root: int = 0, axis: int = 0, recv_axis: int = None) Sends data parts from one process to all other processes in a communicator :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param root: Rank of sending process :type root: int :param axis: The axis along which ``sendbuf`` is packed :type axis: int :param recv_axis: The axis along which ``recvbuf`` is packed :type recv_axis: int .. method:: Scatterv(sendbuf: Union[heat.core.dndarray.DNDarray, torch.Tensor, Any], recvbuf: int, root: int = 0, axis: int = 0, recv_axis: int = None) v-call for Scatter: Sends different amounts of data to different processes :param sendbuf: Buffer address of the send message :type sendbuf: Union[DNDarray, torch.Tensor, Any] :param recvbuf: Buffer address where to store the result :type recvbuf: Union[DNDarray, torch.Tensor, Any] :param root: Rank of sending process :type root: int :param axis: The axis along which ``sendbuf`` is packed :type axis: int :param recv_axis: The axis along which ``recvbuf`` is packed :type recv_axis: int .. method:: __getattr__(name: str) Default pass-through for the communicator methods. :param name: The name of the method to be called. :type name: str .. function:: get_comm() -> Communication Retrieves the currently globally set default communication. .. function:: sanitize_comm(comm: Optional[Communication]) -> Communication Sanitizes a device or device identifier, i.e. checks whether it is already an instance of :class:`heat.core.devices.Device` or a string with known device identifier and maps it to a proper ``Device``. :param comm: The comm to be sanitized :type comm: Communication :raises TypeError: If the given communication is not the proper type .. function:: use_comm(comm: Communication = None) Sets the globally used default communicator. :param comm: The communication to be set :type comm: Communication or None .. data:: e :annotation: = 2.718281828459045 Euler's number, Euler's constant (:math:`e`). .. data:: Euler :annotation: = 2.718281828459045 Euler's number, Euler's constant (:math:`e`). .. data:: inf IEEE 754 floating point representation of (positive) infinity (:math:`\infty`). .. data:: Inf IEEE 754 floating point representation of (positive) infinity (:math:`\infty`). .. data:: Infty IEEE 754 floating point representation of (positive) infinity (:math:`\infty`). .. data:: Infinity IEEE 754 floating point representation of (positive) infinity (:math:`\infty`). .. data:: nan IEEE 754 floating point representation of Not a Number (NaN). .. data:: NaN IEEE 754 floating point representation of Not a Number (NaN). .. data:: pi :annotation: = 3.141592653589793 Archimedes' constant (:math:`\pi`). .. function:: angle(x: heat.core.dndarray.DNDarray, deg: bool = False, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Calculate the element-wise angle of the complex argument. :param x: Input array for which to compute the angle. :type x: DNDarray :param deg: Return the angle in degrees (True) or radiands (False). :type deg: bool, optional :param out: Output array with the angles. :type out: DNDarray, optional .. rubric:: Examples >>> ht.angle(ht.array([1.0, 1.0j, 1 + 1j, -2 + 2j, 3 - 3j])) DNDarray([ 0.0000, 1.5708, 0.7854, 2.3562, -0.7854], dtype=ht.float32, device=cpu:0, split=None) >>> ht.angle(ht.array([1.0, 1.0j, 1 + 1j, -2 + 2j, 3 - 3j]), deg=True) DNDarray([ 0., 90., 45., 135., -45.], dtype=ht.float32, device=cpu:0, split=None) .. function:: conjugate(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compute the complex conjugate, element-wise. :param x: Input array for which to compute the complex conjugate. :type x: DNDarray :param out: Output array with the complex conjugates. :type out: DNDarray, optional .. rubric:: Examples >>> ht.conjugate(ht.array([1.0, 1.0j, 1 + 1j, -2 + 2j, 3 - 3j])) DNDarray([ (1-0j), -1j, (1-1j), (-2-2j), (3+3j)], dtype=ht.complex64, device=cpu:0, split=None) .. function:: imag(x: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Return the imaginary part of the complex argument. The returned DNDarray and the input DNDarray share the same underlying storage. :param x: Input array for which the imaginary part is returned. :type x: DNDarray .. rubric:: Examples >>> ht.imag(ht.array([1.0, 1.0j, 1 + 1j, -2 + 2j, 3 - 3j])) DNDarray([ 0., 1., 1., 2., -3.], dtype=ht.float32, device=cpu:0, split=None) .. function:: real(x: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Return the real part of the complex argument. The returned DNDarray and the input DNDarray share the same underlying storage. :param x: Input array for which the real part is returned. :type x: DNDarray .. rubric:: Examples >>> ht.real(ht.array([1.0, 1.0j, 1 + 1j, -2 + 2j, 3 - 3j])) DNDarray([ 1., 0., 1., -2., 3.], dtype=ht.float32, device=cpu:0, split=None) .. py:class:: Device(device_type: str, device_id: int, torch_device: str) Implements a compute device. Heat can run computations on different compute devices or backends. A device describes the device type and id on which said computation should be carried out. :param device_type: Represents Heat's device name :type device_type: str :param device_id: The device id :type device_id: int :param torch_device: The corresponding PyTorch device type :type torch_device: str .. rubric:: Examples >>> ht.Device("cpu", 0, "cpu:0") device(cpu:0) >>> ht.Device("gpu", 0, "cuda:0") device(gpu:0) >>> ht.Device("gpu", 0, "mps:0") # on Apple M1/M2 device(gpu:0) .. attribute:: __device_type .. attribute:: __device_id .. attribute:: __torch_device .. role:: raw-html(raw) :format: html .. method:: __repr__() -> str Return the unambiguous information of :class:`~heat.core.device.Device`. .. method:: __str__() -> str Return the descriptive information of :class:`~heat.core.device.Device`. .. method:: __eq__(other: Any) -> bool Overloads the `==` operator for local equal check. :param other: The object to compare with :type other: Any .. data:: cpu The standard CPU Device .. rubric:: Examples >>> ht.cpu device(cpu:0) >>> ht.ones((2, 3), device=ht.cpu) DNDarray([[1., 1., 1.], [1., 1., 1.]], dtype=ht.float32, device=cpu:0, split=None) .. function:: get_device() -> Device Retrieves the currently globally set default :class:`~heat.core.device.Device`. .. function:: sanitize_device(device: Optional[Union[str, Device]] = None) -> Device Sanitizes a device or device identifier, i.e. checks whether it is already an instance of :class:`~heat.core.device.Device` or a string with known device identifier and maps it to a proper :class:`~heat.core.device.Device`. :param device: The device to be sanitized :type device: str or Device, optional :raises ValueError: If the given device id is not recognized .. function:: use_device(device: Optional[Union[str, Device]] = None) -> None Sets the globally used default :class:`~heat.core.device.Device`. :param device: The device to be set :type device: str or Device .. function:: exp(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Calculate the exponential of all elements in the input array. Result is a :py:class:`~heat.core.dndarray.DNDarray` of the same shape as ``x``. :param x: The array for which to compute the exponential. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to :keyword:`None`, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.exp(ht.arange(5)) DNDarray([ 1.0000, 2.7183, 7.3891, 20.0855, 54.5981], dtype=ht.float32, device=cpu:0, split=None) .. function:: expm1(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Calculate :math:`exp(x) - 1` for all elements in the array. Result is a :py:class:`~heat.core.dndarray.DNDarray` of the same shape as ``x``. :param x: The array for which to compute the exponential. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to :keyword:`None`, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.expm1(ht.arange(5)) + 1.0 DNDarray([ 1.0000, 2.7183, 7.3891, 20.0855, 54.5981], dtype=ht.float64, device=cpu:0, split=None) .. function:: exp2(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Calculate the exponential of two of all elements in the input array (:math:`2^x`). Result is a :py:class:`~heat.core.dndarray.DNDarray` of the same shape as ``x``. :param x: The array for which to compute the exponential of two. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to :keyword:`None`, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.exp2(ht.arange(5)) DNDarray([ 1., 2., 4., 8., 16.], dtype=ht.float32, device=cpu:0, split=None) .. function:: log(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Natural logarithm, element-wise. The natural logarithm is the inverse of the exponential function, so that :math:`log(exp(x)) = x`. The natural logarithm is logarithm in base e. Result is a :py:class:`~heat.core.dndarray.DNDarray` of the same shape as ``x``. Negative input elements are returned as :abbr:`NaN (Not a Number)`. :param x: The array for which to compute the logarithm. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to :keyword:`None`, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.log(ht.arange(5)) DNDarray([ -inf, 0.0000, 0.6931, 1.0986, 1.3863], dtype=ht.float32, device=cpu:0, split=None) .. function:: log2(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compute the logarithm to the base 2 (:math:`log_2(x)`), element-wise. Result is a :py:class:`~heat.core.dndarray.DNDarray` of the same shape as ``x``. Negative input elements are returned as :abbr:`NaN (Not a Number)`. :param x: The array for which to compute the logarithm. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to :keyword:`None`, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.log2(ht.arange(5)) DNDarray([ -inf, 0.0000, 1.0000, 1.5850, 2.0000], dtype=ht.float32, device=cpu:0, split=None) .. function:: log10(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compute the logarithm to the base 10 (:math:`log_{10}(x)`), element-wise. Result is a :py:class:`~heat.core.dndarray.DNDarray` of the same shape as ``x``. Negative input elements are returned as :abbr:`NaN (Not a Number)`. :param x: The array for which to compute the logarithm. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to :keyword:`None`, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.log10(ht.arange(5)) DNDarray([ -inf, 0.0000, 0.3010, 0.4771, 0.6021], dtype=ht.float32, device=cpu:0, split=None) .. function:: log1p(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Return the natural logarithm of one plus the input array, element-wise. Result is a :class:`~heat.core.dndarray.DNDarray` of the same shape as ``x``. Negative input elements are returned as :abbr:`NaN (Not a Number)`. :param x: The array for which to compute the logarithm. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to :keyword:`None`, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.log1p(ht.arange(5)) DNDarray([0.0000, 0.6931, 1.0986, 1.3863, 1.6094], dtype=ht.float32, device=cpu:0, split=None) .. function:: logaddexp(x1: heat.core.dndarray.DNDarray, x2: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Calculates the logarithm of the sum of exponentiations :math:`log(exp(x1) + exp(x2))` for each element :math:`{x1}_i` of the input array x1 with the respective element :math:`{x2}_i` of the input array x2. :param x1: first input array. Should have a floating-point data type. :type x1: DNDarray :param x2: second input array. Must be compatible with x1. Should have a floating-point data type. :type x2: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to :keyword:`None`, a fresh array is allocated. :type out: DNDarray, optional .. seealso:: :func:`logaddexp2` Logarithm of the sum of exponentiations of inputs in base-2. .. rubric:: Examples >>> ht.logaddexp(ht.array([-1.0]), ht.array([-1.0, -2, -3])) DNDarray([-0.3069, -0.6867, -0.8731], dtype=ht.float32, device=cpu:0, split=None) .. function:: logaddexp2(x1: heat.core.dndarray.DNDarray, x2: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Calculates the logarithm of the sum of exponentiations in base-2 :math:`log2(exp(x1) + exp(x2))` for each element :math:`{x1}_i` of the input array x1 with the respective element :math:`{x2}_i` of the input array x2. :param x1: first input array. Should have a floating-point data type. :type x1: DNDarray :param x2: second input array. Must be compatible with x1. Should have a floating-point data type. :type x2: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to :keyword:`None`, a fresh array is allocated. :type out: DNDarray, optional .. seealso:: :func:`logaddexp` Logarithm of the sum of exponentiations of inputs. .. rubric:: Examples >>> ht.logaddexp2(ht.array([-1.0]), ht.array([-1.0, -2, -3])) DNDarray([ 0.0000, -0.4150, -0.6781], dtype=ht.float32, device=cpu:0, split=None) .. function:: sqrt(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Return the non-negative square-root of a tensor element-wise. Result is a :py:class:`~heat.core.dndarray.DNDarray` of the same shape as ``x``. Negative input elements are returned as :abbr:`NaN (Not a Number)`. :param x: The array for which to compute the square-roots. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to :keyword:`None`, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.sqrt(ht.arange(5)) DNDarray([0.0000, 1.0000, 1.4142, 1.7321, 2.0000], dtype=ht.float32, device=cpu:0, split=None) >>> ht.sqrt(ht.arange(-5, 0)) DNDarray([nan, nan, nan, nan, nan], dtype=ht.float32, device=cpu:0, split=None) .. function:: square(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Return a new tensor with the squares of the elements of input. :param x: The array for which to compute the squares. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to :keyword:`None`, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> a = ht.random.rand(4) >>> a DNDarray([0.8654, 0.1432, 0.9164, 0.6179], dtype=ht.float32, device=cpu:0, split=None) >>> ht.square(a) DNDarray([0.7488, 0.0205, 0.8397, 0.3818], dtype=ht.float32, device=cpu:0, split=None) .. function:: arange(*args: Union[int, float], dtype: Optional[Type[heat.core.types.datatype]] = None, split: Optional[int] = None, device: Optional[Union[str, heat.core.devices.Device]] = None, comm: Optional[heat.core.communication.Communication] = None) -> heat.core.dndarray.DNDarray Return evenly spaced values within a given interval. Values are generated within the half-open interval ``[start, stop)`` (in other words, the interval including `start` but excluding `stop`). For integer arguments the function is equivalent to the Python built-in `range `_ function, but returns a array rather than a list. When using a non-integer step, such as 0.1, the results may be inconsistent due to being subject to numerical rounding. In the cases the usage of :func:`linspace` is recommended. For floating point arguments, the length of the result is :math:`\lceil(stop-start)/step\rceil`. Again, due to floating point rounding, this rule may result in the last element of `out` being greater than `stop` by machine epsilon. :param \*args: Positional arguments defining the interval. Can be: - A single argument: interpreted as `stop`, with `start=0` and `step=1`. - Two arguments: interpreted as `start` and `stop`, with `step=1`. - Three arguments: interpreted as `start`, `stop`, and `step`. The function raises a `TypeError` if more than three arguments are provided. :type \*args: int or float, optional :param dtype: The type of the output array. If `dtype` is not given, it is automatically inferred from the other input arguments. :type dtype: datatype, optional :param split: The axis along which the array is split and distributed; ``None`` means no distribution. :type split: int or None, optional :param device: Specifies the device the array shall be allocated on, defaults to globally set default device. :type device: str, optional :param comm: Handle to the nodes holding distributed parts or copies of this array. :type comm: Communication, optional .. seealso:: :func:`linspace` Evenly spaced numbers with careful handling of endpoints. .. rubric:: Examples >>> ht.arange(3) DNDarray([0, 1, 2], dtype=ht.int32, device=cpu:0, split=None) >>> ht.arange(3.0) DNDarray([0., 1., 2.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.arange(3, 7) DNDarray([3, 4, 5, 6], dtype=ht.int32, device=cpu:0, split=None) >>> ht.arange(3, 7, 2) DNDarray([3, 5], dtype=ht.int32, device=cpu:0, split=None) .. function:: array(obj: Iterable, dtype: Optional[Type[heat.core.types.datatype]] = None, copy: Optional[bool] = None, ndmin: int = 0, order: str = 'C', split: Optional[int] = None, is_split: Optional[int] = None, device: Optional[heat.core.devices.Device] = None, comm: Optional[heat.core.communication.Communication] = None) -> heat.core.dndarray.DNDarray Create a :class:`~heat.core.dndarray.DNDarray`. :param obj: A tensor or array, any object exposing the array interface, an object whose ``__array__`` method returns an array, or any (nested) sequence. :type obj: array_like :param dtype: The desired data-type for the array. If not given, then the type will be determined as the minimum type required to hold the objects in the sequence. This argument can only be used to ‘upcast’ the array. For downcasting, use the :func:`~heat.core.dndarray.astype` method. :type dtype: datatype, optional :param copy: If ``True``, the input object is copied. If ``False``, input which supports the buffer protocol is never copied. If ``None`` (default), the function reuses the existing memory buffer if possible, and copies otherwise. :type copy: bool, optional :param ndmin: Specifies the minimum number of dimensions that the resulting array should have. Ones will, if needed, be attached to the shape if ``ndim > 0`` and prefaced in case of ``ndim < 0`` to meet the requirement. :type ndmin: int, optional :param order: Options: ``'C'`` or ``'F'``. Specifies the memory layout of the newly created array. Default is ``order='C'``, meaning the array will be stored in row-major order (C-like). If ``order=‘F’``, the array will be stored in column-major order (Fortran-like). :type order: str, optional :param split: The axis along which the passed array content ``obj`` is split and distributed in memory. Mutually exclusive with ``is_split``. :type split: int or None, optional :param is_split: Specifies the axis along which the local data portions, passed in obj, are split across all machines. Useful for interfacing with other distributed-memory code. The shape of the global array is automatically inferred. Mutually exclusive with ``split``. :type is_split: int or None, optional :param device: Specifies the :class:`~heat.core.devices.Device` the array shall be allocated on (i.e. globally set default device). :type device: str or Device, optional :param comm: Handle to the nodes holding distributed array chunks. :type comm: Communication, optional :raises NotImplementedError: If order is one of the NumPy options ``'K'`` or ``'A'``. :raises ValueError: If ``copy`` is False but a copy is necessary to satisfy other requirements (e.g. different dtype, device, etc.). :raises TypeError: If the input object cannot be converted to a torch.Tensor, hence it cannot be converted to a :class:`~heat.core.dndarray.DNDarray`. .. rubric:: Examples >>> ht.array([1, 2, 3]) DNDarray([1, 2, 3], dtype=ht.int64, device=cpu:0, split=None) >>> ht.array([1, 2, 3.0]) DNDarray([1., 2., 3.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.array([[1, 2], [3, 4]]) DNDarray([[1, 2], [3, 4]], dtype=ht.int64, device=cpu:0, split=None) >>> ht.array([1, 2, 3], ndmin=2) DNDarray([[1], [2], [3]], dtype=ht.int64, device=cpu:0, split=None) >>> ht.array([1, 2, 3], dtype=float) DNDarray([1., 2., 3.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.array([1, 2, 3, 4], split=0) DNDarray([1, 2, 3, 4], dtype=ht.int64, device=cpu:0, split=0) >>> if ht.MPI_WORLD.rank == 0 >>> a = ht.array([1, 2], is_split=0) >>> else: >>> a = ht.array([3, 4], is_split=0) >>> a DNDarray([1, 2, 3, 4], dtype=ht.int64, device=cpu:0, split=0) >>> a = np.arange(2 * 3).reshape(2, 3) >>> a array([[ 0, 1, 2], [ 3, 4, 5]]) >>> a.strides (24, 8) >>> b = ht.array(a) >>> b DNDarray([[0, 1, 2], [3, 4, 5]], dtype=ht.int64, device=cpu:0, split=None) >>> b.strides (24, 8) >>> b.larray.untyped_storage() 0 1 2 3 4 5 [torch.LongStorage of size 6] >>> c = ht.array(a, order="F") >>> c DNDarray([[0, 1, 2], [3, 4, 5]], dtype=ht.int64, device=cpu:0, split=None) >>> c.strides (8, 16) >>> c.larray.untyped_storage() 0 3 1 4 2 5 [torch.LongStorage of size 6] >>> a = np.arange(4 * 3).reshape(4, 3) >>> a.strides (24, 8) >>> b = ht.array(a, order="F", split=0) >>> b DNDarray([[ 0, 1, 2], [ 3, 4, 5], [ 6, 7, 8], [ 9, 10, 11]], dtype=ht.int64, device=cpu:0, split=0) >>> b.strides [0/2] (8, 16) [1/2] (8, 16) >>> b.larray.untyped_storage() [0/2] 0 3 1 4 2 5 [torch.LongStorage of size 6] [1/2] 6 9 7 10 8 11 [torch.LongStorage of size 6] .. function:: asarray(obj: Iterable, dtype: Optional[Type[heat.core.types.datatype]] = None, copy: Optional[bool] = None, order: str = 'C', is_split: Optional[bool] = None, device: Optional[Union[str, heat.core.devices.Device]] = None) -> heat.core.dndarray.DNDarray Convert ``obj`` to a DNDarray. If ``obj`` is a `DNDarray` or `Tensor` with the same `dtype` and `device` or if the data is an `ndarray` of the corresponding ``dtype`` and the ``device`` is the CPU, no copy will be performed. :param obj: Input data, in any form that can be converted to an array. This includes e.g. lists, lists of tuples, tuples, tuples of tuples, tuples of lists and ndarrays. :type obj: iterable :param dtype: By default, the data-type is inferred from the input data. :type dtype: dtype, optional :param copy: If ``True``, then the object is copied. If ``False``, the object is not copied and a ``ValueError`` is raised in the case a copy would be necessary. If ``None``, a copy will only be made if `obj` is a nested sequence or if a copy is needed to satisfy any of the other requirements, e.g. ``dtype``. :type copy: bool, optional :param order: Whether to use row-major (C-style) or column-major (Fortran-style) memory representation. Defaults to ‘C’. :type order: str, optional :param is_split: Specifies the axis along which the local data portions, passed in obj, are split across all MPI processes. Useful for interfacing with other HPC code. The shape of the global tensor is automatically inferred. :type is_split: None or int, optional :param device: Specifies the device the tensor shall be allocated on. By default, it is inferred from the input data. :type device: str, ht.Device or None, optional .. rubric:: Examples >>> a = [1, 2] >>> ht.asarray(a) DNDarray([1, 2], dtype=ht.int64, device=cpu:0, split=None) >>> a = np.array([1, 2, 3]) >>> n = ht.asarray(a) >>> n DNDarray([1, 2, 3], dtype=ht.int64, device=cpu:0, split=None) >>> n[0] = 0 >>> a DNDarray([0, 2, 3], dtype=ht.int64, device=cpu:0, split=None) >>> a = torch.tensor([1, 2, 3]) >>> t = ht.asarray(a) >>> t DNDarray([1, 2, 3], dtype=ht.int64, device=cpu:0, split=None) >>> t[0] = 0 >>> a DNDarray([0, 2, 3], dtype=ht.int64, device=cpu:0, split=None) >>> a = ht.array([1, 2, 3, 4], dtype=ht.float32) >>> ht.asarray(a, dtype=ht.float32) is a True >>> ht.asarray(a, dtype=ht.float64) is a False .. function:: empty(shape: Union[int, Sequence[int]], dtype: Type[heat.core.types.datatype] = types.float32, split: Optional[int] = None, device: Optional[heat.core.devices.Device] = None, comm: Optional[heat.core.communication.Communication] = None, order: str = 'C') -> heat.core.dndarray.DNDarray Returns a new uninitialized :class:`~heat.core.dndarray.DNDarray` of given shape and data type. May be allocated split up across multiple nodes along the specified axis. :param shape: Desired shape of the output array, e.g. 1 or (1, 2, 3,). :type shape: int or Sequence[int,...] :param dtype: The desired HeAT data type for the array. :type dtype: datatype :param split: The axis along which the array is split and distributed; ``None`` means no distribution. :type split: int, optional :param device: Specifies the :class:`~heat.core.devices.Device`. the array shall be allocated on, defaults to globally set default device. :type device: str or Device, optional :param comm: Handle to the nodes holding distributed parts or copies of this array. :type comm: Communication, optional :param order: Options: ``'C'`` or ``'F'``. Specifies the memory layout of the newly created array. Default is ``order='C'``, meaning the array will be stored in row-major order (C-like). If ``order=‘F’``, the array will be stored in column-major order (Fortran-like). :type order: str, optional :raises NotImplementedError: If order is one of the NumPy options ``'K'`` or ``'A'``. .. rubric:: Examples >>> ht.empty(3) DNDarray([0., 0., 0.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.empty(3, dtype=ht.int) DNDarray([59140784, 0, 59136816], dtype=ht.int32, device=cpu:0, split=None) >>> ht.empty( ... ( ... 2, ... 3, ... ) ... ) DNDarray([[-1.7206e-10, 4.5905e-41, -1.7206e-10], [ 4.5905e-41, 4.4842e-44, 0.0000e+00]], dtype=ht.float32, device=cpu:0, split=None) .. function:: empty_like(a: heat.core.dndarray.DNDarray, dtype: Optional[Type[heat.core.types.datatype]] = None, split: Optional[int] = None, device: Optional[heat.core.devices.Device] = None, comm: Optional[heat.core.communication.Communication] = None, order: str = 'C') -> heat.core.dndarray.DNDarray Returns a new uninitialized :class:`~heat.core.dndarray.DNDarray` with the same type, shape and data distribution of given object. Data type, data distribution axis, and device can be explicitly overridden. :param a: The shape, data-type, split axis and device of ``a`` define these same attributes of the returned array. Uninitialized array with the same shape, type, split axis and device as ``a`` unless overriden. :type a: DNDarray :param dtype: Overrides the data type of the result. :type dtype: datatype, optional :param split: The axis along which the array is split and distributed; ``None`` means no distribution. :type split: int or None, optional :param device: Specifies the :class:`~heat.core.devices.Device` the array shall be allocated on, defaults to globally set default device. :type device: str or Device, optional :param comm: Handle to the nodes holding distributed parts or copies of this array. :type comm: Communication, optional :param order: Options: ``'C'`` or ``'F'``. Specifies the memory layout of the newly created array. Default is ``order='C'``, meaning the array will be stored in row-major order (C-like). If ``order=‘F’``, the array will be stored in column-major order (Fortran-like). :type order: str, optional :raises NotImplementedError: If order is one of the NumPy options ``'K'`` or ``'A'``. .. rubric:: Examples >>> x = ht.ones( ... ( ... 2, ... 3, ... ) ... ) >>> x DNDarray([[1., 1., 1.], [1., 1., 1.]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.empty_like(x) DNDarray([[-1.7205e-10, 4.5905e-41, 7.9442e-37], [ 0.0000e+00, 4.4842e-44, 0.0000e+00]], dtype=ht.float32, device=cpu:0, split=None) .. function:: eye(shape: Union[int, Sequence[int]], dtype: Type[heat.core.types.datatype] = types.float32, split: Optional[int] = None, device: Optional[heat.core.devices.Device] = None, comm: Optional[heat.core.communication.Communication] = None, order: str = 'C') -> heat.core.dndarray.DNDarray Returns a new 2-D :class:`~heat.core.dndarray.DNDarray` with ones on the diagonal and zeroes elsewhere, i.e. an identity matrix. :param shape: The shape of the data-type. If only one number is provided, returning array will be square with that size. In other cases, the first value represents the number rows, the second the number of columns. :type shape: int or Sequence[int,...] :param dtype: Overrides the data type of the result. :type dtype: datatype, optional :param split: The axis along which the array is split and distributed; ``None`` means no distribution. :type split: int or None, optional :param device: Specifies the :class:`~heat.core.devices.Device` the array shall be allocated on, defaults to globally set default device. :type device: str or Device, optional :param comm: Handle to the nodes holding distributed parts or copies of this array. :type comm: Communication, optional :param order: Options: ``'C'`` or ``'F'``. Specifies the memory layout of the newly created array. Default is ``order='C'``, meaning the array will be stored in row-major order (C-like). If ``order=‘F’``, the array will be stored in column-major order (Fortran-like). :type order: str, optional :raises NotImplementedError: If order is one of the NumPy options ``'K'`` or ``'A'``. .. rubric:: Examples >>> ht.eye(2) DNDarray([[1., 0.], [0., 1.]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.eye((2, 3), dtype=ht.int32) DNDarray([[1, 0, 0], [0, 1, 0]], dtype=ht.int32, device=cpu:0, split=None) .. function:: from_partitioned(x, comm: Optional[heat.core.communication.Communication] = None) -> heat.core.dndarray.DNDarray Return a newly created DNDarray constructed from the '__partitioned__' attributed of the input object. Memory of local partitions will be shared (zero-copy) as long as supported by data objects. Currently supports numpy ndarrays and torch tensors as data objects. Current limitations: * Partitions must be ordered in the partition-grid by rank * Only one split-axis * Only one partition per rank * Only SPMD-style __partitioned__ :param x: Requires x.__partitioned__ :type x: object :param comm: Handle to the nodes holding distributed parts or copies of this array. :type comm: Communication, optional .. seealso:: :func:`ht.core.DNDarray.create_partition_interface `. :raises AttributeError: If not hasattr(x, "__partitioned__") or if underlying data has no dtype. :raises TypeError: If it finds an unsupported array types :raises RuntimeError: If other unsupported content is found. .. rubric:: Examples >>> import heat as ht >>> a = ht.ones((44, 55), split=0) >>> b = ht.from_partitioned(a) >>> assert (a == b).all() >>> a[40] = 4711 >>> assert (a == b).all() .. function:: from_partition_dict(parted: dict, comm: Optional[heat.core.communication.Communication] = None) -> heat.core.dndarray.DNDarray Return a newly created DNDarray constructed from the '__partitioned__' attributed of the input object. Memory of local partitions will be shared (zero-copy) as long as supported by data objects. Currently supports numpy ndarrays and torch tensors as data objects. Current limitations: * Partitions must be ordered in the partition-grid by rank * Only one split-axis * Only one partition per rank * Only SPMD-style __partitioned__ :param parted: A partition dictionary used to create the new DNDarray :type parted: dict :param comm: Handle to the nodes holding distributed parts or copies of this array. :type comm: Communication, optional .. seealso:: :func:`ht.core.DNDarray.create_partition_interface `. :raises AttributeError: If not hasattr(x, "__partitioned__") or if underlying data has no dtype. :raises TypeError: If it finds an unsupported array types :raises RuntimeError: If other unsupported content is found. .. rubric:: Examples >>> import heat as ht >>> a = ht.ones((44, 55), split=0) >>> b = ht.from_partition_dict(a.__partitioned__) >>> assert (a == b).all() >>> a[40] = 4711 >>> assert (a == b).all() .. function:: full(shape: Union[int, Sequence[int]], fill_value: Union[int, float], dtype: Type[heat.core.types.datatype] = types.float32, split: Optional[int] = None, device: Optional[heat.core.devices.Device] = None, comm: Optional[heat.core.communication.Communication] = None, order: str = 'C') -> heat.core.dndarray.DNDarray Return a new :class:`~heat.core.dndarray.DNDarray` of given shape and type, filled with ``fill_value``. :param shape: Shape of the new array, e.g., (2, 3) or 2. :type shape: int or Sequence[int,...] :param fill_value: Fill value. :type fill_value: scalar :param dtype: The desired data-type for the array :type dtype: datatype, optional :param split: The axis along which the array is split and distributed; ``None`` means no distribution. :type split: int or None, optional :param device: Specifies the :class:`~heat.core.devices.Device` the array shall be allocated on, defaults to globally set default device. :type device: str or Device, optional :param comm: Handle to the nodes holding distributed parts or copies of this array. :type comm: Communication, optional :param order: Options: ``'C'`` or ``'F'``. Specifies the memory layout of the newly created array. Default is ``order='C'``, meaning the array will be stored in row-major order (C-like). If ``order=‘F’``, the array will be stored in column-major order (Fortran-like). :type order: str, optional :raises NotImplementedError: If order is one of the NumPy options ``'K'`` or ``'A'``. .. rubric:: Examples >>> ht.full((2, 2), ht.inf) DNDarray([[inf, inf], [inf, inf]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.full((2, 2), 10) DNDarray([[10., 10.], [10., 10.]], dtype=ht.float32, device=cpu:0, split=None) .. function:: full_like(a: heat.core.dndarray.DNDarray, fill_value: Union[int, float], dtype: Type[heat.core.types.datatype] = types.float32, split: Optional[int] = None, device: Optional[heat.core.devices.Device] = None, comm: Optional[heat.core.communication.Communication] = None, order: str = 'C') -> heat.core.dndarray.DNDarray Return a full :class:`~heat.core.dndarray.DNDarray` with the same shape and type as a given array. Data type, data distribution axis, and device can be explicitly overridden. :param a: The shape, data-type, split axis and device of ``a`` define these same attributes of the returned array. :type a: DNDarray :param fill_value: Fill value. :type fill_value: scalar :param dtype: The data type of the result, defaults to `a.dtype`. :type dtype: datatype, optional :param split: The axis along which the array is split and distributed; defaults to `a.split`. :type split: int or None, optional :param device: Specifies the :class:`~heat.core.devices.Device` the array shall be allocated on, defaults to `a.device`. :type device: str or Device, optional :param comm: Handle to the nodes holding distributed parts or copies of this array. :type comm: Communication, optional :param order: Options: ``'C'`` or ``'F'``. Specifies the memory layout of the newly created array. Default is ``order='C'``, meaning the array will be stored in row-major order (C-like). If ``order=‘F’``, the array will be stored in column-major order (Fortran-like). :type order: str, optional :raises NotImplementedError: If order is one of the NumPy options ``'K'`` or ``'A'``. .. rubric:: Examples >>> x = ht.zeros( ... ( ... 2, ... 3, ... ) ... ) >>> x DNDarray([[0., 0., 0.], [0., 0., 0.]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.full_like(x, 1.0) DNDarray([[1., 1., 1.], [1., 1., 1.]], dtype=ht.float32, device=cpu:0, split=None) .. function:: linspace(start: Union[int, float], stop: Union[int, float], num: int = 50, endpoint: bool = True, retstep: bool = False, dtype: Optional[Type[heat.core.types.datatype]] = None, split: Optional[int] = None, device: Optional[heat.core.devices.Device] = None, comm: Optional[heat.core.communication.Communication] = None) -> Tuple[heat.core.dndarray.DNDarray, float] Returns num evenly spaced samples, calculated over the interval ``[start, stop]``. The endpoint of the interval can optionally be excluded. There are num equally spaced samples in the closed interval ``[start, stop]`` or the half-open interval ``[start, stop)`` (depending on whether endpoint is ``True`` or ``False``). :param start: The starting value of the sample interval, maybe a sequence if convertible to scalar :type start: scalar or scalar-convertible :param stop: The end value of the sample interval, unless is set to False. In that case, the sequence consists of all but the last of ``num+1`` evenly spaced samples, so that stop is excluded. Note that the step size changes when endpoint is ``False``. :type stop: scalar or scalar-convertible :param num: Number of samples to generate, defaults to 50. Must be non-negative. :type num: int, optional :param endpoint: If ``True``, stop is the last sample, otherwise, it is not included. :type endpoint: bool, optional :param retstep: If ``True``, return (samples, step), where step is the spacing between samples. :type retstep: bool, optional :param dtype: The type of the output array. :type dtype: dtype, optional :param split: The axis along which the array is split and distributed; ``None`` means no distribution. :type split: int or None, optional :param device: Specifies the :class:`~heat.core.devices.Device` the array shall be allocated on, defaults to globally set default device. :type device: str or Device, optional :param comm: Handle to the nodes holding distributed parts or copies of this array. :type comm: Communication, optional .. rubric:: Examples >>> ht.linspace(2.0, 3.0, num=5) DNDarray([2.0000, 2.2500, 2.5000, 2.7500, 3.0000], dtype=ht.float32, device=cpu:0, split=None) >>> ht.linspace(2.0, 3.0, num=5, endpoint=False) DNDarray([2.0000, 2.2000, 2.4000, 2.6000, 2.8000], dtype=ht.float32, device=cpu:0, split=None) >>> ht.linspace(2.0, 3.0, num=5, retstep=True) (DNDarray([2.0000, 2.2500, 2.5000, 2.7500, 3.0000], dtype=ht.float32, device=cpu:0, split=None), 0.25) .. function:: logspace(start: Union[int, float], stop: Union[int, float], num: int = 50, endpoint: bool = True, base: float = 10.0, dtype: Optional[Type[heat.core.types.datatype]] = None, split: Optional[int] = None, device: Optional[heat.core.devices.Device] = None, comm: Optional[heat.core.communication.Communication] = None) -> heat.core.dndarray.DNDarray Return numbers spaced evenly on a log scale. In linear space, the sequence starts at ``base**start`` (``base`` to the power of ``start``) and ends with ``base**stop`` (see ``endpoint`` below). :param start: ``base**start`` is the starting value of the sequence. :type start: scalar or scalar-convertible :param stop: ``base**stop`` is the final value of the sequence, unless `endpoint` is ``False``. In that case, ``num+1`` values are spaced over the interval in log-space, of which all but the last (a sequence of length ``num``) are returned. :type stop: scalar or scalar-convertible :param num: Number of samples to generate. :type num: int, optional :param endpoint: If ``True``, `stop` is the last sample. Otherwise, it is not included. :type endpoint: bool, optional :param base: The base of the log space. The step size between the elements in :math:`ln(samples) / ln(base)` (or :math:`base(samples)`) is uniform. :type base: float, optional :param dtype: The type of the output array. If ``dtype`` is not given, infer the data type from the other input arguments. :type dtype: datatype, optional :param split: The axis along which the array is split and distributed; ``None`` means no distribution. :type split: int or None, optional :param device: Specifies the :class:`~heat.core.devices.Device` the array shall be allocated on, defaults to globally set default device. :type device: str or Device, optional :param comm: Handle to the nodes holding distributed parts or copies of this array. :type comm: Communication, optional .. seealso:: :func:`arange` Similar to :func:`linspace`, with the step size specified instead of the number of samples. Note that, when used with a float endpoint, the endpoint may or may not be included. :func:`linspace` Similar to ``logspace``, but with the samples uniformly distributed in linear space, instead of log space. .. rubric:: Examples >>> ht.logspace(2.0, 3.0, num=4) DNDarray([ 100.0000, 215.4434, 464.1590, 1000.0000], dtype=ht.float32, device=cpu:0, split=None) >>> ht.logspace(2.0, 3.0, num=4, endpoint=False) DNDarray([100.0000, 177.8279, 316.2278, 562.3413], dtype=ht.float32, device=cpu:0, split=None) >>> ht.logspace(2.0, 3.0, num=4, base=2.0) DNDarray([4.0000, 5.0397, 6.3496, 8.0000], dtype=ht.float32, device=cpu:0, split=None) .. function:: meshgrid(*arrays: Sequence[heat.core.dndarray.DNDarray], indexing: str = 'xy') -> List[heat.core.dndarray.DNDarray] Returns coordinate matrices from coordinate vectors. :param arrays: one-dimensional arrays representing grid coordinates. If exactly one vector is distributed, the returned matrices will reflect this distribution. :type arrays: Sequence[ DNDarray ] :param indexing: Cartesian ‘xy’ or matrix ‘ij’ indexing of output. It is ignored if zero or one one-dimensional arrays are provided. Default: 'xy' . :type indexing: str, optional :raises ValueError: If `indexing` is not 'xy' or 'ij'. :raises ValueError: If more than one input vector is distributed. .. rubric:: Examples >>> x = ht.arange(4) >>> y = ht.arange(3) >>> xx, yy = ht.meshgrid(x, y) >>> xx DNDarray(MPI-rank: 0, Shape: [3, 4], Split: None, Local Shape: (3, 4), Device: cpu:0, Dtype: int32, Data: [[0, 1, 2, 3], [0, 1, 2, 3], [0, 1, 2, 3]]) >>> yy DNDarray(MPI-rank: 0, Shape: [3, 4], Split: None, Local Shape: (3, 4), Device: cpu:0, Dtype: int32, Data: [[0, 0, 0, 0], [1, 1, 1, 1], [2, 2, 2, 2]]) >>> x = ht.arange(4, split=0) >>> xx, yy = ht.meshgrid(x, y) >>> xx DNDarray(MPI-rank: 0, Shape: [3, 4], Split: 1, Local Shape: (3, 4), Device: cpu:0, Dtype: int32, Data: [[0, 1, 2, 3], [0, 1, 2, 3], [0, 1, 2, 3]]) >>> xx, yy = ht.meshgrid(x, y, indexing="ij") >>> xx DNDarray(MPI-rank: 0, Shape: (4, 3), Split: 0, Local Shape: (4, 3), Device: cpu:0, Dtype: int32, Data: [[0, 0, 0], [1, 1, 1], [2, 2, 2], [3, 3, 3]]) .. function:: ones(shape: Union[int, Sequence[int]], dtype: Type[heat.core.types.datatype] = types.float32, split: Optional[int] = None, device: Optional[heat.core.devices.Device] = None, comm: Optional[heat.core.communication.Communication] = None, order: str = 'C') -> heat.core.dndarray.DNDarray Returns a new :class:`~heat.core.dndarray.DNDarray` of given shape and data type filled with one. May be allocated split up across multiple nodes along the specified axis. :param shape: Desired shape of the output array, e.g. 1 or (1, 2, 3,). :type shape: int or Sequence[int,...] :param dtype: The desired HeAT data type for the array. :type dtype: datatype, optional :param split: The axis along which the array is split and distributed; ``None`` means no distribution. :type split: int or None, optional :param device: Specifies the :class:`~heat.core.devices.Device` the array shall be allocated on, defaults to globally set default device. :type device: str or Device, optional :param comm: Handle to the nodes holding distributed parts or copies of this array. :type comm: Communication, optional :param order: Options: ``'C'`` or ``'F'``. Specifies the memory layout of the newly created array. Default is ``order='C'``, meaning the array will be stored in row-major order (C-like). If ``order=‘F’``, the array will be stored in column-major order (Fortran-like). :type order: str, optional :raises NotImplementedError: If order is one of the NumPy options ``'K'`` or ``'A'``. .. rubric:: Examples >>> ht.ones(3) DNDarray([1., 1., 1.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.ones(3, dtype=ht.int) DNDarray([1, 1, 1], dtype=ht.int32, device=cpu:0, split=None) >>> ht.ones( ... ( ... 2, ... 3, ... ) ... ) DNDarray([[1., 1., 1.], [1., 1., 1.]], dtype=ht.float32, device=cpu:0, split=None) .. function:: ones_like(a: heat.core.dndarray.DNDarray, dtype: Optional[Type[heat.core.types.datatype]] = None, split: Optional[int] = None, device: Optional[heat.core.devices.Device] = None, comm: Optional[heat.core.communication.Communication] = None, order: str = 'C') -> heat.core.dndarray.DNDarray Returns a new :class:`~heat.core.dndarray.DNDarray` filled with ones with the same type, shape, data distribution and device of the input object. Data type, data distribution axis, and device can be explicitly overridden. :param a: The shape, data-type, split axis and device of ``a`` define these same attributes of the returned array. :type a: DNDarray :param dtype: Overrides the data type of the result. :type dtype: datatype, optional :param split: The axis along which the array is split and distributed; defaults to `a.split`. :type split: int or None, optional :param device: Specifies the :class:`~heat.core.devices.Device` the array shall be allocated on, defaults to `a.device`. :type device: str or Device, optional :param comm: Handle to the nodes holding distributed parts or copies of this array. :type comm: Communication, optional :param order: Options: ``'C'`` or ``'F'``. Specifies the memory layout of the newly created array. Default is ``order='C'``, meaning the array will be stored in row-major order (C-like). If ``order=‘F’``, the array will be stored in column-major order (Fortran-like). :type order: str, optional :raises NotImplementedError: If order is one of the NumPy options ``'K'`` or ``'A'``. .. rubric:: Examples >>> x = ht.zeros( ... ( ... 2, ... 3, ... ) ... ) >>> x DNDarray([[0., 0., 0.], [0., 0., 0.]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.ones_like(x) DNDarray([[1., 1., 1.], [1., 1., 1.]], dtype=ht.float32, device=cpu:0, split=None) .. function:: zeros(shape: Union[int, Sequence[int]], dtype: Type[heat.core.types.datatype] = types.float32, split: Optional[int] = None, device: Optional[heat.core.devices.Device] = None, comm: Optional[heat.core.communication.Communication] = None, order: str = 'C') -> heat.core.dndarray.DNDarray Returns a new :class:`~heat.core.dndarray.DNDarray` of given shape and data type filled with zero values. May be allocated split up across multiple nodes along the specified axis. :param shape: Desired shape of the output array, e.g. 1 or (1, 2, 3,). :type shape: int or Sequence[int,...] :param dtype: The desired HeAT data type for the array. :type dtype: datatype :param split: The axis along which the array is split and distributed; ``None`` means no distribution. :type split: int or None, optional :param device: Specifies the :class:`~heat.core.devices.Device` the array shall be allocated on, defaults to globally set default device. :type device: str or Device, optional :param comm: Handle to the nodes holding distributed parts or copies of this array. :type comm: Communication, optional :param order: Options: ``'C'`` or ``'F'``. Specifies the memory layout of the newly created array. Default is ``order='C'``, meaning the array will be stored in row-major order (C-like). If ``order=‘F’``, the array will be stored in column-major order (Fortran-like). :type order: str, optional :raises NotImplementedError: If order is one of the NumPy options ``'K'`` or ``'A'``. .. rubric:: Examples >>> ht.zeros(3) DNDarray([0., 0., 0.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.zeros(3, dtype=ht.int) DNDarray([0, 0, 0], dtype=ht.int32, device=cpu:0, split=None) >>> ht.zeros( ... ( ... 2, ... 3, ... ) ... ) DNDarray([[0., 0., 0.], [0., 0., 0.]], dtype=ht.float32, device=cpu:0, split=None) .. function:: zeros_like(a: heat.core.dndarray.DNDarray, dtype: Optional[Type[heat.core.types.datatype]] = None, split: Optional[int] = None, device: Optional[heat.core.devices.Device] = None, comm: Optional[heat.core.communication.Communication] = None, order: str = 'C') -> heat.core.dndarray.DNDarray Returns a new :class:`~heat.core.dndarray.DNDarray` filled with zeros with the same type, shape, data distribution, and device of the input object. Data type, data distribution axis, and device can be explicitly overridden. :param a: The shape, data-type, split axis, and device of ``a`` define these same attributes of the returned array. :type a: DNDarray :param dtype: Overrides the data type of the result. :type dtype: datatype, optional :param split: The axis along which the array is split and distributed; defaults to `a.split`. :type split: int or None, optional :param device: Specifies the :class:`~heat.core.devices.Device` the array shall be allocated on, defaults to `a.device`. :type device: str or Device, optional :param comm: Handle to the nodes holding distributed parts or copies of this array. :type comm: Communication, optional :param order: Options: ``'C'`` or ``'F'``. Specifies the memory layout of the newly created array. Default is ``order='C'``, meaning the array will be stored in row-major order (C-like). If ``order=‘F’``, the array will be stored in column-major order (Fortran-like). :type order: str, optional :raises NotImplementedError: If order is one of the NumPy options ``'K'`` or ``'A'``. .. rubric:: Examples >>> x = ht.ones( ... ( ... 2, ... 3, ... ) ... ) >>> x DNDarray([[1., 1., 1.], [1., 1., 1.]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.zeros_like(x) DNDarray([[0., 0., 0.], [0., 0., 0.]], dtype=ht.float32, device=cpu:0, split=None) .. function:: nonzero(x: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Return a :class:`~heat.core.dndarray.DNDarray` containing the indices of the elements that are non-zero (using ``torch.nonzero``). If ``x`` is split then the result is split in the first dimension. However, this :class:`~heat.core.dndarray.DNDarray` can be UNBALANCED as it contains the indices of the non-zero elements on each node. Returns an array with one entry for each dimension of ``x``, containing the indices of the non-zero elements in that dimension. The values in ``x`` are always tested and returned in row-major, C-style order. The corresponding non-zero values can be obtained with: ``x[nonzero(x)]``. :param x: Input array :type x: DNDarray .. rubric:: Examples >>> import heat as ht >>> x = ht.array([[3, 0, 0], [0, 4, 1], [0, 6, 0]], split=0) >>> ht.nonzero(x) DNDarray([[0, 0], [1, 1], [1, 2], [2, 1]], dtype=ht.int64, device=cpu:0, split=0) >>> y = ht.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]], split=0) >>> y > 3 DNDarray([[False, False, False], [ True, True, True], [ True, True, True]], dtype=ht.bool, device=cpu:0, split=0) >>> ht.nonzero(y > 3) DNDarray([[1, 0], [1, 1], [1, 2], [2, 0], [2, 1], [2, 2]], dtype=ht.int64, device=cpu:0, split=0) >>> y[ht.nonzero(y > 3)] DNDarray([4, 5, 6, 7, 8, 9], dtype=ht.int64, device=cpu:0, split=0) .. function:: where(cond: heat.core.dndarray.DNDarray, x: Union[None, int, float, heat.core.dndarray.DNDarray] = None, y: Union[None, int, float, heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Return a :class:`~heat.core.dndarray.DNDarray` containing elements chosen from ``x`` or ``y`` depending on condition. Result is a :class:`~heat.core.dndarray.DNDarray` with elements from ``x`` where cond is ``True``, and elements from ``y`` elsewhere (``False``). :param cond: Condition of interest, where true yield ``x`` otherwise yield ``y`` :type cond: DNDarray :param x: Values from which to choose. ``x``, ``y`` and condition need to be broadcastable to some shape. :type x: DNDarray or int or float, optional :param y: Values from which to choose. ``x``, ``y`` and condition need to be broadcastable to some shape. :type y: DNDarray or int or float, optional :raises NotImplementedError: if splits of the two input :class:`~heat.core.dndarray.DNDarray` differ :raises TypeError: if only x or y is given or both are not DNDarrays or numerical scalars .. rubric:: Notes When only condition is provided, this function is a shorthand for :func:`nonzero`. .. rubric:: Examples >>> import heat as ht >>> x = ht.arange(10, split=0) >>> ht.where(x < 5, x, 10 * x) DNDarray([ 0, 1, 2, 3, 4, 50, 60, 70, 80, 90], dtype=ht.int64, device=cpu:0, split=0) >>> y = ht.array([[0, 1, 2], [0, 2, 4], [0, 3, 6]]) >>> ht.where(y < 4, y, -1) DNDarray([[ 0, 1, 2], [ 0, 2, -1], [ 0, 3, -1]], dtype=ht.int64, device=cpu:0, split=None) .. function:: load(path: str, *args: Optional[List[object]], **kwargs: Optional[Dict[str, object]]) -> heat.core.dndarray.DNDarray Attempts to load data from a file stored on disk. Attempts to auto-detect the file format by determining the extension. Supports at least CSV files, HDF5 and netCDF4 are additionally possible if the corresponding libraries are installed. :param path: Path to the file to be read. :type path: str :param args: Additional options passed to the particular functions. :type args: list, optional :param kwargs: Additional options passed to the particular functions. :type kwargs: dict, optional :raises ValueError: If the file extension is not understood or known. :raises RuntimeError: If the optional dependency for a file extension is not available. .. rubric:: Examples >>> ht.load("data.h5", dataset="DATA") DNDarray([ 1.0000, 2.7183, 7.3891, 20.0855, 54.5981], dtype=ht.float32, device=cpu:0, split=None) >>> ht.load("data.nc", variable="DATA") DNDarray([ 1.0000, 2.7183, 7.3891, 20.0855, 54.5981], dtype=ht.float32, device=cpu:0, split=None) >>> ht.load("my_data.zarr", variable="RECEIVER_1/DATA") DNDarray([ 1.0000, 2.7183, 7.3891, 20.0855, 54.5981], dtype=ht.float32, device=cpu:0, split=0) >>> ht.load("my_data.zarr", variable="RECEIVER_*/DATA") DNDarray([[ 1.0000, 2.7183, 7.3891, 20.0855, 54.5981], [ 1.0000, 2.7183, 7.3891, 20.0855, 54.5981], [ 1.0000, 2.7183, 7.3891, 20.0855, 54.5981]], dtype=ht.float32, device=cpu:0, split=0) .. seealso:: :func:`load_csv` Loads data from a CSV file. :func:`load_csv_from_folder` Loads multiple .csv files into one DNDarray which will be returned. :func:`load_hdf5` Loads data from an HDF5 file. :func:`load_netcdf` Loads data from a NetCDF4 file. :func:`load_npy_from_path` Loads multiple .npy files into one DNDarray which will be returned. :func:`load_zarr` Loads zarr-Format into DNDarray which will be returned. .. function:: load_csv(path: str, header_lines: int = 0, sep: str = ',', dtype: heat.core.types.datatype = types.float32, encoding: str = 'utf-8', split: Optional[int] = None, device: Optional[str] = None, comm: Optional[heat.core.communication.Communication] = None) -> heat.core.dndarray.DNDarray Loads data from a CSV file. The data will be distributed along the axis 0. :param path: Path to the CSV file to be read. :type path: str :param header_lines: The number of columns at the beginning of the file that should not be considered as data. :type header_lines: int, optional :param sep: The single ``char`` or ``str`` that separates the values in each row. :type sep: str, optional :param dtype: Data type of the resulting array. :type dtype: datatype, optional :param encoding: The type of encoding which will be used to interpret the lines of the csv file as strings. :type encoding: str, optional :param split: Along which axis the resulting array should be split. Default is ``None`` which means each node will have the full array. :type split: int or None : optional :param device: The device id on which to place the data, defaults to globally set default device. :type device: str, optional :param comm: The communication to use for the data distribution, defaults to global default :type comm: Communication, optional :raises TypeError: If any of the input parameters are not of correct type. .. rubric:: Examples >>> import heat as ht >>> a = ht.load_csv("data.csv") >>> a.shape [0/3] (150, 4) [1/3] (150, 4) [2/3] (150, 4) [3/3] (150, 4) >>> a.lshape [0/3] (38, 4) [1/3] (38, 4) [2/3] (37, 4) [3/3] (37, 4) >>> b = ht.load_csv("data.csv", header_lines=10) >>> b.shape [0/3] (140, 4) [1/3] (140, 4) [2/3] (140, 4) [3/3] (140, 4) >>> b.lshape [0/3] (35, 4) [1/3] (35, 4) [2/3] (35, 4) [3/3] (35, 4) .. function:: save_csv(data: heat.core.dndarray.DNDarray, path: str, header_lines: Iterable[str] = None, sep: str = ',', decimals: int = -1, encoding: str = 'utf-8', comm: Optional[heat.core.communication.Communication] = None, truncate: bool = True) Saves data to CSV files. Only 2D data, all split axes. :param data: The DNDarray to be saved to CSV. :type data: DNDarray :param path: The path as a string. :type path: str :param header_lines: Optional iterable of str to prepend at the beginning of the file. No pound sign or any other comment marker will be inserted. :type header_lines: Iterable[str] :param sep: The separator character used in this CSV. :type sep: str :param decimals: Number of digits after decimal point. :type decimals: int :param encoding: The encoding to be used in this CSV. :type encoding: str :param comm: An optional object of type Communication to be used. :type comm: Optional[Communication] :param truncate: Whether to truncate an existing file before writing, i.e. fully overwrite it. The sane default is True. Setting it to False will not shorten files if needed and thus may leave garbage at the end of existing files. :type truncate: bool .. function:: save(data: heat.core.dndarray.DNDarray, path: str, *args: Optional[List[object]], **kwargs: Optional[Dict[str, object]]) Attempts to save data from a :class:`~heat.core.dndarray.DNDarray` to disk. An auto-detection based on the file format extension is performed. :param data: The array holding the data to be stored :type data: DNDarray :param path: Path to the file to be stored. :type path: str :param args: Additional options passed to the particular functions. :type args: list, optional :param kwargs: Additional options passed to the particular functions. :type kwargs: dict, optional :raises ValueError: If the file extension is not understood or known. :raises RuntimeError: If the optional dependency for a file extension is not available. .. rubric:: Examples >>> x = ht.arange(100, split=0) >>> ht.save(x, "data.h5", "DATA", mode="a") .. function:: supports_hdf5() -> bool Returns ``True`` if Heat supports reading from and writing to HDF5 files, ``False`` otherwise. .. function:: supports_netcdf() -> bool Returns ``True`` if Heat supports reading from and writing to netCDF4 files, ``False`` otherwise. .. function:: load_npy_from_path(path: str, dtype: heat.core.types.datatype = types.int32, split: int = 0, device: Optional[str] = None, comm: Optional[heat.core.communication.Communication] = None) -> heat.core.dndarray.DNDarray Loads multiple .npy files into one DNDarray which will be returned. The data will be concatenated along the split axis provided as input. :param path: Path to the directory in which .npy-files are located. :type path: str :param dtype: Data type of the resulting array. :type dtype: datatype, optional :param split: Along which axis the loaded arrays should be concatenated. :type split: int :param device: The device id on which to place the data, defaults to globally set default device. :type device: str, optional :param comm: The communication to use for the data distribution, default is 'heat.MPI_WORLD' :type comm: Communication, optional .. function:: supports_zarr() -> bool Returns ``True`` if zarr is installed, ``False`` otherwise. .. function:: all(x: heat.core.dndarray.DNDarray, axis: Union[int, Tuple[int], None] = None, out: Optional[heat.core.dndarray.DNDarray] = None, keepdims: bool = False) -> Union[heat.core.dndarray.DNDarray, bool] Test whether all array elements along a given axis evaluate to ``True``. A new boolean or :class:`~heat.core.dndarray.DNDarray` is returned unless out is specified, in which case a reference to ``out`` is returned. :param x: Input array or object that can be converted to an array. :type x: DNDarray :param axis: Axis or axes along which a logical AND reduction is performed. The default (``axis=None``) is to perform a logical AND over all the dimensions of the input array. ``axis`` may be negative, in which case it counts from the last to the first axis. :type axis: None or int or Tuple[int,...], optional :param out: Alternate output array in which to place the result. It must have the same shape as the expected output and its type is preserved. :type out: DNDarray, optional :param keepdims: If this is set to ``True``, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original array. :type keepdims: bool, optional .. rubric:: Examples >>> x = ht.random.randn(4, 5) >>> x DNDarray([[ 0.7199, 1.3718, 1.5008, 0.3435, 1.2884], [ 0.1532, -0.0968, 0.3739, 1.7843, 0.5614], [ 1.1522, 1.9076, 1.7638, 0.4110, -0.2803], [-0.5475, -0.0271, 0.8564, -1.5870, 1.3108]], dtype=ht.float32, device=cpu:0, split=None) >>> y = x < 0.5 >>> y DNDarray([[False, False, False, True, False], [ True, True, True, False, False], [False, False, False, True, True], [ True, True, False, True, False]], dtype=ht.bool, device=cpu:0, split=None) >>> ht.all(y) DNDarray([False], dtype=ht.bool, device=cpu:0, split=None) >>> ht.all(y, axis=0) DNDarray([False, False, False, False, False], dtype=ht.bool, device=cpu:0, split=None) >>> ht.all(x, axis=1) DNDarray([True, True, True, True], dtype=ht.bool, device=cpu:0, split=None) >>> out = ht.zeros(5) >>> ht.all(y, axis=0, out=out) DNDarray([False, False, False, False, False], dtype=ht.float32, device=cpu:0, split=None) >>> out DNDarray([False, False, False, False, False], dtype=ht.float32, device=cpu:0, split=None) .. function:: allclose(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray, rtol: float = 1e-05, atol: float = 1e-08, equal_nan: bool = False) -> bool Test whether two tensors are element-wise equal within a tolerance. Returns ``True`` if ``|x-y|<=atol+rtol*|y|`` for all elements of ``x`` and ``y``, ``False`` otherwise :param x: First array to compare :type x: DNDarray :param y: Second array to compare :type y: DNDarray :param atol: Absolute tolerance. :type atol: float, optional :param rtol: Relative tolerance (with respect to ``y``). :type rtol: float, optional :param equal_nan: Whether to compare NaN’s as equal. If ``True``, NaN’s in ``x`` will be considered equal to NaN’s in ``y`` in the output array. :type equal_nan: bool, optional .. rubric:: Examples >>> x = ht.float32([[2, 2], [2, 2]]) >>> ht.allclose(x, x) True >>> y = ht.float32([[2.00005, 2.00005], [2.00005, 2.00005]]) >>> ht.allclose(x, y) False >>> ht.allclose(x, y, atol=1e-04) True .. function:: any(x, axis: Optional[int] = None, out: Optional[heat.core.dndarray.DNDarray] = None, keepdims: bool = False) -> heat.core.dndarray.DNDarray Returns a :class:`~heat.core.dndarray.DNDarray` containing the result of the test whether any array elements along a given axis evaluate to ``True``. The returning array is one dimensional unless axis is not ``None``. :param x: Input tensor :type x: DNDarray :param axis: Axis along which a logic OR reduction is performed. With ``axis=None``, the logical OR is performed over all dimensions of the array. :type axis: int, optional :param out: Alternative output tensor in which to place the result. It must have the same shape as the expected output. The output is a array with ``datatype=bool``. :type out: DNDarray, optional :param keepdims: If this is set to ``True``, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original array. :type keepdims: bool, optional .. rubric:: Examples >>> x = ht.float32([[0.3, 0, 0.5]]) >>> x.any() DNDarray([True], dtype=ht.bool, device=cpu:0, split=None) >>> x.any(axis=0) DNDarray([ True, False, True], dtype=ht.bool, device=cpu:0, split=None) >>> x.any(axis=1) DNDarray([True], dtype=ht.bool, device=cpu:0, split=None) >>> y = ht.int32([[0, 0, 1], [0, 0, 0]]) >>> res = ht.zeros(3, dtype=ht.bool) >>> y.any(axis=0, out=res) DNDarray([False, False, True], dtype=ht.bool, device=cpu:0, split=None) >>> res DNDarray([False, False, True], dtype=ht.bool, device=cpu:0, split=None) .. function:: isclose(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray, rtol: float = 1e-05, atol: float = 1e-08, equal_nan: bool = False) -> heat.core.dndarray.DNDarray Returns a boolean :class:`~heat.core.dndarray.DNDarray`, with elements ``True`` where ``a`` and ``b`` are equal within the given tolerance. If both ``x`` and ``y`` are scalars, returns a single boolean value. :param x: Input array to compare. :type x: DNDarray :param y: Input array to compare. :type y: DNDarray :param rtol: The relative tolerance parameter. :type rtol: float :param atol: The absolute tolerance parameter. :type atol: float :param equal_nan: Whether to compare NaN’s as equal. If ``True``, NaN’s in x will be considered equal to NaN’s in y in the output array. :type equal_nan: bool .. function:: isfinite(x: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Test element-wise for finiteness (not infinity or not Not a Number) and return result as a boolean :class:`~heat.core.dndarray.DNDarray`. :param x: Input tensor :type x: DNDarray .. rubric:: Examples >>> ht.isfinite(ht.array([1, ht.inf, -ht.inf, ht.nan])) DNDarray([ True, False, False, False], dtype=ht.bool, device=cpu:0, split=None) .. function:: isinf(x: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Test element-wise for positive or negative infinity and return result as a boolean :class:`~heat.core.dndarray.DNDarray`. :param x: Input tensor :type x: DNDarray .. rubric:: Examples >>> ht.isinf(ht.array([1, ht.inf, -ht.inf, ht.nan])) DNDarray([False, True, True, False], dtype=ht.bool, device=cpu:0, split=None) .. function:: isnan(x: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Test element-wise for NaN and return result as a boolean :class:`~heat.core.dndarray.DNDarray`. :param x: Input tensor :type x: DNDarray .. rubric:: Examples >>> ht.isnan(ht.array([1, ht.inf, -ht.inf, ht.nan])) DNDarray([False, False, False, True], dtype=ht.bool, device=cpu:0, split=None) .. function:: isneginf(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Test if each element of `x` is negative infinite, return result as a boolean :class:`~heat.core.dndarray.DNDarray`. :param x: Input tensor :type x: DNDarray :param out: Alternate output array in which to place the result. It must have the same shape as the expected output and its type is preserved. :type out: DNDarray, optional .. rubric:: Examples >>> ht.isnan(ht.array([1, ht.inf, -ht.inf, ht.nan])) DNDarray([False, False, True, False], dtype=ht.bool, device=cpu:0, split=None) .. function:: isposinf(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) Test if each element of `x` is positive infinite, return result as a boolean :class:`~heat.core.dndarray.DNDarray`. :param x: Input tensor :type x: DNDarray :param out: Alternate output array in which to place the result. It must have the same shape as the expected output and its type is preserved. :type out: DNDarray, optional .. rubric:: Examples >>> ht.isnan(ht.array([1, ht.inf, -ht.inf, ht.nan])) DNDarray([False, True, False, False], dtype=ht.bool, device=cpu:0, split=None) .. function:: logical_and(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Compute the truth value of ``x`` AND ``y`` element-wise. Returns a boolean :class:`~heat.core.dndarray.DNDarray` containing the truth value of ``x`` AND ``y`` element-wise. :param x: Input array of same shape :type x: DNDarray :param y: Input array of same shape :type y: DNDarray .. rubric:: Examples >>> ht.logical_and(ht.array([True, False]), ht.array([False, False])) DNDarray([False, False], dtype=ht.bool, device=cpu:0, split=None) .. function:: logical_not(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Computes the element-wise logical NOT of the given input :class:`~heat.core.dndarray.DNDarray`. :param x: Input array :type x: DNDarray :param out: Alternative output array in which to place the result. It must have the same shape as the expected output. The output is a :class:`~heat.core.dndarray.DNDarray` with ``datatype=bool``. :type out: DNDarray, optional .. rubric:: Examples >>> ht.logical_not(ht.array([True, False])) DNDarray([False, True], dtype=ht.bool, device=cpu:0, split=None) .. function:: logical_or(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Returns boolean :class:`~heat.core.dndarray.DNDarray` containing the element-wise logical NOT of the given input :class:`~heat.core.dndarray.DNDarray`. :param x: Input array of same shape :type x: DNDarray :param y: Input array of same shape :type y: DNDarray .. rubric:: Examples >>> ht.logical_or(ht.array([True, False]), ht.array([False, False])) DNDarray([ True, False], dtype=ht.bool, device=cpu:0, split=None) .. function:: logical_xor(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Computes the element-wise logical XOR of the given input :class:`~heat.core.dndarray.DNDarray`. :param x: Input array of same shape :type x: DNDarray :param y: Input array of same shape :type y: DNDarray .. rubric:: Examples >>> ht.logical_xor(ht.array([True, False, True]), ht.array([True, False, False])) DNDarray([False, False, True], dtype=ht.bool, device=cpu:0, split=None) .. function:: signbit(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Checks if signbit is set element-wise (less than zero). :param x: The input array. :type x: DNDarray :param out: The output array. :type out: DNDarray, optional .. rubric:: Examples >>> a = ht.array([2, -1.3, 0]) >>> ht.signbit(a) DNDarray([False, True, False], dtype=ht.bool, device=cpu:0, split=None) .. function:: balance(array: heat.core.dndarray.DNDarray, copy=False) -> heat.core.dndarray.DNDarray Out of place balance function. More information on the meaning of balance can be found in :func:`DNDarray.balance_() `. :param array: the DNDarray to be balanced :type array: DNDarray :param copy: if the DNDarray should be copied before being balanced. If false (default) this will balance the original array and return that array. Otherwise (true), a balanced copy of the array will be returned. Default: False :type copy: bool, optional .. function:: broadcast_arrays(*arrays: heat.core.dndarray.DNDarray) -> List[heat.core.dndarray.DNDarray] Broadcasts one or more arrays against one another. Returns the broadcasted arrays, distributed along the split dimension of the first array in the list. If the first array is not distributed, the output will not be distributed. :param arrays: An arbitrary number of to-be broadcasted ``DNDarray``s. :type arrays: DNDarray .. rubric:: Notes Broadcasted arrays are a view of the original arrays if possible, otherwise a copy is made. .. rubric:: Examples >>> import heat as ht >>> a = ht.ones((100, 10), split=0) >>> b = ht.ones((10,), split=None) >>> c = ht.ones((1, 10), split=1) >>> d, e, f = ht.broadcast_arrays(a, b, c) >>> d.shape (100, 10) >>> e.shape (100, 10) >>> f.shape (100, 10) >>> d.split 0 >>> e.split 0 >>> f.split 0 .. function:: broadcast_to(x: heat.core.dndarray.DNDarray, shape: Tuple[int, Ellipsis]) -> heat.core.dndarray.DNDarray Broadcasts an array to a specified shape. Returns a view of ``x`` if ``x`` is not distributed, otherwise it returns a broadcasted, distributed, load-balanced copy of ``x``. :param x: `DNDarray` to broadcast. :type x: DNDarray :param shape: Array shape. Must be compatible with ``x``. :type shape: Tuple[int, ...] :raises ValueError: If the array is not compatible with the new shape according to PyTorch's broadcasting rules. .. rubric:: Examples >>> import heat as ht >>> a = ht.arange(100, split=0) >>> b = ht.broadcast_to(a, (10, 100)) >>> b.shape (10, 100) >>> b.split 1 >>> c = ht.broadcast_to(a, (100, 10)) ValueError: Shape mismatch: object cannot be broadcast to the given shape. Original shape: (100,), target shape: (100, 10) .. function:: collect(arr: heat.core.dndarray.DNDarray, target_rank: Optional[int] = 0) -> heat.core.dndarray.DNDarray A function collecting a distributed DNDarray to one rank, chosen by the `target_rank` variable. It is a specific case of the ``redistribute_`` method. :param arr: The DNDarray to be collected. :type arr: DNDarray :param target_rank: The rank to which the DNDarray will be collected. Default: 0. :type target_rank: int, optional :raises TypeError: If the target rank is not an integer. :raises ValueError: If the target rank is out of bounds. .. rubric:: Examples >>> st = ht.ones((50, 81, 67), split=2) >>> print(st.lshape) [0/2] (50, 81, 23) [1/2] (50, 81, 22) [2/2] (50, 81, 22) >>> collected_st = collect(st) >>> print(collected_st) [0/2] (50, 81, 67) [1/2] (50, 81, 0) [2/2] (50, 81, 0) >>> collected_st = collect(collected_st, 1) >>> print(st.lshape) [0/2] (50, 81, 0) [1/2] (50, 81, 67) [2/2] (50, 81, 0) .. function:: column_stack(arrays: Sequence[heat.core.dndarray.DNDarray, Ellipsis]) -> heat.core.dndarray.DNDarray Stack 1-D or 2-D `DNDarray`s as columns into a 2-D `DNDarray`. If the input arrays are 1-D, they will be stacked as columns. If they are 2-D, they will be concatenated along the second axis. :param arrays: Sequence of `DNDarray`s. :type arrays: Sequence[DNDarray, ...] :raises ValueError: If arrays have more than 2 dimensions .. rubric:: Notes All `DNDarray`s in the sequence must have the same number of rows. All `DNDarray`s must be split along the same axis! Note that distributed 1-D arrays (`split = 0`) by default will be transposed into distributed column arrays with `split == 1`. .. seealso:: :func:`concatenate`, :func:`hstack`, :func:`row_stack`, :func:`stack`, :func:`vstack` .. rubric:: Examples >>> # 1-D tensors >>> a = ht.array([1, 2, 3]) >>> b = ht.array([2, 3, 4]) >>> ht.column_stack((a, b)).larray tensor([[1, 2], [2, 3], [3, 4]]) >>> # 1-D and 2-D tensors >>> a = ht.array([1, 2, 3]) >>> b = ht.array([[2, 5], [3, 6], [4, 7]]) >>> c = ht.array([[7, 10], [8, 11], [9, 12]]) >>> ht.column_stack((a, b, c)).larray tensor([[ 1, 2, 5, 7, 10], [ 2, 3, 6, 8, 11], [ 3, 4, 7, 9, 12]]) >>> # distributed DNDarrays, 3 processes >>> a = ht.arange(10, split=0).reshape((5, 2)) >>> b = ht.arange(5, 20, split=0).reshape((5, 3)) >>> c = ht.arange(20, 40, split=0).reshape((5, 4)) >>> ht_column_stack((a, b, c)).larray [0/2] tensor([[ 0, 1, 5, 6, 7, 20, 21, 22, 23], [0/2] [ 2, 3, 8, 9, 10, 24, 25, 26, 27]], dtype=torch.int32) [1/2] tensor([[ 4, 5, 11, 12, 13, 28, 29, 30, 31], [1/2] [ 6, 7, 14, 15, 16, 32, 33, 34, 35]], dtype=torch.int32) [2/2] tensor([[ 8, 9, 17, 18, 19, 36, 37, 38, 39]], dtype=torch.int32) >>> # distributed 1-D and 2-D DNDarrays, 3 processes >>> a = ht.arange(5, split=0) >>> b = ht.arange(5, 20, split=1).reshape((5, 3)) >>> ht_column_stack((a, b)).larray [0/2] tensor([[ 0, 5], [0/2] [ 1, 8], [0/2] [ 2, 11], [0/2] [ 3, 14], [0/2] [ 4, 17]], dtype=torch.int32) [1/2] tensor([[ 6], [1/2] [ 9], [1/2] [12], [1/2] [15], [1/2] [18]], dtype=torch.int32) [2/2] tensor([[ 7], [2/2] [10], [2/2] [13], [2/2] [16], [2/2] [19]], dtype=torch.int32) .. function:: concatenate(arrays: Sequence[heat.core.dndarray.DNDarray, Ellipsis], axis: int = 0) -> heat.core.dndarray.DNDarray Join 2 or more `DNDarrays` along an existing axis. :param arrays: The arrays must have the same shape, except in the dimension corresponding to axis. :type arrays: Sequence[DNDarray, ...] :param axis: The axis along which the arrays will be joined (default is 0). :type axis: int, optional :raises RuntimeError: If the concatenated :class:`~heat.core.dndarray.DNDarray` meta information, e.g. `split` or `comm`, does not match. :raises TypeError: If the passed parameters are not of correct type. :raises ValueError: If the number of passed arrays is less than two or their shapes do not match. .. rubric:: Examples >>> x = ht.zeros((3, 5), split=None) [0/1] tensor([[0., 0., 0., 0., 0.], [0/1] [0., 0., 0., 0., 0.], [0/1] [0., 0., 0., 0., 0.]]) [1/1] tensor([[0., 0., 0., 0., 0.], [1/1] [0., 0., 0., 0., 0.], [1/1] [0., 0., 0., 0., 0.]]) >>> y = ht.ones((3, 6), split=0) [0/1] tensor([[1., 1., 1., 1., 1., 1.], [0/1] [1., 1., 1., 1., 1., 1.]]) [1/1] tensor([[1., 1., 1., 1., 1., 1.]]) >>> ht.concatenate((x, y), axis=1) [0/1] tensor([[0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1.], [0/1] [0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1.]]) [1/1] tensor([[0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1.]]) >>> x = ht.zeros((4, 5), split=1) [0/1] tensor([[0., 0., 0.], [0/1] [0., 0., 0.], [0/1] [0., 0., 0.], [0/1] [0., 0., 0.]]) [1/1] tensor([[0., 0.], [1/1] [0., 0.], [1/1] [0., 0.], [1/1] [0., 0.]]) >>> y = ht.ones((3, 5), split=1) [0/1] tensor([[1., 1., 1.], [0/1] [1., 1., 1.], [0/1] [1., 1., 1.]]) [1/1] tensor([[1., 1.], [1/1] [1., 1.], [1/1] [1., 1.]]) >>> ht.concatenate((x, y), axis=0) [0/1] tensor([[0., 0., 0.], [0/1] [0., 0., 0.], [0/1] [0., 0., 0.], [0/1] [0., 0., 0.], [0/1] [1., 1., 1.], [0/1] [1., 1., 1.], [0/1] [1., 1., 1.]]) [1/1] tensor([[0., 0.], [1/1] [0., 0.], [1/1] [0., 0.], [1/1] [0., 0.], [1/1] [1., 1.], [1/1] [1., 1.], [1/1] [1., 1.]]) .. function:: diag(a: heat.core.dndarray.DNDarray, offset: int = 0) -> heat.core.dndarray.DNDarray Extract a diagonal or construct a diagonal array. See the documentation for :func:`diagonal` for more information about extracting the diagonal. :param a: The array holding data for creating a diagonal array or extracting a diagonal. If `a` is a 1-dimensional array, a diagonal 2d-array will be returned. If `a` is a n-dimensional array with n > 1 the diagonal entries will be returned in an n-1 dimensional array. :type a: DNDarray :param offset: The offset from the main diagonal. Offset greater than zero means above the main diagonal, smaller than zero is below the main diagonal. :type offset: int, optional .. seealso:: :func:`diagonal` .. rubric:: Examples >>> import heat as ht >>> a = ht.array([1, 2]) >>> ht.diag(a) DNDarray([[1, 0], [0, 2]], dtype=ht.int64, device=cpu:0, split=None) >>> ht.diag(a, offset=1) DNDarray([[0, 1, 0], [0, 0, 2], [0, 0, 0]], dtype=ht.int64, device=cpu:0, split=None) >>> ht.equal(ht.diag(ht.diag(a)), a) True >>> a = ht.array([[1, 2], [3, 4]]) >>> ht.diag(a) DNDarray([1, 4], dtype=ht.int64, device=cpu:0, split=None) .. function:: diagonal(a: heat.core.dndarray.DNDarray, offset: int = 0, dim1: int = 0, dim2: int = 1) -> heat.core.dndarray.DNDarray Extract a diagonal of an n-dimensional array with n > 1. The returned array will be of dimension n-1. :param a: The array of which the diagonal should be extracted. :type a: DNDarray :param offset: The offset from the main diagonal. Offset greater than zero means above the main diagonal, smaller than zero is below the main diagonal. Default is 0 which means the main diagonal will be selected. :type offset: int, optional :param dim1: First dimension with respect to which to take the diagonal. :type dim1: int, optional :param dim2: Second dimension with respect to which to take the diagonal. :type dim2: int, optional .. rubric:: Examples >>> import heat as ht >>> a = ht.array([[1, 2], [3, 4]]) >>> ht.diagonal(a) DNDarray([1, 4], dtype=ht.int64, device=cpu:0, split=None) >>> ht.diagonal(a, offset=1) DNDarray([2], dtype=ht.int64, device=cpu:0, split=None) >>> ht.diagonal(a, offset=-1) DNDarray([3], dtype=ht.int64, device=cpu:0, split=None) >>> a = ht.array([[[0, 1], [2, 3]], [[4, 5], [6, 7]]]) >>> ht.diagonal(a) DNDarray([[0, 6], [1, 7]], dtype=ht.int64, device=cpu:0, split=None) >>> ht.diagonal(a, dim2=2) DNDarray([[0, 5], [2, 7]], dtype=ht.int64, device=cpu:0, split=None) .. function:: dsplit(x: Sequence[heat.core.dndarray.DNDarray, Ellipsis], indices_or_sections: Iterable) -> List[heat.core.dndarray.DNDarray, Ellipsis] Split array into multiple sub-DNDarrays along the 3rd axis (depth). Returns a list of sub-DNDarrays as copies of parts of `x`. :param x: DNDArray to be divided into sub-DNDarrays. :type x: DNDarray :param indices_or_sections: If `indices_or_sections` is an integer, N, the DNDarray will be divided into N equal DNDarrays along the 3rd axis. If such a split is not possible, an error is raised. If `indices_or_sections` is a 1-D DNDarray of sorted integers, the entries indicate where along the 3rd axis the array is split. If an index exceeds the dimension of the array along the 3rd axis, an empty sub-DNDarray is returned correspondingly. :type indices_or_sections: int or 1-dimensional array_like (i.e. undistributed DNDarray, list or tuple) :raises ValueError: If `indices_or_sections` is given as integer, but a split does not result in equal division. .. rubric:: Notes Please refer to the split documentation. dsplit is equivalent to split with axis=2, the array is always split along the third axis provided the array dimension is greater than or equal to 3. .. seealso:: :func:`split`, :func:`hsplit`, :func:`vsplit` .. rubric:: Examples >>> x = ht.array(24).reshape((2, 3, 4)) >>> ht.dsplit(x, 2) [DNDarray([[[ 0, 1], [ 4, 5], [ 8, 9]], [[12, 13], [16, 17], [20, 21]]]), DNDarray([[[ 2, 3], [ 6, 7], [10, 11]], [[14, 15], [18, 19], [22, 23]]])] >>> ht.dsplit(x, [1, 4]) [DNDarray([[[ 0], [ 4], [ 8]], [[12], [16], [20]]]), DNDarray([[[ 1, 2, 3], [ 5, 6, 7], [ 9, 10, 11]], [[13, 14, 15], [17, 18, 19], [21, 22, 23]]]), DNDarray([])] .. function:: expand_dims(a: heat.core.dndarray.DNDarray, axis: int) -> heat.core.dndarray.DNDarray Expand the shape of an array. Insert a new axis that will appear at the axis position in the expanded array shape. :param a: Input array to be expanded. :type a: DNDarray :param axis: Position in the expanded axes where the new axis is placed. :type axis: int :raises ValueError: If `axis` is not consistent with the available dimensions. .. rubric:: Examples >>> x = ht.array([1, 2]) >>> x.shape (2,) >>> y = ht.expand_dims(x, axis=0) >>> y array([[1, 2]]) >>> y.shape (1, 2) >>> y = ht.expand_dims(x, axis=1) >>> y array([[1], [2]]) >>> y.shape (2, 1) .. function:: flatten(a: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Flattens an array into one dimension. :param a: Array to collapse :type a: DNDarray .. warning:: If `a.split>0`, the array must be redistributed along the first axis (see :func:`resplit`). .. seealso:: :func:`ravel` .. rubric:: Examples >>> a = ht.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]]) >>> ht.flatten(a) DNDarray([1, 2, 3, 4, 5, 6, 7, 8], dtype=ht.int64, device=cpu:0, split=None) .. function:: flip(a: heat.core.dndarray.DNDarray, axis: Union[int, Tuple[int, Ellipsis]] = None) -> heat.core.dndarray.DNDarray Reverse the order of elements in an array along the given axis. The shape of the array is preserved, but the elements are reordered. :param a: Input array to be flipped :type a: DNDarray :param axis: The axis or sequence of axes to be flipped :type axis: int or Tuple[int,...] .. seealso:: :func:`fliplr`, :func:`flipud` .. rubric:: Examples >>> a = ht.array([[0, 1], [2, 3]]) >>> ht.flip(a, [0]) DNDarray([[2, 3], [0, 1]], dtype=ht.int64, device=cpu:0, split=None) >>> b = ht.array([[0, 1, 2], [3, 4, 5]], split=1) >>> ht.flip(a, [0, 1]) (1/2) tensor([5,4,3]) (2/2) tensor([2,1,0]) .. function:: fliplr(a: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Flip array in the left/right direction. If `a.ndim>2`, flip along dimension 1. :param a: Input array to be flipped, must be at least 2-D :type a: DNDarray .. seealso:: :func:`flip`, :func:`flipud` .. rubric:: Examples >>> a = ht.array([[0, 1], [2, 3]]) >>> ht.fliplr(a) DNDarray([[1, 0], [3, 2]], dtype=ht.int64, device=cpu:0, split=None) >>> b = ht.array([[0, 1, 2], [3, 4, 5]], split=0) >>> ht.fliplr(b) (1/2) tensor([[2, 1, 0]]) (2/2) tensor([[5, 4, 3]]) .. function:: flipud(a: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Flip array in the up/down direction. :param a: Input array to be flipped :type a: DNDarray .. seealso:: :func:`flip`, :func:`fliplr` .. rubric:: Examples >>> a = ht.array([[0, 1], [2, 3]]) >>> ht.flipud(a) DNDarray([[2, 3], [0, 1]], dtype=ht.int64, device=cpu:0, split=None)) >>> b = ht.array([[0, 1, 2], [3, 4, 5]], split=0) >>> ht.flipud(b) (1/2) tensor([3,4,5]) (2/2) tensor([0,1,2]) .. function:: hsplit(x: heat.core.dndarray.DNDarray, indices_or_sections: Iterable) -> List[heat.core.dndarray.DNDarray, Ellipsis] Split array into multiple sub-DNDarrays along the 2nd axis (horizontally/column-wise). Returns a list of sub-DNDarrays as copies of parts of `x`. :param x: DNDArray to be divided into sub-DNDarrays. :type x: DNDarray :param indices_or_sections: If `indices_or_sections` is an integer, N, the DNDarray will be divided into N equal DNDarrays along the 2nd axis. If such a split is not possible, an error is raised. If `indices_or_sections` is a 1-D DNDarray of sorted integers, the entries indicate where along the 2nd axis the array is split. If an index exceeds the dimension of the array along the 2nd axis, an empty sub-DNDarray is returned correspondingly. :type indices_or_sections: int or 1-dimensional array_like (i.e. undistributed DNDarray, list or tuple) :raises ValueError: If `indices_or_sections` is given as integer, but a split does not result in equal division. .. rubric:: Notes Please refer to the split documentation. hsplit is nearly equivalent to split with axis=1, the array is always split along the second axis though, in contrary to split, regardless of the array dimension. .. seealso:: :func:`split`, :func:`dsplit`, :func:`vsplit` .. rubric:: Examples >>> x = ht.arange(24).reshape((2, 4, 3)) >>> ht.hsplit(x, 2) [DNDarray([[[ 0, 1, 2], [ 3, 4, 5]], [[12, 13, 14], [15, 16, 17]]]), DNDarray([[[ 6, 7, 8], [ 9, 10, 11]], [[18, 19, 20], [21, 22, 23]]])] >>> ht.hsplit(x, [1, 3]) [DNDarray([[[ 0, 1, 2]], [[12, 13, 14]]]), DNDarray([[[ 3, 4, 5], [ 6, 7, 8]], [[15, 16, 17], [18, 19, 20]]]), DNDarray([[[ 9, 10, 11]], [[21, 22, 23]]])] .. function:: hstack(arrays: Sequence[heat.core.dndarray.DNDarray, Ellipsis]) -> heat.core.dndarray.DNDarray Stack arrays in sequence horizontally (column-wise). This is equivalent to concatenation along the second axis, except for 1-D arrays where it concatenates along the first axis. :param arrays: The arrays must have the same shape along all but the second axis, except 1-D arrays which can be any length. :type arrays: Sequence[DNDarray, ...] .. seealso:: :func:`concatenate`, :func:`stack`, :func:`vstack`, :func:`column_stack`, :func:`row_stack` .. rubric:: Examples >>> a = ht.array((1, 2, 3)) >>> b = ht.array((2, 3, 4)) >>> ht.hstack((a, b)).larray [0/1] tensor([1, 2, 3, 2, 3, 4]) [1/1] tensor([1, 2, 3, 2, 3, 4]) >>> a = ht.array((1, 2, 3), split=0) >>> b = ht.array((2, 3, 4), split=0) >>> ht.hstack((a, b)).larray [0/1] tensor([1, 2, 3]) [1/1] tensor([2, 3, 4]) >>> a = ht.array([[1], [2], [3]], split=0) >>> b = ht.array([[2], [3], [4]], split=0) >>> ht.hstack((a, b)).larray [0/1] tensor([[1, 2], [0/1] [2, 3]]) [1/1] tensor([[3, 4]]) .. function:: moveaxis(x: heat.core.dndarray.DNDarray, source: Union[int, Sequence[int]], destination: Union[int, Sequence[int]]) -> heat.core.dndarray.DNDarray Moves axes at the positions in `source` to new positions. :param x: The input array. :type x: DNDarray :param source: Original positions of the axes to move. These must be unique. :type source: int or Sequence[int, ...] :param destination: Destination positions for each of the original axes. These must also be unique. :type destination: int or Sequence[int, ...] .. seealso:: :py:obj:`~heat.core.linalg.basics.transpose` Permute the dimensions of an array. :raises TypeError: If `source` or `destination` are not ints, lists or tuples. :raises ValueError: If `source` and `destination` do not have the same number of elements. .. rubric:: Examples >>> x = ht.zeros((3, 4, 5)) >>> ht.moveaxis(x, 0, -1).shape (4, 5, 3) >>> ht.moveaxis(x, -1, 0).shape (5, 3, 4) .. function:: pad(array: heat.core.dndarray.DNDarray, pad_width: Union[int, Sequence[Sequence[int, int], Ellipsis]], mode: str = 'constant', constant_values: int = 0) -> heat.core.dndarray.DNDarray Pads tensor with a specific value (default=0). (Not all dimensions supported) :param array: Array to be padded :type array: DNDarray :param pad_width: Number of values padded to the edges of each axis. ((before_1, after_1),...(before_N, after_N)) unique pad widths for each axis. Determines how many elements are padded along which dimension. Shortcuts: - ((before, after),) or (before, after): before and after pad width for each axis. - (pad_width,) or int: before = after = pad width for all axes. Therefore: - pad last dimension: (padding_left, padding_right) - pad last 2 dimensions: ((padding_top, padding_bottom),(padding_left, padding_right)) - pad last 3 dimensions: ((padding_front, padding_back),(padding_top, padding_bottom),(paddling_left, padding_right) ) - ... (same pattern) :type pad_width: Union[int, Sequence[Sequence[int, int], ...]] :param mode: - 'constant' (default): Pads the input tensor boundaries with a constant value. This is available for arbitrary dimensions :type mode: str, optional :param constant_values: Number or tuple of 2-element-sequences (containing numbers), optional (default=0) The fill values for each axis (1 tuple per axis). ((before_1, after_1), ... (before_N, after_N)) unique pad values for each axis. Shortcuts: - ((before, after),) or (before, after): before and after padding values for each axis. - (value,) or int: before = after = padding value for all axes. :type constant_values: Union[int, float, Sequence[Sequence[int,int], ...], Sequence[Sequence[float,float], ...]] .. rubric:: Notes This function follows the principle of datatype integrity. Therefore, an array can only be padded with values of the same datatype. All values that violate this rule are implicitly cast to the datatype of the `DNDarray`. .. rubric:: Examples >>> a = torch.arange(2 * 3 * 4).reshape(2, 3, 4) >>> b = ht.array(a, split=0) Pad last dimension >>> c = ht.pad(b, (2, 1), constant_values=1) tensor([[[ 1, 1, 0, 1, 2, 3, 1], [ 1, 1, 4, 5, 6, 7, 1], [ 1, 1, 8, 9, 10, 11, 1]], [[ 1, 1, 12, 13, 14, 15, 1], [ 1, 1, 16, 17, 18, 19, 1], [ 1, 1, 20, 21, 22, 23, 1]]]) Pad last 2 dimensions >>> d = ht.pad(b, [(1, 0), (2, 1)]) DNDarray([[[ 0, 0, 0, 0, 0, 0, 0], [ 0, 0, 0, 1, 2, 3, 0], [ 0, 0, 4, 5, 6, 7, 0], [ 0, 0, 8, 9, 10, 11, 0]], [[ 0, 0, 0, 0, 0, 0, 0], [ 0, 0, 12, 13, 14, 15, 0], [ 0, 0, 16, 17, 18, 19, 0], [ 0, 0, 20, 21, 22, 23, 0]]], dtype=ht.int64, device=cpu:0, split=0) Pad last 3 dimensions >>> e = ht.pad(b, ((2, 1), [1, 0], (2, 1))) DNDarray([[[ 0, 0, 0, 0, 0, 0, 0], [ 0, 0, 0, 0, 0, 0, 0], [ 0, 0, 0, 0, 0, 0, 0], [ 0, 0, 0, 0, 0, 0, 0]], [[ 0, 0, 0, 0, 0, 0, 0], [ 0, 0, 0, 0, 0, 0, 0], [ 0, 0, 0, 0, 0, 0, 0], [ 0, 0, 0, 0, 0, 0, 0]], [[ 0, 0, 0, 0, 0, 0, 0], [ 0, 0, 0, 1, 2, 3, 0], [ 0, 0, 4, 5, 6, 7, 0], [ 0, 0, 8, 9, 10, 11, 0]], [[ 0, 0, 0, 0, 0, 0, 0], [ 0, 0, 12, 13, 14, 15, 0], [ 0, 0, 16, 17, 18, 19, 0], [ 0, 0, 20, 21, 22, 23, 0]], [[ 0, 0, 0, 0, 0, 0, 0], [ 0, 0, 0, 0, 0, 0, 0], [ 0, 0, 0, 0, 0, 0, 0], [ 0, 0, 0, 0, 0, 0, 0]]], dtype=ht.int64, device=cpu:0, split=0) .. function:: ravel(a: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Return a flattened view of `a` if possible. A copy is returned otherwise. :param a: array to collapse :type a: DNDarray .. rubric:: Notes Returning a view of distributed data is only possible when `split != 0`. The returned DNDarray may be unbalanced. Otherwise, data must be communicated among processes, and `ravel` falls back to `flatten`. .. seealso:: :func:`flatten` .. rubric:: Examples >>> a = ht.ones((2, 3), split=0) >>> b = ht.ravel(a) >>> a[0, 0] = 4 >>> b DNDarray([4., 1., 1., 1., 1., 1.], dtype=ht.float32, device=cpu:0, split=0) .. function:: redistribute(arr: heat.core.dndarray.DNDarray, lshape_map: torch.Tensor = None, target_map: torch.Tensor = None) -> heat.core.dndarray.DNDarray Redistributes the data of the :class:`DNDarray` *along the split axis* to match the given target map. This function does not modify the non-split dimensions of the ``DNDarray``. This is an abstraction and extension of the balance function. :param arr: DNDarray to redistribute :type arr: DNDarray :param lshape_map: The current lshape of processes. Units are ``[rank, lshape]``. :type lshape_map: torch.Tensor, optional :param target_map: The desired distribution across the processes. Units are ``[rank, target lshape]``. Note: the only important parts of the target map are the values along the split axis, values which are not along this axis are there to mimic the shape of the ``lshape_map``. :type target_map: torch.Tensor, optional .. rubric:: Examples >>> st = ht.ones((50, 81, 67), split=2) >>> target_map = torch.zeros((st.comm.size, 3), dtype=torch.int64) >>> target_map[0, 2] = 67 >>> print(target_map) [0/2] tensor([[ 0, 0, 67], [0/2] [ 0, 0, 0], [0/2] [ 0, 0, 0]], dtype=torch.int32) [1/2] tensor([[ 0, 0, 67], [1/2] [ 0, 0, 0], [1/2] [ 0, 0, 0]], dtype=torch.int32) [2/2] tensor([[ 0, 0, 67], [2/2] [ 0, 0, 0], [2/2] [ 0, 0, 0]], dtype=torch.int32) >>> print(st.lshape) [0/2] (50, 81, 23) [1/2] (50, 81, 22) [2/2] (50, 81, 22) >>> ht.redistribute_(st, target_map=target_map) >>> print(st.lshape) [0/2] (50, 81, 67) [1/2] (50, 81, 0) [2/2] (50, 81, 0) .. function:: repeat(a: Iterable, repeats: Iterable, axis: Optional[int] = None) -> heat.core.dndarray.DNDarray Creates a new `DNDarray` by repeating elements of array `a`. The output has the same shape as `a`, except along the given axis. If axis is None, this function returns a flattened `DNDarray`. :param a: Array containing the elements to be repeated. :type a: array_like (i.e. int, float, or tuple/ list/ np.ndarray/ ht.DNDarray of ints/floats) :param repeats: The number of repetitions for each element, indicates broadcast if int or array_like of 1 element. In this case, the given value is broadcasted to fit the shape of the given axis. Otherwise, its length must be the same as a in the specified axis. To put it differently, the amount of repetitions has to be determined for each element in the corresponding dimension (or in all dimensions if axis is None). :type repeats: int, or 1-dimensional/ DNDarray/ np.ndarray/ list/ tuple of ints :param axis: The axis along which to repeat values. By default, use the flattened input array and return a flat output array. :type axis: int, optional .. rubric:: Examples >>> ht.repeat(3, 4) DNDarray([3, 3, 3, 3]) >>> x = ht.array([[1, 2], [3, 4]]) >>> ht.repeat(x, 2) DNDarray([1, 1, 2, 2, 3, 3, 4, 4]) >>> x = ht.array([[1, 2], [3, 4]]) >>> ht.repeat(x, [0, 1, 2, 0]) DNDarray([2, 3, 3]) >>> ht.repeat(x, [1, 2], axis=0) DNDarray([[1, 2], [3, 4], [3, 4]]) .. function:: reshape(a: heat.core.dndarray.DNDarray, *shape: Union[int, Tuple[int, Ellipsis]], **kwargs) -> heat.core.dndarray.DNDarray Returns an array with the same data and number of elements as `a`, but with the specified shape. :param a: The input array :type a: DNDarray :param shape: Shape of the new array. Must be compatible with the original shape. If an integer, then the result will be a 1-D array of that length. One shape dimension can be -1. In this case, the value is inferred from the length of the array and remaining dimensions. :type shape: Union[int, Tuple[int,...]] :param new_split: The distribution axis of the reshaped array. If `new_split` is not provided, the reshaped array will have: - the same split axis as the input array, if the original dimensionality is unchanged; - split axis 0, if the number of dimensions is modified by reshaping. :type new_split: int, optional :param \*\*kwargs: Extra keyword arguments. :raises ValueError: If the number of elements in the new shape is inconsistent with the input data. .. rubric:: Notes `reshape()` might require significant communication among processes. Communication is minimized if the input array is distributed along axis 0, i.e. `a.split == 0`. .. seealso:: :func:`ravel` .. rubric:: Examples >>> a = ht.zeros((3, 4)) >>> ht.reshape(a, (4, 3)) DNDarray([[0., 0., 0.], [0., 0., 0.], [0., 0., 0.], [0., 0., 0.]], dtype=ht.float32, device=cpu:0, split=None) >>> a = ht.linspace(0, 14, 8, split=0) >>> ht.reshape(a, (2, 4)) (1/2) tensor([[0., 2., 4., 6.]]) (2/2) tensor([[ 8., 10., 12., 14.]]) # 3-dim array, distributed along axis 1 >>> a = ht.random.rand(2, 3, 4, split=1) >>> a DNDarray([[[0.5525, 0.5434, 0.9477, 0.9503], [0.4165, 0.3924, 0.3310, 0.3935], [0.1008, 0.1750, 0.9030, 0.8579]], [[0.0680, 0.4944, 0.4114, 0.6669], [0.6423, 0.2625, 0.5413, 0.2225], [0.0197, 0.5079, 0.4739, 0.4387]]], dtype=ht.float32, device=cpu:0, split=1) >>> a.reshape(-1, 3) # reshape to 2-dim array: split axis will be set to 0 DNDarray([[0.5525, 0.5434, 0.9477], [0.9503, 0.4165, 0.3924], [0.3310, 0.3935, 0.1008], [0.1750, 0.9030, 0.8579], [0.0680, 0.4944, 0.4114], [0.6669, 0.6423, 0.2625], [0.5413, 0.2225, 0.0197], [0.5079, 0.4739, 0.4387]], dtype=ht.float32, device=cpu:0, split=0) >>> a.reshape(2, 3, 2, 2, new_split=1) # reshape to 4-dim array, specify distribution axis DNDarray([[[[0.5525, 0.5434], [0.9477, 0.9503]], [[0.4165, 0.3924], [0.3310, 0.3935]], [[0.1008, 0.1750], [0.9030, 0.8579]]], [[[0.0680, 0.4944], [0.4114, 0.6669]], [[0.6423, 0.2625], [0.5413, 0.2225]], [[0.0197, 0.5079], [0.4739, 0.4387]]]], dtype=ht.float32, device=cpu:0, split=1) .. function:: resplit(arr: heat.core.dndarray.DNDarray, axis: Optional[int] = None) -> heat.core.dndarray.DNDarray Out-of-place redistribution of the content of the `DNDarray`. Allows to "unsplit" (i.e. gather) all values from all nodes, as well as to define a new axis along which the array is split without changes to the values. :param arr: The array from which to resplit :type arr: DNDarray :param axis: The new split axis, `None` denotes gathering, an int will set the new split axis :type axis: int or None .. warning:: This operation might involve a significant communication overhead. Use it sparingly and preferably for small arrays. .. rubric:: Examples >>> a = ht.zeros( ... ( ... 4, ... 5, ... ), ... split=0, ... ) >>> a.lshape (0/2) (2, 5) (1/2) (2, 5) >>> b = resplit(a, None) >>> b.split None >>> b.lshape (0/2) (4, 5) (1/2) (4, 5) >>> a = ht.zeros( ... ( ... 4, ... 5, ... ), ... split=0, ... ) >>> a.lshape (0/2) (2, 5) (1/2) (2, 5) >>> b = resplit(a, 1) >>> b.split 1 >>> b.lshape (0/2) (4, 3) (1/2) (4, 2) .. function:: roll(x: heat.core.dndarray.DNDarray, shift: Union[int, Tuple[int]], axis: Optional[Union[int, Tuple[int]]] = None) -> heat.core.dndarray.DNDarray Rolls array elements along a specified axis. Array elements that roll beyond the last position are re-introduced at the first position. Array elements that roll beyond the first position are re-introduced at the last position. :param x: input array :type x: DNDarray :param shift: number of places by which the elements are shifted. If 'shift' is a tuple, then 'axis' must be a tuple of the same size, and each of the given axes is shifted by the corrresponding element in 'shift'. If 'shift' is an `int` and 'axis' a `tuple`, then the same shift is used for all specified axes. :type shift: Union[int, Tuple[int, ...]] :param axis: axis (or axes) along which elements to shift. If 'axis' is `None`, the array is flattened, shifted, and then restored to its original shape. Default: `None`. :type axis: Optional[Union[int, Tuple[int, ...]]] :raises TypeError: If 'shift' or 'axis' is not of type `int`, `list` or `tuple`. :raises ValueError: If 'shift' and 'axis' are tuples with different sizes. .. rubric:: Examples >>> a = ht.arange(20).reshape((4, 5)) >>> a DNDarray([[ 0, 1, 2, 3, 4], [ 5, 6, 7, 8, 9], [10, 11, 12, 13, 14], [15, 16, 17, 18, 19]], dtype=ht.int32, device=cpu:0, split=None) >>> ht.roll(a, 1) DNDarray([[19, 0, 1, 2, 3], [ 4, 5, 6, 7, 8], [ 9, 10, 11, 12, 13], [14, 15, 16, 17, 18]], dtype=ht.int32, device=cpu:0, split=None) >>> ht.roll(a, -1, 0) DNDarray([[ 5, 6, 7, 8, 9], [10, 11, 12, 13, 14], [15, 16, 17, 18, 19], [ 0, 1, 2, 3, 4]], dtype=ht.int32, device=cpu:0, split=None) .. function:: rot90(m: heat.core.dndarray.DNDarray, k: int = 1, axes: Sequence[int, int] = (0, 1)) -> heat.core.dndarray.DNDarray Rotate an array by 90 degrees in the plane specified by `axes`. Rotation direction is from the first towards the second axis. :param m: Array of two or more dimensions. :type m: DNDarray :param k: Number of times the array is rotated by 90 degrees. :type k: integer :param axes: The array is rotated in the plane defined by the axes. Axes must be different. :type axes: (2,) Sequence[int, int] :raises ValueError: If `len(axis)!=2`. :raises ValueError: If the axes are the same. :raises ValueError: If axes are out of range. .. rubric:: Notes - ``rot90(m, k=1, axes=(1,0))`` is the reverse of ``rot90(m, k=1, axes=(0,1))``. - ``rot90(m, k=1, axes=(1,0))`` is equivalent to ``rot90(m, k=-1, axes=(0,1))``. May change the split axis on distributed tensors. .. rubric:: Examples >>> m = ht.array([[1, 2], [3, 4]], dtype=ht.int) >>> m DNDarray([[1, 2], [3, 4]], dtype=ht.int32, device=cpu:0, split=None) >>> ht.rot90(m) DNDarray([[2, 4], [1, 3]], dtype=ht.int32, device=cpu:0, split=None) >>> ht.rot90(m, 2) DNDarray([[4, 3], [2, 1]], dtype=ht.int32, device=cpu:0, split=None) >>> m = ht.arange(8).reshape((2, 2, 2)) >>> ht.rot90(m, 1, (1, 2)) DNDarray([[[1, 3], [0, 2]], [[5, 7], [4, 6]]], dtype=ht.int32, device=cpu:0, split=None) .. function:: row_stack(arrays: Sequence[heat.core.dndarray.DNDarray, Ellipsis]) -> heat.core.dndarray.DNDarray Stack 1-D or 2-D `DNDarray`s as rows into a 2-D `DNDarray`. If the input arrays are 1-D, they will be stacked as rows. If they are 2-D, they will be concatenated along the first axis. :param arrays: Sequence of `DNDarray`s. :type arrays: Sequence[DNDarrays, ...] :raises ValueError: If arrays have more than 2 dimensions .. rubric:: Notes All ``DNDarray``s in the sequence must have the same number of columns. All ``DNDarray``s must be split along the same axis! .. seealso:: :func:`column_stack`, :func:`concatenate`, :func:`hstack`, :func:`stack`, :func:`vstack` .. rubric:: Examples >>> # 1-D tensors >>> a = ht.array([1, 2, 3]) >>> b = ht.array([2, 3, 4]) >>> ht.row_stack((a, b)).larray tensor([[1, 2, 3], [2, 3, 4]]) >>> # 1-D and 2-D tensors >>> a = ht.array([1, 2, 3]) >>> b = ht.array([[2, 3, 4], [5, 6, 7]]) >>> c = ht.array([[7, 8, 9], [10, 11, 12]]) >>> ht.row_stack((a, b, c)).larray tensor([[ 1, 2, 3], [ 2, 3, 4], [ 5, 6, 7], [ 7, 8, 9], [10, 11, 12]]) >>> # distributed DNDarrays, 3 processes >>> a = ht.arange(10, split=0).reshape((2, 5)) >>> b = ht.arange(5, 20, split=0).reshape((3, 5)) >>> c = ht.arange(20, 40, split=0).reshape((4, 5)) >>> ht.row_stack((a, b, c)).larray [0/2] tensor([[0, 1, 2, 3, 4], [0/2] [5, 6, 7, 8, 9], [0/2] [5, 6, 7, 8, 9]], dtype=torch.int32) [1/2] tensor([[10, 11, 12, 13, 14], [1/2] [15, 16, 17, 18, 19], [1/2] [20, 21, 22, 23, 24]], dtype=torch.int32) [2/2] tensor([[25, 26, 27, 28, 29], [2/2] [30, 31, 32, 33, 34], [2/2] [35, 36, 37, 38, 39]], dtype=torch.int32) >>> # distributed 1-D and 2-D DNDarrays, 3 processes >>> a = ht.arange(5, split=0) >>> b = ht.arange(5, 20, split=0).reshape((3, 5)) >>> ht.row_stack((a, b)).larray [0/2] tensor([[0, 1, 2, 3, 4], [0/2] [5, 6, 7, 8, 9]]) [1/2] tensor([[10, 11, 12, 13, 14]]) [2/2] tensor([[15, 16, 17, 18, 19]]) .. function:: shape(a: heat.core.dndarray.DNDarray) -> Tuple[int, Ellipsis] Returns the global shape of a (potentially distributed) `DNDarray` as a tuple. :param a: The input `DNDarray`. :type a: DNDarray .. function:: sort(a: heat.core.dndarray.DNDarray, axis: int = -1, descending: bool = False, out: Optional[heat.core.dndarray.DNDarray] = None) Sorts the elements of `a` along the given dimension (by default in ascending order) by their value. The sorting is not stable which means that equal elements in the result may have a different ordering than in the original array. Sorting where `axis==a.split` needs a lot of communication between the processes of MPI. Returns a tuple `(values, indices)` with the sorted local results and the indices of the elements in the original data :param a: Input array to be sorted. :type a: DNDarray :param axis: The dimension to sort along. Default is the last axis. :type axis: int, optional :param descending: If set to `True`, values are sorted in descending order. :type descending: bool, optional :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to `None`, a fresh array is allocated. :type out: DNDarray, optional :raises ValueError: If `axis` is not consistent with the available dimensions. .. rubric:: Examples >>> x = ht.array([[4, 1], [2, 3]], split=0) >>> x.shape (1, 2) (1, 2) >>> y = ht.sort(x, axis=0) >>> y (array([[2, 1]], array([[1, 0]])) (array([[4, 3]], array([[0, 1]])) >>> ht.sort(x, descending=True) (array([[4, 1]], array([[0, 1]])) (array([[3, 2]], array([[1, 0]])) .. function:: split(x: heat.core.dndarray.DNDarray, indices_or_sections: Iterable, axis: int = 0) -> List[heat.core.dndarray.DNDarray, Ellipsis] Split a DNDarray into multiple sub-DNDarrays. Returns a list of sub-DNDarrays as copies of parts of `x`. :param x: DNDArray to be divided into sub-DNDarrays. :type x: DNDarray :param indices_or_sections: If `indices_or_sections` is an integer, N, the DNDarray will be divided into N equal DNDarrays along axis. If such a split is not possible, an error is raised. If `indices_or_sections` is a 1-D DNDarray of sorted integers, the entries indicate where along axis the array is split. For example, `indices_or_sections = [2, 3]` would, for `axis = 0`, result in - `x[:2]` - `x[2:3]` - `x[3:]` If an index exceeds the dimension of the array along axis, an empty sub-array is returned correspondingly. :type indices_or_sections: int or 1-dimensional array_like (i.e. undistributed DNDarray, list or tuple) :param axis: The axis along which to split, default is 0. `axis` is not allowed to equal `x.split` if `x` is distributed. :type axis: int, optional :raises ValueError: If `indices_or_sections` is given as integer, but a split does not result in equal division. .. warning:: Though it is possible to distribute `x`, this function has nothing to do with the split parameter of a DNDarray. .. seealso:: :func:`dsplit`, :func:`hsplit`, :func:`vsplit` .. rubric:: Examples >>> x = ht.arange(12).reshape((4, 3)) >>> ht.split(x, 2) [ DNDarray([[0, 1, 2], [3, 4, 5]]), DNDarray([[ 6, 7, 8], [ 9, 10, 11]])] >>> ht.split(x, [2, 3, 5]) [ DNDarray([[0, 1, 2], [3, 4, 5]]), DNDarray([[6, 7, 8]] DNDarray([[ 9, 10, 11]]), DNDarray([])] >>> ht.split(x, [1, 2], 1) [DNDarray([[0], [3], [6], [9]]), DNDarray([[ 1], [ 4], [ 7], [10]], DNDarray([[ 2], [ 5], [ 8], [11]])] .. function:: squeeze(x: heat.core.dndarray.DNDarray, axis: Union[int, Tuple[int, Ellipsis]] = None) -> heat.core.dndarray.DNDarray Remove single-element entries from the shape of a `DNDarray`. Returns the input array, but with all or a subset (indicated by `axis`) of the dimensions of length 1 removed. Split semantics: see Notes below. :param x: Input data. :type x: DNDarray :param axis: Selects a subset of the single-element entries in the shape. If axis is `None`, all single-element entries will be removed from the shape. :type axis: None or int or Tuple[int,...], optional :raises ValueError: .. rubric:: Notes Split semantics: a distributed DNDarray will keep its original split dimension after "squeezing", which, depending on the squeeze axis, may result in a lower numerical `split` value (see Examples). .. rubric:: Examples >>> import heat as ht >>> a = ht.random.randn(1, 3, 1, 5) >>> a DNDarray([[[[-0.2604, 1.3512, 0.1175, 0.4197, 1.3590]], [[-0.2777, -1.1029, 0.0697, -1.3074, -1.1931]], [[-0.4512, -1.2348, -1.1479, -0.0242, 0.4050]]]], dtype=ht.float32, device=cpu:0, split=None) >>> a.shape (1, 3, 1, 5) >>> ht.squeeze(a).shape (3, 5) >>> ht.squeeze(a) DNDarray([[-0.2604, 1.3512, 0.1175, 0.4197, 1.3590], [-0.2777, -1.1029, 0.0697, -1.3074, -1.1931], [-0.4512, -1.2348, -1.1479, -0.0242, 0.4050]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.squeeze(a, axis=0).shape (3, 1, 5) >>> ht.squeeze(a, axis=-2).shape (1, 3, 5) >>> ht.squeeze(a, axis=1).shape Traceback (most recent call last): ... ValueError: Dimension along axis 1 is not 1 for shape (1, 3, 1, 5) >>> x.shape (10, 1, 12, 13) >>> x.split 2 >>> x.squeeze().shape (10, 12, 13) >>> x.squeeze().split 1 .. function:: stack(arrays: Sequence[heat.core.dndarray.DNDarray, Ellipsis], axis: int = 0, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Join a sequence of `DNDarray`s along a new axis. The `axis` parameter specifies the index of the new axis in the dimensions of the result. For example, if `axis=0`, the arrays will be stacked along the first dimension; if `axis=-1`, they will be stacked along the last dimension. See Notes below for split semantics. :param arrays: Each DNDarray must have the same shape, must be split along the same axis, and must be balanced. :type arrays: Sequence[DNDarrays, ...] :param axis: The axis in the result array along which the input arrays are stacked. :type axis: int, optional :param out: If provided, the destination to place the result. The shape and split axis must be correct, matching that of what stack would have returned if no out argument were specified (see Notes below). :type out: DNDarray, optional :raises TypeError: If arrays in sequence are not `DNDarray`s, or if their `dtype` attribute does not match. :raises ValueError: If `arrays` contains less than 2 `DNDarray`s. :raises ValueError: If the `DNDarray`s are of different shapes, or if they are split along different axes (`split` attribute). :raises RuntimeError: If the `DNDarrays` reside on different devices. .. rubric:: Notes Split semantics: :func:`stack` requires that all arrays in the sequence be split along the same dimension. After stacking, the data are still distributed along the original dimension, however a new dimension has been added at `axis`, therefore: - if :math:`axis <= split`, output will be distributed along :math:`split+1` - if :math:`axis > split`, output will be distributed along `split` .. seealso:: :func:`column_stack`, :func:`concatenate`, :func:`hstack`, :func:`row_stack`, :func:`vstack` .. rubric:: Examples >>> a = ht.arange(20).reshape((4, 5)) >>> b = ht.arange(20, 40).reshape((4, 5)) >>> ht.stack((a, b), axis=0).larray tensor([[[ 0, 1, 2, 3, 4], [ 5, 6, 7, 8, 9], [10, 11, 12, 13, 14], [15, 16, 17, 18, 19]], [[20, 21, 22, 23, 24], [25, 26, 27, 28, 29], [30, 31, 32, 33, 34], [35, 36, 37, 38, 39]]]) >>> # distributed DNDarrays, 3 processes, stack along last dimension >>> a = ht.arange(20, split=0).reshape(4, 5) >>> b = ht.arange(20, 40, split=0).reshape(4, 5) >>> ht.stack((a, b), axis=-1).larray [0/2] tensor([[[ 0, 20], [0/2] [ 1, 21], [0/2] [ 2, 22], [0/2] [ 3, 23], [0/2] [ 4, 24]], [0/2] [[ 5, 25], [0/2] [ 6, 26], [0/2] [ 7, 27], [0/2] [ 8, 28], [0/2] [ 9, 29]]]) [1/2] tensor([[[10, 30], [1/2] [11, 31], [1/2] [12, 32], [1/2] [13, 33], [1/2] [14, 34]]]) [2/2] tensor([[[15, 35], [2/2] [16, 36], [2/2] [17, 37], [2/2] [18, 38], [2/2] [19, 39]]]) .. function:: swapaxes(x: heat.core.dndarray.DNDarray, axis1: int, axis2: int) -> heat.core.dndarray.DNDarray Interchanges two axes of an array. :param x: Input array. :type x: DNDarray :param axis1: First axis. :type axis1: int :param axis2: Second axis. :type axis2: int .. seealso:: :func:`~heat.core.linalg.basics.transpose` Permute the dimensions of an array. .. rubric:: Examples >>> x = ht.array([[[0, 1], [2, 3]], [[4, 5], [6, 7]]]) >>> ht.swapaxes(x, 0, 1) DNDarray([[[0, 1], [4, 5]], [[2, 3], [6, 7]]], dtype=ht.int64, device=cpu:0, split=None) >>> ht.swapaxes(x, 0, 2) DNDarray([[[0, 4], [2, 6]], [[1, 5], [3, 7]]], dtype=ht.int64, device=cpu:0, split=None) .. function:: tile(x: heat.core.dndarray.DNDarray, reps: Sequence[int, Ellipsis]) -> heat.core.dndarray.DNDarray Construct a new DNDarray by repeating 'x' the number of times given by 'reps'. If 'reps' has length 'd', the result will have 'max(d, x.ndim)' dimensions: - if 'x.ndim < d', 'x' is promoted to be d-dimensional by prepending new axes. So a shape (3,) array is promoted to (1, 3) for 2-D replication, or shape (1, 1, 3) for 3-D replication (if this is not the desired behavior, promote 'x' to d-dimensions manually before calling this function); - if 'x.ndim > d', 'reps' will replicate the last 'd' dimensions of 'x', i.e., if 'x.shape' is (2, 3, 4, 5), a 'reps' of (2, 2) will be expanded to (1, 1, 2, 2). :param x: Input :type x: DNDarray :param reps: Repetitions :type reps: Sequence[ints,...] :returns: **tiled** -- Split semantics: if `x` is distributed, the tiled data will be distributed along the same dimension. Note that nominally `tiled.split != x.split` in the case where `len(reps) > x.ndim`. See example below. :rtype: DNDarray .. rubric:: Examples >>> x = ht.arange(12).reshape((4, 3)).resplit_(0) >>> x DNDarray([[ 0, 1, 2], [ 3, 4, 5], [ 6, 7, 8], [ 9, 10, 11]], dtype=ht.int32, device=cpu:0, split=0) >>> reps = (1, 2, 2) >>> tiled = ht.tile(x, reps) >>> tiled DNDarray([[[ 0, 1, 2, 0, 1, 2], [ 3, 4, 5, 3, 4, 5], [ 6, 7, 8, 6, 7, 8], [ 9, 10, 11, 9, 10, 11], [ 0, 1, 2, 0, 1, 2], [ 3, 4, 5, 3, 4, 5], [ 6, 7, 8, 6, 7, 8], [ 9, 10, 11, 9, 10, 11]]], dtype=ht.int32, device=cpu:0, split=1) .. function:: topk(a: heat.core.dndarray.DNDarray, k: int, dim: int = -1, largest: bool = True, sorted: bool = True, out: Optional[Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray]] = None) -> Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] Returns the :math:`k` highest entries in the array. (Not Stable for split arrays) :param a: Input data :type a: DNDarray :param k: Desired number of output items :type k: int :param dim: Dimension along which to sort, per default the last dimension :type dim: int, optional :param largest: If `True`, return the :math:`k` largest items, otherwise return the :math:`k` smallest items :type largest: bool, optional :param sorted: Whether to sort the output (descending if `largest` is `True`, else ascending) :type sorted: bool, optional :param out: output buffer :type out: Tuple[DNDarray, ...], optional .. rubric:: Examples >>> a = ht.array([1, 2, 3]) >>> ht.topk(a, 2) (DNDarray([3, 2], dtype=ht.int64, device=cpu:0, split=None), DNDarray([2, 1], dtype=ht.int64, device=cpu:0, split=None)) >>> a = ht.array([[1, 2, 3], [1, 2, 3]]) >>> ht.topk(a, 2, dim=1) (DNDarray([[3, 2], [3, 2]], dtype=ht.int64, device=cpu:0, split=None), DNDarray([[2, 1], [2, 1]], dtype=ht.int64, device=cpu:0, split=None)) >>> a = ht.array([[1, 2, 3], [1, 2, 3]], split=1) >>> ht.topk(a, 2, dim=1) (DNDarray([[3, 2], [3, 2]], dtype=ht.int64, device=cpu:0, split=1), DNDarray([[2, 1], [2, 1]], dtype=ht.int64, device=cpu:0, split=1)) .. function:: unfold(a: heat.core.dndarray.DNDarray, axis: int, size: int, step: int = 1) Returns a DNDarray which contains all slices of size `size` in the axis `axis`. Behaves like torch.Tensor.unfold for DNDarrays. [torch.Tensor.unfold](https://pytorch.org/docs/stable/generated/torch.Tensor.unfold.html) :param a: array to unfold :type a: DNDarray :param axis: axis in which unfolding happens :type axis: int :param size: the size of each slice that is unfolded, must be greater than 1 :type size: int :param step: the step between each slice, must be at least 1 :type step: int :param Example: :param ```: :param >>> x = ht.arange(1.: :param 8): :param >>> x: :param DNDarray([1.: :type DNDarray([1.: 0, split=e) :param 2.: :type 2.: 0, split=e) :param 3.: :type 3.: 0, split=e) :param 4.: :type 4.: 0, split=e) :param 5.: :type 5.: 0, split=e) :param 6.: :type 6.: 0, split=e) :param 7.]: :type 7.]: 0, split=e) :param dtype=ht.float32: :type dtype=ht.float32: 0, split=e) :param device=cpu: :type device=cpu: 0, split=e) :param >>> ht.unfold(x: :param 0: :param 2: :param 1): :param DNDarray([[1.: [2., 3.], [3., 4.], [4., 5.], [5., 6.], [6., 7.]], dtype=ht.float32, device=cpu:0, split=None) :param 2.]: [2., 3.], [3., 4.], [4., 5.], [5., 6.], [6., 7.]], dtype=ht.float32, device=cpu:0, split=None) :param : [2., 3.], [3., 4.], [4., 5.], [5., 6.], [6., 7.]], dtype=ht.float32, device=cpu:0, split=None) :param >>> ht.unfold(x: :param 0: :param 2: :param 2): :param DNDarray([[1.: [3., 4.], [5., 6.]], dtype=ht.float32, device=cpu:0, split=None) :param 2.]: [3., 4.], [5., 6.]], dtype=ht.float32, device=cpu:0, split=None) :param : [3., 4.], [5., 6.]], dtype=ht.float32, device=cpu:0, split=None) :param ```: .. note:: You have to make sure that every node has at least chunk size size-1 if the split axis of the array is the unfold axis. .. function:: unique(a: heat.core.dndarray.DNDarray, sorted: bool = False, return_inverse: bool = False, axis: int = None) -> Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] Finds and returns the unique elements of a `DNDarray`. If return_inverse is `True`, the second tensor will hold the list of inverse indices If distributed, it is most efficient if `axis!=a.split`. :param a: Input array. :type a: DNDarray :param sorted: Whether the found elements should be sorted before returning as output. Warning: sorted is not working if `axis!=None and axis!=a.split` :type sorted: bool, optional :param return_inverse: Whether to also return the indices for where elements in the original input ended up in the returned unique list. :type return_inverse: bool, optional :param axis: Axis along which unique elements should be found. Default to `None`, which will return a one dimensional list of unique values. :type axis: int, optional .. rubric:: Examples >>> x = ht.array([[3, 2], [1, 3]]) >>> ht.unique(x, sorted=True) array([1, 2, 3]) >>> ht.unique(x, sorted=True, axis=0) array([[1, 3], [2, 3]]) >>> ht.unique(x, sorted=True, axis=1) array([[2, 3], [3, 1]]) .. function:: vsplit(x: heat.core.dndarray.DNDarray, indices_or_sections: Iterable) -> List[heat.core.dndarray.DNDarray, Ellipsis] Split array into multiple sub-DNDNarrays along the 1st axis (vertically/row-wise). Returns a list of sub-DNDarrays as copies of parts of ``x``. :param x: DNDArray to be divided into sub-DNDarrays. :type x: DNDarray :param indices_or_sections: If `indices_or_sections` is an integer, N, the DNDarray will be divided into N equal DNDarrays along the 1st axis. If such a split is not possible, an error is raised. If `indices_or_sections` is a 1-D DNDarray of sorted integers, the entries indicate where along the 1st axis the array is split. If an index exceeds the dimension of the array along the 1st axis, an empty sub-DNDarray is returned correspondingly. :type indices_or_sections: Iterable :raises ValueError: If `indices_or_sections` is given as integer, but a split does not result in equal division. .. rubric:: Notes Please refer to the split documentation. :func:`hsplit` is equivalent to split with `axis=0`, the array is always split along the first axis regardless of the array dimension. .. seealso:: :func:`split`, :func:`dsplit`, :func:`hsplit` .. rubric:: Examples >>> x = ht.arange(24).reshape((4, 3, 2)) >>> ht.vsplit(x, 2) [DNDarray([[[ 0, 1], [ 2, 3], [ 4, 5]], [[ 6, 7], [ 8, 9], [10, 11]]]), DNDarray([[[12, 13], [14, 15], [16, 17]], [[18, 19], [20, 21], [22, 23]]])] >>> ht.vsplit(x, [1, 3]) [DNDarray([[[0, 1], [2, 3], [4, 5]]]), DNDarray([[[ 6, 7], [ 8, 9], [10, 11]], [[12, 13], [14, 15], [16, 17]]]), DNDarray([[[18, 19], [20, 21], [22, 23]]])] .. function:: vstack(arrays: Sequence[heat.core.dndarray.DNDarray, Ellipsis]) -> heat.core.dndarray.DNDarray Stack arrays in sequence vertically (row wise). This is equivalent to concatenation along the first axis. This function makes most sense for arrays with up to 3 dimensions. For instance, for pixel-data with a height (first axis), width (second axis), and r/g/b channels (third axis). The :func:`concatenate` function provides more general stacking operations. :param arrays: The arrays must have the same shape along all but the first axis. 1-D arrays must have the same length. :type arrays: Sequence[DNDarray,...] .. rubric:: Notes The split axis will be switched to 1 in the case that both elements are 1D and split=0 .. seealso:: :func:`concatenate`, :func:`stack`, :func:`hstack`, :func:`column_stack`, :func:`row_stack` .. rubric:: Examples >>> a = ht.array([1, 2, 3]) >>> b = ht.array([2, 3, 4]) >>> ht.vstack((a, b)).larray [0/1] tensor([[1, 2, 3], [0/1] [2, 3, 4]]) [1/1] tensor([[1, 2, 3], [1/1] [2, 3, 4]]) >>> a = ht.array([1, 2, 3], split=0) >>> b = ht.array([2, 3, 4], split=0) >>> ht.vstack((a, b)).larray [0/1] tensor([[1, 2], [0/1] [2, 3]]) [1/1] tensor([[3], [1/1] [4]]) >>> a = ht.array([[1], [2], [3]], split=0) >>> b = ht.array([[2], [3], [4]], split=0) >>> ht.vstack((a, b)).larray [0] tensor([[1], [0] [2], [0] [3]]) [1] tensor([[2], [1] [3], [1] [4]]) .. function:: copy(x: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Return a deep copy of the given object. :param x: Input array to be copied. :type x: DNDarray .. rubric:: Examples >>> a = ht.array([1, 2, 3]) >>> b = ht.copy(a) >>> b DNDarray([1, 2, 3], dtype=ht.int64, device=cpu:0, split=None) >>> a[0] = 4 >>> a DNDarray([4, 2, 3], dtype=ht.int64, device=cpu:0, split=None) >>> b DNDarray([1, 2, 3], dtype=ht.int64, device=cpu:0, split=None) .. function:: sanitize_memory_layout(x: torch.Tensor, order: str = 'C') -> torch.Tensor Return the given object with memory layout as defined below. The default memory distribution is assumed. :param x: Input data :type x: torch.Tensor :param order: Default is ``'C'`` as in C-like (row-major) memory layout. The array is stored first dimension first (rows first if ``ndim=2``). Alternative is ``'F'``, as in Fortran-like (column-major) memory layout. The array is stored last dimension first (columns first if ``ndim=2``). :type order: str, optional. .. function:: get_printoptions() -> dict Returns the currently configured printing options as key-value pairs. .. function:: global_printing() -> None For `DNDarray`s, the builtin `print` function will gather all of the data, format it then print it on ONLY rank 0. :rtype: None .. rubric:: Examples >>> x = ht.arange(15 * 5, dtype=ht.float).reshape((15, 5)).resplit(0) >>> print(x) [0] DNDarray([[ 0., 1., 2., 3., 4.], [ 5., 6., 7., 8., 9.], [10., 11., 12., 13., 14.], [15., 16., 17., 18., 19.], [20., 21., 22., 23., 24.], [25., 26., 27., 28., 29.], [30., 31., 32., 33., 34.], [35., 36., 37., 38., 39.], [40., 41., 42., 43., 44.], [45., 46., 47., 48., 49.], [50., 51., 52., 53., 54.], [55., 56., 57., 58., 59.], [60., 61., 62., 63., 64.], [65., 66., 67., 68., 69.], [70., 71., 72., 73., 74.]], dtype=ht.float32, device=cpu:0, split=0) .. function:: local_printing() -> None The builtin `print` function will now print the local PyTorch Tensor values for `DNDarrays` given as arguments. .. rubric:: Examples >>> x = ht.ht.arange(15 * 5, dtype=ht.float).reshape((15, 5)).resplit(0) >>> ht.local_printing() [0/2]Printing options set to LOCAL. DNDarrays will print the local PyTorch Tensors >>> print(x) [0/2] [[ 0., 1., 2., 3., 4.], [0/2] [ 5., 6., 7., 8., 9.], [0/2] [10., 11., 12., 13., 14.], [0/2] [15., 16., 17., 18., 19.], [0/2] [20., 21., 22., 23., 24.]] [1/2] [[25., 26., 27., 28., 29.], [1/2] [30., 31., 32., 33., 34.], [1/2] [35., 36., 37., 38., 39.], [1/2] [40., 41., 42., 43., 44.], [1/2] [45., 46., 47., 48., 49.]] [2/2] [[50., 51., 52., 53., 54.], [2/2] [55., 56., 57., 58., 59.], [2/2] [60., 61., 62., 63., 64.], [2/2] [65., 66., 67., 68., 69.], [2/2] [70., 71., 72., 73., 74.]] .. function:: print0(*args, **kwargs) -> None Wraps the builtin `print` function in such a way that it will only run the command on rank 0. If this is called with DNDarrays and local printing, only the data local to process 0 is printed. For more information see the examples. This function is also available as a builtin when importing heat. .. rubric:: Examples >>> x = ht.arange(15 * 5, dtype=ht.float).reshape((15, 5)).resplit(0) >>> # GLOBAL PRINTING >>> ht.print0(x) [0] DNDarray([[ 0., 1., 2., 3., 4.], [ 5., 6., 7., 8., 9.], [10., 11., 12., 13., 14.], [15., 16., 17., 18., 19.], [20., 21., 22., 23., 24.], [25., 26., 27., 28., 29.], [30., 31., 32., 33., 34.], [35., 36., 37., 38., 39.], [40., 41., 42., 43., 44.], [45., 46., 47., 48., 49.], [50., 51., 52., 53., 54.], [55., 56., 57., 58., 59.], [60., 61., 62., 63., 64.], [65., 66., 67., 68., 69.], [70., 71., 72., 73., 74.]], dtype=ht.float32, device=cpu:0, split=0) >>> ht.local_printing() [0/2] Printing options set to LOCAL. DNDarrays will print the local PyTorch Tensors >>> print0(x) [0/2] [[ 0., 1., 2., 3., 4.], [0/2] [ 5., 6., 7., 8., 9.], [0/2] [10., 11., 12., 13., 14.], [0/2] [15., 16., 17., 18., 19.], [0/2] [20., 21., 22., 23., 24.]], device: cpu:0, split: 0 .. function:: set_printoptions(precision=None, threshold=None, edgeitems=None, linewidth=None, profile=None, sci_mode=None) Configures the printing options. List of items shamelessly taken from NumPy and PyTorch (thanks guys!). :param precision: Number of digits of precision for floating point output (default=4). :type precision: int, optional :param threshold: Total number of array elements which trigger summarization rather than full `repr` string (default=1000). :type threshold: int, optional :param edgeitems: Number of array items in summary at beginning and end of each dimension (default=3). :type edgeitems: int, optional :param linewidth: The number of characters per line for the purpose of inserting line breaks (default = 80). :type linewidth: int, optional :param profile: Sane defaults for pretty printing. Can override with any of the above options. Can be any one of `default`, `short`, `full`. :type profile: str, optional :param sci_mode: Enable (True) or disable (False) scientific notation. If None (default) is specified, the value is automatically inferred by HeAT. :type sci_mode: bool, optional .. function:: eq(x, y) -> heat.core.dndarray.DNDarray Returns a :class:`~heat.core.dndarray.DNDarray` containing the results of element-wise comparision. Takes the first and second operand (scalar or :class:`~heat.core.dndarray.DNDarray`) whose elements are to be compared as argument. Returns False if the operands are not scalars or :class:`~heat.core.dndarray.DNDarray` :param x: The first operand involved in the comparison :type x: DNDarray or scalar :param y: The second operand involved in the comparison :type y: DNDarray or scalar .. rubric:: Examples >>> import heat as ht >>> x = ht.float32([[1, 2], [3, 4]]) >>> ht.eq(x, 3.0) DNDarray([[False, False], [ True, False]], dtype=ht.bool, device=cpu:0, split=None) >>> y = ht.float32([[2, 2], [2, 2]]) >>> ht.eq(x, y) DNDarray([[False, True], [False, False]], dtype=ht.bool, device=cpu:0, split=None) >>> ht.eq(x, slice(None)) False .. function:: equal(x: Union[heat.core.dndarray.DNDarray, float, int], y: Union[heat.core.dndarray.DNDarray, float, int]) -> bool Overall comparison of equality between two :class:`~heat.core.dndarray.DNDarray`. Returns ``True`` if two arrays have the same size and elements, and ``False`` otherwise. :param x: The first operand involved in the comparison :type x: DNDarray or scalar :param y: The second operand involved in the comparison :type y: DNDarray or scalar .. rubric:: Examples >>> import heat as ht >>> x = ht.float32([[1, 2], [3, 4]]) >>> ht.equal(x, ht.float32([[1, 2], [3, 4]])) True >>> y = ht.float32([[2, 2], [2, 2]]) >>> ht.equal(x, y) False >>> ht.equal(x, 3.0) False .. function:: ge(x: Union[heat.core.dndarray.DNDarray, float, int], y: Union[heat.core.dndarray.DNDarray, float, int]) -> heat.core.dndarray.DNDarray Returns a D:class:`~heat.core.dndarray.DNDarray` containing the results of element-wise rich greater than or equal comparison between values from operand ``x`` with respect to values of operand ``y`` (i.e. ``x>=y``), not commutative. Takes the first and second operand (scalar or :class:`~heat.core.dndarray.DNDarray`) whose elements are to be compared as argument. :param x: The first operand to be compared greater than or equal to second operand :type x: DNDarray or scalar :param y: The second operand to be compared less than or equal to first operand :type y: DNDarray or scalar .. rubric:: Examples >>> import heat as ht >>> x = ht.float32([[1, 2], [3, 4]]) >>> ht.ge(x, 3.0) DNDarray([[False, False], [ True, True]], dtype=ht.bool, device=cpu:0, split=None) >>> y = ht.float32([[2, 2], [2, 2]]) >>> ht.ge(x, y) DNDarray([[False, True], [ True, True]], dtype=ht.bool, device=cpu:0, split=None) .. function:: gt(x: Union[heat.core.dndarray.DNDarray, float, int], y: Union[heat.core.dndarray.DNDarray, float, int]) -> heat.core.dndarray.DNDarray Returns a :class:`~heat.core.dndarray.DNDarray` containing the results of element-wise rich greater than comparison between values from operand ``x`` with respect to values of operand ``y`` (i.e. ``x>y``), not commutative. Takes the first and second operand (scalar or :class:`~heat.core.dndarray.DNDarray`) whose elements are to be compared as argument. :param x: The first operand to be compared greater than second operand :type x: DNDarray or scalar :param y: The second operand to be compared less than first operand :type y: DNDarray or scalar .. rubric:: Examples >>> import heat as ht >>> x = ht.float32([[1, 2], [3, 4]]) >>> ht.gt(x, 3.0) DNDarray([[False, False], [False, True]], dtype=ht.bool, device=cpu:0, split=None) >>> y = ht.float32([[2, 2], [2, 2]]) >>> ht.gt(x, y) DNDarray([[False, False], [ True, True]], dtype=ht.bool, device=cpu:0, split=None) .. function:: le(x: Union[heat.core.dndarray.DNDarray, float, int], y: Union[heat.core.dndarray.DNDarray, float, int]) -> heat.core.dndarray.DNDarray Return a :class:`~heat.core.dndarray.DNDarray` containing the results of element-wise rich less than or equal comparison between values from operand ``x`` with respect to values of operand ``y`` (i.e. ``x<=y``), not commutative. Takes the first and second operand (scalar or :class:`~heat.core.dndarray.DNDarray`) whose elements are to be compared as argument. :param x: The first operand to be compared less than or equal to second operand :type x: DNDarray or scalar :param y: The second operand to be compared greater than or equal to first operand :type y: DNDarray or scalar .. rubric:: Examples >>> import heat as ht >>> x = ht.float32([[1, 2], [3, 4]]) >>> ht.le(x, 3.0) DNDarray([[ True, True], [ True, False]], dtype=ht.bool, device=cpu:0, split=None) >>> y = ht.float32([[2, 2], [2, 2]]) >>> ht.le(x, y) DNDarray([[ True, True], [False, False]], dtype=ht.bool, device=cpu:0, split=None) .. function:: lt(x: Union[heat.core.dndarray.DNDarray, float, int], y: Union[heat.core.dndarray.DNDarray, float, int]) -> heat.core.dndarray.DNDarray Returns a :class:`~heat.core.dndarray.DNDarray` containing the results of element-wise rich less than comparison between values from operand ``x`` with respect to values of operand ``y`` (i.e. ``x>> import heat as ht >>> x = ht.float32([[1, 2], [3, 4]]) >>> ht.lt(x, 3.0) DNDarray([[ True, True], [False, False]], dtype=ht.bool, device=cpu:0, split=None) >>> y = ht.float32([[2, 2], [2, 2]]) >>> ht.lt(x, y) DNDarray([[ True, False], [False, False]], dtype=ht.bool, device=cpu:0, split=None) .. function:: ne(x, y) -> heat.core.dndarray.DNDarray Returns a :class:`~heat.core.dndarray.DNDarray` containing the results of element-wise rich comparison of non-equality between values from two operands, commutative. Takes the first and second operand (scalar or :class:`~heat.core.dndarray.DNDarray`) whose elements are to be compared as argument. Returns True if the operands are not scalars or :class:`~heat.core.dndarray.DNDarray` :param x: The first operand involved in the comparison :type x: DNDarray or scalar :param y: The second operand involved in the comparison :type y: DNDarray or scalar .. rubric:: Examples >>> import heat as ht >>> x = ht.float32([[1, 2], [3, 4]]) >>> ht.ne(x, 3.0) DNDarray([[ True, True], [False, True]], dtype=ht.bool, device=cpu:0, split=None) >>> y = ht.float32([[2, 2], [2, 2]]) >>> ht.ne(x, y) DNDarray([[ True, False], [ True, True]], dtype=ht.bool, device=cpu:0, split=None) >>> ht.ne(x, slice(None)) True .. function:: abs(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None, dtype: Optional[Type[heat.core.types.datatype]] = None) -> heat.core.dndarray.DNDarray Returns :class:`~heat.core.dndarray.DNDarray` containing the elementwise abolute values of the input array ``x``. :param x: The array for which the compute the absolute value. :type x: DNDarray :param out: A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or ``None``, a freshly-allocated array is returned. :type out: DNDarray, optional :param dtype: Determines the data type of the output array. The values are cast to this type with potential loss of precision. :type dtype: datatype, optional :raises TypeError: If dtype is not a heat type. .. function:: absolute(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None, dtype: Optional[Type[heat.core.types.datatype]] = None) -> heat.core.dndarray.DNDarray Calculate the absolute value element-wise. :func:`abs` is a shorthand for this function. :param x: The array for which the compute the absolute value. :type x: DNDarray :param out: A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or ``None``, a freshly-allocated array is returned. :type out: DNDarray, optional :param dtype: Determines the data type of the output array. The values are cast to this type with potential loss of precision. :type dtype: datatype, optional .. function:: ceil(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Return the ceil of the input, element-wise. Result is a :class:`~heat.core.dndarray.DNDarray` of the same shape as ``x``. The ceil of the scalar ``x`` is the smallest integer i, such that ``i>=x``. It is often denoted as :math:`\lceil x \rceil`. :param x: The value for which to compute the ceiled values. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> import heat as ht >>> ht.ceil(ht.arange(-2.0, 2.0, 0.4)) DNDarray([-2., -1., -1., -0., -0., 0., 1., 1., 2., 2.], dtype=ht.float32, device=cpu:0, split=None) .. function:: clip(x: heat.core.dndarray.DNDarray, min, max, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Returns a :class:`~heat.core.dndarray.DNDarray` with the elements of this array, but where values ``a_max`` with ``a_max``. :param x: Array containing elements to clip. :type x: DNDarray :param min: Minimum value. If ``None``, clipping is not performed on lower interval edge. Not more than one of ``a_min`` and ``a_max`` may be ``None``. :type min: scalar or None :param max: Maximum value. If ``None``, clipping is not performed on upper interval edge. Not more than one of ``a_min`` and ``a_max`` may be None. :type max: scalar or None :param out: The results will be placed in this array. It may be the input array for in-place clipping. ``out`` must be of the right shape to hold the output. Its type is preserved. :type out: DNDarray, optional :raises ValueError: if either min or max is not set .. function:: fabs(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Calculate the absolute value element-wise and return floating-point class:`~heat.core.dndarray.DNDarray`. This function exists besides ``abs==absolute`` since it will be needed in case complex numbers will be introduced in the future. :param x: The array for which the compute the absolute value. :type x: DNDarray :param out: A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or ``None``, a freshly-allocated array is returned. :type out: DNDarray, optional .. function:: floor(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Return the floor of the input, element-wise. The floor of the scalar ``x`` is the largest integer i, such that ``i<=x``. It is often denoted as :math:`\lfloor x \rfloor`. :param x: The array for which to compute the floored values. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh :class:`~heat.core.dndarray.DNDarray` is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> import heat as ht >>> ht.floor(ht.arange(-2.0, 2.0, 0.4)) DNDarray([-2., -2., -2., -1., -1., 0., 0., 0., 1., 1.], dtype=ht.float32, device=cpu:0, split=None) .. function:: modf(x: heat.core.dndarray.DNDarray, out: Optional[Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray]] = None) -> Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] Return the fractional and integral parts of a :class:`~heat.core.dndarray.DNDarray`, element-wise. The fractional and integral parts are negative if the given number is negative. :param x: Input array :type x: DNDarray :param out: A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or ``None``, a freshly-allocated array is returned. :type out: Tuple[DNDarray, DNDarray], optional :raises TypeError: if ``x`` is not a :class:`~heat.core.dndarray.DNDarray` :raises TypeError: if ``out`` is not None or a tuple of :class:`~heat.core.dndarray.DNDarray` :raises ValueError: if ``out`` is a tuple of length unqual 2 .. rubric:: Examples >>> import heat as ht >>> ht.modf(ht.arange(-2.0, 2.0, 0.4)) (DNDarray([ 0.0000, -0.6000, -0.2000, -0.8000, -0.4000, 0.0000, 0.4000, 0.8000, 0.2000, 0.6000], dtype=ht.float32, device=cpu:0, split=None), DNDarray([-2., -1., -1., -0., -0., 0., 0., 0., 1., 1.], dtype=ht.float32, device=cpu:0, split=None)) .. function:: round(x: heat.core.dndarray.DNDarray, decimals: int = 0, out: Optional[heat.core.dndarray.DNDarray] = None, dtype: Optional[Type[heat.core.types.datatype]] = None) -> heat.core.dndarray.DNDarray Calculate the rounded value element-wise. :param x: The array for which the compute the rounded value. :type x: DNDarray :param decimals: Number of decimal places to round to. If decimals is negative, it specifies the number of positions to the left of the decimal point. :type decimals: int, optional :param out: A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or ``None``, a freshly-allocated array is returned. :type out: DNDarray, optional :param dtype: Determines the data type of the output array. The values are cast to this type with potential loss of precision. :type dtype: datatype, optional :raises TypeError: if dtype is not a heat data type .. rubric:: Examples >>> import heat as ht >>> ht.round(ht.arange(-2.0, 2.0, 0.4)) DNDarray([-2., -2., -1., -1., -0., 0., 0., 1., 1., 2.], dtype=ht.float32, device=cpu:0, split=None) .. function:: sgn(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Returns an indication of the sign of a number, element-wise. The definition for complex values is equivalent to :math:`x / |x|`. :param x: Input array :type x: DNDarray :param out: A location in which to store the results. :type out: DNDarray, optional .. seealso:: :func:`sign` Equivalent function on non-complex arrays. The definition for complex values is equivalent to :math:`x / \sqrt{x \cdot x}` .. rubric:: Examples >>> a = ht.array([-1, -0.5, 0, 0.5, 1]) >>> ht.sign(a) DNDarray([-1., -1., 0., 1., 1.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.sgn(ht.array([5 - 2j, 3 + 4j])) DNDarray([(0.9284766912460327-0.3713906705379486j), (0.6000000238418579+0.800000011920929j)], dtype=ht.complex64, device=cpu:0, split=None) .. function:: sign(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Returns an indication of the sign of a number, element-wise. The definition for complex values is equivalent to :math:`x / \sqrt{x \cdot x}`. :param x: Input array :type x: DNDarray :param out: A location in which to store the results. :type out: DNDarray, optional .. seealso:: :func:`sgn` Equivalent function on non-complex arrays. The definition for complex values is equivalent to :math:`x / |x|`. .. rubric:: Examples >>> a = ht.array([-1, -0.5, 0, 0.5, 1]) >>> ht.sign(a) DNDarray([-1., -1., 0., 1., 1.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.sign(ht.array([5 - 2j, 3 + 4j])) DNDarray([(1+0j), (1+0j)], dtype=ht.complex64, device=cpu:0, split=None) .. function:: trunc(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Return the trunc of the input, element-wise. The truncated value of the scalar ``x`` is the nearest integer ``i`` which is closer to zero than ``x`` is. In short, the fractional part of the signed number ``x`` is discarded. :param x: The array for which to compute the trunced values. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> import heat as ht >>> ht.trunc(ht.arange(-2.0, 2.0, 0.4)) DNDarray([-2., -1., -1., -0., -0., 0., 0., 0., 1., 1.], dtype=ht.float32, device=cpu:0, split=None) .. function:: sanitize_distribution(*args: heat.core.dndarray.DNDarray, target: heat.core.dndarray.DNDarray, diff_map: torch.Tensor = None) -> Union[heat.core.dndarray.DNDarray, Tuple(DNDarray)] Distribute every `arg` according to `target.lshape_map` or, if provided, `diff_map`. After this sanitation, the lshapes are compatible along the split dimension. `Args` can contain non-distributed DNDarrays, they will be split afterwards, if `target` is split. :param args: Dndarrays to be distributed :type args: DNDarray :param target: Dndarray used to sanitize the metadata and to, if diff_map is not given, determine the resulting distribution. :type target: DNDarray :param diff_map: Different lshape_map. Overwrites the distribution of the target array. Used in cases when the target array does not correspond to the actually wanted distribution, e.g. because it only contains a single element along the split axis and gets broadcast. :type diff_map: torch.Tensor (optional) :raises TypeError: When an argument is not a ``DNDarray`` or ``None``. :raises ValueError: When the split-axes or sizes along the split-axis do not match. .. seealso:: :func:`~heat.core.dndarray.create_lshape_map` Function to create the lshape_map. .. function:: sanitize_in(x: Any) Verify that input object is ``DNDarray``. :param x: Input object :type x: Any :raises TypeError: When ``x`` is not a ``DNDarray``. .. function:: sanitize_infinity(x: Union[heat.core.dndarray.DNDarray, torch.Tensor]) -> Union[int, float] Returns largest possible value for the ``dtype`` of the input array. :param x: Input object. :type x: Union[DNDarray, torch.Tensor] .. function:: sanitize_in_tensor(x: Any) Verify that input object is ``torch.Tensor``. :param x: Input object. :type x: Any :raises TypeError: When ``x`` is not a ``torch.Tensor``. .. function:: sanitize_lshape(array: heat.core.dndarray.DNDarray, tensor: torch.Tensor) Verify shape consistency when manipulating process-local arrays. :param array: the original, potentially distributed ``DNDarray`` :type array: DNDarray :param tensor: process-local data meant to replace ``array.larray`` :type tensor: torch.Tensor :raises ValueError: if shape of local ``torch.Tensor`` is inconsistent with global ``DNDarray``. .. function:: sanitize_out(out: heat.core.dndarray.DNDarray, output_shape: Tuple, output_split: int, output_device: str, output_comm: heat.core.communication.Communication = None) Validate output buffer ``out``. :param out: the `out` buffer where the result of some operation will be stored :type out: DNDarray :param output_shape: the calculated shape returned by the operation :type output_shape: Tuple :param output_split: the calculated split axis returned by the operation :type output_split: Int :param output_device: "cpu" or "gpu" as per location of data :type output_device: Str :param output_comm: Communication object of the result of the operation :type output_comm: Communication :raises TypeError: if ``out`` is not a ``DNDarray``. :raises ValueError: if shape, split direction, or device of the output buffer ``out`` do not match the operation result. .. function:: sanitize_sequence(seq: Union[Sequence[int, Ellipsis], Sequence[float, Ellipsis], heat.core.dndarray.DNDarray, torch.Tensor]) -> List Check if sequence is valid, return list. :param seq: Input sequence. :type seq: Union[Sequence[int, ...], Sequence[float, ...], DNDarray, torch.Tensor] :raises TypeError: if ``seq`` is neither a list nor a tuple .. function:: scalar_to_1d(x: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Turn a scalar ``DNDarray`` into a 1-D ``DNDarray`` with 1 element. :param x: with `x.ndim = 0` :type x: DNDarray .. function:: argmax(x: heat.core.dndarray.DNDarray, axis: Optional[int] = None, out: Optional[heat.core.dndarray.DNDarray] = None, **kwargs: object) -> heat.core.dndarray.DNDarray Returns an array of the indices of the maximum values along an axis. It has the same shape as ``x.shape`` with the dimension along axis removed. :param x: Input array. :type x: DNDarray :param axis: By default, the index is into the flattened array, otherwise along the specified axis. :type axis: int, optional :param out: If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype. :type out: DNDarray, optional. :param \*\*kwargs: Extra keyword arguments .. rubric:: Examples >>> a = ht.random.randn(3, 3) >>> a DNDarray([[ 1.0661, 0.7036, -2.0908], [-0.7534, -0.4986, -0.7751], [-0.4815, 1.9436, 0.6400]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.argmax(a) DNDarray([7], dtype=ht.int64, device=cpu:0, split=None) >>> ht.argmax(a, axis=0) DNDarray([0, 2, 2], dtype=ht.int64, device=cpu:0, split=None) >>> ht.argmax(a, axis=1) DNDarray([0, 1, 1], dtype=ht.int64, device=cpu:0, split=None) .. function:: argmin(x: heat.core.dndarray.DNDarray, axis: Optional[int] = None, out: Optional[heat.core.dndarray.DNDarray] = None, **kwargs: object) -> heat.core.dndarray.DNDarray Returns an array of the indices of the minimum values along an axis. It has the same shape as ``x.shape`` with the dimension along axis removed. :param x: Input array. :type x: DNDarray :param axis: By default, the index is into the flattened array, otherwise along the specified axis. :type axis: int, optional :param out: Issue #100 If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype. :type out: DNDarray, optional :param \*\*kwargs: Extra keyword arguments .. rubric:: Examples >>> a = ht.random.randn(3, 3) >>> a DNDarray([[ 1.0661, 0.7036, -2.0908], [-0.7534, -0.4986, -0.7751], [-0.4815, 1.9436, 0.6400]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.argmin(a) DNDarray([2], dtype=ht.int64, device=cpu:0, split=None) >>> ht.argmin(a, axis=0) DNDarray([1, 1, 0], dtype=ht.int64, device=cpu:0, split=None) >>> ht.argmin(a, axis=1) DNDarray([2, 2, 0], dtype=ht.int64, device=cpu:0, split=None) .. function:: average(x: heat.core.dndarray.DNDarray, axis: Optional[Union[int, Tuple[int, Ellipsis]]] = None, weights: Optional[heat.core.dndarray.DNDarray] = None, returned: bool = False) -> Union[heat.core.dndarray.DNDarray, Tuple[heat.core.dndarray.DNDarray, Ellipsis]] Compute the weighted average along the specified axis. If ``returned=True``, return a tuple with the average as the first element and the sum of the weights as the second element. ``sum_of_weights`` is of the same type as ``average``. :param x: Array containing data to be averaged. :type x: DNDarray :param axis: Axis or axes along which to average ``x``. The default, ``axis=None``, will average over all of the elements of the input array. If axis is negative it counts from the last to the first axis. #TODO Issue #351: If axis is a tuple of ints, averaging is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before. :type axis: None or int or Tuple[int,...], optional :param weights: An array of weights associated with the values in ``x``. Each value in ``x`` contributes to the average according to its associated weight. The weights array can either be 1D (in which case its length must be the size of ``x`` along the given axis) or of the same shape as ``x``. If ``weights=None``, then all data in ``x`` are assumed to have a weight equal to one, the result is equivalent to :func:`mean`. :type weights: DNDarray, optional :param returned: If ``True``, the tuple ``(average, sum_of_weights)`` is returned, otherwise only the average is returned. If ``weights=None``, ``sum_of_weights`` is equivalent to the number of elements over which the average is taken. :type returned: bool, optional :raises ZeroDivisionError: When all weights along axis are zero. :raises TypeError: When the length of 1D weights is not the same as the shape of ``x`` along axis. .. rubric:: Examples >>> data = ht.arange(1, 5, dtype=float) >>> data DNDarray([1., 2., 3., 4.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.average(data) DNDarray(2.5000, dtype=ht.float32, device=cpu:0, split=None) >>> ht.average(ht.arange(1, 11, dtype=float), weights=ht.arange(10, 0, -1)) DNDarray([4.], dtype=ht.float64, device=cpu:0, split=None) >>> data = ht.array([[0, 1], [2, 3], [4, 5]], dtype=float, split=1) >>> weights = ht.array([1.0 / 4, 3.0 / 4]) >>> ht.average(data, axis=1, weights=weights) DNDarray([0.7500, 2.7500, 4.7500], dtype=ht.float32, device=cpu:0, split=None) >>> ht.average(data, weights=weights) Traceback (most recent call last): ... TypeError: Axis must be specified when shapes of x and weights differ. .. function:: bincount(x: heat.core.dndarray.DNDarray, weights: Optional[heat.core.dndarray.DNDarray] = None, minlength: int = 0) -> heat.core.dndarray.DNDarray Count number of occurrences of each value in array of non-negative ints. Return a non-distributed ``DNDarray`` of length `max(x) + 1` if input is non-empty, else 0. The number of bins (size 1) is one larger than the largest value in `x` unless `x` is empty, in which case the result is a tensor of size 0. If `minlength` is specified, the number of bins is at least `minlength` and if `x` is empty, then the result is tensor of size `minlength` filled with zeros. If `n` is the value at position `i`, `out[n] += weights[i]` if weights is specified else `out[n] += 1`. :param x: 1-dimensional, non-negative ints :type x: DNDarray :param weights: Weight for each value in the input tensor. Array of the same shape as x. Same split as `x`. :type weights: DNDarray, optional :param minlength: Minimum number of bins :type minlength: int, non-negative, optional :raises ValueError: If `x` and `weights` don't have the same distribution. .. rubric:: Examples >>> ht.bincount(ht.arange(5)) DNDarray([1, 1, 1, 1, 1], dtype=ht.int64, device=cpu:0, split=None) >>> ht.bincount(ht.array([0, 1, 3, 2, 1]), weights=ht.array([0, 0.5, 1, 1.5, 2])) DNDarray([0.0000, 2.5000, 1.5000, 1.0000], dtype=ht.float32, device=cpu:0, split=None) .. function:: bucketize(input: heat.core.dndarray.DNDarray, boundaries: Union[heat.core.dndarray.DNDarray, torch.Tensor], out_int32: bool = False, right: bool = False, out: heat.core.dndarray.DNDarray = None) -> heat.core.dndarray.DNDarray Returns the indices of the buckets to which each value in the input belongs, where the boundaries of the buckets are set by boundaries. :param input: The input array. :type input: DNDarray :param boundaries: monotonically increasing sequence defining the bucket boundaries, 1-dimensional, not distributed :type boundaries: DNDarray or torch.Tensor :param out_int32: set the dtype of the output to ``ht.int64`` (`False`) or ``ht.int32`` (True) :type out_int32: bool, optional :param right: indicate whether the buckets include the right (`False`) or left (`True`) boundaries, see Notes. :type right: bool, optional :param out: The output array, must be the shame shape and split as the input array. :type out: DNDarray, optional .. rubric:: Notes This function uses the PyTorch's setting for ``right``: ===== ==================================== right returned index `i` satisfies ===== ==================================== False boundaries[i-1] < x <= boundaries[i] True boundaries[i-1] <= x < boundaries[i] ===== ==================================== :raises RuntimeError: If `boundaries` is distributed. .. seealso:: :py:obj:`digitize` NumPy-like version of this function. .. rubric:: Examples >>> boundaries = ht.array([1, 3, 5, 7, 9]) >>> v = ht.array([[3, 6, 9], [3, 6, 9]]) >>> ht.bucketize(v, boundaries) DNDarray([[1, 3, 4], [1, 3, 4]], dtype=ht.int64, device=cpu:0, split=None) >>> ht.bucketize(v, boundaries, right=True) DNDarray([[2, 3, 5], [2, 3, 5]], dtype=ht.int64, device=cpu:0, split=None) .. function:: cov(m: heat.core.dndarray.DNDarray, y: Optional[heat.core.dndarray.DNDarray] = None, rowvar: bool = True, bias: bool = False, ddof: Optional[int] = None) -> heat.core.dndarray.DNDarray Estimate the covariance matrix of some data, m. For more imformation on the algorithm please see the numpy function of the same name :param m: A 1-D or 2-D array containing multiple variables and observations. Each row of ``m`` represents a variable, and each column a single observation of all those variables. :type m: DNDarray :param y: An additional set of variables and observations. ``y`` has the same form as that of ``m``. :type y: DNDarray, optional :param rowvar: If ``True`` (default), then each row represents a variable, with observations in the columns. Otherwise, the relationship is transposed: each column represents a variable, while the rows contain observations. :type rowvar: bool, optional :param bias: Default normalization (``False``) is by (N - 1), where N is the number of observations given (unbiased estimate). If ``True``, then normalization is by N. These values can be overridden by using the keyword ``ddof`` in numpy versions >= 1.5. :type bias: bool, optional :param ddof: If not ``None`` the default value implied by ``bias`` is overridden. Note that ``ddof=1`` will return the unbiased estimate and ``ddof=0`` will return the simple average. :type ddof: int, optional .. function:: digitize(x: heat.core.dndarray.DNDarray, bins: Union[heat.core.dndarray.DNDarray, torch.Tensor], right: bool = False) -> heat.core.dndarray.DNDarray Return the indices of the bins to which each value in the input array `x` belongs. If values in `x` are beyond the bounds of bins, 0 or len(bins) is returned as appropriate. :param x: The input array :type x: DNDarray :param bins: A 1-dimensional array containing a monotonic sequence describing the bin boundaries, not distributed. :type bins: DNDarray or torch.Tensor :param right: Indicating whether the intervals include the right or the left bin edge, see Notes. :type right: bool, optional .. rubric:: Notes This function uses NumPy's setting for ``right``: ===== ============= ============================ right order of bins returned index `i` satisfies ===== ============= ============================ False increasing bins[i-1] <= x < bins[i] True increasing bins[i-1] < x <= bins[i] False decreasing bins[i-1] > x >= bins[i] True decreasing bins[i-1] >= x > bins[i] ===== ============= ============================ :raises RuntimeError: If `bins` is distributed. .. seealso:: :py:obj:`bucketize` PyTorch-like version of this function. .. rubric:: Examples >>> x = ht.array([1.2, 10.0, 12.4, 15.5, 20.0]) >>> bins = ht.array([0, 5, 10, 15, 20]) >>> ht.digitize(x, bins, right=True) DNDarray([1, 2, 3, 4, 4], dtype=ht.int64, device=cpu:0, split=None) >>> ht.digitize(x, bins, right=False) DNDarray([1, 3, 3, 4, 5], dtype=ht.int64, device=cpu:0, split=None) .. function:: histc(input: heat.core.dndarray.DNDarray, bins: int = 100, min: int = 0, max: int = 0, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Return the histogram of a DNDarray. The elements are sorted into equal width bins between min and max. If min and max are both equal, the minimum and maximum values of the data are used. Elements lower than min and higher than max are ignored. :param input: the input array, must be of float type :type input: DNDarray :param bins: number of histogram bins :type bins: int, optional :param min: lower end of the range (inclusive) :type min: int, optional :param max: upper end of the range (inclusive) :type max: int, optional :param out: the output tensor, same dtype as input :type out: DNDarray, optional .. rubric:: Examples >>> ht.histc(ht.array([1.0, 2, 1]), bins=4, min=0, max=3) DNDarray([0., 2., 1., 0.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.histc(ht.arange(10, dtype=ht.float64, split=0), bins=10) DNDarray([1., 1., 1., 1., 1., 1., 1., 1., 1., 1.], dtype=ht.float64, device=cpu:0, split=None) .. function:: histogram(a: heat.core.dndarray.DNDarray, bins: int = 10, range: Tuple[int, int] = (0, 0), normed: Optional[bool] = None, weights: Optional[heat.core.dndarray.DNDarray] = None, density: Optional[bool] = None) -> heat.core.dndarray.DNDarray Compute the histogram of a DNDarray. :param a: the input array, must be of float type :type a: DNDarray :param bins: number of histogram bins :type bins: int, optional :param range: lower and upper end of the bins. If not provided, range is simply (a.min(), a.max()). :type range: Tuple[int,int], optional :param normed: Deprecated since NumPy version 1.6. TODO: remove. :type normed: bool, optional :param weights: array of weights. Not implemented yet. :type weights: DNDarray, optional :param density: Not implemented yet. :type density: bool, optional .. rubric:: Notes This is a wrapper function of :func:`histc` for some basic compatibility with the NumPy API. .. seealso:: :func:`histc` .. function:: kurtosis(x: heat.core.dndarray.DNDarray, axis: Optional[int] = None, unbiased: bool = True, Fischer: bool = True) -> heat.core.dndarray.DNDarray Compute the kurtosis (Fisher or Pearson) of a dataset. Kurtosis is the fourth central moment divided by the square of the variance. If Fisher’s definition is used, then 3.0 is subtracted from the result to give 0.0 for a normal distribution. If unbiased is True (defualt) then the kurtosis is calculated using k statistics to eliminate bias coming from biased moment estimators :param x: Input array :type x: ht.DNDarray :param axis: Axis along which skewness is calculated, Default is to compute over the whole array `x` :type axis: NoneType or Int :param unbiased: if True (default) the calculations are corrected for bias :type unbiased: Bool :param Fischer: Whether use Fischer's definition or not. If true 3. is subtracted from the result. :type Fischer: bool .. warning:: UserWarning: Dependent on the axis given and the split configuration, a UserWarning may be thrown during this function as data is transferred between processes. .. function:: max(x: heat.core.dndarray.DNDarray, axis: Optional[Union[int, Tuple[int, Ellipsis]]] = None, out: Optional[heat.core.dndarray.DNDarray] = None, keepdims: Optional[bool] = None) -> heat.core.dndarray.DNDarray Return the maximum along a given axis. :param x: Input array. :type x: DNDarray :param axis: Axis or axes along which to operate. By default, flattened input is used. If this is a tuple of ints, the maximum is selected over multiple axes, instead of a single axis or all the axes as before. :type axis: None or int or Tuple[int,...], optional :param out: Tuple of two output arrays ``(max, max_indices)``. Must be of the same shape and buffer length as the expected output. The minimum value of an output element. Must be present to allow computation on empty slice. :type out: DNDarray, optional :param keepdims: If this is set to ``True``, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original array. :type keepdims: bool, optional .. rubric:: Examples >>> a = ht.float32([ [1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11, 12] ]) >>> ht.max(a) DNDarray([12.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.max(a, axis=0) DNDarray([10., 11., 12.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.max(a, axis=1) DNDarray([ 3., 6., 9., 12.], dtype=ht.float32, device=cpu:0, split=None) .. function:: maximum(x1: heat.core.dndarray.DNDarray, x2: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compares two ``DNDarrays`` and returns a new :class:`~heat.core.dndarray.DNDarray` containing the element-wise maxima. The ``DNDarrays`` must have the same shape, or shapes that can be broadcast to a single shape. For broadcasting semantics, see: https://pytorch.org/docs/stable/notes/broadcasting.html If one of the elements being compared is ``NaN``, then that element is returned. TODO: Check this: If both elements are NaNs then the first is returned. The latter distinction is important for complex NaNs, which are defined as at least one of the real or imaginary parts being ``NaN``. The net effect is that NaNs are propagated. :param x1: The first array containing the elements to be compared. :type x1: DNDarray :param x2: The second array containing the elements to be compared. :type x2: DNDarray :param out: A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or ``None``, a freshly-allocated array is returned. :type out: DNDarray, optional .. rubric:: Examples >>> import heat as ht >>> a = ht.random.randn(3, 4) >>> a DNDarray([[ 0.2701, -0.6993, 1.2197, 0.0579], [ 0.6815, 0.4722, -0.3947, -0.3030], [ 1.0101, -1.2460, -1.3953, -0.6879]], dtype=ht.float32, device=cpu:0, split=None) >>> b = ht.random.randn(3, 4) >>> b DNDarray([[ 0.9664, 0.6159, -0.8555, 0.8204], [-1.2200, -0.0759, 0.0437, 0.4700], [ 1.2271, 1.0530, 0.1095, 0.8386]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.maximum(a, b) DNDarray([[0.9664, 0.6159, 1.2197, 0.8204], [0.6815, 0.4722, 0.0437, 0.4700], [1.2271, 1.0530, 0.1095, 0.8386]], dtype=ht.float32, device=cpu:0, split=None) >>> c = ht.random.randn(1, 4) >>> c DNDarray([[-0.5363, -0.9765, 0.4099, 0.3520]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.maximum(a, c) DNDarray([[ 0.2701, -0.6993, 1.2197, 0.3520], [ 0.6815, 0.4722, 0.4099, 0.3520], [ 1.0101, -0.9765, 0.4099, 0.3520]], dtype=ht.float32, device=cpu:0, split=None) >>> d = ht.random.randn(3, 4, 5) >>> ht.maximum(a, d) ValueError: operands could not be broadcast, input shapes (3, 4) (3, 4, 5) .. function:: mean(x: heat.core.dndarray.DNDarray, axis: Optional[Union[int, Tuple[int, Ellipsis]]] = None) -> heat.core.dndarray.DNDarray Calculates and returns the mean of a ``DNDarray``. If an axis is given, the mean will be taken in that direction. :param x: Values for which the mean is calculated for. The dtype of ``x`` must be a float :type x: DNDarray :param axis: Axis which the mean is taken in. Default ``None`` calculates mean of all data items. :type axis: None or int or iterable .. rubric:: Notes Split semantics when axis is an integer: - if ``axis==x.split``, then ``mean(x).split=None`` - if ``axis>split``, then ``mean(x).split=x.split`` - if ``axis>> a = ht.random.randn(1, 3) >>> a DNDarray([[-0.1164, 1.0446, -0.4093]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.mean(a) DNDarray(0.1730, dtype=ht.float32, device=cpu:0, split=None) >>> a = ht.random.randn(4, 4) >>> a DNDarray([[-1.0585, 0.7541, -1.1011, 0.5009], [-1.3575, 0.3344, 0.4506, 0.7379], [-0.4337, -0.6516, -1.3690, -0.8772], [ 0.6929, -1.0989, -0.9961, 0.3547]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.mean(a, 1) DNDarray([-0.2262, 0.0413, -0.8328, -0.2619], dtype=ht.float32, device=cpu:0, split=None) >>> ht.mean(a, 0) DNDarray([-0.5392, -0.1655, -0.7539, 0.1791], dtype=ht.float32, device=cpu:0, split=None) >>> a = ht.random.randn(4, 4) >>> a DNDarray([[-0.1441, 0.5016, 0.8907, 0.6318], [-1.1690, -1.2657, 1.4840, -0.1014], [ 0.4133, 1.4168, 1.3499, 1.0340], [-0.9236, -0.7535, -0.2466, -0.9703]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.mean(a, (0, 1)) DNDarray(0.1342, dtype=ht.float32, device=cpu:0, split=None) .. function:: median(x: heat.core.dndarray.DNDarray, axis: Optional[int] = None, keepdims: bool = False, sketched: bool = False, sketch_size: Optional[float] = 1.0 / MPI.COMM_WORLD.size) -> heat.core.dndarray.DNDarray Compute the median of the data along the specified axis. Returns the median of the ``DNDarray`` elements. Per default, the "true" median of the entire data set is computed; however, the argument `sketched` allows to switch to a faster but less accurate version that computes the median only on behalf of a random subset of the data set ("sketch"). :param x: Input tensor :type x: DNDarray :param axis: Axis along which the median is computed. Default is ``None``, i.e., the median is computed along a flattened version of the ``DNDarray``. :type axis: int, or None, optional :param keepdims: If True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result can broadcast correctly against the original array ``a``. :type keepdims: bool, optional :param sketched: If True, the median is computed on a random subset of the data set ("sketch"). This is faster but less accurate. Default is False. The size of the sketch is controlled by the argument `sketch_size`. :type sketched: bool, optional :param sketch_size: The size of the sketch as a fraction of the data set size. Default is `1./n_proc` where `n_proc` is the number of MPI processes, e.g. `n_proc = MPI.COMM_WORLD.size`. Must be in the range (0, 1). Ignored for sketched = False. :type sketch_size: float, optional .. function:: min(x: heat.core.dndarray.DNDarray, axis: Optional[Union[int, Tuple[int, Ellipsis]]] = None, out: Optional[heat.core.dndarray.DNDarray] = None, keepdims: Optional[bool] = None) -> heat.core.dndarray.DNDarray Return the minimum along a given axis. :param x: Input array. :type x: DNDarray :param axis: Axis or axes along which to operate. By default, flattened input is used. If this is a tuple of ints, the minimum is selected over multiple axes, instead of a single axis or all the axes as before. :type axis: None or int or Tuple[int,...] :param out: Tuple of two output arrays ``(min, min_indices)``. Must be of the same shape and buffer length as the expected output. The maximum value of an output element. Must be present to allow computation on empty slice. :type out: Tuple[DNDarray,DNDarray], optional :param keepdims: If this is set to ``True``, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original array. :type keepdims: bool, optional .. rubric:: Examples >>> a = ht.float32([ [1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11, 12] ]) >>> ht.min(a) DNDarray([1.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.min(a, axis=0) DNDarray([1., 2., 3.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.min(a, axis=1) DNDarray([ 1., 4., 7., 10.], dtype=ht.float32, device=cpu:0, split=None) .. function:: minimum(x1: heat.core.dndarray.DNDarray, x2: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compares two ``DNDarrays`` and returns a new :class:`~heat.core.dndarray.DNDarray` containing the element-wise minima. If one of the elements being compared is ``NaN``, then that element is returned. They must have the same shape, or shapes that can be broadcast to a single shape. For broadcasting semantics, see: https://pytorch.org/docs/stable/notes/broadcasting.html TODO: Check this: If both elements are NaNs then the first is returned. The latter distinction is important for complex NaNs, which are defined as at least one of the real or imaginary parts being ``NaN``. The net effect is that NaNs are propagated. :param x1: The first array containing the elements to be compared. :type x1: DNDarray :param x2: The second array containing the elements to be compared. :type x2: DNDarray :param out: A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or ``None``, a freshly-allocated array is returned. :type out: DNDarray, optional .. rubric:: Examples >>> import heat as ht >>> a = ht.random.randn(3, 4) >>> a DNDarray([[-0.5462, 0.0079, 1.2828, 1.4980], [ 0.6503, -1.1069, 1.2131, 1.4003], [-0.3203, -0.2318, 1.0388, 0.4439]], dtype=ht.float32, device=cpu:0, split=None) >>> b = ht.random.randn(3, 4) >>> b DNDarray([[ 1.8505, 2.3055, -0.2825, -1.4718], [-0.3684, 1.6866, -0.8570, -0.4779], [ 1.0532, 0.3775, -0.8669, -1.7275]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.minimum(a, b) DNDarray([[-0.5462, 0.0079, -0.2825, -1.4718], [-0.3684, -1.1069, -0.8570, -0.4779], [-0.3203, -0.2318, -0.8669, -1.7275]], dtype=ht.float32, device=cpu:0, split=None) >>> c = ht.random.randn(1, 4) >>> c DNDarray([[-1.4358, 1.2914, -0.6042, -1.4009]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.minimum(a, c) DNDarray([[-1.4358, 0.0079, -0.6042, -1.4009], [-1.4358, -1.1069, -0.6042, -1.4009], [-1.4358, -0.2318, -0.6042, -1.4009]], dtype=ht.float32, device=cpu:0, split=None) >>> d = ht.random.randn(3, 4, 5) >>> ht.minimum(a, d) ValueError: operands could not be broadcast, input shapes (3, 4) (3, 4, 5) .. function:: percentile(x: heat.core.dndarray.DNDarray, q: Union[heat.core.dndarray.DNDarray, int, float, Tuple, List], axis: Optional[Union[int, Tuple[int, Ellipsis]]] = None, out: Optional[heat.core.dndarray.DNDarray] = None, interpolation: str = 'linear', keepdims: bool = False, sketched: bool = False, sketch_size: Optional[float] = 1.0 / MPI.COMM_WORLD.size) -> heat.core.dndarray.DNDarray Compute the q-th percentile of the data along the specified axis/axes. Returns the q-th percentile(s) of the ``DNDarray`` elements. Per default, the "true" percentile(s) of the entire data set are computed; however, the argument `sketched` allows to switch to a faster but inaccurate version that computes the percentile only on behalf of a random subset of the data set ("sketch"). :param x: Input tensor :type x: DNDarray :param q: Percentile or sequence of percentiles to compute. Must belong to the interval [0, 100]. :type q: DNDarray, scalar, or list of scalars :param axis: Axis (if int) or axes (if tuple) along which the percentiles are computed. Default is None, corresponds to calculating the percentile over the flattened array. :type axis: int, tuple of ints, or None, optional :param out: Output buffer. :type out: DNDarray, optional. :param interpolation: Interpolation method to use when the desired percentile lies between two data points :math:`i < j`. Can be one of: - ‘linear’: :math:`i + (j - i) \cdot fraction`, where `fraction` is the fractional part of the index surrounded by `i` and `j`. - ‘lower’: `i`. - ‘higher’: `j`. - ‘nearest’: `i` or `j`, whichever is nearest. - ‘midpoint’: :math:`(i + j) / 2`. :type interpolation: str, optional :param keepdims: If True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result can broadcast correctly against the original array x. :type keepdims: bool, optional :param sketched: If False (default), the entire data is used and no sketching is performed. If True, a fraction of the data to use for estimating the percentile. The fraction is determined by `sketch_size`. :type sketched: bool, optional :param sketch_size: The fraction of the data to use for estimating the percentile; needs to be strictly between 0 and 1. The default is `1/nprocs`, where `nprocs` is the number of MPI processes involved in the calculation, i.e., roughly the portion of the data that is anyway processed on a single process. Ignored for sketched = False. :type sketch_size: float, optional .. function:: ptp(x: heat.core.dndarray.DNDarray, axis: Optional[Union[int, Tuple[int, Ellipsis]]] = None, out: Optional[heat.core.dndarray.DNDarray] = None, keepdims: bool = False) -> heat.core.dndarray.DNDarray Range of values (maximum - minimum) along a given axis. :param x: Input array. :type x: ht.DNDarray :param axis: Axis or axes along which to operate. By default, flattened input is used. If this is a tuple of ints, the ptp is selected over multiple axes, instead of a single axis or all the axes as before. :type axis: None or int or Tuple[int,...], optional :param out: Output array to place the result. :type out: DNDarray, optional :param keepdims: If this is set to ``True``, the axes which are reduced are left in the result as dimensions with size one. :type keepdims: bool, optional :returns: **ptp** -- An array with the same shape as `x`, with the specified axis removed. If `keepdims` is True, the reduced axes are left in the result as dimensions with size one. :rtype: ht.DNDarray .. rubric:: Examples >>> a = ht.array([[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11, 12]], dtype=ht.float32) >>> ht.ptp(a) DNDarray([11.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.ptp(a, axis=0) DNDarray([9., 9., 9.], dtype=ht.float32, device=cpu:0, split=None) >>> ht.ptp(a, axis=1) DNDarray([2., 2., 2., 2.], dtype=ht.float32, device=cpu:0, split=None) .. function:: skew(x: heat.core.dndarray.DNDarray, axis: int = None, unbiased: bool = True) -> heat.core.dndarray.DNDarray Compute the sample skewness of a data set. :param x: Input array :type x: ht.DNDarray :param axis: Axis along which skewness is calculated, Default is to compute over the whole array `x` :type axis: NoneType or Int :param unbiased: if True (default) the calculations are corrected for bias :type unbiased: Bool .. warning:: UserWarning: Dependent on the axis given and the split configuration, a UserWarning may be thrown during this function as data is transferred between processes. .. function:: std(x: heat.core.dndarray.DNDarray, axis: Union[int, Tuple[int], List[int]] = None, ddof: int = 0, **kwargs: object) -> heat.core.dndarray.DNDarray Calculates the standard deviation of a ``DNDarray`` with the bessel correction. If an axis is given, the variance will be taken in that direction. :param x: array for which the std is calculated for. The datatype of ``x`` must be a float :type x: DNDarray :param axis: Axis which the std is taken in. Default ``None`` calculates std of all data items. :type axis: None or int or iterable :param ddof: Delta Degrees of Freedom: the denominator implicitely used in the calculation is N - ddof, where N represents the number of elements. If ``ddof=1``, the Bessel correction will be applied. Setting ``ddof>1`` raises a ``NotImplementedError``. :type ddof: int, optional :param \*\*kwargs: Extra keyword arguments .. rubric:: Examples >>> a = ht.random.randn(1, 3) >>> a DNDarray([[ 0.5714, 0.0048, -0.2942]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.std(a) DNDarray(0.3590, dtype=ht.float32, device=cpu:0, split=None) >>> a = ht.random.randn(4, 4) >>> a DNDarray([[ 0.8488, 1.2225, 1.2498, -1.4592], [-0.5820, -0.3928, 0.1509, -0.0174], [ 0.6426, -1.8149, 0.1369, 0.0042], [-0.6043, -0.0523, -1.6653, 0.6631]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.std(a, 1, ddof=1) DNDarray([1.2961, 0.3362, 1.0739, 0.9820], dtype=ht.float32, device=cpu:0, split=None) >>> ht.std(a, 1) DNDarray([1.2961, 0.3362, 1.0739, 0.9820], dtype=ht.float32, device=cpu:0, split=None) .. function:: var(x: heat.core.dndarray.DNDarray, axis: Union[int, Tuple[int], List[int]] = None, ddof: int = 0, **kwargs: object) -> heat.core.dndarray.DNDarray Calculates and returns the variance of a ``DNDarray``. If an axis is given, the variance will be taken in that direction. :param x: Array for which the variance is calculated for. The datatype of ``x`` must be a float :type x: DNDarray :param axis: Axis which the std is taken in. Default ``None`` calculates std of all data items. :type axis: None or int or iterable :param ddof: Delta Degrees of Freedom: the denominator implicitely used in the calculation is N - ddof, where N represents the number of elements. If ``ddof=1``, the Bessel correction will be applied. Setting ``ddof>1`` raises a ``NotImplementedError``. :type ddof: int, optional :param \*\*kwargs: Extra keyword arguments .. rubric:: Notes Split semantics when axis is an integer: - if ``axis=x.split``, then ``var(x).split=None`` - if ``axis>split``, then ``var(x).split = x.split`` - if ``axis>> a = ht.random.randn(1, 3) >>> a DNDarray([[-2.3589, -0.2073, 0.8806]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.var(a) DNDarray(1.8119, dtype=ht.float32, device=cpu:0, split=None) >>> ht.var(a, ddof=1) DNDarray(2.7179, dtype=ht.float32, device=cpu:0, split=None) >>> a = ht.random.randn(4, 4) >>> a DNDarray([[-0.8523, -1.4982, -0.5848, -0.2554], [ 0.8458, -0.3125, -0.2430, 1.9016], [-0.6778, -0.3584, -1.5112, 0.6545], [-0.9161, 0.0168, 0.0462, 0.5964]], dtype=ht.float32, device=cpu:0, split=None) >>> ht.var(a, 1) DNDarray([0.2777, 1.0957, 0.8015, 0.3936], dtype=ht.float32, device=cpu:0, split=None) >>> ht.var(a, 0) DNDarray([0.7001, 0.4376, 0.4576, 0.7890], dtype=ht.float32, device=cpu:0, split=None) >>> ht.var(a, 0, ddof=1) DNDarray([0.7001, 0.4376, 0.4576, 0.7890], dtype=ht.float32, device=cpu:0, split=None) >>> ht.var(a, 0, ddof=0) DNDarray([0.7001, 0.4376, 0.4576, 0.7890], dtype=ht.float32, device=cpu:0, split=None) .. function:: broadcast_shape(shape_a: Tuple[int, Ellipsis], shape_b: Tuple[int, Ellipsis]) -> Tuple[int, Ellipsis] Infers, if possible, the broadcast output shape of two operands a and b. Inspired by stackoverflow post: https://stackoverflow.com/questions/24743753/test-if-an-array-is-broadcastable-to-a-shape :param shape_a: Shape of first operand :type shape_a: Tuple[int,...] :param shape_b: Shape of second operand :type shape_b: Tuple[int,...] :raises ValueError: If the two shapes cannot be broadcast. .. rubric:: Examples >>> import heat as ht >>> ht.core.stride_tricks.broadcast_shape((5, 4), (4,)) (5, 4) >>> ht.core.stride_tricks.broadcast_shape((1, 100, 1), (10, 1, 5)) (10, 100, 5) >>> ht.core.stride_tricks.broadcast_shape( ... (8, 1, 6, 1), ... ( ... 7, ... 1, ... 5, ... ), ... ) (8,7,6,5)) >>> ht.core.stride_tricks.broadcast_shape((2, 1), (8, 4, 3)) Traceback (most recent call last): File "", line 1, in File "heat/core/stride_tricks.py", line 42, in broadcast_shape "operands could not be broadcast, input shapes {} {}".format(shape_a, shape_b) ValueError: operands could not be broadcast, input shapes (2, 1) (8, 4, 3) .. function:: broadcast_shapes(*shapes: Tuple[int, Ellipsis]) -> Tuple[int, Ellipsis] Infers, if possible, the broadcast output shape of multiple operands. :param \*shapes: Shapes of operands. :type \*shapes: Tuple[int,...] :returns: The broadcast output shape. :rtype: Tuple[int, ...] :raises ValueError: If the shapes cannot be broadcast. .. rubric:: Examples >>> import heat as ht >>> ht.broadcast_shapes((5, 4), (4,)) (5, 4) >>> ht.broadcast_shapes((1, 100, 1), (10, 1, 5)) (10, 100, 5) >>> ht.broadcast_shapes( ... (8, 1, 6, 1), ... ( ... 7, ... 1, ... 5, ... ), ... ) (8,7,6,5)) >>> ht.broadcast_shapes((2, 1), (8, 4, 3)) Traceback (most recent call last): File "", line 1, in File "heat/core/stride_tricks.py", line 100, in broadcast_shapes "operands could not be broadcast, input shapes {}".format(shapes)) ValueError: operands could not be broadcast, input shapes ((2, 1), (8, 4, 3)) .. function:: sanitize_shape(shape: Union[int, Tuple[int, Ellipsis]], lval: int = 0) -> Tuple[int, Ellipsis] Verifies and normalizes the given shape. :param shape: Shape of an array. :type shape: int or Tupe[int,...] :param lval: Lowest legal value :type lval: int :raises ValueError: If the shape contains illegal values, e.g. negative numbers. :raises TypeError: If the given shape is neither and int or a sequence of ints. .. rubric:: Examples >>> import heat as ht >>> ht.core.stride_tricks.sanitize_shape(3) (3,) >>> ht.core.stride_tricks.sanitize_shape([1, 2, 3]) (1, 2, 3,) >>> ht.core.stride_tricks.sanitize_shape(1.0) Traceback (most recent call last): File "", line 1, in File "heat/heat/core/stride_tricks.py", line 159, in sanitize_shape raise TypeError("expected sequence object with length >= 0 or a single integer") TypeError: expected sequence object with length >= 0 or a single integer .. function:: sanitize_slice(sl: slice, max_dim: int) -> slice Remove None-types from a slice :param sl: slice to adjust :type sl: slice :param max_dim: maximum index for the given slice :type max_dim: int :raises TypeError: if sl is not a slice. .. py:class:: SplitTiles(arr: heat.core.dndarray.DNDarray) Initialize tiles with the tile divisions equal to the theoretical split dimensions in every dimension :param arr: Base array for which to create the tiles :type arr: DNDarray :ivar __DNDarray: the ``DNDarray`` associated with the tiles :vartype __DNDarray: DNDarray :ivar __lshape_map: map of the shapes of the local torch tensors of arr :vartype __lshape_map: torch.Tensor :ivar __tile_locations: locations of the tiles of ``arr`` :vartype __tile_locations: torch.Tensor :ivar __tile_ends_g: the global indices of the ends of the tiles :vartype __tile_ends_g: torch.Tensor :ivar __tile_dims: the dimensions of all of the tiles :vartype __tile_dims: torch.Tensor .. rubric:: Examples >>> a = ht.zeros( ... ( ... 10, ... 11, ... ), ... split=None, ... ) >>> a.create_split_tiles() >>> print(a.tiles.tile_ends_g) [0/2] tensor([[ 4, 7, 10], [0/2] [ 4, 8, 11]], dtype=torch.int32) [1/2] tensor([[ 4, 7, 10], [1/2] [ 4, 8, 11]], dtype=torch.int32) [2/2] tensor([[ 4, 7, 10], [2/2] [ 4, 8, 11]], dtype=torch.int32) >>> print(a.tiles.tile_locations) [0/2] tensor([[0, 0, 0], [0/2] [0, 0, 0], [0/2] [0, 0, 0]], dtype=torch.int32) [1/2] tensor([[1, 1, 1], [1/2] [1, 1, 1], [1/2] [1, 1, 1]], dtype=torch.int32) [2/2] tensor([[2, 2, 2], [2/2] [2, 2, 2], [2/2] [2, 2, 2]], dtype=torch.int32) >>> a = ht.zeros((10, 11), split=1) >>> a.create_split_tiles() >>> print(a.tiles.tile_ends_g) [0/2] tensor([[ 4, 7, 10], [0/2] [ 4, 8, 11]], dtype=torch.int32) [1/2] tensor([[ 4, 7, 10], [1/2] [ 4, 8, 11]], dtype=torch.int32) [2/2] tensor([[ 4, 7, 10], [2/2] [ 4, 8, 11]], dtype=torch.int32) >>> print(a.tiles.tile_locations) [0/2] tensor([[0, 1, 2], [0/2] [0, 1, 2], [0/2] [0, 1, 2]], dtype=torch.int32) [1/2] tensor([[0, 1, 2], [1/2] [0, 1, 2], [1/2] [0, 1, 2]], dtype=torch.int32) [2/2] tensor([[0, 1, 2], [2/2] [0, 1, 2], [2/2] [0, 1, 2]], dtype=torch.int32) .. attribute:: __DNDarray .. attribute:: __lshape_map .. attribute:: __tile_locations .. attribute:: __tile_ends_g .. attribute:: __tile_dims .. role:: raw-html(raw) :format: html .. method:: set_tile_locations(split: int, tile_dims: torch.Tensor, arr: heat.core.dndarray.DNDarray) -> torch.Tensor Create a `torch.Tensor` which contains the locations of the tiles of ``arr`` for the given split :param split: Target split dimension. Does not need to be equal to ``arr.split`` :type split: int :param tile_dims: Tensor containing the sizes of the each tile :type tile_dims: torch.Tensor :param arr: Array for which the tiles are being created for :type arr: DNDarray .. method:: __getitem__(key: Union[int, slice, Tuple[Union[int, slice], Ellipsis]]) -> torch.Tensor Getitem function for getting tiles. Returns the tile which is specified is returned, but only on the process which it resides :param key: Key which identifies the tile/s to get :type key: int or Tuple or Slice .. rubric:: Examples >>> test = torch.arange(np.prod([i + 6 for i in range(2)])).reshape( ... [i + 6 for i in range(2)] ... ) >>> a = ht.array(test, split=0).larray [0/2] tensor([[ 0., 1., 2., 3., 4., 5., 6.], [0/2] [ 7., 8., 9., 10., 11., 12., 13.]]) [1/2] tensor([[14., 15., 16., 17., 18., 19., 20.], [1/2] [21., 22., 23., 24., 25., 26., 27.]]) [2/2] tensor([[28., 29., 30., 31., 32., 33., 34.], [2/2] [35., 36., 37., 38., 39., 40., 41.]]) >>> a.create_split_tiles() >>> a.tiles[:2, 2] [0/2] tensor([[ 5., 6.], [0/2] [12., 13.]]) [1/2] tensor([[19., 20.], [1/2] [26., 27.]]) [2/2] None >>> a = ht.array(test, split=1) >>> a.create_split_tiles() >>> a.tiles[1] [0/2] tensor([[14., 15., 16.], [0/2] [21., 22., 23.]]) [1/2] tensor([[17., 18.], [1/2] [24., 25.]]) [2/2] tensor([[19., 20.], [2/2] [26., 27.]]) .. method:: __get_tile_slices(key: Union[int, slice, Tuple[Union[int, slice], Ellipsis]]) -> Tuple[slice, Ellipsis] Create and return slices to convert a key from the tile indices to the normal indices .. method:: get_tile_size(key: Union[int, slice, Tuple[Union[int, slice], Ellipsis]]) -> Tuple[int, Ellipsis] Get the size of a tile or tiles indicated by the given key :param key: which tiles to get :type key: int or slice or tuple .. method:: __setitem__(key: Union[int, slice, Tuple[Union[int, slice], Ellipsis]], value: Union[int, float, torch.Tensor]) -> None Set the values of a tile :param key: Key which identifies the tile/s to get :type key: int or Tuple or Slice :param value: Value to be set on the tile :type value: int or torch.Tensor .. rubric:: Examples see getitem function for this class .. method:: get_subarray_params(from_axis: int, to_axis: int) -> List[Tuple[List[int], List[int], List[int]]] Create subarray types of the local array along a new split axis. For use with Alltoallw. Based on the work by Dalcin et al. (https://arxiv.org/abs/1804.09536) Return type is a list of tuples, each tuple containing the shape of the local array, the shape of the subarray, and the start index of the subarray. :param from_axis: Current split axis of global array. :type from_axis: int :param to_axis: New split axis of of subarrays array. :type to_axis: int .. py:class:: SquareDiagTiles(arr: heat.core.dndarray.DNDarray, tiles_per_proc: int = 2) Generate the tile map and the other objects which may be useful. The tiles generated here are based of square tiles along the diagonal. The size of these tiles along the diagonal dictate the divisions across all processes. If ``gshape[0]>>gshape[1]`` then there will be extra tiles generated below the diagonal. If ``gshape[0]`` is close to ``gshape[1]``, then the last tile (as well as the other tiles which correspond with said tile) will be extended to cover the whole array. However, extra tiles are not generated above the diagonal in the case that ``gshape[0]< [rank, row size, column size]`` Tensor filled with the shapes of the local tensors :vartype __lshape_map: torch.Tensor :ivar __tile_map: ``units -> row, column, start index in each direction, process`` Tensor filled with the global indices of the generated tiles :vartype __tile_map: torch.Tensor :ivar __row_per_proc_list: List is length of the number of processes, each element has the number of tile rows on the process whos rank equals the index :vartype __row_per_proc_list: List .. warning:: The generation of these tiles may unbalance the original ``DNDarray``! .. rubric:: Notes This tiling scheme is intended for use with the :func:`~heat.core.linalg.qr.qr` function. .. attribute:: __DNDarray .. attribute:: __col_per_proc_list .. attribute:: __lshape_map .. attribute:: __last_diag_pr .. attribute:: __row_per_proc_list .. attribute:: __tile_map .. attribute:: __row_inds .. attribute:: __col_inds .. role:: raw-html(raw) :format: html .. method:: __adjust_cols_sp1_m_ls_n(arr: heat.core.dndarray.DNDarray, col_per_proc_list: List[int, Ellipsis], last_diag_pr: int, col_inds: List[int, Ellipsis], lshape_map: torch.Tensor) -> None Add more columns after the diagonal ends if ``m None Need to adjust the size of last row if ``arr.split==0`` and the diagonal ends before the last tile. This should only be run if ``arr,split==0`` and ``last_diag_pr None If the split is 0 and the number of tiles per proc is 1 then the local data may need to be redistributed to fit the full diagonal on as many processes as possible. If there is a process where there is only 1 element, this function will adjust the ``lshape_map`` then redistribute ``arr`` so that there is not a single diagonal element on one process .. method:: __create_cols(arr: heat.core.dndarray.DNDarray, lshape_map: torch.Tensor, tiles_per_proc: int) -> Tuple[torch.Tensor, List[int, Ellipsis], List[int, Ellipsis], torch.Tensor] Calculates the last diagonal process, then creates a list of the number of tile columns per process, then calculates the starting indices of the columns. Also returns the number of tile columns. :param arr: DNDarray for which to find the tile columns for :type arr: DNDarray :param lshape_map: The map of the local shapes (for more info see: :func:`~heat.core.dndarray.DNDarray.create_lshape_map`) :type lshape_map: torch.Tensor :param tiles_per_proc: The number of divisions per process :type tiles_per_proc: int .. method:: __def_end_row_inds_sp0_m_ge_n(arr: heat.core.dndarray.DNDarray, row_inds: List[int, Ellipsis], last_diag_pr: int, tiles_per_proc: int, lshape_map: torch.Tensor) -> None Adjust the rows on the processes which are greater than the last diagonal processs to have rows which are chunked evenly into ``tiles_per_proc`` rows. .. method:: __last_tile_row_adjust_sp1(arr: heat.core.dndarray.DNDarray, row_inds: List[int, Ellipsis]) -> None Add extra row/s if there is space below the diagonal (``split=1``) .. method:: get_start_stop(key: Union[int, slice, Tuple[int, slice, Ellipsis]]) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor] Returns the start and stop indices in form of ``(dim0 start, dim0 stop, dim1 start, dim1 stop)`` which correspond to the tile/s which corresponds to the given key. The key MUST use global indices. :param key: Indices to select the tile STRIDES ARE NOT ALLOWED, MUST BE GLOBAL INDICES :type key: int or Tuple or List or slice .. rubric:: Examples >>> a = ht.zeros((12, 10), split=0) >>> a_tiles = ht.tiling.SquareDiagTiles(a, tiles_per_proc=2) # type: tiling.SquareDiagTiles >>> print(a_tiles.get_start_stop(key=(slice(0, 2), 2))) [0/1] (tensor(0), tensor(6), tensor(6), tensor(8)) [1/1] (tensor(0), tensor(6), tensor(6), tensor(8)) >>> print(a_tiles.get_start_stop(key=(0, 2))) [0/1] (tensor(0), tensor(3), tensor(6), tensor(8)) [1/1] (tensor(0), tensor(3), tensor(6), tensor(8)) >>> print(a_tiles.get_start_stop(key=2)) [0/1] (tensor(0), tensor(2), tensor(0), tensor(10)) [1/1] (tensor(0), tensor(2), tensor(0), tensor(10)) >>> print(a_tiles.get_start_stop(key=(3, 3))) [0/1] (tensor(2), tensor(6), tensor(8), tensor(10)) [1/1] (tensor(2), tensor(6), tensor(8), tensor(10)) .. method:: __getitem__(key: Union[int, slice, Tuple[int, slice, Ellipsis]]) -> torch.Tensor Returns a local selection of the DNDarray corresponding to the tile/s desired Standard getitem function for the tiles. The returned item is a view of the original DNDarray, operations which are done to this view will change the original array. **STRIDES ARE NOT AVAILABLE, NOR ARE CROSS-SPLIT SLICES** :param key: indices of the tile/s desired :type key: int, slice, tuple .. rubric:: Examples >>> a = ht.zeros((12, 10), split=0) >>> a_tiles = tiling.SquareDiagTiles(a, tiles_per_proc=2) # type: tiling.SquareDiagTiles >>> print(a_tiles[2, 3]) [0/1] None [1/1] tensor([[0., 0.], [1/1] [0., 0.]]) >>> print(a_tiles[2]) [0/1] None [1/1] tensor([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [1/1] [0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]) >>> print(a_tiles[0:2, 1]) [0/1] tensor([[0., 0., 0.], [0/1] [0., 0., 0.], [0/1] [0., 0., 0.], [0/1] [0., 0., 0.], [0/1] [0., 0., 0.], [0/1] [0., 0., 0.]]) [1/1] None .. method:: local_get(key: Union[int, slice, Tuple[int, slice, Ellipsis]]) -> torch.Tensor Returns the local tile/s corresponding to the key given Getitem routing using local indices, converts to global indices then uses getitem :param key: Indices of the tile/s desired. If the stop index of a slice is larger than the end will be adjusted to the maximum allowed :type key: int, slice, tuple, list .. rubric:: Examples See local_set function. .. method:: local_set(key: Union[int, slice, Tuple[int, slice, Ellipsis]], value: Union[int, float, torch.Tensor]) Setitem routing to set data to a local tile (using local indices) :param key: Indices of the tile/s desired If the stop index of a slice is larger than the end will be adjusted to the maximum allowed :type key: int or slice or Tuple[int,...] :param value: Data to be written to the tile :type value: torch.Tensor or int or float .. rubric:: Examples >>> a = ht.zeros((11, 10), split=0) >>> a_tiles = tiling.SquareDiagTiles(a, tiles_per_proc=2) # type: tiling.SquareDiagTiles >>> local = a_tiles.local_get(key=slice(None)) >>> a_tiles.local_set( ... key=slice(None), value=torch.arange(local.numel()).reshape(local.shape) ... ) >>> print(a.larray) [0/1] tensor([[ 0., 1., 2., 3., 4., 5., 6., 7., 8., 9.], [0/1] [10., 11., 12., 13., 14., 15., 16., 17., 18., 19.], [0/1] [20., 21., 22., 23., 24., 25., 26., 27., 28., 29.], [0/1] [30., 31., 32., 33., 34., 35., 36., 37., 38., 39.], [0/1] [40., 41., 42., 43., 44., 45., 46., 47., 48., 49.], [0/1] [50., 51., 52., 53., 54., 55., 56., 57., 58., 59.]]) [1/1] tensor([[ 0., 1., 2., 3., 4., 5., 6., 7., 8., 9.], [1/1] [10., 11., 12., 13., 14., 15., 16., 17., 18., 19.], [1/1] [20., 21., 22., 23., 24., 25., 26., 27., 28., 29.], [1/1] [30., 31., 32., 33., 34., 35., 36., 37., 38., 39.], [1/1] [40., 41., 42., 43., 44., 45., 46., 47., 48., 49.]]) >>> a.lloc[:] = 0 >>> a_tiles.local_set(key=(0, 2), value=10) [0/1] tensor([[ 0., 0., 0., 0., 0., 0., 10., 10., 0., 0.], [0/1] [ 0., 0., 0., 0., 0., 0., 10., 10., 0., 0.], [0/1] [ 0., 0., 0., 0., 0., 0., 10., 10., 0., 0.], [0/1] [ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0/1] [ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0/1] [ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]) [1/1] tensor([[ 0., 0., 0., 0., 0., 0., 10., 10., 0., 0.], [1/1] [ 0., 0., 0., 0., 0., 0., 10., 10., 0., 0.], [1/1] [ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [1/1] [ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [1/1] [ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]) >>> a_tiles.local_set(key=(slice(None), 1), value=10) [0/1] tensor([[ 0., 0., 0., 10., 10., 10., 0., 0., 0., 0.], [0/1] [ 0., 0., 0., 10., 10., 10., 0., 0., 0., 0.], [0/1] [ 0., 0., 0., 10., 10., 10., 0., 0., 0., 0.], [0/1] [ 0., 0., 0., 10., 10., 10., 0., 0., 0., 0.], [0/1] [ 0., 0., 0., 10., 10., 10., 0., 0., 0., 0.], [0/1] [ 0., 0., 0., 10., 10., 10., 0., 0., 0., 0.]]) [1/1] tensor([[ 0., 0., 0., 10., 10., 10., 0., 0., 0., 0.], [1/1] [ 0., 0., 0., 10., 10., 10., 0., 0., 0., 0.], [1/1] [ 0., 0., 0., 10., 10., 10., 0., 0., 0., 0.], [1/1] [ 0., 0., 0., 10., 10., 10., 0., 0., 0., 0.], [1/1] [ 0., 0., 0., 10., 10., 10., 0., 0., 0., 0.]]) .. method:: local_to_global(key: Union[int, slice, Tuple[int, slice, Ellipsis]], rank: int) -> Tuple[int, slice, Ellipsis] Convert local indices to global indices :param key: Indices of the tile/s desired. If the stop index of a slice is larger than the end will be adjusted to the maximum allowed :type key: int or slice or Tuple or List :param rank: Process rank :type rank: int .. rubric:: Examples >>> a = ht.zeros((11, 10), split=0) >>> a_tiles = tiling.SquareDiagTiles(a, tiles_per_proc=2) # type: tiling.SquareDiagTiles >>> rank = a.comm.rank >>> print(a_tiles.local_to_global(key=(slice(None), 1), rank=rank)) [0/1] (slice(0, 2, None), 1) [1/1] (slice(2, 4, None), 1) >>> print(a_tiles.local_to_global(key=(0, 2), rank=0)) [0/1] (0, 2) [1/1] (0, 2) >>> print(a_tiles.local_to_global(key=(0, 2), rank=1)) [0/1] (2, 2) [1/1] (2, 2) .. method:: match_tiles(tiles_to_match: SquareDiagTiles) -> None Function to match the tile sizes of another tile map :param tiles_to_match: The tiles which should be matched by the current tiling scheme :type tiles_to_match: SquareDiagTiles .. rubric:: Notes This function overwrites most, if not all, of the elements of this class. Intended for use with the Q matrix, to match the tiling of a/R. For this to work properly it is required that the 0th dim of both matrices is equal .. method:: __setitem__(key: Union[int, slice, Tuple[int, slice, Ellipsis]], value: Union[int, float, torch.Tensor]) -> None Item setter, uses the torch item setter and the getitem routines to set the values of the original array (arr in __init__) :param key: Tile indices to identify the target tiles :type key: int or slice or Tuple[int,...] :param value: Values to be set :type value: int or torch.Tensor .. rubric:: Example >>> a = ht.zeros((12, 10), split=0) >>> a_tiles = tiling.SquareDiagTiles(a, tiles_per_proc=2) # type: tiling.SquareDiagTiles >>> a_tiles[0:2, 2] = 11 >>> a_tiles[0, 0] = 22 >>> a_tiles[2] = 33 >>> a_tiles[3, 3] = 44 >>> print(a.larray) [0/1] tensor([[22., 22., 22., 0., 0., 0., 11., 11., 0., 0.], [0/1] [22., 22., 22., 0., 0., 0., 11., 11., 0., 0.], [0/1] [22., 22., 22., 0., 0., 0., 11., 11., 0., 0.], [0/1] [ 0., 0., 0., 0., 0., 0., 11., 11., 0., 0.], [0/1] [ 0., 0., 0., 0., 0., 0., 11., 11., 0., 0.], [0/1] [ 0., 0., 0., 0., 0., 0., 11., 11., 0., 0.]]) [1/1] tensor([[33., 33., 33., 33., 33., 33., 33., 33., 33., 33.], [1/1] [33., 33., 33., 33., 33., 33., 33., 33., 33., 33.], [1/1] [ 0., 0., 0., 0., 0., 0., 0., 0., 44., 44.], [1/1] [ 0., 0., 0., 0., 0., 0., 0., 0., 44., 44.], [1/1] [ 0., 0., 0., 0., 0., 0., 0., 0., 44., 44.], [1/1] [ 0., 0., 0., 0., 0., 0., 0., 0., 44., 44.]]) .. data:: acos Alias for :py:func:`arccos` .. function:: acosh(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compute the inverse hyperbolic cosine, element-wise. Result is a ``DNDarray`` of the same shape as ``x``. Input elements outside [1., +infinity] are returned as ``NaN``. If ``out`` was provided, ``acosh`` is a reference to it. :param x: The array for which to compute the inverse hyperbolic cosine. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.acosh(ht.array([1.0, 10.0, 20.0])) DNDarray([0.0000, 2.9932, 3.6883], dtype=ht.float32, device=cpu:0, split=None) .. data:: asin Alias for :py:func:`arcsin` .. function:: asinh(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compute the inverse hyperbolic sine, element-wise. Result is a ``DNDarray`` of the same shape as ``x``. Input elements outside [-infinity., +infinity] are returned as ``NaN``. If ``out`` was provided, ``asinh`` is a reference to it. :param x: The array for which to compute the inverse hyperbolic sine. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.asinh(ht.array([-10.0, 0.0, 10.0])) DNDarray([-2.9982, 0.0000, 2.9982], dtype=ht.float32, device=cpu:0, split=None) .. data:: atan Alias for :py:func:`arctan` .. data:: atan2 Alias for :py:func:`arctan2` .. function:: atanh(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compute the inverse hyperbolic tangent, element-wise. Result is a ``DNDarray`` of the same shape as ``x``. Input elements outside [-1., 1.] are returned as ``NaN``. If ``out`` was provided, ``atanh`` is a reference to it. :param x: The array for which to compute the inverse hyperbolic tangent. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.atanh(ht.array([-1.0, -0.0, 0.83])) DNDarray([ -inf, -0.0000, 1.1881], dtype=ht.float32, device=cpu:0, split=None) .. function:: arccos(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compute the trigonometric arccos, element-wise. Result is a ``DNDarray`` of the same shape as ``x``. Input elements outside [-1., 1.] are returned as ``NaN``. If ``out`` was provided, ``arccos`` is a reference to it. :param x: The array for which to compute the trigonometric cosine. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.arccos(ht.array([-1.0, -0.0, 0.83])) DNDarray([3.1416, 1.5708, 0.5917], dtype=ht.float32, device=cpu:0, split=None) .. data:: arccosh Alias for :py:func:`acosh` .. function:: arcsin(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compute the trigonometric arcsin, element-wise. Result is a ``DNDarray`` of the same shape as ``x``. Input elements outside [-1., 1.] are returned as ``NaN``. If ``out`` was provided, ``arcsin`` is a reference to it. :param x: The array for which to compute the trigonometric cosine. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.arcsin(ht.array([-1.0, -0.0, 0.83])) DNDarray([-1.5708, -0.0000, 0.9791], dtype=ht.float32, device=cpu:0, split=None) .. data:: arcsinh Alias for :py:func:`asinh` .. function:: arctan(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compute the trigonometric arctan, element-wise. Result is a ``DNDarray`` of the same shape as ``x``. Input elements outside [-1., 1.] are returned as ``NaN``. If ``out`` was provided, ``arctan`` is a reference to it. :param x: The array for which to compute the trigonometric cosine. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.arctan(ht.arange(-6, 7, 2)) DNDarray([-1.4056, -1.3258, -1.1071, 0.0000, 1.1071, 1.3258, 1.4056], dtype=ht.float32, device=cpu:0, split=None) .. function:: arctan2(x1: heat.core.dndarray.DNDarray, x2: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Element-wise arc tangent of ``x1/x2`` choosing the quadrant correctly. Returns a new ``DNDarray`` with the signed angles in radians between vector (``x2``,``x1``) and vector (1,0) :param x1: y-coordinates :type x1: DNDarray :param x2: x-coordinates. If ``x1.shape!=x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). :type x2: DNDarray .. rubric:: Examples >>> x = ht.array([-1, +1, +1, -1]) >>> y = ht.array([-1, -1, +1, +1]) >>> ht.arctan2(y, x) * 180 / ht.pi DNDarray([-135.0000, -45.0000, 45.0000, 135.0000], dtype=ht.float64, device=cpu:0, split=None) .. data:: arctanh Alias for :py:func:`atanh` .. function:: cos(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Return the trigonometric cosine, element-wise. :param x: The value for which to compute the trigonometric cosine. :type x: ht.DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to None, a fresh tensor is allocated. :type out: ht.DNDarray or None, optional .. rubric:: Examples >>> ht.cos(ht.arange(-6, 7, 2)) DNDarray([ 0.9602, -0.6536, -0.4161, 1.0000, -0.4161, -0.6536, 0.9602], dtype=ht.float32, device=cpu:0, split=None) .. function:: cosh(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compute the hyperbolic cosine, element-wise. Result is a ``DNDarray`` of the same shape as ``x``. Negative input elements are returned as ``NaN``. If ``out`` was provided, ``cosh`` is a reference to it. :param x: The value for which to compute the hyperbolic cosine. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.cosh(ht.arange(-6, 7, 2)) DNDarray([201.7156, 27.3082, 3.7622, 1.0000, 3.7622, 27.3082, 201.7156], dtype=ht.float32, device=cpu:0, split=None) .. function:: deg2rad(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Convert angles from degrees to radians. :param x: The value for which to compute the angles in radians. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.deg2rad(ht.array([0.0, 20.0, 45.0, 78.0, 94.0, 120.0, 180.0, 270.0, 311.0])) DNDarray([0.0000, 0.3491, 0.7854, 1.3614, 1.6406, 2.0944, 3.1416, 4.7124, 5.4280], dtype=ht.float32, device=cpu:0, split=None) .. function:: degrees(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Convert angles from radians to degrees. :param x: The value for which to compute the angles in degrees. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.degrees(ht.array([0.0, 0.2, 0.6, 0.9, 1.2, 2.7, 3.14])) DNDarray([ 0.0000, 11.4592, 34.3775, 51.5662, 68.7549, 154.6986, 179.9088], dtype=ht.float32, device=cpu:0, split=None) .. function:: rad2deg(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Convert angles from radians to degrees. :param x: The value for which to compute the angles in degrees. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.rad2deg(ht.array([0.0, 0.2, 0.6, 0.9, 1.2, 2.7, 3.14])) DNDarray([ 0.0000, 11.4592, 34.3775, 51.5662, 68.7549, 154.6986, 179.9088], dtype=ht.float32, device=cpu:0, split=None) .. function:: radians(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Convert angles from degrees to radians. :param x: The value for which to compute the angles in radians. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.radians(ht.array([0.0, 20.0, 45.0, 78.0, 94.0, 120.0, 180.0, 270.0, 311.0])) DNDarray([0.0000, 0.3491, 0.7854, 1.3614, 1.6406, 2.0944, 3.1416, 4.7124, 5.4280], dtype=ht.float32, device=cpu:0, split=None) .. function:: sin(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compute the trigonometric sine, element-wise. Result is a ``DNDarray`` of the same shape as ``x``. Negative input elements are returned as ``NaN``. If ``out`` was provided, ``sin`` is a reference to it. :param x: The value for which to compute the trigonometric tangent. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray, optional .. rubric:: Examples >>> ht.sin(ht.arange(-6, 7, 2)) DNDarray([ 0.2794, 0.7568, -0.9093, 0.0000, 0.9093, -0.7568, -0.2794], dtype=ht.float32, device=cpu:0, split=None) .. function:: sinh(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compute the hyperbolic sine, element-wise. Result is a ``DNDarray`` of the same shape as ``x``. Negative input elements are returned as ``NaN``. If ``out`` was provided, ``sinh`` is a reference to it. :param x: The value for which to compute the hyperbolic sine. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray or None, optional .. rubric:: Examples >>> ht.sinh(ht.arange(-6, 7, 2)) DNDarray([-201.7132, -27.2899, -3.6269, 0.0000, 3.6269, 27.2899, 201.7132], dtype=ht.float32, device=cpu:0, split=None) .. function:: tan(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compute tangent element-wise. Result is a ``DNDarray`` of the same shape as ``x``. Equivalent to :func:`sin`/:func:`cos` element-wise. If ``out`` was provided, ``tan`` is a reference to it. :param x: The value for which to compute the trigonometric tangent. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray or None, optional .. rubric:: Examples >>> ht.tan(ht.arange(-6, 7, 2)) DNDarray([ 0.2910, -1.1578, 2.1850, 0.0000, -2.1850, 1.1578, -0.2910], dtype=ht.float32, device=cpu:0, split=None) .. function:: tanh(x: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Compute the hyperbolic tangent, element-wise. Result is a ``DNDarray`` of the same shape as ``x``. If ``out`` was provided, ``tanh`` is a reference to it. :param x: The value for which to compute the hyperbolic tangent. :type x: DNDarray :param out: A location in which to store the results. If provided, it must have a broadcastable shape. If not provided or set to ``None``, a fresh array is allocated. :type out: DNDarray or None, optional .. rubric:: Examples >>> ht.tanh(ht.arange(-6, 7, 2)) DNDarray([-1.0000, -0.9993, -0.9640, 0.0000, 0.9640, 0.9993, 1.0000], dtype=ht.float32, device=cpu:0, split=None) .. py:class:: datatype Defines the basic heat data types in the hierarchy as shown below. Design inspired by the Python package numpy. As part of the type-hierarchy: xx -- is bit-width - generic - bool, bool_ (kind=?) - number - integer - signedinteger (intxx)(kind=b, i) - int8, byte - int16, short - int32, int - int64, long - unsignedinteger (uintxx)(kind=B, u) - uint8, ubyte - floating (floatxx) (kind=f) - float16, half - float32, float, float_ - float64, double (double) - flexible (currently unused, placeholder for characters) .. attribute:: _can_be_cast_safely_to :annotation: = [] .. attribute:: _can_be_cast_intuitively_to :annotation: = [] .. attribute:: mappings :annotation: = [] .. role:: raw-html(raw) :format: html .. method:: torch_type() -> NotImplemented Torch Datatype .. method:: char() -> NotImplemented Datatype short-hand name .. method:: can_cast_to(to, casting: str = 'intuitive') -> bool Returns True if cast between this datatype and `to`-datatype can occur according to the casting rule. If `to` is a scalar or array scalar, also returns True if the scalar value can be cast without overflow or truncation to an integer. :param to: Target type to cast to. :type to: Union[str, Type[datatype], Any] :param casting: options: {"no", "safe", "same_kind", "unsafe", "intuitive"}, optional Controls the way the cast is evaluated * "no" the types may not be cast, i.e. they need to be identical * "safe" allows only casts that can preserve values with complete precision * "same_kind" safe casts are possible and down_casts within the same type family, e.g. int32 -> int8 * "unsafe" means any conversion can be performed, i.e. this casting is always possible * "intuitive" allows all of the casts of safe plus casting from int32 to float32 :type casting: str, optional :raises TypeError: If the types are not understood or casting is not a string :raises ValueError: If the casting rule is not understood .. rubric:: Examples >>> ht.int32.can_cast_to(ht.int64) True >>> ht.int64.can_cast_to(ht.float64) True >>> ht.int16.can_cast_to(ht.int8) False >>> ht.int16.can_cast_to(1) True >>> ht.int16.can_cast_to("f4") True >>> ht.int64.can_cast_to("i2", casting="safe") False .. py:class:: number Bases: :class:`datatype` The general number datatype. Integer and Float classes will inherit from this. .. role:: raw-html(raw) :format: html .. py:class:: integer Bases: :class:`number` The general integer datatype. Specific integer classes inherit from this. .. role:: raw-html(raw) :format: html .. py:class:: signedinteger Bases: :class:`integer` The general signed integer datatype. .. role:: raw-html(raw) :format: html .. py:class:: unsignedinteger Bases: :class:`integer` The general unsigned integer datatype .. role:: raw-html(raw) :format: html .. py:class:: bool Bases: :class:`datatype` The boolean datatype in Heat .. attribute:: _can_be_cast_safely_to :annotation: = ['bool', 'uint8', 'int8', 'int16', 'int32', 'int64', 'float16', 'float32', 'float64', 'complex64', 'complex128'] .. attribute:: mappings .. role:: raw-html(raw) :format: html .. method:: torch_type() -> torch.dtype Torch Datatype .. method:: char() -> str Datatype short-hand name .. py:class:: floating Bases: :class:`number` The general floating point datatype class. .. role:: raw-html(raw) :format: html .. py:class:: int8 Bases: :class:`signedinteger` 8 bit signed integer datatype .. attribute:: _can_be_cast_safely_to :annotation: = ['int8', 'int16', 'int32', 'int64', 'float16', 'float32', 'float64', 'complex64', 'complex128'] .. attribute:: mappings .. role:: raw-html(raw) :format: html .. method:: torch_type() -> torch.dtype Torch Datatype .. method:: char() -> str Datatype short-hand name .. py:class:: int16 Bases: :class:`signedinteger` 16 bit signed integer datatype .. attribute:: _can_be_cast_safely_to :annotation: = ['int16', 'int32', 'int64', 'float32', 'float64', 'complex64', 'complex128'] .. attribute:: _can_be_cast_intuitively_to :annotation: = ['float16'] .. attribute:: mappings .. role:: raw-html(raw) :format: html .. method:: torch_type() -> torch.dtype Torch Datatype .. method:: char() -> str Datatype short-hand name .. py:class:: int32 Bases: :class:`signedinteger` 32 bit signed integer datatype .. attribute:: _can_be_cast_safely_to :annotation: = ['int32', 'int64', 'float64', 'complex128'] .. attribute:: _can_be_cast_intuitively_to :annotation: = ['float32', 'complex64'] .. attribute:: mappings .. role:: raw-html(raw) :format: html .. method:: torch_type() -> torch.dtype Torch Datatype .. method:: char() -> str Datatype short-hand name .. py:class:: int64 Bases: :class:`signedinteger` 64 bit signed integer datatype .. attribute:: _can_be_cast_safely_to :annotation: = ['int64', 'float64', 'complex128'] .. attribute:: mappings .. role:: raw-html(raw) :format: html .. method:: torch_type() -> torch.dtype Torch Datatype .. method:: char() -> str Datatype short-hand name .. py:class:: uint8 Bases: :class:`unsignedinteger` 8 bit unsigned integer datatype .. attribute:: _can_be_cast_safely_to :annotation: = ['uint8', 'int16', 'int32', 'int64', 'float16', 'float32', 'float64', 'complex64', 'complex128'] .. attribute:: mappings .. role:: raw-html(raw) :format: html .. method:: torch_type() -> torch.dtype Torch Datatype .. method:: char() -> str Datatype short-hand name .. py:class:: float16 Bases: :class:`floating` The 16 bit floating point datatype .. attribute:: _can_be_cast_safely_to :annotation: = ['float16', 'float32', 'float64', 'complex64', 'complex128'] .. attribute:: mappings .. role:: raw-html(raw) :format: html .. method:: torch_type() -> torch.dtype Torch Datatype .. method:: char() -> str Datatype short-hand name .. py:class:: float32 Bases: :class:`floating` The 32 bit floating point datatype .. attribute:: _can_be_cast_safely_to :annotation: = ['float32', 'float64', 'complex64', 'complex128'] .. attribute:: mappings .. role:: raw-html(raw) :format: html .. method:: torch_type() -> torch.dtype Torch Datatype .. method:: char() -> str Datatype short-hand name .. py:class:: float64 Bases: :class:`floating` The 64 bit floating point datatype .. attribute:: _can_be_cast_safely_to :annotation: = ['float64', 'complex128'] .. attribute:: mappings .. role:: raw-html(raw) :format: html .. method:: torch_type() -> torch.dtype Torch Datatye .. method:: char() -> str Datatype short-hand name .. py:class:: flexible Bases: :class:`datatype` The general flexible datatype. Currently unused, placeholder for characters .. role:: raw-html(raw) :format: html .. function:: can_cast(from_: Union[str, Type[datatype], Any], to: Union[str, Type[datatype], Any], casting: str = 'intuitive') -> bool Returns True if cast between data types can occur according to the casting rule. If from is a scalar or array scalar, also returns True if the scalar value can be cast without overflow or truncation to an integer. :param from_: Scalar, data type or type specifier to cast from. :type from_: Union[str, Type[datatype], Any] :param to: Target type to cast to. :type to: Union[str, Type[datatype], Any] :param casting: options: {"no", "safe", "same_kind", "unsafe", "intuitive"}, optional Controls the way the cast is evaluated * "no" the types may not be cast, i.e. they need to be identical * "safe" allows only casts that can preserve values with complete precision * "same_kind" safe casts are possible and down_casts within the same type family, e.g. int32 -> int8 * "unsafe" means any conversion can be performed, i.e. this casting is always possible * "intuitive" allows all of the casts of safe plus casting from int32 to float32 :type casting: str, optional :raises TypeError: If the types are not understood .. rubric:: Examples >>> ht.can_cast(ht.int32, ht.int64) True >>> ht.can_cast(ht.int64, ht.float64) True >>> ht.can_cast(ht.int16, ht.int8) False >>> ht.can_cast(1, ht.float64) True >>> ht.can_cast(2.0e200, "u1") False >>> ht.can_cast("i8", "i4", "no") False >>> ht.can_cast("i8", "i4", "safe") False >>> ht.can_cast("i8", "i4", "same_kind") True >>> ht.can_cast("i8", "i4", "unsafe") True .. function:: canonical_heat_type(a_type: Union[str, Type[datatype], Any]) -> Type[datatype] Canonicalize the builtin Python type, type string or HeAT type into a canonical HeAT type. :param a_type: A description for the type. It may be a Python builtin type, string or an HeAT type already. In the three former cases the according mapped type is looked up, in the latter the type is simply returned. :type a_type: type, str, datatype :raises TypeError: If the type cannot be converted. .. function:: heat_type_is_exact(ht_dtype: Type[datatype]) -> bool Check if HeAT type is an exact type, i.e an integer type. True if ht_dtype is an integer, False otherwise :param ht_dtype: HeAT type to check :type ht_dtype: Type[datatype] .. function:: heat_type_is_inexact(ht_dtype: Type[datatype]) -> bool Check if HeAT type is an inexact type, i.e floating point type. True if ht_dtype is a float or complex, False otherwise :param ht_dtype: HeAT type to check :type ht_dtype: Type[datatype] .. function:: heat_type_is_realfloating(ht_dtype: Type[datatype]) -> bool Check if Heat type is a real floating point number, i.e float32 or float64 :param ht_dtype: Heat type to check :type ht_dtype: Type[datatype] :returns: **out** -- True if ht_dtype is a real float, False otherwise :rtype: bool .. function:: heat_type_is_complexfloating(ht_dtype: Type[datatype]) -> bool Check if Heat type is a complex floating point number, i.e complex64 :param ht_dtype: HeAT type to check :type ht_dtype: ht.dtype :returns: **out** -- True if ht_dtype is a complex float, False otherwise :rtype: bool .. function:: iscomplex(x: dndarray.DNDarray) -> dndarray.DNDarray Test element-wise if input is complex. :param x: The input DNDarray :type x: DNDarray .. rubric:: Examples >>> ht.iscomplex(ht.array([1 + 1j, 1])) DNDarray([ True, False], dtype=ht.bool, device=cpu:0, split=None) .. function:: isreal(x: dndarray.DNDarray) -> dndarray.DNDarray Test element-wise if input is real-valued. :param x: The input DNDarray :type x: DNDarray .. rubric:: Examples >>> ht.iscomplex(ht.array([1 + 1j, 1])) DNDarray([ True, False], dtype=ht.bool, device=cpu:0, split=None) .. function:: issubdtype(arg1: Union[str, Type[datatype], Any], arg2: Union[str, Type[datatype], Any]) -> bool Returns True if first argument is a typecode lower/equal in type hierarchy. :param arg1: A description representing the type. It may be a a Python builtin type, string or an HeAT type already. :type arg1: type, str, ht.dtype :param arg2: A description representing the type. It may be a a Python builtin type, string or an HeAT type already. :type arg2: type, str, ht.dtype .. rubric:: Examples >>> ints = ht.array([1, 2, 3], dtype=ht.int32) >>> ht.issubdtype(ints.dtype, ht.integer) True >>> ht.issubdype(ints.dtype, ht.floating) False >>> ht.issubdtype(ht.float64, ht.float32) False >>> ht.issubdtype("i", ht.integer) True .. function:: heat_type_of(obj: Union[str, Type[datatype], Any, Iterable[str, Type[datatype], Any]]) -> Type[datatype] Returns the corresponding HeAT data type of given object, i.e. scalar, array or iterable. Attempts to determine the canonical data type based on the following priority list: 1. dtype property 2. type(obj) 3. type(obj[0]) :param obj: The object for which to infer the type. :type obj: scalar or DNDarray or iterable :raises TypeError: If the object's type cannot be inferred. .. function:: promote_types(type1: Union[str, Type[datatype], Any], type2: Union[str, Type[datatype], Any]) -> Type[datatype] Returns the data type with the smallest size and smallest scalar kind to which both ``type1`` and ``type2`` may be intuitively cast to, where intuitive casting refers to maintaining the same bit length if possible. This function is symmetric. :param type1: type of first operand :type type1: type or str or datatype :param type2: type of second operand :type type2: type or str or datatype .. rubric:: Examples >>> ht.promote_types(ht.uint8, ht.uint8) >>> ht.promote_types(ht.int32, ht.float32) >>> ht.promote_types(ht.int8, ht.uint8) >>> ht.promote_types("i8", "f4") .. function:: result_type(*arrays_and_types: Tuple[Union[dndarray.DNDarray, Type[datatype], Any]]) -> Type[datatype] Returns the data type that results from type promotions rules performed in an arithmetic operation. :param arrays_and_types: Input arrays, types or numbers of the operation. :type arrays_and_types: List of arrays and types .. rubric:: Examples >>> ht.result_type(ht.array([1], dtype=ht.int32), 1) ht.int32 >>> ht.result_type(ht.float32, ht.array(1, dtype=ht.int8)) ht.float32 >>> ht.result_type("i8", "f4") ht.float64 .. py:class:: complex64 Bases: :class:`complex` The complex 64 bit datatype. Both real and imaginary are 32 bit floating point .. attribute:: _can_be_cast_safely_to :annotation: = ['complex64', 'complex128'] .. attribute:: mappings .. role:: raw-html(raw) :format: html .. method:: torch_type() Torch Datatype .. method:: char() Datatype short-hand name .. py:class:: complex128 Bases: :class:`complex` The complex 128 bit datatype. Both real and imaginary are 64 bit floating point .. attribute:: _can_be_cast_safely_to :annotation: = ['complex128'] .. attribute:: mappings .. role:: raw-html(raw) :format: html .. method:: torch_type() Torch Datatype .. method:: char() Datatype short-hand name .. function:: convolve(a: heat.core.dndarray.DNDarray, v: heat.core.dndarray.DNDarray, mode: str = 'full', stride: int = 1) -> heat.core.dndarray.DNDarray Returns the discrete, linear convolution of two one-dimensional `DNDarray`s or scalars. Unlike `numpy.signal.convolve`, if ``a`` and/or ``v`` have more than one dimension, batch-convolution along the last dimension will be attempted. See `Examples` below. :param a: One- or N-dimensional signal ``DNDarray`` of shape (..., N), or scalar. If ``a`` has more than one dimension, it will be treated as a batch of 1D signals. Distribution along the batch dimension is required for distributed batch processing. See the examples for details. :type a: DNDarray or scalar :param v: One- or N-dimensional filter weight `DNDarray` of shape (..., M), or scalar. If ``v`` has more than one dimension, it will be treated as a batch of 1D filter weights. The batch dimension(s) of ``v`` must match the batch dimension(s) of ``a``. :type v: DNDarray or scalar :param mode: Can be 'full', 'valid', or 'same'. Default is 'full'. 'full': Returns the convolution at each point of overlap, with a length of '(N+M-2)//stride+1'. At the end-points of the convolution, the signals do not overlap completely, and boundary effects may be seen. 'same': Mode 'same' returns output of length 'N'. Boundary effects are still visible. This mode is not supported for even-sized filter weights 'valid': Mode 'valid' returns output of length '(N-M)//stride+1'. The convolution product is only given for points where the signals overlap completely. Values outside the signal boundary have no effect. :type mode: str :param stride: Stride of the convolution. Must be a positive integer. Default is 1. Stride must be 1 for mode 'same'. :type stride: int .. rubric:: Examples Note how the convolution operator flips the second array before "sliding" the two across one another: >>> a = ht.ones(5) >>> v = ht.arange(3).astype(ht.float) >>> ht.convolve(a, v, mode="full") DNDarray([0., 1., 3., 3., 3., 3., 2.]) >>> ht.convolve(a, v, mode="same") DNDarray([1., 3., 3., 3., 3.]) >>> ht.convolve(a, v, mode="valid") DNDarray([3., 3., 3.]) >>> ht.convolve(a, v, stride=2) DNDarray([0., 3., 3., 2.]) >>> ht.convolve(a, v, mode="valid", stride=2) DNDarray([3., 3.]) >>> a = ht.ones(10, split=0) >>> v = ht.arange(3, split=0).astype(ht.float) >>> ht.convolve(a, v, mode="valid") DNDarray([3., 3., 3., 3., 3., 3., 3., 3.]) [0/3] DNDarray([3., 3., 3.]) [1/3] DNDarray([3., 3., 3.]) [2/3] DNDarray([3., 3.]) >>> a = ht.ones(10, split=0) >>> v = ht.arange(3, split=0) >>> ht.convolve(a, v) DNDarray([0., 1., 3., 3., 3., 3., 3., 3., 3., 3., 3., 2.], dtype=ht.float32, device=cpu:0, split=0) [0/3] DNDarray([0., 1., 3., 3.]) [1/3] DNDarray([3., 3., 3., 3.]) [2/3] DNDarray([3., 3., 3., 2.]) >>> a = ht.arange(50, dtype=ht.float64, split=0) >>> a = a.reshape(10, 5) # 10 signals of length 5 >>> v = ht.arange(3) >>> ht.convolve(a, v) # batch processing: 10 signals convolved with filter v DNDarray([[ 0., 0., 1., 4., 7., 10., 8.], [ 0., 5., 16., 19., 22., 25., 18.], [ 0., 10., 31., 34., 37., 40., 28.], [ 0., 15., 46., 49., 52., 55., 38.], [ 0., 20., 61., 64., 67., 70., 48.], [ 0., 25., 76., 79., 82., 85., 58.], [ 0., 30., 91., 94., 97., 100., 68.], [ 0., 35., 106., 109., 112., 115., 78.], [ 0., 40., 121., 124., 127., 130., 88.], [ 0., 45., 136., 139., 142., 145., 98.]], dtype=ht.float64, device=cpu:0, split=0) >>> v = ht.random.randint(0, 3, (10, 3), split=0) # 10 filters of length 3 >>> ht.convolve(a, v) # batch processing: 10 signals convolved with 10 filters DNDarray([[ 0., 0., 2., 4., 6., 8., 0.], [ 5., 6., 7., 8., 9., 0., 0.], [ 20., 42., 56., 61., 66., 41., 14.], [ 0., 15., 16., 17., 18., 19., 0.], [ 20., 61., 64., 67., 70., 48., 0.], [ 50., 52., 104., 108., 112., 56., 58.], [ 0., 30., 61., 63., 65., 67., 34.], [ 35., 106., 109., 112., 115., 78., 0.], [ 0., 40., 81., 83., 85., 87., 44.], [ 0., 0., 45., 46., 47., 48., 49.]], dtype=ht.float64, device=cpu:0, split=0) .. function:: vmap(func: Callable[[Tuple[torch.Tensor]], Tuple[torch.Tensor]], out_dims: Union[Tuple[int], int] = 0, randomness: str = 'error', *, chunk_size: int = None) -> Callable[[Tuple[heat.core.dndarray.DNDarray]], Tuple[heat.core.dndarray.DNDarray]] Apply a function to a DNDarray in a vectorized way. `heat.vmap` return a callable that can be applied to DNDarrays. Vectorization will automatically take place along the split axis/axes of the DNDarray(s); therefore, unlike in PyTorch, there is no argument `in_dims`. What we here refer to as "split axis/dimension" in the Heat terminology is often referred to as "batch axis/dimension" in the PyTorch terminology. :param func: The function to apply in a vmapped way to the DNDarray(s). It must take PyTorch tensor(s) as positional arguments. Additional parameters, not to be vmapped over, can be passed as keyword arguments. The callable returned by by `heat.vmap` will also accept these keyword arguments. :type func: callable :param out_dims: The dimensions of the output(s) that are mapped over; identical to the split dimension(s) of the output(s). Default is 0. :type out_dims: int or tuple of int, optional :param randomness: Determines how to handle randomness in the function to be vmapped. This argument is directly passed to the underlying PyTorch vmaps; see the corresponding PyTorch documentation for more information and the note below. If 'error' (default), an error is raised if the function to be mapped contains randomness. :type randomness: {'error', 'different', 'same'}, optional :param chunk_size: The size of the chunks to use for the process-local computation. If None (default), apply a single PyTorch vmap over the process-local chunks of data. If not None, then compute the process-local PyTorch vmap `chunk_size` many samples at a time. Note that `chunk_size=1` is equivalent to computing the process-local PyTorch vmap's with a for-loop. If you run into memory issues computing the vmap, please try a non-None chunk_size. :type chunk_size: int, optional .. note:: This function is a wrapper around PyTorch's `torch.vmap` function. In essence, a PyTorch vmap is applied to the input function `func` on each MPI process separately. This process-local PyTorch-vmapped function is then applied to the process-local chunks of the input DNDarray(s). Please note that the options 'same' and 'different' for `randomness` will result in behaviour different from the one known by PyTorch as (at least currently) no actions are taken to synchronize randomness across the MPI processes. .. py:class:: MPILibrary(*args, **kwds) Bases: :class:`enum.Enum` Create a collection of name/value pairs. Example enumeration: >>> class Color(Enum): ... RED = 1 ... BLUE = 2 ... GREEN = 3 Access them by: - attribute access:: >>> Color.RED - value lookup: >>> Color(1) - name lookup: >>> Color['RED'] Enumerations can be iterated over, and know how many members they have: >>> len(Color) 3 >>> list(Color) [, , ] Methods can be added to enumerations, and members can have their own attributes -- see the documentation for details. .. attribute:: OpenMPI :annotation: = 'ompi' .. attribute:: IntelMPI :annotation: = 'impi' .. attribute:: MVAPICH :annotation: = 'mvapich' .. attribute:: MPICH :annotation: = 'mpich' .. attribute:: CrayMPI :annotation: = 'craympi' .. attribute:: ParaStationMPI :annotation: = 'psmpi' .. attribute:: Other :annotation: = 'other' .. role:: raw-html(raw) :format: html .. py:class:: MPILibraryInfo .. attribute:: name :annotation: :MPILibrary .. attribute:: version :annotation: :str .. role:: raw-html(raw) :format: html .. function:: _get_mpi_library() -> MPILibraryInfo .. function:: _check_gpu_aware_mpi(library: MPILibraryInfo) -> tuple[bool, bool] .. function:: condest(A: heat.core.dndarray.DNDarray, p: Union[int, str] = None, algorithm: str = 'randomized', params: list = None) -> heat.core.dndarray.DNDarray Computes a (possibly randomized) upper estimate of the l2-condition number of the input 2D DNDarray. :param A: The matrix, i.e., a 2D DNDarray, for which the condition number shall be estimated. :type A: DNDarray :param p: The norm to use for the condition number computation. If None, the l2-norm (default, p=2) is used. So far, only p=2 is implemented. :type p: int or str (optional) :param algorithm: The algorithm to use for the estimation. Currently, only "randomized" (default) is implemented. :type algorithm: str :param params: A list of parameters required for the chosen algorithm; if not provided, default values for the respective algorithm are chosen. If `algorithm="randomized"` the number of random samples to use can be specified under the key "nsamples"; default is 10. :type params: dict (optional) .. rubric:: Notes The "randomized" algorithm follows the approach described in [1]; note that in the paper actually the condition number w.r.t. the Frobenius norm is estimated. However, this yields an upper bound for the condition number w.r.t. the l2-norm as well. .. rubric:: References [1] T. Gudmundsson, C. S. Kenney, and A. J. Laub. Small-Sample Statistical Estimates for Matrix Norms. SIAM Journal on Matrix Analysis and Applications 1995 16:3, 776-792. .. function:: cross(a: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray, axisa: int = -1, axisb: int = -1, axisc: int = -1, axis: int = -1) -> heat.core.dndarray.DNDarray Returns the cross product. 2D vectors will we converted to 3D. :param a: First input array. :type a: DNDarray :param b: Second input array. Must have the same shape as 'a'. :type b: DNDarray :param axisa: Axis of `a` that defines the vector(s). By default, the last axis. :type axisa: int :param axisb: Axis of `b` that defines the vector(s). By default, the last axis. :type axisb: int :param axisc: Axis of the output containing the cross product vector(s). By default, the last axis. :type axisc: int :param axis: Axis that defines the vectors for which to compute the cross product. Overrides `axisa`, `axisb` and `axisc`. Default: -1 :type axis: int :raises ValueError: If the two input arrays don't match in shape, split, device, or comm. If the vectors are along the split axis. :raises TypeError: If 'axis' is not an integer. .. rubric:: Examples >>> a = ht.eye(3) >>> b = ht.array([[0, 1, 0], [0, 0, 1], [1, 0, 0]]) >>> cross = ht.cross(a, b) DNDarray([[0., 0., 1.], [1., 0., 0.], [0., 1., 0.]], dtype=ht.float32, device=cpu:0, split=None) .. function:: det(a: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Returns the determinant of a square matrix. :param a: A square matrix or a stack of matrices. Shape = (...,M,M) :type a: DNDarray :raises RuntimeError: If the dtype of 'a' is not floating-point. :raises RuntimeError: If `a.ndim < 2` or if the length of the last two dimensions is not the same. .. rubric:: Examples >>> a = ht.array([[-2, -1, 2], [2, 1, 4], [-3, 3, -1]]) >>> ht.linalg.det(a) DNDarray(54., dtype=ht.float64, device=cpu:0, split=None) .. function:: dot(a: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> Union[heat.core.dndarray.DNDarray, float] Returns the dot product of two ``DNDarrays``. Specifically, 1. If both a and b are 1-D arrays, it is inner product of vectors. 2. If both a and b are 2-D arrays, it is matrix multiplication, but using matmul or ``a@b`` is preferred. 3. If either a or b is 0-D (scalar), it is equivalent to multiply and using ``multiply(a, b)`` or ``a*b`` is preferred. :param a: First input DNDarray :type a: DNDarray :param b: Second input DNDarray :type b: DNDarray :param out: Output buffer. :type out: DNDarray, optional .. seealso:: :py:obj:`vecdot` Supports (vector) dot along an axis. .. function:: inv(a: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Computes the multiplicative inverse of a square matrix. :param a: Square matrix of floating-point data type or a stack of square matrices. Shape = (...,M,M) :type a: DNDarray :raises RuntimeError: If the inverse does not exist. :raises RuntimeError: If the dtype is not floating-point :raises RuntimeError: If a is not at least two-dimensional or if the lengths of the last two dimensions are not the same. .. rubric:: Examples >>> a = ht.array([[1.0, 2], [2, 3]]) >>> ht.linalg.inv(a) DNDarray([[-3., 2.], [ 2., -1.]], dtype=ht.float32, device=cpu:0, split=None) .. function:: matmul(a: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray, allow_resplit: bool = False) -> heat.core.dndarray.DNDarray Matrix multiplication of two ``DNDarrays``: ``a@b=c`` or ``A@B=c``. Returns a tensor with the result of ``a@b``. The split dimension of the returned array is typically the split dimension of a. If both are ``None`` and if ``allow_resplit=False`` then ``c.split`` is also ``None``. Batched inputs (with batch dimensions being leading dimensions) are allowed; see also the Notes below. :param a: matrix :math:`L \times P` or vector :math:`P` or batch of matrices: :math:`B_1 \times ... \times B_k \times L \times P` :type a: DNDarray :param b: matrix :math:`P \times Q` or vector :math:`P` or batch of matrices: :math:`B_1 \times ... \times B_k \times P \times Q` :type b: DNDarray :param allow_resplit: Whether to distribute ``a`` in the case that both ``a.split is None`` and ``b.split is None``. Default is ``False``. If ``True``, if both are not split then ``a`` will be distributed in-place along axis 0. :type allow_resplit: bool, optional .. rubric:: Notes - For batched inputs, batch dimensions must coincide and if one matrix is split along a batch axis the other must be split along the same axis. - If ``a`` or ``b`` is a vector the result will also be a vector. - We recommend to avoid the particular split combinations ``1``-``0``, ``None``-``0``, and ``1``-``None`` (for ``a.split``-``b.split``) due to their comparably high memory consumption, if possible. Applying ``DNDarray.resplit_`` or ``heat.resplit`` on one of the two factors before calling ``matmul`` in these situations might improve performance of your code / might avoid memory bottlenecks. .. rubric:: References [1] R. Gu, et al., "Improving Execution Concurrency of Large-scale Matrix Multiplication on Distributed Data-parallel Platforms," IEEE Transactions on Parallel and Distributed Systems, vol 28, no. 9. 2017. [2] S. Ryu and D. Kim, "Parallel Huge Matrix Multiplication on a Cluster with GPGPU Accelerators," 2018 IEEE International Parallel and Distributed Processing Symposium Workshops (IPDPSW), Vancouver, BC, 2018, pp. 877-882. .. rubric:: Examples >>> a = ht.ones((n, m), split=1) >>> a[0] = ht.arange(1, m + 1) >>> a[:, -1] = ht.arange(1, n + 1).larray [0/1] tensor([[1., 2.], [1., 1.], [1., 1.], [1., 1.], [1., 1.]]) [1/1] tensor([[3., 1.], [1., 2.], [1., 3.], [1., 4.], [1., 5.]]) >>> b = ht.ones((j, k), split=0) >>> b[0] = ht.arange(1, k + 1) >>> b[:, 0] = ht.arange(1, j + 1).larray [0/1] tensor([[1., 2., 3., 4., 5., 6., 7.], [2., 1., 1., 1., 1., 1., 1.]]) [1/1] tensor([[3., 1., 1., 1., 1., 1., 1.], [4., 1., 1., 1., 1., 1., 1.]]) >>> linalg.matmul(a, b).larray [0/1] tensor([[18., 8., 9., 10.], [14., 6., 7., 8.], [18., 7., 8., 9.], [22., 8., 9., 10.], [26., 9., 10., 11.]]) [1/1] tensor([[11., 12., 13.], [ 9., 10., 11.], [10., 11., 12.], [11., 12., 13.], [12., 13., 14.]]) .. function:: matrix_norm(x: heat.core.dndarray.DNDarray, axis: Optional[Tuple[int, int]] = None, keepdims: bool = False, ord: Optional[Union[int, str]] = None) -> heat.core.dndarray.DNDarray Computes the matrix norm of an array. :param x: Input array :type x: DNDarray :param axis: Both axes of the matrix. If `None` 'x' must be a matrix. Default: `None` :type axis: tuple, optional :param keepdims: Retains the reduced dimension when `True`. Default: `False` :type keepdims: bool, optional :param ord: The matrix norm order to compute. If `None` the Frobenius norm (`'fro'`) is used. Default: `None` :type ord: int, 'fro', 'nuc', optional .. seealso:: :py:obj:`norm` Computes the vector or matrix norm of an array. :py:obj:`vector_norm` Computes the vector norm of an array. .. rubric:: Notes The following norms are supported: ===== ============================ ord norm for matrices ===== ============================ None Frobenius norm 'fro' Frobenius norm 'nuc' nuclear norm inf max(sum(abs(x), axis=1)) -inf min(sum(abs(x), axis=1)) 1 max(sum(abs(x), axis=0)) -1 min(sum(abs(x), axis=0)) ===== ============================ The following matrix norms are currently **not** supported: ===== ============================ ord norm for matrices ===== ============================ 2 largest singular value -2 smallest singular value ===== ============================ :raises TypeError: If axis is not a 2-tuple :raises ValueError: If an invalid matrix norm is given or 'x' is a vector. .. rubric:: Examples >>> ht.matrix_norm(ht.array([[1, 2], [3, 4]])) DNDarray([[5.4772]], dtype=ht.float64, device=cpu:0, split=None) >>> ht.matrix_norm(ht.array([[1, 2], [3, 4]]), keepdims=True, ord=-1) DNDarray([[4.]], dtype=ht.float64, device=cpu:0, split=None) .. function:: matrix_exp(A: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Computes the matrix exponential of a square matrix. Letting :math:`\mathbb{K}` be :math:`\mathbb{R}` or :math:`\mathbb{C}`, this function computes the **matrix exponential** of :math:`A \in \mathbb{K}^{n \times n}`, which is defined as .. math:: \mathrm{matrix\_exp}(A) = \sum_{k=0}^\infty \frac{1}{k!}A^k \in \mathbb{K}^{n \times n}. If the matrix :math:`A` has eigenvalues :math:`\lambda_i \in \mathbb{C}`, the matrix :math:`\mathrm{matrix\_exp}(A)` has eigenvalues :math:`e^{\lambda_i} \in \mathbb{C}`. Supports input of bfloat16, float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if :attr:`A` is a batch of matrices then the output has the same batch dimensions. .. note:: A may only be distributed in the batch dimensions. .. seealso:: :func:`torch.linalg.matrix_exp` is called under the hood on the local data. :param A: DNDarray of shape `(*, n, n)` where `*` is zero or more batch dimensions. :type A: DNDarray Example:: >>> A = ht.empty((2, 2, 2), split=0) >>> A[0, :, :] = ht.eye((2, 2)) >>> A[1, :, :] = 2 * ht.eye((2, 2)) >>> ht.linalg.matrix_exp(A) DNDarray([[[2.7183, 0.0000], [0.0000, 2.7183]], [[7.3891, 0.0000], [0.0000, 7.3891]]], dtype=ht.float32, device=cpu:0, split=0) .. data:: expm Alias for :py:func:`matrix_exp` .. function:: norm(x: heat.core.dndarray.DNDarray, axis: Optional[Union[int, Tuple[int, int]]] = None, keepdims: bool = False, ord: Optional[Union[int, float, str]] = None) -> heat.core.dndarray.DNDarray Return the vector or matrix norm of an array. :param x: Input vector :type x: DNDarray :param axis: Axes along which to compute the norm. If an integer, vector norm is used. If a 2-tuple, matrix norm is used. If `None`, it is inferred from the dimension of the array. Default: `None` :type axis: int, tuple, optional :param keepdims: Retains the reduced dimension when `True`. Default: `False` :type keepdims: bool, optional :param ord: The norm order to compute. See Notes :type ord: int, float, inf, -inf, 'fro', 'nuc' .. seealso:: :py:obj:`vector_norm` Computes the vector norm of an array. :py:obj:`matrix_norm` Computes the matrix norm of an array. .. rubric:: Notes The following norms are supported: ===== ============================ ========================== ord norm for matrices norm for vectors ===== ============================ ========================== None Frobenius norm L2-norm (Euclidean) 'fro' Frobenius norm -- 'nuc' nuclear norm -- inf max(sum(abs(x), axis=1)) max(abs(x)) -inf min(sum(abs(x), axis=1)) min(abs(x)) 0 -- sum(x != 0) 1 max(sum(abs(x), axis=0)) L1-norm (Manhattan) -1 min(sum(abs(x), axis=0)) 1./sum(1./abs(a)) 2 -- L2-norm (Euclidean) -2 -- 1./sqrt(sum(1./abs(a)**2)) other -- sum(abs(x)**ord)**(1./ord) ===== ============================ ========================== The following matrix norms are currently **not** supported: ===== ============================ ord norm for matrices ===== ============================ 2 largest singular value -2 smallest singular value ===== ============================ :raises ValueError: If 'axis' has more than 2 elements .. rubric:: Examples >>> from heat import linalg as LA >>> a = ht.arange(9, dtype=ht.float) - 4 >>> a DNDarray([-4., -3., -2., -1., 0., 1., 2., 3., 4.], dtype=ht.float32, device=cpu:0, split=None) >>> b = a.reshape((3, 3)) >>> b DNDarray([[-4., -3., -2.], [-1., 0., 1.], [ 2., 3., 4.]], dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(a) DNDarray(7.7460, dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(b) DNDarray(7.7460, dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(b, ord="fro") DNDarray(7.7460, dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(a, float("inf")) DNDarray([4.], dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(b, ht.inf) DNDarray([9.], dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(a, -ht.inf)) DNDarray([0.], dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(b, -ht.inf) DNDarray([2.], dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(a, 1) DNDarray([20.], dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(b, 1) DNDarray([7.], dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(a, -1) DNDarray([0.], dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(b, -1) DNDarray([6.], dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(a, 2) DNDarray(7.7460, dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(a, -2) DNDarray([0.], dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(a, 3) DNDarray([5.8480], dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(a, -3) DNDarray([0.], dtype=ht.float32, device=cpu:0, split=None) c = ht.array([[ 1, 2, 3], [-1, 1, 4]]) >>> LA.norm(c, axis=0) DNDarray([1.4142, 2.2361, 5.0000], dtype=ht.float64, device=cpu:0, split=None) >>> LA.norm(c, axis=1) DNDarray([3.7417, 4.2426], dtype=ht.float64, device=cpu:0, split=None) >>> LA.norm(c, axis=1, ord=1) DNDarray([6., 6.], dtype=ht.float64, device=cpu:0, split=None) >>> m = ht.arange(8).reshape(2, 2, 2) >>> LA.norm(m, axis=(1, 2)) DNDarray([ 3.7417, 11.2250], dtype=ht.float32, device=cpu:0, split=None) >>> LA.norm(m[0, :, :]), LA.norm(m[1, :, :]) (DNDarray(3.7417, dtype=ht.float32, device=cpu:0, split=None), DNDarray(11.2250, dtype=ht.float32, device=cpu:0, split=None)) .. function:: outer(a: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None, split: Optional[int] = None) -> heat.core.dndarray.DNDarray Compute the outer product of two 1-D DNDarrays: :math:`out(i, j) = a(i) \times b(j)`. Given two vectors, :math:`a = (a_0, a_1, ..., a_N)` and :math:`b = (b_0, b_1, ..., b_M)`, the outer product is: .. math:: :nowrap: \begin{pmatrix} a_0 \cdot b_0 & a_0 \cdot b_1 & . & . & a_0 \cdot b_M \\ a_1 \cdot b_0 & a_1 \cdot b_1 & . & . & a_1 \cdot b_M \\ . & . & . & . & . \\ a_N \cdot b_0 & a_N \cdot b_1 & . & . & a_N \cdot b_M \end{pmatrix} :param a: 1-dimensional: :math:`N` Will be flattened by default if more than 1-D. :type a: DNDarray :param b: 1-dimensional: :math:`M` Will be flattened by default if more than 1-D. :type b: DNDarray :param out: 2-dimensional: :math:`N \times M` A location where the result is stored :type out: DNDarray, optional :param split: Split dimension of the resulting DNDarray. Can be 0, 1, or None. This is only relevant if the calculations are memory-distributed. Default is ``split=0`` (see Notes). :type split: int, optional .. rubric:: Notes Parallel implementation of outer product, assumes arrays are dense. In the classical (dense) case, one of the two arrays needs to be communicated around the processes in a ring. * Sending ``b`` around in a ring results in ``outer`` being split along the rows (``outer.split = 0``). * Sending ``a`` around in a ring results in ``outer`` being split along the columns (``outer.split = 1``). So, if specified, ``split`` defines which ``DNDarray`` stays put and which one is passed around. If ``split`` is ``None`` or unspecified, the result will be distributed along axis ``0``, i.e. by default ``b`` is passed around, ``a`` stays put. .. rubric:: Examples >>> a = ht.arange(4) >>> b = ht.arange(3) >>> ht.outer(a, b).larray (3 processes) [0/2] tensor([[0, 0, 0], [0, 1, 2], [0, 2, 4], [0, 3, 6]], dtype=torch.int32) [1/2] tensor([[0, 0, 0], [0, 1, 2], [0, 2, 4], [0, 3, 6]], dtype=torch.int32) [2/2] tensor([[0, 0, 0], [0, 1, 2], [0, 2, 4], [0, 3, 6]], dtype=torch.int32) >>> a = ht.arange(4, split=0) >>> b = ht.arange(3, split=0) >>> ht.outer(a, b).larray [0/2] tensor([[0, 0, 0], [0, 1, 2]], dtype=torch.int32) [1/2] tensor([[0, 2, 4]], dtype=torch.int32) [2/2] tensor([[0, 3, 6]], dtype=torch.int32) >>> ht.outer(a, b, split=1).larray [0/2] tensor([[0], [0], [0], [0]], dtype=torch.int32) [1/2] tensor([[0], [1], [2], [3]], dtype=torch.int32) [2/2] tensor([[0], [2], [4], [6]], dtype=torch.int32) >>> a = ht.arange(5, dtype=ht.float32, split=0) >>> b = ht.arange(4, dtype=ht.float64, split=0) >>> out = ht.empty((5,4), dtype=ht.float64, split=1) >>> ht.outer(a, b, split=1, out=out) >>> out.larray [0/2] tensor([[0., 0.], [0., 1.], [0., 2.], [0., 3.], [0., 4.]], dtype=torch.float64) [1/2] tensor([[0.], [2.], [4.], [6.], [8.]], dtype=torch.float64) [2/2] tensor([[ 0.], [ 3.], [ 6.], [ 9.], [12.]], dtype=torch.float64) .. function:: projection(a: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Projection of vector ``a`` onto vector ``b`` :param a: The vector to be projected. Must be a 1D ``DNDarray`` :type a: DNDarray :param b: The vector to project onto. Must be a 1D ``DNDarray`` :type b: DNDarray .. function:: trace(a: heat.core.dndarray.DNDarray, offset: Optional[int] = 0, axis1: Optional[int] = 0, axis2: Optional[int] = 1, dtype: Optional[heat.core.types.datatype] = None, out: Optional[heat.core.dndarray.DNDarray] = None) -> Union[heat.core.dndarray.DNDarray, float] Return the sum along diagonals of the array If `a` is 2D, the sum along its diagonal with the given offset is returned, i.e. the sum of elements a[i, i+offset] for all i. If `a` has more than two dimensions, then the axes specified by `axis1` and `axis2` are used to determine the 2D-sub-DNDarrays whose traces are returned. The shape of the resulting array is the same as that of `a` with `axis1` and `axis2` removed. :param a: Input array, from which the diagonals are taken :type a: array_like :param offset: Offsets of the diagonal from the main diagonal. Can be both positive and negative. Defaults to 0. :type offset: int, optional :param axis1: Axis to be used as the first axis of the 2D-sub-arrays from which the diagonals should be taken. Default is the first axis of `a` :type axis1: int, optional :param axis2: Axis to be used as the second axis of the 2D-sub-arrays from which the diagonals should be taken. Default is the second two axis of `a` :type axis2: int, optional :param dtype: Determines the data-type of the returned array and of the accumulator where the elements are summed. If `dtype` has value None than the dtype is the same as that of `a` :type dtype: dtype, optional :param out: Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output Only applicable if `a` has more than 2 dimensions, thus the result is not a scalar. If distributed, its split axis might change eventually. :type out: ht.DNDarray, optional :returns: **sum_along_diagonals** -- If `a` is 2D, the sum along the diagonal is returned as a scalar If `a` has more than 2 dimensions, then a DNDarray of sums along diagonals is returned :rtype: number (of defined dtype) or ht.DNDarray .. rubric:: Examples 2D-case >>> x = ht.arange(24).reshape((4, 6)) >>> x DNDarray([[ 0, 1, 2, 3, 4, 5], [ 6, 7, 8, 9, 10, 11], [12, 13, 14, 15, 16, 17], [18, 19, 20, 21, 22, 23]], dtype=ht.int32, device=cpu:0, split=None) >>> ht.trace(x) 42 >>> ht.trace(x, 1) 46 >>> ht.trace(x, -2) 31 > 2D-case >>> x = x.reshape((2, 3, 4)) >>> x DNDarray([[[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11]], [[12, 13, 14, 15], [16, 17, 18, 19], [20, 21, 22, 23]]], dtype=ht.int32, device=cpu:0, split=None) >>> ht.trace(x) DNDarray([16, 18, 20, 22], dtype=ht.int32, device=cpu:0, split=None) >>> ht.trace(x, 1) DNDarray([24, 26, 28, 30], dtype=ht.int32, device=cpu:0, split=None) >>> ht.trace(x, axis1=0, axis2=2) DNDarray([13, 21, 29], dtype=ht.int32, device=cpu:0, split=None) .. function:: transpose(a: heat.core.dndarray.DNDarray, axes: Optional[List[int]] = None) -> heat.core.dndarray.DNDarray Permute the dimensions of an array. :param a: Input array. :type a: DNDarray :param axes: By default, reverse the dimensions, otherwise permute the axes according to the values given. :type axes: None or List[int,...], optional .. function:: tril(m: heat.core.dndarray.DNDarray, k: int = 0) -> heat.core.dndarray.DNDarray Returns the lower triangular part of the ``DNDarray``. The lower triangular part of the array is defined as the elements on and below the diagonal, the other elements of the result array are set to 0. The argument ``k`` controls which diagonal to consider. If ``k=0``, all elements on and below the main diagonal are retained. A positive value includes just as many diagonals above the main diagonal, and similarly a negative value excludes just as many diagonals below the main diagonal. :param m: Input array for which to compute the lower triangle. :type m: DNDarray :param k: Diagonal above which to zero elements. ``k=0`` (default) is the main diagonal, ``k<0`` is below and ``k>0`` is above. :type k: int, optional .. function:: triu(m: heat.core.dndarray.DNDarray, k: int = 0) -> heat.core.dndarray.DNDarray Returns the upper triangular part of the ``DNDarray``. The upper triangular part of the array is defined as the elements on and below the diagonal, the other elements of the result array are set to 0. The argument ``k`` controls which diagonal to consider. If ``k=0``, all elements on and below the main diagonal are retained. A positive value includes just as many diagonals above the main diagonal, and similarly a negative value excludes just as many diagonals below the main diagonal. :param m: Input array for which to compute the upper triangle. :type m: DNDarray :param k: Diagonal above which to zero elements. ``k=0`` (default) is the main diagonal, ``k<0`` is below and ``k>0`` is above. :type k: int, optional .. function:: vdot(x1: heat.core.dndarray.DNDarray, x2: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Computes the dot product of two vectors. Higher-dimensional arrays will be flattened. :param x1: first input array. If it's complex, it's complex conjugate will be used. :type x1: DNDarray :param x2: second input array. :type x2: DNDarray :raises ValueError: If the number of elements is inconsistent. .. seealso:: :py:obj:`dot` Return the dot product without using the complex conjugate. .. rubric:: Examples >>> a = ht.array([1 + 1j, 2 + 2j]) >>> b = ht.array([1 + 2j, 3 + 4j]) >>> ht.vdot(a, b) DNDarray([(17+3j)], dtype=ht.complex64, device=cpu:0, split=None) >>> ht.vdot(b, a) DNDarray([(17-3j)], dtype=ht.complex64, device=cpu:0, split=None) .. function:: vecdot(x1: heat.core.dndarray.DNDarray, x2: heat.core.dndarray.DNDarray, axis: Optional[int] = None, keepdims: Optional[bool] = None) -> heat.core.dndarray.DNDarray Computes the (vector) dot product of two DNDarrays. :param x1: first input array. :type x1: DNDarray :param x2: second input array. Must be compatible with x1. :type x2: DNDarray :param axis: axis over which to compute the dot product. The last dimension is used if 'None'. :type axis: int, optional :param keepdims: If this is set to 'True', the axes which are reduced are left in the result as dimensions with size one. :type keepdims: bool, optional .. seealso:: :py:obj:`dot` NumPy-like dot function. .. rubric:: Examples >>> ht.vecdot(ht.full((3, 3, 3), 3), ht.ones((3, 3)), axis=0) DNDarray([[9., 9., 9.], [9., 9., 9.], [9., 9., 9.]], dtype=ht.float32, device=cpu:0, split=None) .. function:: vector_norm(x: heat.core.dndarray.DNDarray, axis: Optional[Union[int, Tuple[int]]] = None, keepdims=False, ord: Optional[Union[int, float]] = None) -> heat.core.dndarray.DNDarray Computes the vector norm of an array. :param x: Input array :type x: DNDarray :param axis: Axis along which to compute the vector norm. If `None` 'x' must be a vector. Default: `None` :type axis: int, tuple, optional :param keepdims: Retains the reduced dimension when `True`. Default: `False` :type keepdims: bool, optional :param ord: The norm order to compute. If `None` the euclidean norm (`2`) is used. Default: `None` :type ord: int, float, optional .. seealso:: :py:obj:`norm` Computes the vector norm or matrix norm of an array. :py:obj:`matrix_norm` Computes the matrix norm of an array. .. rubric:: Notes The following norms are suported: ===== ========================== ord norm for vectors ===== ========================== None L2-norm (Euclidean) inf max(abs(x)) -inf min(abs(x)) 0 sum(x != 0) 1 L1-norm (Manhattan) -1 1./sum(1./abs(a)) 2 L2-norm (Euclidean) -2 1./sqrt(sum(1./abs(a)**2)) other sum(abs(x)**ord)**(1./ord) ===== ========================== :raises TypeError: If axis is not an integer or a 1-tuple :raises ValueError: If an invalid vector norm is given. .. rubric:: Examples >>> ht.vector_norm(ht.array([1, 2, 3, 4])) DNDarray([5.4772], dtype=ht.float64, device=cpu:0, split=None) >>> ht.vector_norm(ht.array([[1, 2], [3, 4]]), axis=0, ord=1) DNDarray([[4., 6.]], dtype=ht.float64, device=cpu:0, split=None) .. function:: cg(A: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray, x0: heat.core.dndarray.DNDarray, out: Optional[heat.core.dndarray.DNDarray] = None) -> heat.core.dndarray.DNDarray Conjugate gradients method for solving a system of linear equations :math: `Ax = b` :param A: 2D symmetric, positive definite Matrix :type A: DNDarray :param b: 1D vector :type b: DNDarray :param x0: Arbitrary 1D starting vector :type x0: DNDarray :param out: Output Vector :type out: DNDarray, optional .. function:: lanczos(A: heat.core.dndarray.DNDarray, m: int, v0: Optional[heat.core.dndarray.DNDarray] = None, V_out: Optional[heat.core.dndarray.DNDarray] = None, T_out: Optional[heat.core.dndarray.DNDarray] = None) -> Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] The Lanczos algorithm is an iterative approximation of the solution to the eigenvalue problem, as an adaptation of power methods to find the m "most useful" (tending towards extreme highest/lowest) eigenvalues and eigenvectors of an :math:`n \times n` Hermitian matrix, where often :math:`m< heat.core.dndarray.DNDarray Computes the solution of a square system of linear equations with a unique solution. Letting :math:`\mathbb{K}` be :math:`\mathbb{R}` or :math:`\mathbb{C}`, this function computes the solution :math:`X \in \mathbb{K}^{n \times k}` of the **linear system** associated to :math:`A \in \mathbb{K}^{n \times n}, B \in \mathbb{K}^{n \times k}`, which is defined as .. math:: AX = B Supports inputs of integer, float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if the inputs are batches of matrices then the output has the same batch dimensions. Letting `*` be zero or more batch dimensions, - If :attr:`A` has shape `(*, n, n)` and :attr:`B` has shape `(*, n)` (a batch of vectors) or shape `(*, n, k)` (a batch of matrices or "multiple right-hand sides"), this function returns `X` of shape `(*, n)` or `(*, n, k)` respectively. - Otherwise, if :attr:`A` has shape `(*, n, n)` and :attr:`B` has shape `(n,)` or `(n, k)`, :attr:`B` is broadcast to have shape `(*, n)` or `(*, n, k)` respectively. This function then returns the solution of the resulting batch of systems of linear equations. .. note:: A and b may only be distributed in the batch dimensions. If both are split, they must be split along matching batch axes. .. seealso:: :func:`torch.linalg.solve` is called under the hood on the local data. This docstring is also heavily inspired by the docstring of this function. :param A: Matrix to be inverted of shape `(*, n, n)` where `*` is zero or more batch dimensions :type A: DNDarray :param b: Right-hand side of shape `(*, n)` or `(*, n, k)` or `(n,)` or `(n, k)` :type b: DNDarray :param out: Output Vector :type out: DNDarray, optional :param Examples::: >>> A = ht.random.randn(3, 3) >>> b = ht.random.randn(3) >>> x = ht.linalg.solve(A, b) >>> ht.allclose(A @ x, b, atol=1e-5) True >>> A = ht.random.randn(2, 3, 3, split=0) >>> B = ht.random.randn(2, 3, 4, split=0) >>> X = ht.linalg.solve(A, B) >>> X.shape (2, 3, 4) >>> ht.allclose(A @ X, B, atol=1e-5) True >>> A = ht.random.randn(2, 3, 3, split=None) >>> B = ht.random.randn(2, 3, 4, split=2) >>> X = ht.linalg.solve(A, B) >>> X.split 2 >>> ht.allclose(A @ X, B, atol=1e-5) True >>> A = ht.random.randn(2, 3, 3, split=0) >>> b = ht.random.randn(3, 1) >>> x = ht.linalg.solve(A, b) # b is broadcast to size (2, 3, 1) >>> x.shape (2, 3, 1) >>> x.split 0 >>> ht.allclose((A @ x).resplit_(None), b, atol=1e-5) True .. function:: solve_triangular(A: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray Solver for (possibly batched) upper triangular systems of linear equations: it returns `x` in `Ax = b`, where `A` is a (possibly batched) upper triangular matrix and `b` a (possibly batched) vector or matrix of suitable shape, both provided as input to the function. The implementation builts on the corresponding solver in PyTorch and implements an memory-distributed, MPI-parallel block-wise version thereof. :param A: An upper triangular invertible square (n x n) matrix or a batch thereof, i.e. a ``DNDarray`` of shape `(..., n, n)`. :type A: DNDarray :param b: a (possibly batched) n x k matrix, i.e. an DNDarray of shape (..., n, k), where the batch-dimensions denoted by ... need to coincide with those of A. (Batched) Vectors have to be provided as ... x n x 1 matrices and the split dimension of b must the second last dimension if not None. :type b: DNDarray .. note:: Since such a check might be computationally expensive, we do not check whether A is indeed upper triangular. If you require such a check, please open an issue on our GitHub page and request this feature. .. function:: qr(A: heat.core.dndarray.DNDarray, mode: str = 'reduced', procs_to_merge: int = 2) -> Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] Calculates the QR decomposition of a 2D ``DNDarray``. Factor the matrix ``A`` as *QR*, where ``Q`` is orthonormal and ``R`` is upper-triangular. If ``mode = "reduced"``, function returns ``QR(Q=Q, R=R)``, if ``mode = "r"`` function returns ``QR(Q=None, R=R)`` This function also works for batches of matrices; in this case, the last two dimensions of the input array are considered as the matrix dimensions. The output arrays have the same leading batch dimensions as the input array. :param A: Array which will be decomposed. :type A: DNDarray of shape (M, N), of shape (...,M,N) in the batched case :param mode: default "reduced" returns Q and R with dimensions (M, min(M,N)) and (min(M,N), N). Potential batch dimensions are not modified. "r" returns only R, with dimensions (min(M,N), N). :type mode: str, optional :param procs_to_merge: This parameter is only relevant for split=0 (-2, in the batched case) and determines the number of processes to be merged at one step during the so-called TS-QR algorithm. The default is 2. Higher choices might be faster, but will probably result in higher memory consumption. 0 corresponds to merging all processes at once. We only recommend to modify this parameter if you are familiar with the TS-QR algorithm (see the references below). :type procs_to_merge: int, optional .. rubric:: Notes The distribution schemes of ``Q`` and ``R`` depend on that of the input ``A``. - If ``A`` is distributed along the columns (A.split = 1), so will be ``Q`` and ``R``. - If ``A`` is distributed along the rows (A.split = 0), ``Q`` too will have `split=0`. ``R`` won't be distributed, i.e. `R. split = None`, if ``A`` is tall-skinny, i.e., if the largest local chunk of data of ``A`` has at least as many rows as columns. Otherwise, ``R`` will be distributed along the rows as well, i.e., `R.split = 0`. Note that the argument `calc_q` allowed in earlier Heat versions is no longer supported; `calc_q = False` is equivalent to `mode = "r"`. Unlike ``numpy.linalg.qr()``, `ht.linalg.qr` only supports ``mode="reduced"`` or ``mode="r"`` for the moment, since "complete" may result in heavy memory usage. Heats QR function is built on top of PyTorchs QR function, ``torch.linalg.qr()``, using LAPACK (CPU) and MAGMA (CUDA) on the backend. Both cases split=0 and split=1 build on a column-block-wise version of stabilized Gram-Schmidt orthogonalization. For split=1 (-1, in the batched case), this is directly applied to the local arrays of the input array. For split=0, a tall-skinny QR (TS-QR) is implemented for the case of tall-skinny matrices (i.e., the largest local chunk of data has at least as many rows as columns), and extended to non tall-skinny matrices by applying a block-wise version of stabilized Gram-Schmidt orthogonalization. .. rubric:: References Basic information about QR factorization/decomposition can be found at, e.g.: - https://en.wikipedia.org/wiki/QR_factorization, - Gene H. Golub and Charles F. Van Loan. 1996. Matrix Computations (3rd Ed.). For an extensive overview on TS-QR and its variants we refer to, e.g., - Demmel, James, et al. “Communication-Optimal Parallel and Sequential QR and LU Factorizations.” SIAM Journal on Scientific Computing, vol. 34, no. 1, 2 Feb. 2012, pp. A206–A239., doi:10.1137/080731992. .. function:: hsvd_rank(A: heat.core.dndarray.DNDarray, maxrank: int, compute_sv: bool = False, maxmergedim: Optional[int] = None, safetyshift: int = 5, silent: bool = True) -> Union[Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray, float], Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray], heat.core.dndarray.DNDarray] Hierarchical SVD (hSVD) with prescribed truncation rank `maxrank`. If A = U diag(sigma) V^T is the true SVD of A, this routine computes an approximation for U[:,:maxrank] (and sigma[:maxrank], V[:,:maxrank]). The accuracy of this approximation depends on the structure of A ("low-rank" is best) and appropriate choice of parameters. One can expect a similar outcome from this routine as for sci-kit learn's TruncatedSVD (with `algorithm='randomized'`) although a different, determinstic algorithm is applied here. Hereby, the parameters `n_components` and `n_oversamples` (sci-kit learn) roughly correspond to `maxrank` and `safetyshift` (see below). :param A: 2D-array (float32/64) of which the hSVD has to be computed. :type A: DNDarray :param maxrank: truncation rank. (This parameter corresponds to `n_components` in sci-kit learn's TruncatedSVD.) :type maxrank: int :param compute_sv: compute_sv=True implies that also Sigma and V.T are computed and returned. The default is False. :type compute_sv: bool, optional :param maxmergedim: maximal size of the concatenation matrices during the merging procedure. The default is None and results in an appropriate choice depending on the size of the local slices of A and maxrank. Too small choices for this parameter will result in failure if the maximal size of the concatenation matrices does not allow to merge at least two matrices. Too large choices for this parameter can cause memory errors if the resulting merging problem becomes too large. :type maxmergedim: int, optional :param safetyshift: Increases the actual truncation rank within the computations by a safety shift. The default is 5. (There is some similarity to `n_oversamples` in sci-kit learn's TruncatedSVD.) :type safetyshift: int, optional :param silent: silent=False implies that some information on the computations are printed. The default is True. :type silent: bool, optional :returns: if compute_sv=True: U, Sigma, V.T, a-posteriori error estimate for the reconstruction error ||A-U Sigma V^T ||_F / ||A||_F (computed according to [2] along the "true" merging tree). if compute_sv=False: U, a-posteriori error estimate :rtype: (Union[ Tuple[DNDarray, DNDarray, DNDarray, float], Tuple[DNDarray, DNDarray, DNDarray], DNDarray]) .. rubric:: Notes The size of the process local SVDs to be computed during merging is proportional to the non-split size of the input A and (maxrank + safetyshift). Therefore, conservative choice of maxrank and safetyshift is advised to avoid memory issues. Note that, as sci-kit learn's randomized SVD, this routine is different from `numpy.linalg.svd` because not all singular values and vectors are computed and even those computed may be inaccurate if the input matrix exhibts a unfavorable structure. Please note that "rank" in the context of SVD always refers to the number of singular values/vectors to compute (i.e., "rank" refers to the mathematical rank of a matrix). This is completely different from the notion of "(MPI-)rank", i.e., the ID given to a process, in a parallel MPI-application. .. seealso:: :func:`hsvd`, :func:`hsvd_rtol` .. rubric:: References [1] Iwen, Ong. A distributed and incremental SVD algorithm for agglomerative data analysis on large networks. SIAM J. Matrix Anal. Appl., 37(4), 2016. [2] Himpe, Leibner, Rave. Hierarchical approximate proper orthogonal decomposition. SIAM J. Sci. Comput., 40 (5), 2018. .. function:: hsvd_rtol(A: heat.core.dndarray.DNDarray, rtol: float, compute_sv: bool = False, maxrank: Optional[int] = None, maxmergedim: Optional[int] = None, safetyshift: int = 5, no_of_merges: Optional[int] = None, silent: bool = True) -> Union[Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray, float], Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray], heat.core.dndarray.DNDarray] Hierchical SVD (hSVD) with prescribed upper bound on the relative reconstruction error. If A = U diag(sigma) V^T is the true SVD of A, this routine computes an approximation for U[:,:r] (and sigma[:r], V[:,:r]) such that the rel. reconstruction error ||A-U[:,:r] diag(sigma[:r]) V[:,:r]^T ||_F / ||A||_F does not exceed rtol. The accuracy of this approximation depends on the structure of A ("low-rank" is best) and appropriate choice of parameters. This routine is similar to `hsvd_rank` with the difference that truncation is not performed after a fixed number (namly `maxrank` many) singular values but after such a number of singular values that suffice to capture a prescribed fraction of the amount of information contained in the input data (`rtol`). :param A: 2D-array (float32/64) of which the hSVD has to be computed. :type A: DNDarray :param rtol: desired upper bound on the relative reconstruction error ||A-U Sigma V^T ||_F / ||A||_F. This upper bound is processed into 'local' tolerances during the actual computations assuming the worst case scenario of a binary "merging tree"; therefore, the a-posteriori error for the relative error using the true "merging tree" (see output) may be significantly smaller than rtol. Prescription of maxrank or maxmergedim (disabled in default) can result in loss of desired precision, but can help to avoid memory issues. :type rtol: float :param compute_sv: compute_sv=True implies that also Sigma and V.T are computed and returned. The default is False. :type compute_sv: bool, optional :param no_of_merges: Maximum number of processes to be merged at each step. If no further arguments are provided (see below), this completely determines the "merging tree" and may cause memory issues. The default is None and results in a binary merging tree. Note that no_of_merges dominates maxrank and maxmergedim in the sense that at most no_of_merges processes are merged even if maxrank and maxmergedim would allow merging more processes. :type no_of_merges: int, optional :param maxrank: maximal truncation rank. The default is None. Setting at least one of maxrank and maxmergedim is recommended to avoid memory issues, but can result in loss of desired precision. Setting only maxrank (and not maxmergedim) results in an appropriate default choice for maxmergedim depending on the size of the local slices of A and the value of maxrank. :type maxrank: int, optional :param maxmergedim: maximal size of the concatenation matrices during the merging procedure. The default is None and results in an appropriate choice depending on the size of the local slices of A and maxrank. The default is None. Too small choices for this parameter will result in failure if the maximal size of the concatenation matrices does not allow to merge at least two matrices. Too large choices for this parameter can cause memory errors if the resulting merging problem becomes too large. Setting at least one of maxrank and maxmergedim is recommended to avoid memory issues, but can result in loss of desired precision. Setting only maxmergedim (and not maxrank) results in an appropriate default choice for maxrank. :type maxmergedim: int, optional :param safetyshift: Increases the actual truncation rank within the computations by a safety shift. The default is 5. :type safetyshift: int, optional :param silent: silent=False implies that some information on the computations are printed. The default is True. :type silent: bool, optional :returns: if compute_sv=True: U, Sigma, V.T, a-posteriori error estimate for the reconstruction error ||A-U Sigma V^T ||_F / ||A||_F (computed according to [2] along the "true" merging tree used in the computations). if compute_sv=False: U, a-posteriori error estimate :rtype: (Union[ Tuple[DNDarray, DNDarray, DNDarray, float], Tuple[DNDarray, DNDarray, DNDarray], DNDarray]) .. rubric:: Notes The maximum size of the process local SVDs to be computed during merging is proportional to the non-split size of the input A and (maxrank + safetyshift). Therefore, conservative choice of maxrank and safetyshift is advised to avoid memory issues. For similar reasons, prescribing only rtol and the number of processes to be merged in each step (without specifying maxrank or maxmergedim) may result in memory issues. Although prescribing maxrank is therefore strongly recommended to avoid memory issues, but may result in loss of desired precision (rtol). If this occures, a separate warning will be raised. Note that this routine is different from `numpy.linalg.svd` because not all singular values and vectors are computed and even those computed may be inaccurate if the input matrix exhibts a unfavorable structure. To avoid confusion, note that `rtol` in this routine does not have any similarity to `tol` in scikit learn's TruncatedSVD. Please note that "rank" in the context of SVD always refers to the number of singular values/vectors to compute (i.e., "rank" refers to the mathematical rank of a matrix). This is completely different from the notion of "(MPI-)rank", i.e., the ID given to a process, in a parallel MPI-application. .. seealso:: :func:`hsvd`, :func:`hsvd_rank` .. rubric:: References [1] Iwen, Ong. A distributed and incremental SVD algorithm for agglomerative data analysis on large networks. SIAM J. Matrix Anal. Appl., 37(4), 2016. [2] Himpe, Leibner, Rave. Hierarchical approximate proper orthogonal decomposition. SIAM J. Sci. Comput., 40 (5), 2018. .. function:: hsvd(A: heat.core.dndarray.DNDarray, maxrank: Optional[int] = None, maxmergedim: Optional[int] = None, rtol: Optional[float] = None, safetyshift: int = 0, no_of_merges: Optional[int] = 2, compute_sv: bool = False, silent: bool = True, warnings_off: bool = False) -> Union[Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray, float], Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray], heat.core.dndarray.DNDarray] Computes an approximate truncated SVD of A utilizing a distributed hierarchical algorithm; see the references. The present function `hsvd` is a low-level routine, provides many options/parameters, but no default values, and is not recommended for usage by non-experts since conflicts arising from inappropriate parameter choice will not be caught. We strongly recommend to use the corresponding high-level functions `hsvd_rank` and `hsvd_rtol` instead. Input ------- A: DNDarray 2D-array (float32/64) of which hSVD has to be computed maxrank: int, optional truncation rank of the SVD maxmergedim: int, optional maximal size of the concatenation matrices when "merging" the local SVDs rtol: float, optional upper bound on the relative reconstruction error ||A-U Sigma V^T ||_F / ||A||_F (may deteriorate due to other parameters) safetyshift: int, optional shift that increases the actual truncation rank of the local SVDs during the computations in order to increase accuracy no_of_merges: int, optional maximum number of local SVDs to be "merged" at one step compute_sv: bool, optional determines whether to compute U, Sigma, V.T (compute_sv=True) or not (then U only) silent: bool, optional determines whether to print infos on the computations performed (silent=False) warnings_off: bool, optional switch on and off warnings that are not intended for the high-level routines based on this function .. rubric:: Notes Please note that "rank" in the context of SVD always refers to the number of singular values/vectors to compute (i.e., "rank" refers to the mathematical rank of a matrix). This is completely different from the notion of "(MPI-)rank", i.e., the ID given to a process, in a parallel MPI-application. .. rubric:: References [1] Iwen, Ong. A distributed and incremental SVD algorithm for agglomerative data analysis on large networks. SIAM J. Matrix Anal. Appl., 37(4), 2016. [2] Himpe, Leibner, Rave. Hierarchical approximate proper orthogonal decomposition. SIAM J. Sci. Comput., 40 (5), 2018. .. seealso:: :func:`hsvd_rank`, :func:`hsvd_rtol` .. function:: isvd(new_data: heat.core.dndarray.DNDarray, U_old: heat.core.dndarray.DNDarray, S_old: heat.core.dndarray.DNDarray, Vt_old: heat.core.dndarray.DNDarray, maxrank: Optional[int] = None) -> Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] Incremental SVD (iSVD) for the addition of new data to an existing SVD. Given the SVD of an "old" matrix, :math:`X_\textnormal{old} = `U_\textnormal{old} \cdot S_\textnormal{old} \cdot V_\textnormal{old}^T`, and additional columns :math:`N` (\"`new_data`\"), this routine computes (a possibly approximate) SVD of the extended matrix :math:`X_\textnormal{new} = [ X_\textnormal{old} | N]`. :param new_data: 2D-array (float32/64) of columns that are added to the "old" SVD. It must hold `new_data.split != 1` if `U_old.split = 0`. :type new_data: DNDarray :param U_old: U-factor of the SVD of the "old" matrix, 2D-array (float32/64). It must hold `U_old.split != 0` if `new_data.split = 1`. :type U_old: DNDarray :param S_old: Sigma-factor of the SVD of the "old" matrix, 1D-array (float32/64) :type S_old: DNDarray :param Vt_old: Transpose of V-factor of the SVD of the "old" matrix, 2D-array (float32/64) :type Vt_old: DNDarray :param maxrank: truncation rank of the SVD of the extended matrix. The default is None, i.e., no bound on the maximal rank is imposed. :type maxrank: int, optional .. rubric:: Notes Inexactness may arise due to truncation to maximal rank `maxrank` if rank of the data to be processed exceeds this rank. If you set `maxrank` to a high number (or None) in order to avoid inexactness, you may encounter memory issues. The implementation follows the approach described in Ref. [1], Sect. 2. Please note that "rank" in the context of SVD always refers to the number of singular values/vectors to compute (i.e., "rank" refers to the mathematical rank of a matrix). This is completely different from the notion of "(MPI-)rank", i.e., the ID given to a process, in a parallel MPI-application. .. rubric:: References [1] Brand, M. (2006). Fast low-rank modifications of the thin singular value decomposition. Linear algebra and its applications, 415(1), 20-30. .. function:: svd(A: heat.core.dndarray.DNDarray, full_matrices: bool = False, compute_uv: bool = True, qr_procs_to_merge: int = 2, r_max_zolopd: int = 8) -> Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] Computes the singular value decomposition of a matrix (the input array ``A``). For an input DNDarray ``A`` of shape ``(M, N)``, the function returns DNDarrays ``U``, ``S``, and ``V.T`` such that ``A = U @ ht.diag(S) @ V.T`` with shapes ``(M, min(M,N))``, ``(min(M, N),)``, and ``(min(M,N),N)``, respectively, in the case that ``compute_uv=True``, or only the vector containing the singular values ``S`` of shape ``(min(M, N),)`` in the case that ``compute_uv=False``. By definition of the singular value decomposition, the matrix ``U`` is orthogonal, the matrix ``V`` is orthogonal, and the entries of the vector ``S``are non-negative real numbers. We refer to, e.g., wikipedia (https://en.wikipedia.org/wiki/Singular_value_decomposition) or to Gene H. Golub and Charles F. Van Loan, Matrix Computations (3rd Ed., 1996), for more detailed information on the singular value decomposition. :param A: The input array (2D, float32 or float64) for which the singular value decomposition is computed. Must be tall skinny (``M >> N``) or short fat (``M << n``) for the current implementation; an implementation that covers the remaining cases is planned. :type A: ht.DNDarray :param full_matrices: currently, only the default value ``False`` is supported. This argument is included for compatibility with NumPy. :type full_matrices: bool, optional :param compute_uv: if ``True``, the matrices ``U`` and ``V.T`` are computed and returned together with the singular values ``S``. If ``False``, only the vector ``S`` containing the singular values is returned. :type compute_uv: bool, optional :param qr_procs_to_merge: the number of processes to merge in the tall skinny QR decomposition that is applied if the input array is tall skinny (``M > N``) or short fat (``M < N``). See the corresponding remarks for :func:``heat.linalg.qr`` for more details. :type qr_procs_to_merge: int, optional :param r_max_zolopd: an internal parameter only relevant for the case that the input matrix is neither tall-skinny nor short-fat. This parameter is passed to the Zolotarev-Polar Decomposition and the symmetric eigenvalue decomposition that is applied in this case. See the documentation of :func:``heat.linalg.polar`` as well as of :func:``heat.linalg.eigh`` for more details. :type r_max_zolopd: int, optional .. rubric:: Notes Unlike in NumPy, we currently do not support the option ``full_matrices=True``, since this can result in heavy memory consumption (in particular for tall skinny and short fat matrices) that should be avoided in the context Heat is designed for. If you nevertheless require this feature, please open an issue on GitHub. The algorithm used for the computation of the singular value depends on the shape of the input array ``A``. For tall and skinny matrices (``M > N``), the algorithm is based on the tall-skinny QR decomposition. For the remaining cases we use the approach based on Zolotarev-Polar Decomposition and a symmetric eigenvalue decomposition based on Zolotarev-Polar Decomposition; see Algorithm 5.3 in: Nakatsukasa, Y., & Freund, R. W. (2016). Computing fundamental matrix decompositions accurately via the matrix sign function in two iterations: The power of Zolotarev's functions. SIAM Review, 58(3). .. seealso:: :func:`heat.linalg.qr`, :func:`heat.linalg.polar`, :func:`heat.linalg.eigh` .. function:: polar(A: heat.core.dndarray.DNDarray, r: int = None, calcH: bool = True, condition_estimate: float = 1e+16, silent: bool = True, r_max: int = 8) -> Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] Computes the so-called polar decomposition of the input 2D DNDarray ``A``, i.e., it returns the orthogonal matrix ``U`` and the symmetric, positive definite matrix ``H`` such that ``A = U @ H``. Input ----- A : ht.DNDarray, The input matrix for which the polar decomposition is computed; must be two-dimensional, of data type float32 or float64, and must have at least as many rows as columns. r : int, optional, default: None The parameter r used in the Zolotarev-PD algorithm; if provided, must be an integer between 1 and 8 that divides the number of MPI processes. Higher values of r lead to faster convergence, but memory consumption is proportional to r. If not provided, the largest 1 <= r <= r_max that divides the number of MPI processes is chosen. calcH : bool, optional, default: True If True, the function returns the symmetric, positive definite matrix H. If False, only the orthogonal matrix U is returned. condition_estimate : float, optional, default: 1.e16. This argument allows to provide an estimate for the condition number of the input matrix ``A``, if such estimate is already known. If a positive number greater than 1., this value is used as an estimate for the condition number of A. If smaller or equal than 1., the condition number is estimated internally. The default value of 1.e16 is the worst case scenario considered in [1]. silent : bool, optional, default: True If True, the function does not print any output. If False, some information is printed during the computation. r_max : int, optional, default: 8 See the description of r for the meaning; r_max is only taken into account if r is not provided. .. rubric:: Notes The implementation follows Algorithm 5.1 in Reference [1]; however, instead of switching from QR to Cholesky decomposition depending on the condition number, we stick to QR decomposition in all iterations. .. rubric:: References [1] Nakatsukasa, Y., & Freund, R. W. (2016). Computing Fundamental Matrix Decompositions Accurately via the Matrix Sign Function in Two Iterations: The Power of Zolotarev's Functions. SIAM Review, 58(3), DOI: https://doi.org/10.1137/140990334. .. function:: eigh(A: heat.core.dndarray.DNDarray, r_max_zolopd: int = 8, silent: bool = True) -> Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] Computes the symmetric eigenvalue decomposition of a symmetric n x n - matrix A, provided as a DNDarray. The function returns DNDarrays Lambda (shape (n,) with split = 0) and V (shape (n,n)) such that A = V @ diag(Lambda) @ V^T, where Lambda contains the eigenvalues of A and V is an orthonormal matrix containing the corresponding eigenvectors as columns. :param A: The input matrix. Must be symmetric. :type A: DNDarray :param r_max_zolopd: This is a hyperparameter for the computation of the polar decomposition via :func:`heat.linalg.polar` which is applied multiple times in this function. See the documentation of :func:`heat.linalg.polar` for more details on its meaning and the respective default value. :type r_max_zolopd: int, optional :param silent: If True (default), suppresses output messages; otherwise, some information on the recursion is printed to the console. :type silent: bool, optional .. rubric:: Notes Unlike the :func:`torch.linalg.eigh` function, the eigenvalues are returned in descending order. Note that no check of symmetry is performed on the input matrix A; thus, applying this function to a non-symmetric matrix may result in unpredictable behaviour without a specific error message pointing to this issue. The algorithm used for the computation of the symmetric eigenvalue decomposition is based on the Zolotarev polar decomposition; see Algorithm 5.2 in: Nakatsukasa, Y., & Freund, R. W. (2016). Computing fundamental matrix decompositions accurately via the matrix sign function in two iterations: The power of Zolotarev's functions. SIAM Review, 58(3). .. seealso:: :func:`heat.linalg.polar` .. function:: rsvd(A: heat.core.dndarray.DNDarray, svd_rank: int, n_oversamples: int = 10, power_iter: int = 0, qr_procs_to_merge: int = 2) -> Union[Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray], Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray]] Randomized SVD (rSVD) with prescribed truncation rank `svd_rank`. If :math:`A = U \operatorname{diag}(S) V^T` is the true SVD of A, this routine computes an approximation for U[:,:svd_rank] (and S[:svd_rank], V.T[:,:svd_rank]). The accuracy of this approximation depends on the structure of A ("low-rank" is best) and appropriate choice of parameters. :param A: 2D-array (float32/64) of which the rSVD has to be computed. :type A: DNDarray :param svd_rank: truncation rank of the SVD. (This parameter corresponds to `n_components` in scikit-learn's TruncatedSVD.) :type svd_rank: int :param n_oversamples: number of oversamples. The default is 10. :type n_oversamples: int, optional :param power_iter: number of power iterations. The default is 0. Choosing `power_iter > 0` can improve the accuracy of the SVD approximation in the case of slowly decaying singular values, but increases the computational cost. :type power_iter: int, optional :param qr_procs_to_merge: number of processes to merge at each step of QR decomposition in the power iteration (if power_iter > 0). The default is 2. See the corresponding remarks for :func:`heat.linalg.qr() ` for more details. :type qr_procs_to_merge: int, optional .. rubric:: Notes Memory requirements: the SVD computation of a matrix of size (svd_rank + n_oversamples) x (svd_rank + n_oversamples) must fit into the memory of a single process. The implementation follows Algorithm 4.4 (randomized range finder) and Algorithm 5.1 (direct SVD) in [1]. Please note that "rank" in the context of SVD always refers to the number of singular values/vectors to compute (i.e., "rank" refers to the mathematical rank of a matrix). This is completely different from the notion of "(MPI-)rank", i.e., the ID given to a process, in a parallel MPI-application. .. rubric:: References [1] Halko, N., Martinsson, P. G., & Tropp, J. A. (2011). Finding structure with randomness: Probabilistic algorithms for constructing approximate matrix decompositions. SIAM review, 53(2), 217-288. .. function:: reigh(A: heat.core.dndarray.DNDarray, n_eigenvalues: int, n_oversamples: int = 10, power_iter: int = 0, qr_procs_to_merge: int = 2) -> Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] Randomized eigenvalue decomposition (rEIGH). Only the top `n_eigenvalues` eigenvalues (ordered by magnitude) and corresponding eigenvectors are computed. :param A: 2D-array (float32/64) of which the rEIGH has to be computed. Must be symmetric. :type A: DNDarray :param n_eigenvalues: number of eigenvalues to compute. (This parameter corresponds to `n_components` in scikit-learn's PCA.) :type n_eigenvalues: int :param n_oversamples: number of oversamples. The default is 10. :type n_oversamples: int, optional :param power_iter: number of power iterations. The default is 0. Choosing `power_iter > 0` can improve the accuracy of the eigenvalue approximation in the case of slowly decaying eigenvalues, but increases the computational cost. :type power_iter: int, optional :param qr_procs_to_merge: number of processes to merge at each step of QR decomposition in the power iteration (if power_iter > 0). The default is 2. See the corresponding remarks for :func:`heat.linalg.qr() ` for more details. :type qr_procs_to_merge: int, optional .. rubric:: Notes Memory requirements: the symmetric eigenvalue decomposition of a matrix of size (n_eigenvalues + n_oversamples) x (n_eigenvalues + n_oversamples) must fit into the memory of a single process. The implementation follows Algorithm 4.4 (randomized range finder) and Algorithm 5.3 (eigenvalue decomposition from an SVD) in [1]. .. rubric:: References [1] Halko, N., Martinsson, P. G., & Tropp, J. A. (2011). Finding structure with randomness: Probabilistic algorithms for constructing approximate matrix decompositions. SIAM review, 53(2), 217-288. .. data:: __version__ :annotation: :str = '1.8.0' The combined version string, consisting out of major, minor, micro and possibly extension.