`heat`

add modules/namespaces to the heat namespace

Subpackages

Submodules

heat.cli

Package Contents

class finfo[source]

Class describing machine limits (bit representation) of floating point types.

Variables:

bits (int) – The number of bits occupied by the type.
eps (float) – The smallest representable positive number such that 1.0 + eps != 1.0. Type of eps is an appropriate floating point type.
max (float) – The largest representable number.
min (float) – The smallest representable number, typically -max.
tiny (float) – The smallest positive usable number. Type of tiny is an appropriate floating point type.

Parameters:

dtype (datatype) – Kind of floating point data-type about which to get information.

Examples

>>> import heat as ht
>>> info = ht.types.finfo(ht.float32)
>>> info.bits
32
>>> info.eps
1.1920928955078125e-07

_init(dtype: Type[datatype])[source]

class iinfo[source]

Class describing machine limits (bit representation) of integer types.

Variables:

bits (int) – The number of bits occupied by the type.
max (float) – The largest representable number.
min (float) – The smallest representable number, typically -max.

Parameters:

dtype (datatype) – Kind of floating point data-type about which to get information.

Examples

>>> import heat as ht
>>> info = ht.types.iinfo(ht.int32)
>>> info.bits
32

_init(dtype: Type[datatype])[source]

__version__ :str = '1.9.0': The combined version string, consisting out of major, minor, micro and possibly extension.

add(t1: heat.core.dndarray.DNDarray | float, t2: heat.core.dndarray.DNDarray | float, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

Element-wise addition of values from two operands, commutative. Takes the first and second operand (scalar or DNDarray) whose elements are to be added as argument and returns a DNDarray containing the results of element-wise addition of t1 and t2.

Parameters:

t1 (DNDarray or scalar) – The first operand involved in the addition
t2 (DNDarray or scalar) – The second operand involved in the addition
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

bitwise_and(t1: heat.core.dndarray.DNDarray | float, t2: heat.core.dndarray.DNDarray | float, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

Compute the bitwise AND of two 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)

Parameters:

t1 (DNDarray or scalar) – The first operand involved in the operation
t2 (DNDarray or scalar) – The second operand involved in the operation
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

bitwise_not: Alias for invert()

bitwise_or(t1: heat.core.dndarray.DNDarray | float, t2: heat.core.dndarray.DNDarray | float, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

Compute the bit-wise OR of two 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)

Parameters:

t1 (DNDarray or scalar) – The first operand involved in the operation
t2 (DNDarray or scalar) – The second operand involved in the operation
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

bitwise_xor(t1: heat.core.dndarray.DNDarray | float, t2: heat.core.dndarray.DNDarray | float, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

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).

Parameters:

t1 (DNDarray or scalar) – The first operand involved in the operation
t2 (DNDarray or scalar) – The second operand involved in the operation
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

copysign(a: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray | float | int, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

Create a new floating-point tensor with the magnitude of ‘a’ and the sign of ‘b’, element-wise

Parameters:

a (DNDarray) – The input array
b (DNDarray or Number) – value(s) whose signbit(s) are applied to the magnitudes in ‘a’
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

cumprod(a: heat.core.dndarray.DNDarray, axis: int, dtype: heat.core.types.datatype = None, out=None) → heat.core.dndarray.DNDarray[source]

Return the cumulative product of elements along a given axis.

Parameters:

a (DNDarray) – Input array.
axis (int) – Axis along which the cumulative product is computed.
dtype (datatype, optional) – 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.
out (DNDarray, optional) – 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.

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)

cumproduct: Alias for cumprod()

cumsum(a: heat.core.dndarray.DNDarray, axis: int, dtype: heat.core.types.datatype = None, out=None) → heat.core.dndarray.DNDarray[source]

Return the cumulative sum of the elements along a given axis.

Parameters:

a (DNDarray) – Input array.
axis (int) – Axis along which the cumulative sum is computed.
dtype (datatype, optional) – 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.
out (DNDarray, optional) – 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.

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)

diff(a: heat.core.dndarray.DNDarray, n: int = 1, axis: int = -1, prepend: int | float | heat.core.dndarray.DNDarray = None, append: int | float | heat.core.dndarray.DNDarray = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

a (DNDarray) – Input array
n (int, optional) – The number of times values are differenced. If zero, the input is returned as-is. n=2 is equivalent to diff(diff(a))
axis (int, optional) – The axis along which the difference is taken, default is the last axis.
prepend (Union[int, float, DNDarray]) – 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.
append (Union[int, float, DNDarray]) – 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.

div(t1: heat.core.dndarray.DNDarray | float, t2: heat.core.dndarray.DNDarray | float, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

Element-wise true division of values of operand t1 by values of operands t2 (i.e t1/t2). Operation is not commutative.

Parameters:

t1 (DNDarray or scalar) – The first operand whose values are divided.
t2 (DNDarray or scalar) – The second operand by whose values is divided.
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

divide: Alias for div()

divmod(t1: heat.core.dndarray.DNDarray | float, t2: 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: bool | heat.core.dndarray.DNDarray = True) → Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray][source]

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.

Parameters:

t1 (DNDarray or scalar) – The first operand whose values are divided (may be floats)
t2 (DNDarray or scalar) – The second operand by whose values is divided (may be floats)
out1 (DNDarray, optional) – 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.
out2 (DNDarray, optional) – 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.
out (tuple of two DNDarrays, optional) – 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.
where (DNDarray, optional) – 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.

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))

floordiv(t1: heat.core.dndarray.DNDarray | float, t2: heat.core.dndarray.DNDarray | float, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

Element-wise floor division of value(s) of operand t1 by value(s) of operand t2 (i.e. t1//t2), not commutative.

Parameters:

t1 (DNDarray or scalar) – The first operand whose values are divided
t2 (DNDarray or scalar) – The second operand by whose values is divided
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

floor_divide: Alias for floordiv()

fmod(t1: heat.core.dndarray.DNDarray | float, t2: heat.core.dndarray.DNDarray | float, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

t1 (DNDarray or scalar) – The first operand whose values are divided (may be floats)
t2 (DNDarray or scalar) – The second operand by whose values is divided (may be floats)
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

gcd(a: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

Returns the greatest common divisor of |a| and |b| element-wise.

Parameters:

a (DNDarray) – The first input array, must be of integer type
b (DNDarray) – the second input array, must be of integer type
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

hypot(t1: heat.core.dndarray.DNDarray, t2: heat.core.dndarray.DNDarray, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

Given the ‘legs’ of a right triangle, return its hypotenuse. Equivalent to \(sqrt(a^2 + b^2)\), element-wise.

Parameters:

t1 (DNDarray) – The first input array
t2 (DNDarray) – the second input array
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

invert(a: heat.core.dndarray.DNDarray, /, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Computes the bitwise NOT of the given input 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.

Parameters:

a (DNDarray) – The input array to invert. Must be of integral or Boolean types
out (DNDarray, optional) – 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.

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)

lcm(a: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

Returns the lowest common multiple of |a| and |b| element-wise.

Parameters:

a (DNDarray or scalar) – The first input (array), must be of integer type
b (DNDarray or scalar) – the second input (array), must be of integer type
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

left_shift(t1: heat.core.dndarray.DNDarray, t2: heat.core.dndarray.DNDarray | float, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

Shift the bits of an integer to the left.

Parameters:

t1 (DNDarray) – Input array
t2 (DNDarray or float) – Integer number of zero bits to add
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

Examples

>>> ht.left_shift(ht.array([1, 2, 3]), 1)
DNDarray([2, 4, 6], dtype=ht.int64, device=cpu:0, split=None)

mod: Alias for remainder()

mul(t1: heat.core.dndarray.DNDarray | float, t2: heat.core.dndarray.DNDarray | float, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

Element-wise multiplication (NOT matrix multiplication) of values from two operands, commutative. Takes the first and second operand (scalar or DNDarray) whose elements are to be multiplied as argument.

Parameters:

t1 (DNDarray or scalar) – The first operand involved in the multiplication
t2 (DNDarray or scalar) – The second operand involved in the multiplication
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

multiply: Alias for mul()

nan_to_num(a: heat.core.dndarray.DNDarray, nan: float = 0.0, posinf: float = None, neginf: float = None, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

a (DNDarray) – Input array.
nan (float, optional) – Value to be used to replace NaNs. Default value is 0.0.
posinf (float, optional) – 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.
neginf (float, optional) – 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.
out (DNDarray, optional) – 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.

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)

nanprod(a: heat.core.dndarray.DNDarray, axis: int | Tuple[int, Ellipsis] = None, out: heat.core.dndarray.DNDarray = None, keepdims: bool = None) → heat.core.dndarray.DNDarray[source]

Return the product of array elements over a given axis treating Not a Numbers (NaNs) as one.

Parameters:

a (DNDarray) – Input array.
axis (None or int or Tuple[int,...], optional) – 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.
out (DNDarray, optional) – 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.
keepdims (bool, optional) – 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.

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)

nansum(a: heat.core.dndarray.DNDarray, axis: int | Tuple[int, Ellipsis] = None, out: heat.core.dndarray.DNDarray = None, keepdims: bool = None) → heat.core.dndarray.DNDarray[source]

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)

Parameters:

a (DNDarray) – Input array.
axis (None or int or Tuple[int,...], optional) – 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.
out (DNDarray, optional) – 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.
keepdims (bool, optional) – 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.

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)

neg(a: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Element-wise negation of a.

Parameters:

a (DNDarray) – The input array.
out (DNDarray, optional) – The output array. It must have a shape that the inputs broadcast to

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)

negative: Alias for neg()

pos(a: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Element-wise positive of a.

Parameters:

a (DNDarray) – The input array.
out (DNDarray, optional) – The output array. It must have a shape that the inputs broadcast to.

Notes

Equivalent to a.copy().

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)

positive: Alias for pos()

pow(t1: heat.core.dndarray.DNDarray | float, t2: heat.core.dndarray.DNDarray | float, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

t1 (DNDarray or scalar) – The first operand whose values represent the base
t2 (DNDarray or scalar) – The second operand whose values represent the exponent
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

power: Alias for pow()

prod(a: heat.core.dndarray.DNDarray, axis: int | Tuple[int, Ellipsis] = None, out: heat.core.dndarray.DNDarray = None, keepdims: bool = None) → heat.core.dndarray.DNDarray[source]

Return the product of array elements over a given axis in form of a DNDarray shaped as a but with the specified axis removed.

Parameters:

a (DNDarray) – Input array.
axis (None or int or Tuple[int,...], optional) – 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.
out (DNDarray, optional) – 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.
keepdims (bool, optional) – 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.

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)

remainder(t1: heat.core.dndarray.DNDarray | float, t2: heat.core.dndarray.DNDarray | float, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

t1 (DNDarray or scalar) – The first operand whose values are divided
t2 (DNDarray or scalar) – The second operand by whose values is divided
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

right_shift(t1: heat.core.dndarray.DNDarray | float, t2: heat.core.dndarray.DNDarray | float, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

Shift the bits of an integer to the right.

Parameters:

t1 (DNDarray or scalar) – Input array
t2 (DNDarray or scalar) – Integer number of bits to remove
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

Examples

>>> ht.right_shift(ht.array([1, 2, 3]), 1)
DNDarray([0, 1, 1], dtype=ht.int64, device=cpu:0, split=None)

sub(t1: heat.core.dndarray.DNDarray | float, t2: heat.core.dndarray.DNDarray | float, /, out: heat.core.dndarray.DNDarray | None = None, *, where: bool | heat.core.dndarray.DNDarray = True) → heat.core.dndarray.DNDarray[source]

Element-wise subtraction of values of operand t2 from values of operands t1 (i.e t1-t2). Operation is not commutative.

Parameters:

t1 (DNDarray or scalar) – The first operand from which values are subtracted
t2 (DNDarray or scalar) – The second operand whose values are subtracted
out (DNDarray, optional) – 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.
where (DNDarray, optional) – 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.

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)

subtract: Alias for sub()

sum(a: heat.core.dndarray.DNDarray, axis: int | Tuple[int, Ellipsis] = None, out: heat.core.dndarray.DNDarray = None, keepdims: bool = None) → heat.core.dndarray.DNDarray[source]

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)

Parameters:

a (DNDarray) – Input array.
axis (None or int or Tuple[int,...], optional) – 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.
out (DNDarray, optional) – 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.
keepdims (bool, optional) – 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.

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)

class DNDarray(array: torch.Tensor, gshape: Tuple[int, Ellipsis], dtype: heat.core.types.datatype, split: int | None, device: heat.core.devices.Device, comm: Communication, balanced: bool)[source]

Distributed N-Dimensional array. The core element of HeAT. It is composed of PyTorch tensors local to each process.

Parameters:

array (torch.Tensor) – Local array elements
gshape (Tuple[int,...]) – The global shape of the array
dtype (datatype) – The datatype of the array
split (int or None) – The axis on which the array is divided between processes
device (Device) – The device on which the local arrays are using (cpu or gpu)
comm (Communication) – The communications object for sending and receiving data
balanced (bool or None) – 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 is_balanced() method (requires communication).

__array

__gshape

__dtype

__split

__device

__comm

__balanced

__ishalo = False

__halo_next = None

__halo_prev = None

__partitions_dict__ = None

__lshape_map = None

__prephalo(start, end) → torch.Tensor

Extracts the halo indexed by start, end from self.array in the direction of self.split

Parameters:

start (int) – Start index of the halo extracted from self.array
end (int) – End index of the halo extracted from self.array

get_halo(halo_size: int, prev: bool = True, next: bool = True)[source]

Fetch halos of size halo_size from neighboring ranks and save them in self.halo_next/self.halo_prev.

Parameters:

halo_size (int) – Size of the halo.
prev (bool, optional) – If True, fetch the halo from the previous rank. Default: True.
next (bool, optional) – If True, fetch the halo from the next rank. Default: True.

__cat_halo() → torch.Tensor: Return local array concatenated to halos if they are available.

__array__() → numpy.ndarray[source]: Returns a view of the process-local slice of the 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.

__array_ufunc__(ufunc, method, *inputs, **kwargs)[source]: Override NumPy’s universal functions.

__array_function__(func, types, args, kwargs)[source]: Augments NumPy’s functions.

astype(dtype, copy=True) → DNDarray[source]

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.

Parameters:

dtype (datatype) – Heat type to which the array is cast
copy (bool, optional) – 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

balance_() → DNDarray[source]

Function for balancing a DNDarray between all nodes. To determine if this is needed use the 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.

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)

__bool__() → bool[source]: Boolean scalar casting.

__cast(cast_function) → float | int

Implements a generic cast function for DNDarray objects.

Parameters:: cast_function (function) – The actual cast function, e.g. float or int
Raises:: TypeError – If the DNDarray object cannot be converted into a scalar.

collect_(target_rank: int | None = 0) → None[source]

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.

Parameters:

target_rank (int, optional) – The rank to which the DNDarray will be collected. Default: 0.

Raises:

TypeError – If the target rank is not an integer.
ValueError – If the target rank is out of bounds.

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)

__complex__() → DNDarray[source]: Complex scalar casting.

counts_displs() → Tuple[Tuple[int], Tuple[int]][source]: Returns actual counts (number of items per process) and displacements (offsets) of the DNDarray. Does not assume load balance.

cpu() → DNDarray[source]: 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.

create_lshape_map(force_check: bool = False) → torch.Tensor[source]

Generate a ‘map’ of the lshapes of the data on all processes. Units are (process rank, lshape)

Parameters:: force_check (bool, optional) – if False (default) and the lshape map has already been created, use the previous result. Otherwise, create the lshape_map

create_partition_interface()[source]

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,

}

Return type:: dictionary containing the partition interface as shown above.

__float__() → DNDarray[source]: Float scalar casting.

See also

flatten()

fill_diagonal(value: float) → DNDarray[source]

Fill the main diagonal of a 2D DNDarray. This function modifies the input tensor in-place, and returns the input array.

Parameters:: value (float) – The value to be placed in the DNDarrays main diagonal

__getitem__(key: int | Tuple[int, Ellipsis] | List[int, Ellipsis]) → DNDarray[source]

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 balance() (issue #187)

Parameters:: key (int, slice, Tuple[int,...], List[int,...]) – Indices to get from the tensor.

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.])

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.

__int__() → DNDarray[source]: Integer scalar casting.

is_balanced(force_check: bool = False) → bool[source]

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.

Parameters:: force_check (bool, optional) – If True, the balanced status of the DNDarray will be assessed via collective communication in any case.

is_distributed() → bool[source]: Determines whether the data of this DNDarray is distributed across multiple processes.

__key_is_singular(key: any, axis: int, self_proxy: torch.Tensor) → bool

__key_adds_dimension(key: any, axis: int, self_proxy: torch.Tensor) → bool

item()[source]

Returns the only element of a 1-element DNDarray. Mirror of the pytorch command by the same name. If size of DNDarray is >1 element, then a ValueError is raised (by pytorch)

Examples

>>> import heat as ht
>>> x = ht.zeros((1))
>>> x.item()
0.0

__len__() → int[source]: The length of the DNDarray, i.e. the number of items in the first dimension.

numpy() → numpy.array[source]

Returns a copy of the 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!

Examples

>>> import heat as ht
T1 = ht.random.randn((10,8))
T1.numpy()

_repr_pretty_(p, cycle)[source]: Pretty print for IPython.

__repr__() → str[source]: Returns a printable representation of the passed DNDarray, targeting developers.

ravel()[source]

Flattens the DNDarray.

See also

ravel()

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)

redistribute_(lshape_map: torch.Tensor | None = None, target_map: torch.Tensor | None = None)[source]

Redistributes the data of the 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.

Parameters:

lshape_map (torch.Tensor, optional) – The current lshape of processes. Units are [rank, lshape].
target_map (torch.Tensor, optional) – 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.

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)

__redistribute_shuffle(snd_pr: int | torch.Tensor, send_amt: int | torch.Tensor, rcv_pr: int | torch.Tensor, snd_dtype: torch.dtype)

Function to abstract the function used during redistribute for shuffling data between processes along the split axis

Parameters:

snd_pr (int or torch.Tensor) – Sending process
send_amt (int or torch.Tensor) – Amount of data to be sent by the sending process
rcv_pr (int or torch.Tensor) – Receiving process
snd_dtype (torch.dtype) – Torch type of the data in question

resplit_(axis: int = None)[source]

In-place option for resplitting a DNDarray.

Parameters:: axis (int) – The new split axis, None denotes gathering, an int will set the new split axis

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)

__setitem__(key: int | Tuple[int, Ellipsis] | List[int, Ellipsis], value: float | DNDarray | torch.Tensor)[source]

Global item setter

Parameters:

key (Union[int, Tuple[int,...], List[int,...]]) – Index/indices to be set
value (Union[float, DNDarray,torch.Tensor]) – Value to be set to the specified positions in the DNDarray (self)

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

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.]])

__setter(key: int | Tuple[int, Ellipsis] | List[int, Ellipsis], value: float | DNDarray | torch.Tensor)

Utility function for checking value and forwarding to :func:__setitem__

Raises:: NotImplementedError – If the type of value ist not supported

__str__() → str[source]: Computes a string representation of the passed DNDarray.

tolist(keepsplit: bool = False) → List[source]

Return a copy of the local array data as a (nested) Python list. For scalars, a standard Python number is returned.

Parameters:: keepsplit (bool) – Whether the list should be returned locally or globally.

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]]

__torch_function__(func, types, args=(), kwargs=None)[source]: Supports PyTorch’s dispatch mechanism.

__torch_proxy__() → torch.Tensor[source]: Return a 1-element torch.Tensor strided as the global self shape. Used internally for sanitation purposes.

__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]

class BaseEstimator[source]

Abstract base class for all estimators, i.e. parametrized analysis algorithms, in Heat. Can be used as mixin.

_parameter_names() → List[str][source]: Get the names of all parameters that can be set inside the constructor of the estimator.

get_params(deep: bool = True) → Dict[str, object][source]

Get parameters for this estimator.

Parameters:: deep (bool, default: True) – If True, will return the parameters for this estimator and contained sub-objects that are estimators.

__repr__(indent: int = 1) → str[source]

Returns a printable representation of the object.

Parameters:: indent (int, default: 1) – Indicates the indentation for the top-level output.

set_params(**params: Dict[str, object]) → BaseEstimator.set_params.self[source]

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.

Parameters:: **params (dict[str, object]) – Estimator parameters to bet set.

class ClassificationMixin[source]

Mixin for all classifiers in Heat.

fit(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray)[source]

Fits the classification model.

Parameters:

x (DNDarray) – Training instances to train on. Shape = (n_samples, n_features)
y (DNDarray) – Class values to fit. Shape = (n_samples, )

fit_predict(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Fits model and returns classes for each input sample Convenience method; equivalent to calling fit() followed by predict().

Parameters:

x (DNDarray) – Input data to be predicted. Shape = (n_samples, n_features)
y (DNDarray) – Class values to fit. Shape = (n_samples, )

predict(x: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Predicts the class labels for each sample.

Parameters:: x (DNDarray) – Values to predict the classes for. Shape = (n_samples, n_features)

class TransformMixin[source]

Mixin for all transformations in Heat.

fit(x: heat.core.dndarray.DNDarray)[source]

Fits the transformation model.

Parameters:: x (DNDarray) – Training instances to train on. Shape = (n_samples, n_features)

fit_transform(x: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Fits model and returns transformed data for each input sample Convenience method; equivalent to calling fit() followed by transform().

Parameters:: x (DNDarray) – Input data to be transformed. Shape = (n_samples, n_features)

transform(x: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Transforms the input data.

Parameters:: x (DNDarray) – Values to transform. Shape = (n_samples, n_features)

class ClusteringMixin[source]

Clustering mixin for all clusterers in Heat.

fit(x: heat.core.dndarray.DNDarray)[source]

Computes the clustering.

Parameters:: x (DNDarray) – Training instances to cluster. Shape = (n_samples, n_features)

fit_predict(x: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

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 fit() followed by predict().

Parameters:: x (DNDarray) – Input data to be clustered. Shape = (n_samples, n_features)

class RegressionMixin[source]

Mixin for all regression estimators in Heat.

fit(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray)[source]

Fits the regression model.

Parameters:

x (DNDarray) – Training instances to train on. Shape = (n_samples, n_features)
y (DNDarray) – Continuous values to fit. Shape = (n_samples,)

fit_predict(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Fits model and returns regression predictions for each input sample Convenience method; equivalent to calling fit() followed by predict().

Parameters:

x (DNDarray) – Input data to be predicted. Shape = (n_samples, n_features)
y (DNDarray) – Continuous values to fit. Shape = (n_samples,)

predict(x: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Predicts the continuous labels for each sample.

Parameters:: x (DNDarray) – Values to let the model predict. Shape = (n_samples, n_features)

is_classifier(estimator: object) → bool[source]

Return True if the given estimator is a classifier, False otherwise.

Parameters:: estimator (object) – Estimator object to test.

is_transformer(estimator: object) → bool[source]

Return True if the given estimator is a transformer, False otherwise.

Parameters:: estimator (object) – Estimator object to test.

is_estimator(estimator: object) → bool[source]

Return True if the given estimator is an estimator, False otherwise.

Parameters:: estimator (object) – Estimator object to test.

is_clusterer(estimator: object) → bool[source]

Return True if the given estimator is a clusterer, False otherwise.

Parameters:: estimator (object) – Estimator object to test.

is_regressor(estimator: object) → bool[source]

Return True if the given estimator is a regressor, False otherwise.

Parameters:: estimator (object) – Estimator object to test.

sanitize_axis(shape: Tuple[int, Ellipsis], axis: int | None | Tuple[int, Ellipsis]) → int | None | Tuple[int, Ellipsis][source]

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

Parameters:

shape (Tuple[int, ...]) – Shape of an array
axis (ints or Tuple[int, ...] or None) – The axis to be sanitized

Raises:

ValueError – if the axis cannot be sanitized, i.e. out of bounds.
TypeError – if the axis is not integral.

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 "<stdin>", line 1, in <module>
  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 <class 'float'>

class MPIRequest(handle, sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any = None, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any = None, tensor: torch.Tensor = None, permutation: Tuple[int, Ellipsis] = None)[source]

Represents a handle on a non-blocking operation

Parameters:

handle (MPI.Communicator) – Handle for the mpi4py Communicator
sendbuf (DNDarray or torch.Tensor or Any) – The buffer for the data to be send
recvbuf (DNDarray or torch.Tensor or Any) – The buffer to the receive data
tensor (torch.Tensor) – Internal Data
permutation (Tuple[int,...]) – Permutation of the tensor axes

handle

tensor = None

recvbuf = None

sendbuf = None

permutation = None

Wait(status: mpi4py.MPI.Status = None)[source]: Waits for an MPI request to complete

__getattr__(name: str) → Callable[source]

Default pass-through for the communicator methods.

Parameters:: name (str) – The name of the method to be called.

class Communication[source]

Base class for Communications (inteded for other backends)

is_distributed() → NotImplementedError[source]: Whether or not the Communication is distributed

chunk(shape, split) → NotImplementedError[source]

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

Parameters:

shape (Tuple[int,...]) – The global shape of the data to be split
split (int) – The axis along which to chunk the data

class MPICommunication(handle=MPI.COMM_WORLD)[source]

Bases: Communication

Class encapsulating all MPI Communication

Parameters:: handle (MPI.Communicator) – Handle for the mpi4py Communicator

COUNT_LIMIT

__mpi_type_mappings

__mpi_dtype2ctype

handle

__del__()[source]

is_distributed() → bool[source]: Determines whether the communicator is distributed, i.e. handles more than one node.

chunk(shape: Tuple[int], split: int, rank: int = None, w_size: int = None, sparse: bool = False) → Tuple[int, Tuple[int], Tuple[slice]][source]

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

Parameters:

shape (Tuple[int,...]) – The global shape of the data to be split
split (int) – The axis along which to chunk the data
rank (int, optional) – Process for which the chunking is calculated for, defaults to self.rank. Intended for creating chunk maps without communication
w_size (int, optional) – The MPI world size, defaults to self.size. Intended for creating chunk maps without communication
sparse (bool, optional) – Specifies whether the array is a sparse matrix

counts_displs_shape(shape: Tuple[int], axis: int) → Tuple[Tuple[int], Tuple[int], Tuple[int]][source]

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.

Parameters:

shape (Tuple[int,...]) – The object for which to calculate the chunking.
axis (int) – The axis along which the chunking is performed.

mpi_type_of(dtype: torch.dtype) → mpi4py.MPI.Datatype[source]

Determines the MPI Datatype from the torch dtype.

Parameters:: dtype (torch.dtype) – PyTorch data type

_handle_large_count(mpi_type: mpi4py.MPI.Datatype, elements: int) → Tuple[mpi4py.MPI.Datatype, int][source]

Handles large counts for MPI data types by creating vector types to circumvent the MAX_INT limit on certain MPI implementations.

Parameters:

mpi_type (MPI.Datatype) – The base MPI data type
elements (int) – The total number of elements to be sent

Returns:

A tuple containing the constructed MPI data type and the count (always 1 in this case)

Return type:

Tuple[MPI.Datatype, int]

Raises:

ValueError – If the tensor is too large to be handled

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

mpi_type_and_elements_of(obj: heat.core.dndarray.DNDarray | torch.Tensor, counts: Tuple[int] | None, displs: Tuple[int], is_contiguous: bool | None) → Tuple[mpi4py.MPI.Datatype, Tuple[int, Ellipsis]][source]

Determines the MPI data type and number of respective elements for the given tensor (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.

Parameters:

obj (DNDarray or torch.Tensor) – The object for which to construct the MPI data type and number of elements
counts (Tuple[ints,...], optional) – Optional counts arguments for variable MPI-calls (e.g. Alltoallv)
displs (Tuple[ints,...], optional) – Optional displacements arguments for variable MPI-calls (e.g. Alltoallv)
is_contiguous (bool) – Information on global contiguity of the memory-distributed object. If None, it will be set to local contiguity via torch.Tensor.is_contiguous().
ToDo (#)

as_mpi_memory(obj: torch.Tensor) → mpi4py.MPI.memory[source]

Converts the passed torch.Tensor into an MPI compatible memory view.

Parameters:: obj (torch.Tensor) – The tensor to be converted into a MPI memory view.

Converts a passed torch.Tensor into a memory buffer object with associated number of elements and MPI data type.

Parameters:

obj (torch.Tensor) – The object to be converted into a buffer representation.
counts (Tuple[int,...], optional) – Optional counts arguments for variable MPI-calls (e.g. Alltoallv)
displs (Tuple[int,...], optional) – Optional displacements arguments for variable MPI-calls (e.g. Alltoallv)
is_contiguous (bool, optional) – Optional information on global contiguity of the memory-distributed object.

_moveToCompDevice(x: torch.Tensor, func: Callable | None) → torch.Tensor[source]: Moves the torch tensor to the relevant device, in case the function is not compatible with the MPI+GPU library.

alltoall_sendbuffer(obj: torch.Tensor) → List[mpi4py.MPI.memory | Tuple[int, int] | mpi4py.MPI.Datatype][source]

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

Parameters:: obj (torch.Tensor) – The object to be transformed into a custom MPI datatype

alltoall_recvbuffer(obj: torch.Tensor) → List[mpi4py.MPI.memory | Tuple[int, int] | mpi4py.MPI.Datatype][source]

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

Parameters:: obj (torch.Tensor) – The object to be transformed into a custom MPI datatype

Free() → None[source]: Free a communicator.

Split(color: int = 0, key: int = 0) → MPICommunication[source]

Split communicator by color and key.

Parameters:

color (int, optional) – Determines the new communicator for a process.
key (int, optional) – Ordering within the new communicator.

Irecv(buf: heat.core.dndarray.DNDarray | torch.Tensor | Any, source: int = MPI.ANY_SOURCE, tag: int = MPI.ANY_TAG) → MPIRequest[source]

Nonblocking receive

Parameters:

buf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to place the received message
source (int, optional) – Rank of source process, that send the message
tag (int, optional) – A Tag to identify the message

Recv(buf: heat.core.dndarray.DNDarray | torch.Tensor | Any, source: int = MPI.ANY_SOURCE, tag: int = MPI.ANY_TAG, status: mpi4py.MPI.Status = None)[source]

Blocking receive

Parameters:

buf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to place the received message
source (int, optional) – Rank of the source process, that send the message
tag (int, optional) – A Tag to identify the message
status (MPI.Status, optional) – Details on the communication

__send_like(func: Callable, buf: heat.core.dndarray.DNDarray | torch.Tensor | Any, dest: int, tag: int) → Tuple[heat.core.dndarray.DNDarray | torch.Tensor | None]

Generic function for sending a message to process with rank “dest”

Parameters:

func (Callable) – The respective MPI sending function
buf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the message to be send
dest (int, optional) – Rank of the destination process, that receives the message
tag (int, optional) – A Tag to identify the message

Bsend(buf: heat.core.dndarray.DNDarray | torch.Tensor | Any, dest: int, tag: int = 0)[source]

Blocking buffered send

Parameters:

buf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the message to be send
dest (int, optional) – Index of the destination process, that receives the message
tag (int, optional) – A Tag to identify the message

Ibsend(buf: heat.core.dndarray.DNDarray | torch.Tensor | Any, dest: int, tag: int = 0) → MPIRequest[source]

Nonblocking buffered send

Parameters:

buf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the message to be send
dest (int, optional) – Rank of the destination process, that receives the message
tag (int, optional) – A Tag to identify the message

Irsend(buf: heat.core.dndarray.DNDarray | torch.Tensor | Any, dest: int, tag: int = 0) → MPIRequest[source]

Nonblocking ready send

Parameters:

buf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the message to be send
dest (int, optional) – Rank of the destination process, that receives the message
tag (int, optional) – A Tag to identify the message

Isend(buf: heat.core.dndarray.DNDarray | torch.Tensor | Any, dest: int, tag: int = 0) → MPIRequest[source]

Nonblocking send

Parameters:

buf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the message to be send
dest (int, optional) – Rank of the destination process, that receives the message
tag (int, optional) – A Tag to identify the message

Issend(buf: heat.core.dndarray.DNDarray | torch.Tensor | Any, dest: int, tag: int = 0) → MPIRequest[source]

Nonblocking synchronous send

Parameters:

buf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the message to be send
dest (int, optional) – Rank of the destination process, that receives the message
tag (int, optional) – A Tag to identify the message

Rsend(buf: heat.core.dndarray.DNDarray | torch.Tensor | Any, dest: int, tag: int = 0)[source]

Blocking ready send

Parameters:

buf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the message to be send
dest (int, optional) – Rank of the destination process, that receives the message
tag (int, optional) – A Tag to identify the message

Ssend(buf: heat.core.dndarray.DNDarray | torch.Tensor | Any, dest: int, tag: int = 0)[source]

Blocking synchronous send

Parameters:

buf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the message to be send
dest (int, optional) – Rank of the destination process, that receives the message
tag (int, optional) – A Tag to identify the message

Send(buf: heat.core.dndarray.DNDarray | torch.Tensor | Any, dest: int, tag: int = 0)[source]

Blocking send

Parameters:

buf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the message to be send
dest (int, optional) – Rank of the destination process, that receives the message
tag (int, optional) – A Tag to identify the message

__broadcast_like(func: Callable, buf: heat.core.dndarray.DNDarray | torch.Tensor | Any, root: int) → Tuple[heat.core.dndarray.DNDarray | torch.Tensor | None]

Generic function for broadcasting a message from the process with rank “root” to all other processes of the communicator

Parameters:

func (Callable) – The respective MPI broadcast function
buf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the message to be broadcasted
root (int) – Rank of the root process, that broadcasts the message

Bcast(buf: heat.core.dndarray.DNDarray | torch.Tensor | Any, root: int = 0) → None[source]

Blocking Broadcast

Parameters:

buf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the message to be broadcasted
root (int) – Rank of the root process, that broadcasts the message

Ibcast(buf: heat.core.dndarray.DNDarray | torch.Tensor | Any, root: int = 0) → MPIRequest[source]

Nonblocking Broadcast

Parameters:

buf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the message to be broadcasted
root (int) – Rank of the root process, that broadcasts the message

__derived_op(tensor: torch.Tensor, datatype: mpi4py.MPI.Datatype, operation: mpi4py.MPI.Op) → Callable[[mpi4py.MPI.memory, mpi4py.MPI.memory, mpi4py.MPI.Datatype], None]

_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][source]

Create an MPI.Op for elementwise min/max combine of a packed buffer [mins; maxs].

Parameters:

dtype (torch.dtype) – torch.dtype of underlying elements
total_count (int) – Number of elements per mins OR per max (so recv buffer has 2*total_count elements)
shape (Tuple[int]) – Shape of the packed buffer that the MPI callback will operate on. This describes the logical shape of the concatenated buffer [mins; maxs]
stride (Tuple[int]) – Stride (in elements) of the packed buffer’s storage, matching the layout
offset (int, optional) – Storage offset (if needed), default 0

Generic function for reduction operations.

Parameters:

func (Callable) – The respective MPI reduction operation
sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result of the reduction
op (MPI.Op) – Operation to apply during the reduction.
*args (Any) – Additional positional arguments to be passed to the function
**kwargs (Any) – Additional keyword arguments to be passed to the function

Allreduce(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, op: mpi4py.MPI.Op = MPI.SUM)[source]

Combines values from all processes and distributes the result back to all processes

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result of the reduction
op (MPI.Op) – The operation to perform upon reduction

Exscan(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, op: mpi4py.MPI.Op = MPI.SUM)[source]

Computes the exclusive scan (partial reductions) of data on a collection of processes

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result of the reduction
op (MPI.Op) – The operation to perform upon reduction

Iallreduce(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, op: mpi4py.MPI.Op = MPI.SUM) → MPIRequest[source]

Nonblocking allreduce reducing values on all processes to a single value

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result of the reduction
op (MPI.Op) – The operation to perform upon reduction

Iexscan(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, op: mpi4py.MPI.Op = MPI.SUM) → MPIRequest[source]

Nonblocking Exscan

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result of the reduction
op (MPI.Op) – The operation to perform upon reduction

Iscan(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, op: mpi4py.MPI.Op = MPI.SUM) → MPIRequest[source]

Nonblocking Scan

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result of the reduction
op (MPI.Op) – The operation to perform upon reduction

Ireduce(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, op: mpi4py.MPI.Op = MPI.SUM, root: int = 0) → MPIRequest[source]

Nonblocking reduction operation

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result of the reduction
op (MPI.Op) – The operation to perform upon reduction
root (int) – Rank of the root process

Reduce(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, op: mpi4py.MPI.Op = MPI.SUM, root: int = 0)[source]

Reduce values from all processes to a single value on process “root”

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result of the reduction
op (MPI.Op) – The operation to perform upon reduction
root (int) – Rank of the root process

Scan(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, op: mpi4py.MPI.Op = MPI.SUM)[source]

Computes the scan (partial reductions) of data on a collection of processes in a nonblocking way

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result of the reduction
op (MPI.Op) – The operation to perform upon reduction

__allgather_like(func: Callable, sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, axis: int, **kwargs)

Generic function for allgather operations.

Parameters:

func (Callable) – Type of MPI Allgather function (i.e. allgather, allgatherv, iallgather)
sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
axis (int) – Concatenation axis: The axis along which sendbuf is packed and along which recvbuf puts together individual chunks
**kwargs – Extra arguments to be passed to the function.

Allgather(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recv_axis: int = 0)[source]

Gathers data from all tasks and distribute the combined data to all tasks

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
recv_axis (int) – Concatenation axis: The axis along which sendbuf is packed and along which recvbuf puts together individual chunks

Allgatherv(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recv_axis: int = 0)[source]

v-call of Allgather: Each process may contribute a different amount of data.

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
recv_axis (int) – Concatenation axis: The axis along which sendbuf is packed and along which recvbuf puts together individual chunks

Iallgather(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recv_axis: int = 0) → MPIRequest[source]

Nonblocking Allgather.

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
recv_axis (int) – Concatenation axis: The axis along which sendbuf is packed and along which recvbuf puts together individual chunks

Iallgatherv(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recv_axis: int = 0)[source]

Nonblocking v-call of Allgather: Each process may contribute a different amount of data.

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
recv_axis (int) – Concatenation axis: The axis along which sendbuf is packed and along which recvbuf puts together individual chunks

__alltoall_like(func: Callable, sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, send_axis: int, recv_axis: int, **kwargs)

Generic function for alltoall operations.

Parameters:

func (Callable) – Specific alltoall function
sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
send_axis (int) –
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
recv_axis (int) – Prior split axis, along which blocks are received from the individual ranks
**kwargs – Extra arguments to be passed to the function.

Alltoall(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, send_axis: int = 0, recv_axis: int = None)[source]

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.

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
send_axis (int) –
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
recv_axis (int) – Prior split axis, along which blocks are received from the individual ranks

Alltoallv(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, send_axis: int = 0, recv_axis: int = None)[source]

v-call of Alltoall: All processes send different amount of data to, and receive different amount of data from, all processes

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
send_axis (int) –
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
recv_axis (int) – Prior split axis, along which blocks are received from the individual ranks

Alltoallw(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any)[source]

Generalized All-to-All communication allowing different counts, displacements and datatypes for each partner. See MPI standard for more information.

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – 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).
recvbuf (Union[DNDarray, torch.Tensor, Any]) – 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).

_create_recursive_vectortype(datatype: mpi4py.MPI.Datatype, tensor_stride: Tuple[int], subarray_sizes: List[int], start: List[int]) → mpi4py.MPI.Datatype[source]

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.

Parameters:

datatype (MPI.Datatype) – The base datatype to create the recursive vector datatype from.
tensor_stride (Tuple[int]) – A list of tensor strides for each dimension.
subarray_sizes (List[int]) – A list of subarray sizes for each dimension.
start (List[int]) – Index of the first element of the subarray in the original array.

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.

Examples

>>> datatype = MPI.INT
>>> tensor_stride = [1, 2, 3]
>>> subarray_sizes = [4, 5, 6]
>>> recursive_vectortype = create_recursive_vectortype(
...     datatype, tensor_stride, subarray_sizes
... )

Ialltoall(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, send_axis: int = 0, recv_axis: int = None) → MPIRequest[source]

Nonblocking Alltoall

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
send_axis (int) –
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
recv_axis (int) – Prior split axis, along which blocks are received from the individual ranks

Ialltoallv(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, send_axis: int = 0, recv_axis: int = None) → MPIRequest[source]

Nonblocking v-call of Alltoall: All processes send different amount of data to, and receive different amount of data from, all processes

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
send_axis (int) –
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
recv_axis (int) – Prior split axis, along which blocks are received from the individual ranks

__gather_like(func: Callable, sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: 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.

Parameters:

func (Callable) – Type of MPI Scatter/Gather function
sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
send_axis (int) – The axis along which sendbuf is packed
recv_axis (int) – The axis along which recvbuf is packed
send_factor (int) – Number of elements to be scattered (vor non-v-calls)
recv_factor (int) – Number of elements to be gathered (vor non-v-calls)
**kwargs – Extra arguments to be passed to the function.

Gather(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, root: int = 0, axis: int = 0, recv_axis: int = None)[source]

Gathers together values from a group of processes

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
root (int) – Rank of receiving process
axis (int) – The axis along which sendbuf is packed
recv_axis (int) – The axis along which recvbuf is packed

Gatherv(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, root: int = 0, axis: int = 0, recv_axis: int = None)[source]

v-call for Gather: All processes send different amount of data

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
root (int) – Rank of receiving process
axis (int) – The axis along which sendbuf is packed
recv_axis (int) – The axis along which recvbuf is packed

Igather(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, root: int = 0, axis: int = 0, recv_axis: int = None) → MPIRequest[source]

Non-blocking Gather

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
root (int) – Rank of receiving process
axis (int) – The axis along which sendbuf is packed
recv_axis (int) – The axis along which recvbuf is packed

Igatherv(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, root: int = 0, axis: int = 0, recv_axis: int = None) → MPIRequest[source]

Non-blocking v-call for Gather: All processes send different amount of data

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
root (int) – Rank of receiving process
axis (int) – The axis along which sendbuf is packed
recv_axis (int) – The axis along which recvbuf is packed

__scatter_like(func: Callable, sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: 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.

Parameters:

func (Callable) – Type of MPI Scatter/Gather function
sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
send_axis (int) – The axis along which sendbuf is packed
recv_axis (int) – The axis along which recvbuf is packed
send_factor (int) – Number of elements to be scattered (vor non-v-calls)
recv_factor (int) – Number of elements to be gathered (vor non-v-calls)
**kwargs – Extra arguments to be passed to the function.

Iscatter(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, root: int = 0, axis: int = 0, recv_axis: int = None) → MPIRequest[source]

Non-blocking Scatter

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
root (int) – Rank of sending process
axis (int) – The axis along which sendbuf is packed
recv_axis (int) – The axis along which recvbuf is packed

Iscatterv(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, root: int = 0, axis: int = 0, recv_axis: int = None) → MPIRequest[source]

Non-blocking v-call for Scatter: Sends different amounts of data to different processes

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
root (int) – Rank of sending process
axis (int) – The axis along which sendbuf is packed
recv_axis (int) – The axis along which recvbuf is packed

Scatter(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, root: int = 0, axis: int = 0, recv_axis: int = None)[source]

Sends data parts from one process to all other processes in a communicator

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
root (int) – Rank of sending process
axis (int) – The axis along which sendbuf is packed
recv_axis (int) – The axis along which recvbuf is packed

Scatterv(sendbuf: heat.core.dndarray.DNDarray | torch.Tensor | Any, recvbuf: int, root: int = 0, axis: int = 0, recv_axis: int = None)[source]

v-call for Scatter: Sends different amounts of data to different processes

Parameters:

sendbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address of the send message
recvbuf (Union[DNDarray, torch.Tensor, Any]) – Buffer address where to store the result
root (int) – Rank of sending process
axis (int) – The axis along which sendbuf is packed
recv_axis (int) – The axis along which recvbuf is packed

__getattr__(name: str)[source]

Default pass-through for the communicator methods.

Parameters:: name (str) – The name of the method to be called.

get_comm() → Communication[source]: Retrieves the currently globally set default communication.

sanitize_comm(comm: Communication | None) → Communication[source]

Sanitizes a device or device identifier, i.e. checks whether it is already an instance of heat.core.devices.Device or a string with known device identifier and maps it to a proper Device.

Parameters:: comm (Communication) – The comm to be sanitized
Raises:: TypeError – If the given communication is not the proper type

use_comm(comm: Communication = None)[source]

Sets the globally used default communicator.

Parameters:: comm (Communication or None) – The communication to be set

e = 2.718281828459045: Euler’s number, Euler’s constant (\(e\)).

Euler = 2.718281828459045: Euler’s number, Euler’s constant (\(e\)).

inf: IEEE 754 floating point representation of (positive) infinity (\(\infty\)).

Inf: IEEE 754 floating point representation of (positive) infinity (\(\infty\)).

Infty: IEEE 754 floating point representation of (positive) infinity (\(\infty\)).

Infinity: IEEE 754 floating point representation of (positive) infinity (\(\infty\)).

nan: IEEE 754 floating point representation of Not a Number (NaN).

NaN: IEEE 754 floating point representation of Not a Number (NaN).

pi = 3.141592653589793: Archimedes’ constant (\(\pi\)).

angle(x: heat.core.dndarray.DNDarray, deg: bool = False, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Calculate the element-wise angle of the complex argument.

Parameters:

x (DNDarray) – Input array for which to compute the angle.
deg (bool, optional) – Return the angle in degrees (True) or radiands (False).
out (DNDarray, optional) – Output array with the angles.

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)

conjugate(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Compute the complex conjugate, element-wise.

Parameters:

x (DNDarray) – Input array for which to compute the complex conjugate.
out (DNDarray, optional) – Output array with the complex conjugates.

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)

imag(x: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Return the imaginary part of the complex argument. The returned DNDarray and the input DNDarray share the same underlying storage.

Parameters:: x (DNDarray) – Input array for which the imaginary part is returned.

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)

real(x: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Return the real part of the complex argument. The returned DNDarray and the input DNDarray share the same underlying storage.

Parameters:: x (DNDarray) – Input array for which the real part is returned.

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)

class Device(device_type: str, device_id: int, torch_device: str)[source]

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.

Parameters:

device_type (str) – Represents Heat’s device name
device_id (int) – The device id
torch_device (str) – The corresponding PyTorch device type

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)

__device_type

__device_id

__torch_device

__repr__() → str[source]: Return the unambiguous information of Device.

__str__() → str[source]: Return the descriptive information of Device.

__eq__(other: Any) → bool[source]

Overloads the == operator for local equal check.

Parameters:: other (Any) – The object to compare with

cpu

The standard CPU Device

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)

get_device() → Device[source]: Retrieves the currently globally set default Device.

sanitize_device(device: str | Device | None = None) → Device[source]

Sanitizes a device or device identifier, i.e. checks whether it is already an instance of Device or a string with known device identifier and maps it to a proper Device.

Parameters:: device (str or Device, optional) – The device to be sanitized
Raises:: ValueError – If the given device id is not recognized

use_device(device: str | Device | None = None) → None[source]

Sets the globally used default Device.

Parameters:: device (str or Device) – The device to be set

exp(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Calculate the exponential of all elements in the input array. Result is a DNDarray of the same shape as x.

Parameters:

x (DNDarray) – The array for which to compute the exponential.
out (DNDarray, optional) – 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.

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)

expm1(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Calculate \(exp(x) - 1\) for all elements in the array. Result is a DNDarray of the same shape as x.

Parameters:

x (DNDarray) – The array for which to compute the exponential.
out (DNDarray, optional) – 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.

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)

exp2(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Calculate the exponential of two of all elements in the input array (\(2^x\)). Result is a DNDarray of the same shape as x.

Parameters:

x (DNDarray) – The array for which to compute the exponential of two.
out (DNDarray, optional) – 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.

Examples

>>> ht.exp2(ht.arange(5))
DNDarray([ 1.,  2.,  4.,  8., 16.], dtype=ht.float32, device=cpu:0, split=None)

log(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Natural logarithm, element-wise. The natural logarithm is the inverse of the exponential function, so that \(log(exp(x)) = x\). The natural logarithm is logarithm in base e. Result is a DNDarray of the same shape as x. Negative input elements are returned as NaN.

Parameters:

x (DNDarray) – The array for which to compute the logarithm.
out (DNDarray, optional) – 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.

Examples

>>> ht.log(ht.arange(5))
DNDarray([  -inf, 0.0000, 0.6931, 1.0986, 1.3863], dtype=ht.float32, device=cpu:0, split=None)

log2(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Compute the logarithm to the base 2 (\(log_2(x)\)), element-wise. Result is a DNDarray of the same shape as x. Negative input elements are returned as NaN.

Parameters:

x (DNDarray) – The array for which to compute the logarithm.
out (DNDarray, optional) – 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.

Examples

>>> ht.log2(ht.arange(5))
DNDarray([  -inf, 0.0000, 1.0000, 1.5850, 2.0000], dtype=ht.float32, device=cpu:0, split=None)

log10(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Compute the logarithm to the base 10 (\(log_{10}(x)\)), element-wise. Result is a DNDarray of the same shape as x. Negative input elements are returned as NaN.

Parameters:

x (DNDarray) – The array for which to compute the logarithm.
out (DNDarray, optional) – 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.

Examples

>>> ht.log10(ht.arange(5))
DNDarray([  -inf, 0.0000, 0.3010, 0.4771, 0.6021], dtype=ht.float32, device=cpu:0, split=None)

log1p(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Return the natural logarithm of one plus the input array, element-wise. Result is a DNDarray of the same shape as x. Negative input elements are returned as NaN.

Parameters:

x (DNDarray) – The array for which to compute the logarithm.
out (DNDarray, optional) – 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.

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)

logaddexp(x1: heat.core.dndarray.DNDarray, x2: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Calculates the logarithm of the sum of exponentiations \(log(exp(x1) + exp(x2))\) for each element \({x1}_i\) of the input array x1 with the respective element \({x2}_i\) of the input array x2.

Parameters:

x1 (DNDarray) – first input array. Should have a floating-point data type.
x2 (DNDarray) – second input array. Must be compatible with x1. Should have a floating-point data type.
out (DNDarray, optional) – 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.

See also

logaddexp2(): Logarithm of the sum of exponentiations of inputs in base-2.

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)

logaddexp2(x1: heat.core.dndarray.DNDarray, x2: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Calculates the logarithm of the sum of exponentiations in base-2 \(log2(exp(x1) + exp(x2))\) for each element \({x1}_i\) of the input array x1 with the respective element \({x2}_i\) of the input array x2.

Parameters:

x1 (DNDarray) – first input array. Should have a floating-point data type.
x2 (DNDarray) – second input array. Must be compatible with x1. Should have a floating-point data type.
out (DNDarray, optional) – 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.

See also

logaddexp(): Logarithm of the sum of exponentiations of inputs.

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)

sqrt(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Return the non-negative square-root of a tensor element-wise. Result is a DNDarray of the same shape as x. Negative input elements are returned as NaN.

Parameters:

x (DNDarray) – The array for which to compute the square-roots.
out (DNDarray, optional) – 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.

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)

square(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Return a new tensor with the squares of the elements of input.

Parameters:

x (DNDarray) – The array for which to compute the squares.
out (DNDarray, optional) – 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.

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)

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 linspace() is recommended. For floating point arguments, the length of the result is \(\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.

Parameters:

*args (int or float, optional) – 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.
dtype (datatype, optional) – The type of the output array. If dtype is not given, it is automatically inferred from the other input arguments.
split (int or None, optional) – The axis along which the array is split and distributed; None means no distribution.
device (str, optional) – Specifies the device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.

See also

linspace(): Evenly spaced numbers with careful handling of endpoints.

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)

array(obj: Iterable, dtype: Type[heat.core.types.datatype] | None = None, copy: bool | None = None, ndmin: int = 0, order: str = 'C', split: int | None = None, is_split: int | None = None, device: heat.core.devices.Device | None = None, comm: heat.core.communication.Communication | None = None) → heat.core.dndarray.DNDarray[source]

Create a DNDarray.

Parameters:

obj (array_like) – A tensor or array, any object exposing the array interface, an object whose __array__ method returns an array, or any (nested) sequence.
dtype (datatype, optional) – 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 astype() method.
copy (bool, optional) – 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.
ndmin (int, optional) – 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.
order (str, optional) – 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).
split (int or None, optional) – The axis along which the passed array content obj is split and distributed in memory. Mutually exclusive with is_split.
is_split (int or None, optional) – 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.
device (str or Device, optional) – Specifies the Device the array shall be allocated on (i.e. globally set default device).
comm (Communication, optional) – Handle to the nodes holding distributed array chunks.

Raises:

NotImplementedError – If order is one of the NumPy options 'K' or 'A'.
ValueError – If copy is False but a copy is necessary to satisfy other requirements (e.g. different dtype, device, etc.).
TypeError – If the input object cannot be converted to a torch.Tensor, hence it cannot be converted to a DNDarray.

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]

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.

Parameters:

obj (iterable) – 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.
dtype (dtype, optional) – By default, the data-type is inferred from the input data.
copy (bool, optional) – 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.
order (str, optional) – Whether to use row-major (C-style) or column-major (Fortran-style) memory representation. Defaults to ‘C’.
is_split (None or int, optional) – 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.
device (str, ht.Device or None, optional) – Specifies the device the tensor shall be allocated on. By default, it is inferred from the input data.

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

empty(shape: int | Sequence[int], dtype: Type[heat.core.types.datatype] = types.float32, split: int | None = None, device: heat.core.devices.Device | None = None, comm: heat.core.communication.Communication | None = None, order: str = 'C') → heat.core.dndarray.DNDarray[source]

Returns a new uninitialized DNDarray of given shape and data type. May be allocated split up across multiple nodes along the specified axis.

Parameters:

shape (int or Sequence[int,...]) – Desired shape of the output array, e.g. 1 or (1, 2, 3,).
dtype (datatype) – The desired HeAT data type for the array.
split (int, optional) – The axis along which the array is split and distributed; None means no distribution.
device (str or Device, optional) – Specifies the Device. the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.
order (str, optional) – 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).

Raises:

NotImplementedError – If order is one of the NumPy options 'K' or 'A'.

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)

empty_like(a: heat.core.dndarray.DNDarray, dtype: Type[heat.core.types.datatype] | None = None, split: int | None = None, device: heat.core.devices.Device | None = None, comm: heat.core.communication.Communication | None = None, order: str = 'C') → heat.core.dndarray.DNDarray[source]

Returns a new uninitialized DNDarray with the same type, shape and data distribution of given object. Data type, data distribution axis, and device can be explicitly overridden.

Parameters:

a (DNDarray) – 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.
dtype (datatype, optional) – Overrides the data type of the result.
split (int or None, optional) – The axis along which the array is split and distributed; None means no distribution.
device (str or Device, optional) – Specifies the Device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.
order (str, optional) – 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).

Raises:

NotImplementedError – If order is one of the NumPy options 'K' or 'A'.

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)

eye(shape: int | Sequence[int], dtype: Type[heat.core.types.datatype] = types.float32, split: int | None = None, device: heat.core.devices.Device | None = None, comm: heat.core.communication.Communication | None = None, order: str = 'C') → heat.core.dndarray.DNDarray[source]

Returns a new 2-D DNDarray with ones on the diagonal and zeroes elsewhere, i.e. an identity matrix.

Parameters:

shape (int or Sequence[int,...]) – 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.
dtype (datatype, optional) – Overrides the data type of the result.
split (int or None, optional) – The axis along which the array is split and distributed; None means no distribution.
device (str or Device, optional) – Specifies the Device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.
order (str, optional) – 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).

Raises:

NotImplementedError – If order is one of the NumPy options 'K' or 'A'.

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)

from_partitioned(x, comm: heat.core.communication.Communication | None = None) → heat.core.dndarray.DNDarray[source]

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__

Parameters:

x (object) – Requires x.__partitioned__
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.

See also

ht.core.DNDarray.create_partition_interface.

Raises:

AttributeError – If not hasattr(x, “__partitioned__”) or if underlying data has no dtype.
TypeError – If it finds an unsupported array types
RuntimeError – If other unsupported content is found.

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()

from_partition_dict(parted: dict, comm: heat.core.communication.Communication | None = None) → heat.core.dndarray.DNDarray[source]

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__

Parameters:

parted (dict) – A partition dictionary used to create the new DNDarray
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.

See also

ht.core.DNDarray.create_partition_interface.

Raises:

AttributeError – If not hasattr(x, “__partitioned__”) or if underlying data has no dtype.
TypeError – If it finds an unsupported array types
RuntimeError – If other unsupported content is found.

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()

full(shape: int | Sequence[int], fill_value: int | float, dtype: Type[heat.core.types.datatype] = types.float32, split: int | None = None, device: heat.core.devices.Device | None = None, comm: heat.core.communication.Communication | None = None, order: str = 'C') → heat.core.dndarray.DNDarray[source]

Return a new DNDarray of given shape and type, filled with fill_value.

Parameters:

shape (int or Sequence[int,...]) – Shape of the new array, e.g., (2, 3) or 2.
fill_value (scalar) – Fill value.
dtype (datatype, optional) – The desired data-type for the array
split (int or None, optional) – The axis along which the array is split and distributed; None means no distribution.
device (str or Device, optional) – Specifies the Device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.
order (str, optional) – 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).

Raises:

NotImplementedError – If order is one of the NumPy options 'K' or 'A'.

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)

full_like(a: heat.core.dndarray.DNDarray, fill_value: int | float, dtype: Type[heat.core.types.datatype] = types.float32, split: int | None = None, device: heat.core.devices.Device | None = None, comm: heat.core.communication.Communication | None = None, order: str = 'C') → heat.core.dndarray.DNDarray[source]

Return a full DNDarray with the same shape and type as a given array. Data type, data distribution axis, and device can be explicitly overridden.

Parameters:

a (DNDarray) – The shape, data-type, split axis and device of a define these same attributes of the returned array.
fill_value (scalar) – Fill value.
dtype (datatype, optional) – The data type of the result, defaults to a.dtype.
split (int or None, optional) – The axis along which the array is split and distributed; defaults to a.split.
device (str or Device, optional) – Specifies the Device the array shall be allocated on, defaults to a.device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.
order (str, optional) – 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).

Raises:

NotImplementedError – If order is one of the NumPy options 'K' or 'A'.

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)

linspace(start: int | float, stop: int | float, num: int = 50, endpoint: bool = True, retstep: bool = False, dtype: Type[heat.core.types.datatype] | None = None, split: int | None = None, device: heat.core.devices.Device | None = None, comm: heat.core.communication.Communication | None = None) → Tuple[heat.core.dndarray.DNDarray, float][source]

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).

Parameters:

start (scalar or scalar-convertible) – The starting value of the sample interval, maybe a sequence if convertible to scalar
stop (scalar or scalar-convertible) – 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.
num (int, optional) – Number of samples to generate, defaults to 50. Must be non-negative.
endpoint (bool, optional) – If True, stop is the last sample, otherwise, it is not included.
retstep (bool, optional) – If True, return (samples, step), where step is the spacing between samples.
dtype (dtype, optional) – The type of the output array.
split (int or None, optional) – The axis along which the array is split and distributed; None means no distribution.
device (str or Device, optional) – Specifies the Device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.

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)

logspace(start: int | float, stop: int | float, num: int = 50, endpoint: bool = True, base: float = 10.0, dtype: Type[heat.core.types.datatype] | None = None, split: int | None = None, device: heat.core.devices.Device | None = None, comm: heat.core.communication.Communication | None = None) → heat.core.dndarray.DNDarray[source]

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).

Parameters:

start (scalar or scalar-convertible) – base**start is the starting value of the sequence.
stop (scalar or scalar-convertible) – 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.
num (int, optional) – Number of samples to generate.
endpoint (bool, optional) – If True, stop is the last sample. Otherwise, it is not included.
base (float, optional) – The base of the log space. The step size between the elements in \(ln(samples) / ln(base)\) (or \(base(samples)\)) is uniform.
dtype (datatype, optional) – The type of the output array. If dtype is not given, infer the data type from the other input arguments.
split (int or None, optional) – The axis along which the array is split and distributed; None means no distribution.
device (str or Device, optional) – Specifies the Device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.

See also

arange(): Similar to 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.
linspace(): Similar to logspace, but with the samples uniformly distributed in linear space, instead of log space.

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)

meshgrid(*arrays: Sequence[heat.core.dndarray.DNDarray], indexing: str = 'xy') → List[heat.core.dndarray.DNDarray][source]

Returns coordinate matrices from coordinate vectors.

Parameters:

arrays (Sequence[ DNDarray ]) – one-dimensional arrays representing grid coordinates. If exactly one vector is distributed, the returned matrices will reflect this distribution.
indexing (str, optional) – Cartesian ‘xy’ or matrix ‘ij’ indexing of output. It is ignored if zero or one one-dimensional arrays are provided. Default: ‘xy’ .

Raises:

ValueError – If indexing is not ‘xy’ or ‘ij’.
ValueError – If more than one input vector is distributed.

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]])

ones(shape: int | Sequence[int], dtype: Type[heat.core.types.datatype] = types.float32, split: int | None = None, device: heat.core.devices.Device | None = None, comm: heat.core.communication.Communication | None = None, order: str = 'C') → heat.core.dndarray.DNDarray[source]

Returns a new DNDarray of given shape and data type filled with one. May be allocated split up across multiple nodes along the specified axis.

Parameters:

shape (int or Sequence[int,...]) – Desired shape of the output array, e.g. 1 or (1, 2, 3,).
dtype (datatype, optional) – The desired HeAT data type for the array.
split (int or None, optional) – The axis along which the array is split and distributed; None means no distribution.
device (str or Device, optional) – Specifies the Device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.
order (str, optional) – 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).

Raises:

NotImplementedError – If order is one of the NumPy options 'K' or 'A'.

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)

ones_like(a: heat.core.dndarray.DNDarray, dtype: Type[heat.core.types.datatype] | None = None, split: int | None = None, device: heat.core.devices.Device | None = None, comm: heat.core.communication.Communication | None = None, order: str = 'C') → heat.core.dndarray.DNDarray[source]

Returns a new 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.

Parameters:

a (DNDarray) – The shape, data-type, split axis and device of a define these same attributes of the returned array.
dtype (datatype, optional) – Overrides the data type of the result.
split (int or None, optional) – The axis along which the array is split and distributed; defaults to a.split.
device (str or Device, optional) – Specifies the Device the array shall be allocated on, defaults to a.device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.
order (str, optional) – 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).

Raises:

NotImplementedError – If order is one of the NumPy options 'K' or 'A'.

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)

zeros(shape: int | Sequence[int], dtype: Type[heat.core.types.datatype] = types.float32, split: int | None = None, device: heat.core.devices.Device | None = None, comm: heat.core.communication.Communication | None = None, order: str = 'C') → heat.core.dndarray.DNDarray[source]

Returns a new DNDarray of given shape and data type filled with zero values. May be allocated split up across multiple nodes along the specified axis.

Parameters:

shape (int or Sequence[int,...]) – Desired shape of the output array, e.g. 1 or (1, 2, 3,).
dtype (datatype) – The desired HeAT data type for the array.
split (int or None, optional) – The axis along which the array is split and distributed; None means no distribution.
device (str or Device, optional) – Specifies the Device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.
order (str, optional) – 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).

Raises:

NotImplementedError – If order is one of the NumPy options 'K' or 'A'.

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)

zeros_like(a: heat.core.dndarray.DNDarray, dtype: Type[heat.core.types.datatype] | None = None, split: int | None = None, device: heat.core.devices.Device | None = None, comm: heat.core.communication.Communication | None = None, order: str = 'C') → heat.core.dndarray.DNDarray[source]

Returns a new 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.

Parameters:

a (DNDarray) – The shape, data-type, split axis, and device of a define these same attributes of the returned array.
dtype (datatype, optional) – Overrides the data type of the result.
split (int or None, optional) – The axis along which the array is split and distributed; defaults to a.split.
device (str or Device, optional) – Specifies the Device the array shall be allocated on, defaults to a.device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.
order (str, optional) – 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).

Raises:

NotImplementedError – If order is one of the NumPy options 'K' or 'A'.

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)

nonzero(x: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Return a 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 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)].

Parameters:: x (DNDarray) – Input array

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)

Return a DNDarray containing elements chosen from x or y depending on condition. Result is a DNDarray with elements from x where cond is True, and elements from y elsewhere (False).

Parameters:

cond (DNDarray) – Condition of interest, where true yield x otherwise yield y
x (DNDarray or int or float, optional) – Values from which to choose. x, y and condition need to be broadcastable to some shape.
y (DNDarray or int or float, optional) – Values from which to choose. x, y and condition need to be broadcastable to some shape.

Raises:

NotImplementedError – if splits of the two input DNDarray differ
TypeError – if only x or y is given or both are not DNDarrays or numerical scalars

Notes

When only condition is provided, this function is a shorthand for nonzero().

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)

load(path: str, *args: List[object] | None, **kwargs: Dict[str, object] | None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

path (str) – Path to the file to be read.
args (list, optional) – Additional options passed to the particular functions.
kwargs (dict, optional) – Additional options passed to the particular functions.

Raises:

ValueError – If the file extension is not understood or known.
RuntimeError – If the optional dependency for a file extension is not available.

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)

See also

load_csv(): Loads data from a CSV file.
load_csv_from_folder(): Loads multiple .csv files into one DNDarray which will be returned.
load_hdf5(): Loads data from an HDF5 file.
load_netcdf(): Loads data from a NetCDF4 file.
load_npy_from_path(): Loads multiple .npy files into one DNDarray which will be returned.
load_zarr(): Loads zarr-Format into DNDarray which will be returned.

load_csv(path: str, header_lines: int = 0, sep: str = ',', dtype: heat.core.types.datatype = types.float32, encoding: str = 'utf-8', split: int | None = None, device: str | None = None, comm: heat.core.communication.Communication | None = None) → heat.core.dndarray.DNDarray[source]

Loads data from a CSV file. The data will be distributed along the axis 0.

Parameters:

path (str) – Path to the CSV file to be read.
header_lines (int, optional) – The number of columns at the beginning of the file that should not be considered as data.
sep (str, optional) – The single char or str that separates the values in each row.
dtype (datatype, optional) – Data type of the resulting array.
encoding (str, optional) – The type of encoding which will be used to interpret the lines of the csv file as strings.
split (int or None : optional) – Along which axis the resulting array should be split. Default is None which means each node will have the full array.
device (str, optional) – The device id on which to place the data, defaults to globally set default device.
comm (Communication, optional) – The communication to use for the data distribution, defaults to global default

Raises:

TypeError – If any of the input parameters are not of correct type.

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)

save_csv(data: heat.core.dndarray.DNDarray, path: str, header_lines: Iterable[str] = None, sep: str = ',', decimals: int = -1, encoding: str = 'utf-8', comm: heat.core.communication.Communication | None = None, truncate: bool = True)[source]

Saves data to CSV files. Only 2D data, all split axes.

Parameters:

data (DNDarray) – The DNDarray to be saved to CSV.
path (str) – The path as a string.
header_lines (Iterable[str]) – Optional iterable of str to prepend at the beginning of the file. No pound sign or any other comment marker will be inserted.
sep (str) – The separator character used in this CSV.
decimals (int) – Number of digits after decimal point.
encoding (str) – The encoding to be used in this CSV.
comm (Optional[Communication]) – An optional object of type Communication to be used.
truncate (bool) – 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.

save(data: heat.core.dndarray.DNDarray, path: str, *args: List[object] | None, **kwargs: Dict[str, object] | None)[source]

Attempts to save data from a DNDarray to disk. An auto-detection based on the file format extension is performed.

Parameters:

data (DNDarray) – The array holding the data to be stored
path (str) – Path to the file to be stored.
args (list, optional) – Additional options passed to the particular functions.
kwargs (dict, optional) – Additional options passed to the particular functions.

Raises:

ValueError – If the file extension is not understood or known.
RuntimeError – If the optional dependency for a file extension is not available.

Examples

>>> x = ht.arange(100, split=0)
>>> ht.save(x, "data.h5", "DATA", mode="a")

supports_hdf5() → bool[source]: Returns True if Heat supports reading from and writing to HDF5 files, False otherwise.

supports_netcdf() → bool[source]: Returns True if Heat supports reading from and writing to netCDF4 files, False otherwise.

load_npy_from_path(path: str, dtype: heat.core.types.datatype = types.int32, split: int = 0, device: str | None = None, comm: heat.core.communication.Communication | None = None) → heat.core.dndarray.DNDarray[source]

Loads multiple .npy files into one DNDarray which will be returned. The data will be concatenated along the split axis provided as input.

Parameters:

path (str) – Path to the directory in which .npy-files are located.
dtype (datatype, optional) – Data type of the resulting array.
split (int) – Along which axis the loaded arrays should be concatenated.
device (str, optional) – The device id on which to place the data, defaults to globally set default device.
comm (Communication, optional) – The communication to use for the data distribution, default is ‘heat.MPI_WORLD’

supports_zarr() → bool[source]: Returns True if zarr is installed, False otherwise.

all(x: heat.core.dndarray.DNDarray, axis: int | Tuple[int] | None = None, out: heat.core.dndarray.DNDarray | None = None, keepdims: bool = False) → heat.core.dndarray.DNDarray | bool[source]

Test whether all array elements along a given axis evaluate to True. A new boolean or DNDarray is returned unless out is specified, in which case a reference to out is returned.

Parameters:

x (DNDarray) – Input array or object that can be converted to an array.
axis (None or int or Tuple[int,...], optional) – 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.
out (DNDarray, optional) – Alternate output array in which to place the result. It must have the same shape as the expected output and its type is preserved.
keepdims (bool, optional) – 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.

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)

allclose(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray, rtol: float = 1e-05, atol: float = 1e-08, equal_nan: bool = False) → bool[source]

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

Parameters:

x (DNDarray) – First array to compare
y (DNDarray) – Second array to compare
atol (float, optional) – Absolute tolerance.
rtol (float, optional) – Relative tolerance (with respect to y).
equal_nan (bool, optional) – 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.

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

any(x, axis: int | None = None, out: heat.core.dndarray.DNDarray | None = None, keepdims: bool = False) → heat.core.dndarray.DNDarray[source]

Returns a 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.

Parameters:

x (DNDarray) – Input tensor
axis (int, optional) – Axis along which a logic OR reduction is performed. With axis=None, the logical OR is performed over all dimensions of the array.
out (DNDarray, optional) – 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.
keepdims (bool, optional) – 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.

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)

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[source]

Returns a boolean 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.

Parameters:

x (DNDarray) – Input array to compare.
y (DNDarray) – Input array to compare.
rtol (float) – The relative tolerance parameter.
atol (float) – The absolute tolerance parameter.
equal_nan (bool) – 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.

isfinite(x: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Test element-wise for finiteness (not infinity or not Not a Number) and return result as a boolean DNDarray.

Parameters:: x (DNDarray) – Input tensor

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)

isinf(x: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Test element-wise for positive or negative infinity and return result as a boolean DNDarray.

Parameters:: x (DNDarray) – Input tensor

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)

isnan(x: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Test element-wise for NaN and return result as a boolean DNDarray.

Parameters:: x (DNDarray) – Input tensor

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)

isneginf(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Test if each element of x is negative infinite, return result as a boolean DNDarray.

Parameters:

x (DNDarray) – Input tensor
out (DNDarray, optional) – Alternate output array in which to place the result. It must have the same shape as the expected output and its type is preserved.

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)

isposinf(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None)[source]

Test if each element of x is positive infinite, return result as a boolean DNDarray.

Parameters:

x (DNDarray) – Input tensor
out (DNDarray, optional) – Alternate output array in which to place the result. It must have the same shape as the expected output and its type is preserved.

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)

logical_and(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Compute the truth value of x AND y element-wise. Returns a boolean DNDarray containing the truth value of x AND y element-wise.

Parameters:

x (DNDarray) – Input array of same shape
y (DNDarray) – Input array of same shape

Examples

>>> ht.logical_and(ht.array([True, False]), ht.array([False, False]))
DNDarray([False, False], dtype=ht.bool, device=cpu:0, split=None)

logical_not(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Computes the element-wise logical NOT of the given input DNDarray.

Parameters:

x (DNDarray) – Input array
out (DNDarray, optional) – Alternative output array in which to place the result. It must have the same shape as the expected output. The output is a DNDarray with datatype=bool.

Examples

>>> ht.logical_not(ht.array([True, False]))
DNDarray([False,  True], dtype=ht.bool, device=cpu:0, split=None)

logical_or(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Returns boolean DNDarray containing the element-wise logical NOT of the given input DNDarray.

Parameters:

x (DNDarray) – Input array of same shape
y (DNDarray) – Input array of same shape

Examples

>>> ht.logical_or(ht.array([True, False]), ht.array([False, False]))
DNDarray([ True, False], dtype=ht.bool, device=cpu:0, split=None)

logical_xor(x: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Computes the element-wise logical XOR of the given input DNDarray.

Parameters:

x (DNDarray) – Input array of same shape
y (DNDarray) – Input array of same shape

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)

signbit(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Checks if signbit is set element-wise (less than zero).

Parameters:

x (DNDarray) – The input array.
out (DNDarray, optional) – The output array.

Examples

>>> a = ht.array([2, -1.3, 0])
>>> ht.signbit(a)
DNDarray([False,  True, False], dtype=ht.bool, device=cpu:0, split=None)

balance(array: heat.core.dndarray.DNDarray, copy=False) → heat.core.dndarray.DNDarray[source]

Out of place balance function. More information on the meaning of balance can be found in DNDarray.balance_().

Parameters:

array (DNDarray) – the DNDarray to be balanced
copy (bool, optional) – 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

broadcast_arrays(*arrays: heat.core.dndarray.DNDarray) → List[heat.core.dndarray.DNDarray][source]

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.

Parameters:: arrays (DNDarray) – An arbitrary number of to-be broadcasted ``DNDarray``s.

Notes

Broadcasted arrays are a view of the original arrays if possible, otherwise a copy is made.

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

broadcast_to(x: heat.core.dndarray.DNDarray, shape: Tuple[int, Ellipsis]) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – DNDarray to broadcast.
shape (Tuple[int, ...]) – Array shape. Must be compatible with x.

Raises:

ValueError – If the array is not compatible with the new shape according to PyTorch’s broadcasting rules.

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)

collect(arr: heat.core.dndarray.DNDarray, target_rank: int | None = 0) → heat.core.dndarray.DNDarray[source]

A function collecting a distributed DNDarray to one rank, chosen by the target_rank variable. It is a specific case of the redistribute_ method.

Parameters:

arr (DNDarray) – The DNDarray to be collected.
target_rank (int, optional) – The rank to which the DNDarray will be collected. Default: 0.

Raises:

TypeError – If the target rank is not an integer.
ValueError – If the target rank is out of bounds.

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)

column_stack(arrays: Sequence[heat.core.dndarray.DNDarray, Ellipsis]) → heat.core.dndarray.DNDarray[source]

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.

Parameters:: arrays (Sequence[DNDarray, ...]) – Sequence of `DNDarray`s.
Raises:: ValueError – If arrays have more than 2 dimensions

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.

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)

concatenate(arrays: Sequence[heat.core.dndarray.DNDarray, Ellipsis], axis: int = 0) → heat.core.dndarray.DNDarray[source]

Join 2 or more DNDarrays along an existing axis.

Parameters:

arrays (Sequence[DNDarray, ...]) – The arrays must have the same shape, except in the dimension corresponding to axis.
axis (int, optional) – The axis along which the arrays will be joined (default is 0).

Raises:

RuntimeError – If the concatenated DNDarray meta information, e.g. split or comm, does not match.
TypeError – If the passed parameters are not of correct type.
ValueError – If the number of passed arrays is less than two or their shapes do not match.

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.]])

diag(a: heat.core.dndarray.DNDarray, offset: int = 0) → heat.core.dndarray.DNDarray[source]

Extract a diagonal or construct a diagonal array. See the documentation for diagonal() for more information about extracting the diagonal.

Parameters:

a (DNDarray) – 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.
offset (int, optional) – The offset from the main diagonal. Offset greater than zero means above the main diagonal, smaller than zero is below the main diagonal.

See also

diagonal()

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)

diagonal(a: heat.core.dndarray.DNDarray, offset: int = 0, dim1: int = 0, dim2: int = 1) → heat.core.dndarray.DNDarray[source]

Extract a diagonal of an n-dimensional array with n > 1. The returned array will be of dimension n-1.

Parameters:

a (DNDarray) – The array of which the diagonal should be extracted.
offset (int, optional) – 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.
dim1 (int, optional) – First dimension with respect to which to take the diagonal.
dim2 (int, optional) – Second dimension with respect to which to take the diagonal.

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)

dsplit(x: Sequence[heat.core.dndarray.DNDarray, Ellipsis], indices_or_sections: Iterable) → List[heat.core.dndarray.DNDarray, Ellipsis][source]

Split array into multiple sub-DNDarrays along the 3rd axis (depth). Returns a list of sub-DNDarrays as copies of parts of x.

Parameters:

x (DNDarray) – DNDArray to be divided into sub-DNDarrays.
indices_or_sections (int or 1-dimensional array_like (i.e. undistributed DNDarray, list or tuple)) – 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.

Raises:

ValueError – If indices_or_sections is given as integer, but a split does not result in equal division.

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.

See also

split(), hsplit(), vsplit()

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([])]

expand_dims(a: heat.core.dndarray.DNDarray, axis: int) → heat.core.dndarray.DNDarray[source]

Expand the shape of an array. Insert a new axis that will appear at the axis position in the expanded array shape.

Parameters:

a (DNDarray) – Input array to be expanded.
axis (int) – Position in the expanded axes where the new axis is placed.

Raises:

ValueError – If axis is not consistent with the available dimensions.

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)

flatten(a: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Flattens an array into one dimension.

Parameters:: a (DNDarray) – Array to collapse

Warning

If a.split>0, the array must be redistributed along the first axis (see resplit()).

See also

ravel()

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)

flip(a: heat.core.dndarray.DNDarray, axis: int | Tuple[int, Ellipsis] = None) → heat.core.dndarray.DNDarray[source]

Reverse the order of elements in an array along the given axis. The shape of the array is preserved, but the elements are reordered.

Parameters:

a (DNDarray) – Input array to be flipped
axis (int or Tuple[int,...]) – The axis or sequence of axes to be flipped

See also

fliplr(), flipud()

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])

fliplr(a: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Flip array in the left/right direction. If a.ndim>2, flip along dimension 1.

Parameters:: a (DNDarray) – Input array to be flipped, must be at least 2-D

See also

flip(), flipud()

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]])

flipud(a: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Flip array in the up/down direction.

Parameters:: a (DNDarray) – Input array to be flipped

See also

flip(), fliplr()

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])

hsplit(x: heat.core.dndarray.DNDarray, indices_or_sections: Iterable) → List[heat.core.dndarray.DNDarray, Ellipsis][source]

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.

Parameters:

x (DNDarray) – DNDArray to be divided into sub-DNDarrays.
indices_or_sections (int or 1-dimensional array_like (i.e. undistributed DNDarray, list or tuple)) – 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.

Raises:

ValueError – If indices_or_sections is given as integer, but a split does not result in equal division.

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.

See also

split(), dsplit(), vsplit()

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]]])]

hstack(arrays: Sequence[heat.core.dndarray.DNDarray, Ellipsis]) → heat.core.dndarray.DNDarray[source]

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.

Parameters:: arrays (Sequence[DNDarray, ...]) – The arrays must have the same shape along all but the second axis, except 1-D arrays which can be any length.

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]])

moveaxis(x: heat.core.dndarray.DNDarray, source: int | Sequence[int], destination: int | Sequence[int]) → heat.core.dndarray.DNDarray[source]

Moves axes at the positions in source to new positions.

Parameters:

x (DNDarray) – The input array.
source (int or Sequence[int, ...]) – Original positions of the axes to move. These must be unique.
destination (int or Sequence[int, ...]) – Destination positions for each of the original axes. These must also be unique.

See also

transpose: Permute the dimensions of an array.

Raises:

TypeError – If source or destination are not ints, lists or tuples.
ValueError – If source and destination do not have the same number of elements.

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)

pad(array: heat.core.dndarray.DNDarray, pad_width: int | Sequence[Sequence[int, int], Ellipsis], mode: str = 'constant', constant_values: int = 0) → heat.core.dndarray.DNDarray[source]

Pads tensor with a specific value (default=0). (Not all dimensions supported)

Parameters:

array (DNDarray) – Array to be padded
pad_width (Union[int, Sequence[Sequence[int, int], ...]]) –
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)
mode (str, optional) –
- ‘constant’ (default): Pads the input tensor boundaries with a constant value. This is available for arbitrary dimensions
constant_values (Union[int, float, Sequence[Sequence[int,int], ...], Sequence[Sequence[float,float], ...]]) –
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.

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.

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)

ravel(a: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Return a flattened view of a if possible. A copy is returned otherwise.

Parameters:: a (DNDarray) – array to collapse

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.

See also

flatten()

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)

redistribute(arr: heat.core.dndarray.DNDarray, lshape_map: torch.Tensor = None, target_map: torch.Tensor = None) → heat.core.dndarray.DNDarray[source]

Redistributes the data of the 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.

Parameters:

arr (DNDarray) – DNDarray to redistribute
lshape_map (torch.Tensor, optional) – The current lshape of processes. Units are [rank, lshape].
target_map (torch.Tensor, optional) – 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.

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)

repeat(a: Iterable, repeats: Iterable, axis: int | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

a (array_like (i.e. int, float, or tuple/ list/ np.ndarray/ ht.DNDarray of ints/floats)) – Array containing the elements to be repeated.
repeats (int, or 1-dimensional/ DNDarray/ np.ndarray/ list/ tuple of ints) – 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).
axis (int, optional) – The axis along which to repeat values. By default, use the flattened input array and return a flat output array.

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]])

reshape(a: heat.core.dndarray.DNDarray, *shape: int | Tuple[int, Ellipsis], **kwargs) → heat.core.dndarray.DNDarray[source]

Returns an array with the same data and number of elements as a, but with the specified shape.

Parameters:

a (DNDarray) – The input array
shape (Union[int, Tuple[int,...]]) – 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.
new_split (int, optional) – 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.
**kwargs – Extra keyword arguments.

Raises:

ValueError – If the number of elements in the new shape is inconsistent with the input data.

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.

See also

ravel()

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)

resplit(arr: heat.core.dndarray.DNDarray, axis: int | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

arr (DNDarray) – The array from which to resplit
axis (int or None) – The new split axis, None denotes gathering, an int will set the new split axis

Warning

This operation might involve a significant communication overhead. Use it sparingly and preferably for small arrays.

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)

roll(x: heat.core.dndarray.DNDarray, shift: int | Tuple[int], axis: int | Tuple[int] | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – input array
shift (Union[int, Tuple[int, ...]]) – 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.
axis (Optional[Union[int, Tuple[int, ...]]]) – 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.

Raises:

TypeError – If ‘shift’ or ‘axis’ is not of type int, list or tuple.
ValueError – If ‘shift’ and ‘axis’ are tuples with different sizes.

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)

rot90(m: heat.core.dndarray.DNDarray, k: int = 1, axes: Sequence[int, int] = (0, 1)) → heat.core.dndarray.DNDarray[source]

Rotate an array by 90 degrees in the plane specified by axes. Rotation direction is from the first towards the second axis.

Parameters:

m (DNDarray) – Array of two or more dimensions.
k (integer) – Number of times the array is rotated by 90 degrees.
axes ((2,) Sequence[int, int]) – The array is rotated in the plane defined by the axes. Axes must be different.

Raises:

ValueError – If len(axis)!=2.
ValueError – If the axes are the same.
ValueError – If axes are out of range.

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.

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)

row_stack(arrays: Sequence[heat.core.dndarray.DNDarray, Ellipsis]) → heat.core.dndarray.DNDarray[source]

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.

Parameters:: arrays (Sequence[DNDarrays, ...]) – Sequence of `DNDarray`s.
Raises:: ValueError – If arrays have more than 2 dimensions

Notes

All ``DNDarray``s in the sequence must have the same number of columns. All ``DNDarray``s must be split along the same axis!

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]])

shape(a: heat.core.dndarray.DNDarray) → Tuple[int, Ellipsis][source]

Returns the global shape of a (potentially distributed) DNDarray as a tuple.

Parameters:: a (DNDarray) – The input DNDarray.

sort(a: heat.core.dndarray.DNDarray, axis: int = -1, descending: bool = False, out: heat.core.dndarray.DNDarray | None = None)[source]

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

Parameters:

a (DNDarray) – Input array to be sorted.
axis (int, optional) – The dimension to sort along. Default is the last axis.
descending (bool, optional) – If set to True, values are sorted in descending order.
out (DNDarray, optional) – 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.

Raises:

ValueError – If axis is not consistent with the available dimensions.

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]]))

split(x: heat.core.dndarray.DNDarray, indices_or_sections: Iterable, axis: int = 0) → List[heat.core.dndarray.DNDarray, Ellipsis][source]

Split a DNDarray into multiple sub-DNDarrays. Returns a list of sub-DNDarrays as copies of parts of x.

Parameters:

x (DNDarray) – DNDArray to be divided into sub-DNDarrays.
indices_or_sections (int or 1-dimensional array_like (i.e. undistributed DNDarray, list or tuple)) –
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.
axis (int, optional) – The axis along which to split, default is 0. axis is not allowed to equal x.split if x is distributed.

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.

See also

dsplit(), hsplit(), vsplit()

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]])]

squeeze(x: heat.core.dndarray.DNDarray, axis: int | Tuple[int, Ellipsis] = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – Input data.
axis (None or int or Tuple[int,...], optional) – 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.

Raises:

ValueError –

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).

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

stack(arrays: Sequence[heat.core.dndarray.DNDarray, Ellipsis], axis: int = 0, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

arrays (Sequence[DNDarrays, ...]) – Each DNDarray must have the same shape, must be split along the same axis, and must be balanced.
axis (int, optional) – The axis in the result array along which the input arrays are stacked.
out (DNDarray, optional) – 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).

Raises:

TypeError – If arrays in sequence are not DNDarray`s, or if their `dtype attribute does not match.
ValueError – If arrays contains less than 2 `DNDarray`s.
ValueError – If the DNDarray`s are of different shapes, or if they are split along different axes (`split attribute).
RuntimeError – If the DNDarrays reside on different devices.

Notes

Split semantics: 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 \(axis <= split\), output will be distributed along \(split+1\)
if \(axis > split\), output will be distributed along split

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]]])

swapaxes(x: heat.core.dndarray.DNDarray, axis1: int, axis2: int) → heat.core.dndarray.DNDarray[source]

Interchanges two axes of an array.

Parameters:

x (DNDarray) – Input array.
axis1 (int) – First axis.
axis2 (int) – Second axis.

See also

transpose(): Permute the dimensions of an array.

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)

tile(x: heat.core.dndarray.DNDarray, reps: Sequence[int, Ellipsis]) → heat.core.dndarray.DNDarray[source]

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).

Parameters:

x (DNDarray) – Input
reps (Sequence[ints,...]) – Repetitions

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.

Return type:

DNDarray

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)

topk(a: heat.core.dndarray.DNDarray, k: int, dim: int = -1, largest: bool = True, sorted: bool = True, out: Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] | None = None) → Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray][source]

Returns the \(k\) highest entries in the array. (Not Stable for split arrays)

Parameters:

a (DNDarray) – Input data
k (int) – Desired number of output items
dim (int, optional) – Dimension along which to sort, per default the last dimension
largest (bool, optional) – If True, return the \(k\) largest items, otherwise return the \(k\) smallest items
sorted (bool, optional) – Whether to sort the output (descending if largest is True, else ascending)
out (Tuple[DNDarray, ...], optional) – output buffer

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))

unfold(a: heat.core.dndarray.DNDarray, axis: int, size: int, step: int = 1)[source]

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)

Parameters:

a (DNDarray) – array to unfold
axis (int) – axis in which unfolding happens
size (int) – the size of each slice that is unfolded, must be greater than 1
step (int) – the step between each slice, must be at least 1
Example
``` –
ht.arange(1. (>>> x =)
8)
x (>>>)
DNDarray([1. (0, split=e))
2. (0, split=e))
3. (0, split=e))
4. (0, split=e))
5. (0, split=e))
6. (0, split=e))
7.] (0, split=e))
dtype=ht.float32 (0, split=e))
device=cpu (0, split=e))
ht.unfold(x (>>>)
0
2
1)
DNDarray([[1. – [2., 3.], [3., 4.], [4., 5.], [5., 6.], [6., 7.]], dtype=ht.float32, device=cpu:0, split=None)
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)

Parameters:

ht.unfold(x (>>>)
0
2
2)
DNDarray([[1. – [3., 4.], [5., 6.]], dtype=ht.float32, device=cpu:0, split=None)
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)

Parameters:: ``` –

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.

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][source]

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.

Parameters:

a (DNDarray) – Input array.
sorted (bool, optional) – Whether the found elements should be sorted before returning as output. Warning: sorted is not working if axis!=None and axis!=a.split
return_inverse (bool, optional) – Whether to also return the indices for where elements in the original input ended up in the returned unique list.
axis (int, optional) – Axis along which unique elements should be found. Default to None, which will return a one dimensional list of unique values.

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]])

vsplit(x: heat.core.dndarray.DNDarray, indices_or_sections: Iterable) → List[heat.core.dndarray.DNDarray, Ellipsis][source]

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.

Parameters:

x (DNDarray) – DNDArray to be divided into sub-DNDarrays.
indices_or_sections (Iterable) –
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.

Raises:

ValueError – If indices_or_sections is given as integer, but a split does not result in equal division.

Notes

Please refer to the split documentation. hsplit() is equivalent to split with axis=0, the array is always split along the first axis regardless of the array dimension.

See also

split(), dsplit(), hsplit()

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]]])]

vstack(arrays: Sequence[heat.core.dndarray.DNDarray, Ellipsis]) → heat.core.dndarray.DNDarray[source]

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 concatenate() function provides more general stacking operations.

Parameters:: arrays (Sequence[DNDarray,...]) – The arrays must have the same shape along all but the first axis. 1-D arrays must have the same length.

Notes

The split axis will be switched to 1 in the case that both elements are 1D and split=0

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]])

copy(x: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Return a deep copy of the given object.

Parameters:: x (DNDarray) – Input array to be copied.

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)

sanitize_memory_layout(x: torch.Tensor, order: str = 'C') → torch.Tensor[source]

Return the given object with memory layout as defined below. The default memory distribution is assumed.

Parameters:

x (torch.Tensor) – Input data
order (str, optional.) – 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).

get_printoptions() → dict[source]: Returns the currently configured printing options as key-value pairs.

global_printing() → None[source]

For DNDarray`s, the builtin `print function will gather all of the data, format it then print it on ONLY rank 0.

Return type:: None

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)

local_printing() → None[source]

The builtin print function will now print the local PyTorch Tensor values for DNDarrays given as arguments.

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.]]

print0(*args, **kwargs) → None[source]

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.

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

set_printoptions(precision=None, threshold=None, edgeitems=None, linewidth=None, profile=None, sci_mode=None)[source]

Configures the printing options. List of items shamelessly taken from NumPy and PyTorch (thanks guys!).

Parameters:

precision (int, optional) – Number of digits of precision for floating point output (default=4).
threshold (int, optional) – Total number of array elements which trigger summarization rather than full repr string (default=1000).
edgeitems (int, optional) – Number of array items in summary at beginning and end of each dimension (default=3).
linewidth (int, optional) – The number of characters per line for the purpose of inserting line breaks (default = 80).
profile (str, optional) – Sane defaults for pretty printing. Can override with any of the above options. Can be any one of default, short, full.
sci_mode (bool, optional) – Enable (True) or disable (False) scientific notation. If None (default) is specified, the value is automatically inferred by HeAT.

eq(x, y) → heat.core.dndarray.DNDarray[source]

Returns a DNDarray containing the results of element-wise comparision. Takes the first and second operand (scalar or DNDarray) whose elements are to be compared as argument. Returns False if the operands are not scalars or DNDarray

Parameters:

x (DNDarray or scalar) – The first operand involved in the comparison
y (DNDarray or scalar) – The second operand involved in the comparison

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

equal(x: heat.core.dndarray.DNDarray | float | int, y: heat.core.dndarray.DNDarray | float | int) → bool[source]

Overall comparison of equality between two DNDarray. Returns True if two arrays have the same size and elements, and False otherwise.

Parameters:

x (DNDarray or scalar) – The first operand involved in the comparison
y (DNDarray or scalar) – The second operand involved in the comparison

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

ge(x: heat.core.dndarray.DNDarray | float | int, y: heat.core.dndarray.DNDarray | float | int) → heat.core.dndarray.DNDarray[source]

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 DNDarray) whose elements are to be compared as argument.

Parameters:

x (DNDarray or scalar) – The first operand to be compared greater than or equal to second operand
y (DNDarray or scalar) – The second operand to be compared less than or equal to first operand

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)

gt(x: heat.core.dndarray.DNDarray | float | int, y: heat.core.dndarray.DNDarray | float | int) → heat.core.dndarray.DNDarray[source]

Returns a 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 DNDarray) whose elements are to be compared as argument.

Parameters:

x (DNDarray or scalar) – The first operand to be compared greater than second operand
y (DNDarray or scalar) – The second operand to be compared less than first operand

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)

le(x: heat.core.dndarray.DNDarray | float | int, y: heat.core.dndarray.DNDarray | float | int) → heat.core.dndarray.DNDarray[source]

Return a 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 DNDarray) whose elements are to be compared as argument.

Parameters:

x (DNDarray or scalar) – The first operand to be compared less than or equal to second operand
y (DNDarray or scalar) – The second operand to be compared greater than or equal to first operand

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)

lt(x: heat.core.dndarray.DNDarray | float | int, y: heat.core.dndarray.DNDarray | float | int) → heat.core.dndarray.DNDarray[source]

Returns a 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<y), not commutative. Takes the first and second operand (scalar or DNDarray) whose elements are to be compared as argument.

Parameters:

x (DNDarray or scalar) – The first operand to be compared less than second operand
y (DNDarray or scalar) – The second operand to be compared greater than first operand

Examples

>>> 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)

ne(x, y) → heat.core.dndarray.DNDarray[source]

Returns a 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 DNDarray) whose elements are to be compared as argument. Returns True if the operands are not scalars or DNDarray

Parameters:

x (DNDarray or scalar) – The first operand involved in the comparison
y (DNDarray or scalar) – The second operand involved in the comparison

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

abs(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None, dtype: Type[heat.core.types.datatype] | None = None) → heat.core.dndarray.DNDarray[source]

Returns DNDarray containing the elementwise abolute values of the input array x.

Parameters:

x (DNDarray) – The array for which the compute the absolute value.
out (DNDarray, optional) – 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.
dtype (datatype, optional) – Determines the data type of the output array. The values are cast to this type with potential loss of precision.

Raises:

TypeError – If dtype is not a heat type.

absolute(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None, dtype: Type[heat.core.types.datatype] | None = None) → heat.core.dndarray.DNDarray[source]

Calculate the absolute value element-wise. abs() is a shorthand for this function.

Parameters:

x (DNDarray) – The array for which the compute the absolute value.
out (DNDarray, optional) – 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.
dtype (datatype, optional) – Determines the data type of the output array. The values are cast to this type with potential loss of precision.

ceil(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Return the ceil of the input, element-wise. Result is a 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 \(\lceil x \rceil\).

Parameters:

x (DNDarray) – The value for which to compute the ceiled values.
out (DNDarray, optional) – 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.

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)

clip(x: heat.core.dndarray.DNDarray, min, max, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Returns a DNDarray with the elements of this array, but where values <a_min are replaced with a_min, and those >a_max with a_max.

Parameters:

x (DNDarray) – Array containing elements to clip.
min (scalar or None) – 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.
max (scalar or None) – 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.
out (DNDarray, optional) – 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.

Raises:

ValueError – if either min or max is not set

fabs(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – The array for which the compute the absolute value.
out (DNDarray, optional) – 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.

floor(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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 \(\lfloor x \rfloor\).

Parameters:

x (DNDarray) – The array for which to compute the floored values.
out (DNDarray, optional) – 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 DNDarray is allocated.

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)

modf(x: heat.core.dndarray.DNDarray, out: Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] | None = None) → Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray][source]

Return the fractional and integral parts of a DNDarray, element-wise. The fractional and integral parts are negative if the given number is negative.

Parameters:

x (DNDarray) – Input array
out (Tuple[DNDarray, DNDarray], optional) – 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.

Raises:

TypeError – if x is not a DNDarray
TypeError – if out is not None or a tuple of DNDarray
ValueError – if out is a tuple of length unqual 2

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))

round(x: heat.core.dndarray.DNDarray, decimals: int = 0, out: heat.core.dndarray.DNDarray | None = None, dtype: Type[heat.core.types.datatype] | None = None) → heat.core.dndarray.DNDarray[source]

Calculate the rounded value element-wise.

Parameters:

x (DNDarray) – The array for which the compute the rounded value.
decimals (int, optional) – Number of decimal places to round to. If decimals is negative, it specifies the number of positions to the left of the decimal point.
out (DNDarray, optional) – 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.
dtype (datatype, optional) – Determines the data type of the output array. The values are cast to this type with potential loss of precision.

Raises:

TypeError – if dtype is not a heat data type

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)

sgn(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Returns an indication of the sign of a number, element-wise. The definition for complex values is equivalent to \(x / |x|\).

Parameters:

x (DNDarray) – Input array
out (DNDarray, optional) – A location in which to store the results.

See also

sign(): Equivalent function on non-complex arrays. The definition for complex values is equivalent to \(x / \sqrt{x \cdot x}\)

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)

sign(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Returns an indication of the sign of a number, element-wise. The definition for complex values is equivalent to \(x / \sqrt{x \cdot x}\).

Parameters:

x (DNDarray) – Input array
out (DNDarray, optional) – A location in which to store the results.

See also

sgn(): Equivalent function on non-complex arrays. The definition for complex values is equivalent to \(x / |x|\).

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)

trunc(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – The array for which to compute the trunced values.
out (DNDarray, optional) – 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.

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)

sanitize_distribution(*args: heat.core.dndarray.DNDarray, target: heat.core.dndarray.DNDarray, diff_map: torch.Tensor = None) → heat.core.dndarray.DNDarray | Tuple(DNDarray)[source]

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.

Parameters:

args (DNDarray) – Dndarrays to be distributed
target (DNDarray) – Dndarray used to sanitize the metadata and to, if diff_map is not given, determine the resulting distribution.
diff_map (torch.Tensor (optional)) – 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.

Raises:

TypeError – When an argument is not a DNDarray or None.
ValueError – When the split-axes or sizes along the split-axis do not match.

See also

create_lshape_map(): Function to create the lshape_map.

sanitize_in(x: Any)[source]

Verify that input object is DNDarray.

Parameters:: x (Any) – Input object
Raises:: TypeError – When x is not a DNDarray.

sanitize_infinity(x: heat.core.dndarray.DNDarray | torch.Tensor) → int | float[source]

Returns largest possible value for the dtype of the input array.

Parameters:: x (Union[DNDarray, torch.Tensor]) – Input object.

sanitize_in_tensor(x: Any)[source]

Verify that input object is torch.Tensor.

Parameters:: x (Any) – Input object.
Raises:: TypeError – When x is not a torch.Tensor.

sanitize_lshape(array: heat.core.dndarray.DNDarray, tensor: torch.Tensor)[source]

Verify shape consistency when manipulating process-local arrays.

Parameters:

array (DNDarray) – the original, potentially distributed DNDarray
tensor (torch.Tensor) – process-local data meant to replace array.larray

Raises:

ValueError – if shape of local torch.Tensor is inconsistent with global DNDarray.

sanitize_out(out: heat.core.dndarray.DNDarray, output_shape: Tuple, output_split: int, output_device: str, output_comm: heat.core.communication.Communication = None)[source]

Validate output buffer out.

Parameters:

out (DNDarray) – the out buffer where the result of some operation will be stored
output_shape (Tuple) – the calculated shape returned by the operation
output_split (Int) – the calculated split axis returned by the operation
output_device (Str) – “cpu” or “gpu” as per location of data
output_comm (Communication) – Communication object of the result of the operation

Raises:

TypeError – if out is not a DNDarray.
ValueError – if shape, split direction, or device of the output buffer out do not match the operation result.

sanitize_sequence(seq: Sequence[int, Ellipsis] | Sequence[float, Ellipsis] | heat.core.dndarray.DNDarray | torch.Tensor) → List[source]

Check if sequence is valid, return list.

Parameters:: seq (Union[Sequence[int, ...], Sequence[float, ...], DNDarray, torch.Tensor]) – Input sequence.
Raises:: TypeError – if seq is neither a list nor a tuple

scalar_to_1d(x: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Turn a scalar DNDarray into a 1-D DNDarray with 1 element.

Parameters:: x (DNDarray) – with x.ndim = 0

sanitize_in_min_max_nd(input: Any, min_nd: int | None = None, max_nd: int | None = None) → None[source]: Verify that input object input is a DNDarray with at least min_nd or at most max_nd dimensions. If not raise ValueError If not DNDarray raise TypeError

argmax(x: heat.core.dndarray.DNDarray, axis: int | None = None, out: heat.core.dndarray.DNDarray | None = None, **kwargs: object) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – Input array.
axis (int, optional) – By default, the index is into the flattened array, otherwise along the specified axis.
out (DNDarray, optional.) – If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype.
**kwargs – Extra keyword arguments

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)

argmin(x: heat.core.dndarray.DNDarray, axis: int | None = None, out: heat.core.dndarray.DNDarray | None = None, **kwargs: object) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – Input array.
axis (int, optional) – By default, the index is into the flattened array, otherwise along the specified axis.
out (DNDarray, optional) – Issue #100 If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype.
**kwargs – Extra keyword arguments

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)

average(x: heat.core.dndarray.DNDarray, axis: int | Tuple[int, Ellipsis] | None = None, weights: heat.core.dndarray.DNDarray | None = None, returned: bool = False) → heat.core.dndarray.DNDarray | Tuple[heat.core.dndarray.DNDarray, Ellipsis][source]

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.

Parameters:

x (DNDarray) – Array containing data to be averaged.
axis (None or int or Tuple[int,...], optional) – 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.
weights (DNDarray, optional) – 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 mean().
returned (bool, optional) – 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.

Raises:

ZeroDivisionError – When all weights along axis are zero.
TypeError – When the length of 1D weights is not the same as the shape of x along axis.

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.

bincount(x: heat.core.dndarray.DNDarray, weights: heat.core.dndarray.DNDarray | None = None, minlength: int = 0) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – 1-dimensional, non-negative ints
weights (DNDarray, optional) – Weight for each value in the input tensor. Array of the same shape as x. Same split as x.
minlength (int, non-negative, optional) – Minimum number of bins

Raises:

ValueError – If x and weights don’t have the same distribution.

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)

bucketize(input: heat.core.dndarray.DNDarray, boundaries: heat.core.dndarray.DNDarray | torch.Tensor, out_int32: bool = False, right: bool = False, out: heat.core.dndarray.DNDarray = None) → heat.core.dndarray.DNDarray[source]

Returns the indices of the buckets to which each value in the input belongs, where the boundaries of the buckets are set by boundaries.

Parameters:

input (DNDarray) – The input array.
boundaries (DNDarray or torch.Tensor) – monotonically increasing sequence defining the bucket boundaries, 1-dimensional, not distributed
out_int32 (bool, optional) – set the dtype of the output to ht.int64 (False) or ht.int32 (True)
right (bool, optional) – indicate whether the buckets include the right (False) or left (True) boundaries, see Notes.
out (DNDarray, optional) – The output array, must be the shame shape and split as the input array.

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.

See also

digitize: NumPy-like version of this function.

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)

cov(m: heat.core.dndarray.DNDarray, y: heat.core.dndarray.DNDarray | None = None, rowvar: bool = True, bias: bool = False, ddof: int | None = None) → heat.core.dndarray.DNDarray[source]

Estimate the covariance matrix of some data, m. For more imformation on the algorithm please see the numpy function of the same name

Parameters:

m (DNDarray) – 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.
y (DNDarray, optional) – An additional set of variables and observations. y has the same form as that of m.
rowvar (bool, optional) – 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.
bias (bool, optional) – 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.
ddof (int, optional) – 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.

digitize(x: heat.core.dndarray.DNDarray, bins: heat.core.dndarray.DNDarray | torch.Tensor, right: bool = False) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – The input array
bins (DNDarray or torch.Tensor) – A 1-dimensional array containing a monotonic sequence describing the bin boundaries, not distributed.
right (bool, optional) – Indicating whether the intervals include the right or the left bin edge, see Notes.

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.

See also

bucketize: PyTorch-like version of this function.

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)

histc(input: heat.core.dndarray.DNDarray, bins: int = 100, min: int = 0, max: int = 0, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

input (DNDarray) – the input array, must be of float type
bins (int, optional) – number of histogram bins
min (int, optional) – lower end of the range (inclusive)
max (int, optional) – upper end of the range (inclusive)
out (DNDarray, optional) – the output tensor, same dtype as input

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)

histogram(a: heat.core.dndarray.DNDarray, bins: int = 10, range: Tuple[int, int] = (0, 0), normed: bool | None = None, weights: heat.core.dndarray.DNDarray | None = None, density: bool | None = None) → heat.core.dndarray.DNDarray[source]

Compute the histogram of a DNDarray.

Parameters:

a (DNDarray) – the input array, must be of float type
bins (int, optional) – number of histogram bins
range (Tuple[int,int], optional) – lower and upper end of the bins. If not provided, range is simply (a.min(), a.max()).
normed (bool, optional) – Deprecated since NumPy version 1.6. TODO: remove.
weights (DNDarray, optional) – array of weights. Not implemented yet.
density (bool, optional) – Not implemented yet.

Notes

This is a wrapper function of histc() for some basic compatibility with the NumPy API.

See also

histc()

kurtosis(x: heat.core.dndarray.DNDarray, axis: int | None = None, unbiased: bool = True, Fischer: bool = True) → heat.core.dndarray.DNDarray[source]

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

Parameters:

x (ht.DNDarray) – Input array
axis (NoneType or Int) – Axis along which skewness is calculated, Default is to compute over the whole array x
unbiased (Bool) – if True (default) the calculations are corrected for bias
Fischer (bool) – Whether use Fischer’s definition or not. If true 3. is subtracted from the result.

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.

max(x: heat.core.dndarray.DNDarray, axis: int | Tuple[int, Ellipsis] | None = None, out: heat.core.dndarray.DNDarray | None = None, keepdims: bool | None = None) → heat.core.dndarray.DNDarray[source]

Return the maximum along a given axis.

Parameters:

x (DNDarray) – Input array.
axis (None or int or Tuple[int,...], optional) – 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.
out (DNDarray, optional) – 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.
keepdims (bool, optional) – 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.

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)

maximum(x1: heat.core.dndarray.DNDarray, x2: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Compares two DNDarrays and returns a new 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.

Parameters:

x1 (DNDarray) – The first array containing the elements to be compared.
x2 (DNDarray) – The second array containing the elements to be compared.
out (DNDarray, optional) – 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.

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)

mean(x: heat.core.dndarray.DNDarray, axis: int | Tuple[int, Ellipsis] | None = None) → heat.core.dndarray.DNDarray[source]

Calculates and returns the mean of a DNDarray. If an axis is given, the mean will be taken in that direction.

Parameters:

x (DNDarray) – Values for which the mean is calculated for. The dtype of x must be a float
axis (None or int or iterable) – Axis which the mean is taken in. Default None calculates mean of all data items.

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<split, then mean(x).split=x.split-1

Examples

>>> 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)

median(x: heat.core.dndarray.DNDarray, axis: int | None = None, keepdims: bool = False, sketched: bool = False, sketch_size: float | None = 1.0 / MPI.COMM_WORLD.size) → heat.core.dndarray.DNDarray[source]

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”).

Parameters:

x (DNDarray) – Input tensor
axis (int, or None, optional) – Axis along which the median is computed. Default is None, i.e., the median is computed along a flattened version of the DNDarray.
keepdims (bool, optional) – 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.
sketched (bool, optional) – 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.
sketch_size (float, optional) – 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.

min(x: heat.core.dndarray.DNDarray, axis: int | Tuple[int, Ellipsis] | None = None, out: heat.core.dndarray.DNDarray | None = None, keepdims: bool | None = None) → heat.core.dndarray.DNDarray[source]

Return the minimum along a given axis.

Parameters:

x (DNDarray) – Input array.
axis (None or int or Tuple[int,...]) – 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.
out (Tuple[DNDarray,DNDarray], optional) – 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.
keepdims (bool, optional) – 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.

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)

minimum(x1: heat.core.dndarray.DNDarray, x2: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Compares two DNDarrays and returns a new 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.

Parameters:

x1 (DNDarray) – The first array containing the elements to be compared.
x2 (DNDarray) – The second array containing the elements to be compared.
out (DNDarray, optional) – 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.

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)

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”).

Parameters:

x (DNDarray) – Input tensor
q (DNDarray, scalar, or list of scalars) – Percentile or sequence of percentiles to compute. Must belong to the interval [0, 100].
axis (int, tuple of ints, or None, optional) – 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.
out (DNDarray, optional.) – Output buffer.
interpolation (str, optional) –
Interpolation method to use when the desired percentile lies between two data points \(i < j\). Can be one of:
- ‘linear’: \(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’: \((i + j) / 2\).
keepdims (bool, optional) – 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.
sketched (bool, optional) – 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.
sketch_size (float, optional) – 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.

ptp(x: heat.core.dndarray.DNDarray, axis: int | Tuple[int, Ellipsis] | None = None, out: heat.core.dndarray.DNDarray | None = None, keepdims: bool = False) → heat.core.dndarray.DNDarray[source]

Range of values (maximum - minimum) along a given axis.

Parameters:

x (ht.DNDarray) – Input array.
axis (None or int or Tuple[int,...], optional) – 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.
out (DNDarray, optional) – Output array to place the result.
keepdims (bool, optional) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one.

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.

Return type:

ht.DNDarray

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)

skew(x: heat.core.dndarray.DNDarray, axis: int = None, unbiased: bool = True) → heat.core.dndarray.DNDarray[source]

Compute the sample skewness of a data set.

Parameters:

x (ht.DNDarray) – Input array
axis (NoneType or Int) – Axis along which skewness is calculated, Default is to compute over the whole array x
unbiased (Bool) – if True (default) the calculations are corrected for bias

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.

std(x: heat.core.dndarray.DNDarray, axis: int | Tuple[int] | List[int] = None, ddof: int = 0, **kwargs: object) → heat.core.dndarray.DNDarray[source]

Calculates the standard deviation of a DNDarray with the bessel correction. If an axis is given, the variance will be taken in that direction.

Parameters:

x (DNDarray) – array for which the std is calculated for. The datatype of x must be a float
axis (None or int or iterable) – Axis which the std is taken in. Default None calculates std of all data items.
ddof (int, optional) – 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.
**kwargs – Extra keyword arguments

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)

var(x: heat.core.dndarray.DNDarray, axis: int | Tuple[int] | List[int] = None, ddof: int = 0, **kwargs: object) → heat.core.dndarray.DNDarray[source]

Calculates and returns the variance of a DNDarray. If an axis is given, the variance will be taken in that direction.

Parameters:

x (DNDarray) – Array for which the variance is calculated for. The datatype of x must be a float
axis (None or int or iterable) – Axis which the std is taken in. Default None calculates std of all data items.
ddof (int, optional) – 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.
**kwargs – Extra keyword arguments

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<split, then var(x).split=x.split - 1

The variance is the average of the squared deviations from the mean, i.e., var=mean(abs(x - x.mean())**2). The mean is normally calculated as x.sum()/N, where N = len(x). If, however, ddof is specified, the divisor N - ddof is used instead. In standard statistical practice, ddof=1 provides an unbiased estimator of the variance of a hypothetical infinite population. ddof=0 provides a maximum likelihood estimate of the variance for normally distributed variables.

Examples

>>> 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)

broadcast_shape(shape_a: Tuple[int, Ellipsis], shape_b: Tuple[int, Ellipsis]) → Tuple[int, Ellipsis][source]

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

Parameters:

shape_a (Tuple[int,...]) – Shape of first operand
shape_b (Tuple[int,...]) – Shape of second operand

Raises:

ValueError – If the two shapes cannot be broadcast.

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 "<stdin>", line 1, in <module>
  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)

broadcast_shapes(*shapes: Tuple[int, Ellipsis]) → Tuple[int, Ellipsis][source]

Infers, if possible, the broadcast output shape of multiple operands.

Parameters:: *shapes (Tuple[int,...]) – Shapes of operands.
Returns:: The broadcast output shape.
Return type:: Tuple[int, …]
Raises:: ValueError – If the shapes cannot be broadcast.

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 "<stdin>", line 1, in <module>
  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))

sanitize_shape(shape: int | Tuple[int, Ellipsis], lval: int = 0) → Tuple[int, Ellipsis][source]

Verifies and normalizes the given shape.

Parameters:

shape (int or Tupe[int,...]) – Shape of an array.
lval (int) – Lowest legal value

Raises:

ValueError – If the shape contains illegal values, e.g. negative numbers.
TypeError – If the given shape is neither and int or a sequence of ints.

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 "<stdin>", line 1, in <module>
  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

sanitize_slice(sl: slice, max_dim: int) → slice[source]

Remove None-types from a slice

Parameters:

sl (slice) – slice to adjust
max_dim (int) – maximum index for the given slice

Raises:

TypeError – if sl is not a slice.

class SplitTiles(arr: heat.core.dndarray.DNDarray)[source]

Initialize tiles with the tile divisions equal to the theoretical split dimensions in every dimension

Parameters:

arr (DNDarray) – Base array for which to create the tiles

Variables:

__DNDarray (DNDarray) – the DNDarray associated with the tiles
__lshape_map (torch.Tensor) – map of the shapes of the local torch tensors of arr
__tile_locations (torch.Tensor) – locations of the tiles of arr
__tile_ends_g (torch.Tensor) – the global indices of the ends of the tiles
__tile_dims (torch.Tensor) – the dimensions of all of the tiles

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)

__DNDarray

__lshape_map

__tile_locations

__tile_ends_g

__tile_dims

set_tile_locations(split: int, tile_dims: torch.Tensor, arr: heat.core.dndarray.DNDarray) → torch.Tensor[source]

Create a torch.Tensor which contains the locations of the tiles of arr for the given split

Parameters:

split (int) – Target split dimension. Does not need to be equal to arr.split
tile_dims (torch.Tensor) – Tensor containing the sizes of the each tile
arr (DNDarray) – Array for which the tiles are being created for

__getitem__(key: int | slice | Tuple[int | slice, Ellipsis]) → torch.Tensor[source]

Getitem function for getting tiles. Returns the tile which is specified is returned, but only on the process which it resides

Parameters:: key (int or Tuple or Slice) – Key which identifies the tile/s to get

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.]])

__get_tile_slices(key: int | slice | Tuple[int | slice, Ellipsis]) → Tuple[slice, Ellipsis]: Create and return slices to convert a key from the tile indices to the normal indices

get_tile_size(key: int | slice | Tuple[int | slice, Ellipsis]) → Tuple[int, Ellipsis][source]

Get the size of a tile or tiles indicated by the given key

Parameters:: key (int or slice or tuple) – which tiles to get

Set the values of a tile

Parameters:

key (int or Tuple or Slice) – Key which identifies the tile/s to get
value (int or torch.Tensor) – Value to be set on the tile

Examples

see getitem function for this class

get_subarray_params(from_axis: int, to_axis: int) → List[Tuple[List[int], List[int], List[int]]][source]

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.

Parameters:

from_axis (int) – Current split axis of global array.
to_axis (int) – New split axis of of subarrays array.

class SquareDiagTiles(arr: heat.core.dndarray.DNDarray, tiles_per_proc: int = 2)[source]

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]<<gshape[1].

Parameters:

arr (DNDarray) – The array to be tiled
tiles_per_proc (int, optional) – The number of divisions per process Default: 2

Variables:

__col_per_proc_list (List) – List is length of the number of processes, each element has the number of tile columns on the process whos rank equals the index
__DNDarray (DNDarray) – The whole DNDarray
__lshape_map (torch.Tensor) – unit -> [rank, row size, column size] Tensor filled with the shapes of the local tensors
__tile_map (torch.Tensor) – units -> row, column, start index in each direction, process Tensor filled with the global indices of the generated tiles
__row_per_proc_list (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

Warning

The generation of these tiles may unbalance the original DNDarray!

Notes

This tiling scheme is intended for use with the qr() function.

__DNDarray

__col_per_proc_list

__lshape_map

__last_diag_pr

__row_per_proc_list

__tile_map

__row_inds

__col_inds

__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<n and arr.split==1

__adjust_last_row_sp0_m_ge_n(arr: heat.core.dndarray.DNDarray, lshape_map: torch.Tensor, last_diag_pr: int, row_inds: List[int, Ellipsis], row_per_proc_list: List[int, Ellipsis], tile_columns: int) → 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<arr.comm.size-1.

__adjust_lshape_sp0_1tile(arr: heat.core.dndarray.DNDarray, col_inds: List[int, Ellipsis], lshape_map: torch.Tensor, tiles_per_proc: int) → 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

__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.

Parameters:

arr (DNDarray) – DNDarray for which to find the tile columns for
lshape_map (torch.Tensor) – The map of the local shapes (for more info see: create_lshape_map())
tiles_per_proc (int) – The number of divisions per process

__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.

__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)

get_start_stop(key: int | slice | Tuple[int, slice, Ellipsis]) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor][source]

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.

Parameters:: key (int or Tuple or List or slice) – Indices to select the tile STRIDES ARE NOT ALLOWED, MUST BE GLOBAL INDICES

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))

__getitem__(key: int | slice | Tuple[int, slice, Ellipsis]) → torch.Tensor[source]

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

Parameters:: key (int, slice, tuple) – indices of the tile/s desired

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

local_get(key: int | slice | Tuple[int, slice, Ellipsis]) → torch.Tensor[source]

Returns the local tile/s corresponding to the key given Getitem routing using local indices, converts to global indices then uses getitem

Parameters:: key (int, slice, tuple, list) – 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

Examples

See local_set function.

local_set(key: int | slice | Tuple[int, slice, Ellipsis], value: int | float | torch.Tensor)[source]

Setitem routing to set data to a local tile (using local indices)

Parameters:

key (int or slice or Tuple[int,...]) – 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
value (torch.Tensor or int or float) – Data to be written to the tile

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.]])

local_to_global(key: int | slice | Tuple[int, slice, Ellipsis], rank: int) → Tuple[int, slice, Ellipsis][source]

Convert local indices to global indices

Parameters:

key (int or slice or Tuple or List) – 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
rank (int) – Process rank

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)

match_tiles(tiles_to_match: SquareDiagTiles) → None[source]

Function to match the tile sizes of another tile map

Parameters:: tiles_to_match (SquareDiagTiles) – The tiles which should be matched by the current tiling scheme

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

__setitem__(key: int | slice | Tuple[int, slice, Ellipsis], value: int | float | torch.Tensor) → None[source]

Item setter, uses the torch item setter and the getitem routines to set the values of the original array (arr in __init__)

Parameters:

key (int or slice or Tuple[int,...]) – Tile indices to identify the target tiles
value (int or torch.Tensor) – Values to be set

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.]])

acos: Alias for arccos()

acosh(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – The array for which to compute the inverse hyperbolic cosine.
out (DNDarray, optional) – 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.

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)

asin: Alias for arcsin()

asinh(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – The array for which to compute the inverse hyperbolic sine.
out (DNDarray, optional) – 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.

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)

atan: Alias for arctan()

atan2: Alias for arctan2()

atanh(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – The array for which to compute the inverse hyperbolic tangent.
out (DNDarray, optional) – 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.

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)

arccos(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – The array for which to compute the trigonometric cosine.
out (DNDarray, optional) – 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.

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)

arccosh: Alias for acosh()

arcsin(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – The array for which to compute the trigonometric cosine.
out (DNDarray, optional) – 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.

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)

arcsinh: Alias for asinh()

arctan(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – The array for which to compute the trigonometric cosine.
out (DNDarray, optional) – 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.

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)

arctan2(x1: heat.core.dndarray.DNDarray, x2: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

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)

Parameters:

x1 (DNDarray) – y-coordinates
x2 (DNDarray) – x-coordinates. If x1.shape!=x2.shape, they must be broadcastable to a common shape (which becomes the shape of the output).

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)

arctanh: Alias for atanh()

cos(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Return the trigonometric cosine, element-wise.

Parameters:

x (ht.DNDarray) – The value for which to compute the trigonometric cosine.
out (ht.DNDarray or None, optional) – 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.

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)

cosh(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – The value for which to compute the hyperbolic cosine.
out (DNDarray, optional) – 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.

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)

deg2rad(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Convert angles from degrees to radians.

Parameters:

x (DNDarray) – The value for which to compute the angles in radians.
out (DNDarray, optional) – 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.

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)

degrees(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Convert angles from radians to degrees.

Parameters:

x (DNDarray) – The value for which to compute the angles in degrees.
out (DNDarray, optional) – 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.

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)

rad2deg(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Convert angles from radians to degrees.

Parameters:

x (DNDarray) – The value for which to compute the angles in degrees.
out (DNDarray, optional) – 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.

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)

radians(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Convert angles from degrees to radians.

Parameters:

x (DNDarray) – The value for which to compute the angles in radians.
out (DNDarray, optional) – 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.

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)

sin(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – The value for which to compute the trigonometric tangent.
out (DNDarray, optional) – 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.

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)

sinh(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – The value for which to compute the hyperbolic sine.
out (DNDarray or None, optional) – 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.

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)

tan(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Compute tangent element-wise. Result is a DNDarray of the same shape as x. Equivalent to sin()/cos() element-wise. If out was provided, tan is a reference to it.

Parameters:

x (DNDarray) – The value for which to compute the trigonometric tangent.
out (DNDarray or None, optional) – 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.

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)

tanh(x: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

x (DNDarray) – The value for which to compute the hyperbolic tangent.
out (DNDarray or None, optional) – 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.

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)

class datatype[source]

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)

_can_be_cast_safely_to = []

_can_be_cast_intuitively_to = []

mappings = []

torch_type() → NotImplemented[source]: Torch Datatype

char() → NotImplemented[source]: Datatype short-hand name

can_cast_to(to, casting: str = 'intuitive') → bool[source]

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.

Parameters:

to (Union[str, Type[datatype], Any]) – Target type to cast to.
casting (str, optional) –
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

Raises:

TypeError – If the types are not understood or casting is not a string
ValueError – If the casting rule is not understood

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

class number[source]

Bases: datatype

The general number datatype. Integer and Float classes will inherit from this.

class integer[source]

Bases: number

The general integer datatype. Specific integer classes inherit from this.

class signedinteger[source]

Bases: integer

The general signed integer datatype.

class unsignedinteger[source]

Bases: integer

The general unsigned integer datatype

class bool[source]

Bases: datatype

The boolean datatype in Heat

_can_be_cast_safely_to = ['bool', 'uint8', 'int8', 'int16', 'int32', 'int64', 'float16', 'float32', 'float64', 'complex64', 'complex128']

mappings

torch_type() → torch.dtype[source]: Torch Datatype

char() → str[source]: Datatype short-hand name

class floating[source]

Bases: number

The general floating point datatype class.

class int8[source]

Bases: signedinteger

8 bit signed integer datatype

_can_be_cast_safely_to = ['int8', 'int16', 'int32', 'int64', 'float16', 'float32', 'float64', 'complex64', 'complex128']

mappings

torch_type() → torch.dtype[source]: Torch Datatype

char() → str[source]: Datatype short-hand name

class int16[source]

Bases: signedinteger

16 bit signed integer datatype

_can_be_cast_safely_to = ['int16', 'int32', 'int64', 'float32', 'float64', 'complex64', 'complex128']

_can_be_cast_intuitively_to = ['float16']

mappings

torch_type() → torch.dtype[source]: Torch Datatype

char() → str[source]: Datatype short-hand name

class int32[source]

Bases: signedinteger

32 bit signed integer datatype

_can_be_cast_safely_to = ['int32', 'int64', 'float64', 'complex128']

_can_be_cast_intuitively_to = ['float32', 'complex64']

mappings

torch_type() → torch.dtype[source]: Torch Datatype

char() → str[source]: Datatype short-hand name

class int64[source]

Bases: signedinteger

64 bit signed integer datatype

_can_be_cast_safely_to = ['int64', 'float64', 'complex128']

mappings

torch_type() → torch.dtype[source]: Torch Datatype

char() → str[source]: Datatype short-hand name

class uint8[source]

Bases: unsignedinteger

8 bit unsigned integer datatype

_can_be_cast_safely_to = ['uint8', 'int16', 'int32', 'int64', 'float16', 'float32', 'float64', 'complex64', 'complex128']

mappings

torch_type() → torch.dtype[source]: Torch Datatype

char() → str[source]: Datatype short-hand name

class float16[source]

Bases: floating

The 16 bit floating point datatype

_can_be_cast_safely_to = ['float16', 'float32', 'float64', 'complex64', 'complex128']

mappings

torch_type() → torch.dtype[source]: Torch Datatype

char() → str[source]: Datatype short-hand name

class float32[source]

Bases: floating

The 32 bit floating point datatype

_can_be_cast_safely_to = ['float32', 'float64', 'complex64', 'complex128']

mappings

torch_type() → torch.dtype[source]: Torch Datatype

char() → str[source]: Datatype short-hand name

class float64[source]

Bases: floating

The 64 bit floating point datatype

_can_be_cast_safely_to = ['float64', 'complex128']

mappings

torch_type() → torch.dtype[source]: Torch Datatye

char() → str[source]: Datatype short-hand name

class flexible[source]

Bases: datatype

The general flexible datatype. Currently unused, placeholder for characters

can_cast(from_: str | Type[datatype] | Any, to: str | Type[datatype] | Any, casting: str = 'intuitive') → bool[source]

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.

Parameters:

from (Union[str, Type[datatype], Any]) – Scalar, data type or type specifier to cast from.
to (Union[str, Type[datatype], Any]) – Target type to cast to.
casting (str, optional) –
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

Raises:

TypeError – If the types are not understood

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

canonical_heat_type(a_type: str | Type[datatype] | Any) → Type[datatype][source]

Canonicalize the builtin Python type, type string or HeAT type into a canonical HeAT type.

Parameters:: a_type (type, str, datatype) – 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.
Raises:: TypeError – If the type cannot be converted.

heat_type_is_exact(ht_dtype: Type[datatype]) → bool[source]

Check if HeAT type is an exact type, i.e an integer type. True if ht_dtype is an integer, False otherwise

Parameters:: ht_dtype (Type[datatype]) – HeAT type to check

heat_type_is_inexact(ht_dtype: Type[datatype]) → bool[source]

Check if HeAT type is an inexact type, i.e floating point type. True if ht_dtype is a float or complex, False otherwise

Parameters:: ht_dtype (Type[datatype]) – HeAT type to check

heat_type_is_realfloating(ht_dtype: Type[datatype]) → bool[source]

Check if Heat type is a real floating point number, i.e float32 or float64

Parameters:: ht_dtype (Type[datatype]) – Heat type to check
Returns:: out – True if ht_dtype is a real float, False otherwise
Return type:: bool

heat_type_is_complexfloating(ht_dtype: Type[datatype]) → bool[source]

Check if Heat type is a complex floating point number, i.e complex64

Parameters:: ht_dtype (ht.dtype) – HeAT type to check
Returns:: out – True if ht_dtype is a complex float, False otherwise
Return type:: bool

iscomplex(x: dndarray.DNDarray) → dndarray.DNDarray[source]

Test element-wise if input is complex.

Parameters:: x (DNDarray) – The input DNDarray

Examples

>>> ht.iscomplex(ht.array([1 + 1j, 1]))
DNDarray([ True, False], dtype=ht.bool, device=cpu:0, split=None)

isreal(x: dndarray.DNDarray) → dndarray.DNDarray[source]

Test element-wise if input is real-valued.

Parameters:: x (DNDarray) – The input DNDarray

Examples

>>> ht.iscomplex(ht.array([1 + 1j, 1]))
DNDarray([ True, False], dtype=ht.bool, device=cpu:0, split=None)

issubdtype(arg1: str | Type[datatype] | Any, arg2: str | Type[datatype] | Any) → bool[source]

Returns True if first argument is a typecode lower/equal in type hierarchy.

Parameters:

arg1 (type, str, ht.dtype) – A description representing the type. It may be a a Python builtin type, string or an HeAT type already.
arg2 (type, str, ht.dtype) – A description representing the type. It may be a a Python builtin type, string or an HeAT type already.

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

heat_type_of(obj: str | Type[datatype] | Any | Iterable[str, Type[datatype], Any]) → Type[datatype][source]

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:

dtype property

type(obj)

type(obj[0])

Parameters:: obj (scalar or DNDarray or iterable) – The object for which to infer the type.
Raises:: TypeError – If the object’s type cannot be inferred.

promote_types(type1: str | Type[datatype] | Any, type2: str | Type[datatype] | Any) → Type[datatype][source]

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.

Parameters:

type1 (type or str or datatype) – type of first operand
type2 (type or str or datatype) – type of second operand

Examples

>>> ht.promote_types(ht.uint8, ht.uint8)
<class 'heat.core.types.uint8'>
>>> ht.promote_types(ht.int32, ht.float32)
<class 'heat.core.types.float32'>
>>> ht.promote_types(ht.int8, ht.uint8)
<class 'heat.core.types.int16'>
>>> ht.promote_types("i8", "f4")
<class 'heat.core.types.float64'>

result_type(*arrays_and_types: Tuple[dndarray.DNDarray | Type[datatype] | Any]) → Type[datatype][source]

Returns the data type that results from type promotions rules performed in an arithmetic operation.

Parameters:: arrays_and_types (List of arrays and types) – Input arrays, types or numbers of the operation.

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

class complex64[source]

Bases: complex

The complex 64 bit datatype. Both real and imaginary are 32 bit floating point

_can_be_cast_safely_to = ['complex64', 'complex128']

mappings

torch_type()[source]: Torch Datatype

char()[source]: Datatype short-hand name

class complex128[source]

Bases: complex

The complex 128 bit datatype. Both real and imaginary are 64 bit floating point

_can_be_cast_safely_to = ['complex128']

mappings

torch_type()[source]: Torch Datatype

char()[source]: Datatype short-hand name

convolve(a: heat.core.dndarray.DNDarray, v: heat.core.dndarray.DNDarray, mode: str = 'full', stride: int = 1) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

a (DNDarray or scalar) – 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.
v (DNDarray or scalar) – 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.
mode (str) –
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.
stride (int) – Stride of the convolution. Must be a positive integer. Default is 1. Stride must be 1 for mode ‘same’.

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)

convolve2d(a: heat.core.dndarray.DNDarray, v: heat.core.dndarray.DNDarray, mode: str = 'full', stride: tuple[int, int] = (1, 1)) → heat.core.dndarray.DNDarray[source]

Returns the discrete, linear convolution of two two-dimensional HeAT tensors.

Recommendation: For better memory consumption, it is recommended to pad the array before running the convolution in mode “valid”

Parameters:

a (scalar, array_like, DNDarray) – Two-dimensional signal, float precision required on gpu
v (scalar, array_like, DNDarray) – Two-dimensional filter mask. float precision required on gpu
mode ({'full', 'valid', 'same'}, optional) –

‘full’:
By default, mode is ‘full’. This returns the convolution at each point of overlap, with an output shape of (N+M-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+1’. The convolution product is only given for points where the signals overlap completely. Values outside the signal boundary have no effect.
stride (Tuple(int,int), optional) – Stride of the convolution in (x,y) direction. Default is (1,1).

Returns:

out (DNDarray) – Discrete, linear convolution of ‘a’ and ‘v’, balanced
Note (If the filter weight is larger) – than fitting into memory, using the FFT for convolution is recommended.

Example

>>> a = ht.ones((5, 5))
>>> v = ht.ones((3, 3))
>>> ht.convolve2d(a, v, mode="valid")
DNDarray([[9., 9., 9.],
          [9., 9., 9.],
          [9., 9., 9.]], dtype=ht.float32, device=cpu:0, split=None)

>>> a = ht.ones((5, 5), split=1))
>>> v = ht.ones((3, 3), split=1))
>>> ht.convolve2d(a, v)
DNDarray([[1., 2., 3., 3., 3., 2., 1.],
          [2., 4., 6., 6., 6., 4., 2.],
          [3., 6., 9., 9., 9., 6., 3.],
          [3., 6., 9., 9., 9., 6., 3.],
          [3., 6., 9., 9., 9., 6., 3.],
          [2., 4., 6., 6., 6., 4., 2.],
          [1., 2., 3., 3., 3., 2., 1.]], dtype=ht.float32, device=cpu:0, split=1)

>>> a = ht.ones((5, 5), split=0)).astype(ht.float)
>>> v = ht.ones((3, 3), split=0)).astype(ht.float)
>>> stride = (1, 2)
>>> ht.convolve2d(a, v, stride=stride)
DNDarray([[1., 3., 3., 1.],
          [2., 6., 6., 2.],
          [3., 9., 9., 3.],
          [3., 9., 9., 3.],
          [3., 9., 9., 3.],
          [2., 6., 6., 2.],
          [1., 3., 3., 1.]], dtype=ht.float32, device=cpu:0, split=0)

vmap(func: Callable[[Tuple[torch.Tensor]], Tuple[torch.Tensor]], out_dims: Tuple[int] | int = 0, randomness: str = 'error', *, chunk_size: int = None) → Callable[[Tuple[heat.core.dndarray.DNDarray]], Tuple[heat.core.dndarray.DNDarray]][source]

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.

Parameters:

func (callable) – 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.
out_dims (int or tuple of int, optional) – The dimensions of the output(s) that are mapped over; identical to the split dimension(s) of the output(s). Default is 0.
randomness ({'error', 'different', 'same'}, optional) – 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.
chunk_size (int, optional) – 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.

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.

class MPILibrary(*args, **kwds)[source]

Bases: 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
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

OpenMPI = 'ompi'

IntelMPI = 'impi'

MVAPICH = 'mvapich'

MPICH = 'mpich'

CrayMPI = 'craympi'

ParaStationMPI = 'psmpi'

Other = 'other'

class MPILibraryInfo[source]

name :MPILibrary

version :str

_get_mpi_library() → MPILibraryInfo

_check_gpu_aware_mpi(library: MPILibraryInfo) → tuple[bool, bool]

condest(A: heat.core.dndarray.DNDarray, p: int | str = None, algorithm: str = 'randomized', params: list = None) → heat.core.dndarray.DNDarray[source]

Computes a (possibly randomized) upper estimate of the l2-condition number of the input 2D DNDarray.

Parameters:

A (DNDarray) – The matrix, i.e., a 2D DNDarray, for which the condition number shall be estimated.
p (int or str (optional)) – 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.
algorithm (str) – The algorithm to use for the estimation. Currently, only “randomized” (default) is implemented.
params (dict (optional)) – 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.

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.

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.

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[source]

Returns the cross product. 2D vectors will we converted to 3D.

Parameters:

a (DNDarray) – First input array.
b (DNDarray) – Second input array. Must have the same shape as ‘a’.
axisa (int) – Axis of a that defines the vector(s). By default, the last axis.
axisb (int) – Axis of b that defines the vector(s). By default, the last axis.
axisc (int) – Axis of the output containing the cross product vector(s). By default, the last axis.
axis (int) – Axis that defines the vectors for which to compute the cross product. Overrides axisa, axisb and axisc. Default: -1

Raises:

ValueError – If the two input arrays don’t match in shape, split, device, or comm. If the vectors are along the split axis.
TypeError – If ‘axis’ is not an integer.

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)

det(a: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Returns the determinant of a square matrix.

Parameters:

a (DNDarray) – A square matrix or a stack of matrices. Shape = (…,M,M)

Raises:

RuntimeError – If the dtype of ‘a’ is not floating-point.
RuntimeError – If a.ndim < 2 or if the length of the last two dimensions is not the same.

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)

dot(a: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray | float[source]

Returns the dot product of two DNDarrays. Specifically,

If both a and b are 1-D arrays, it is inner product of vectors.

If both a and b are 2-D arrays, it is matrix multiplication, but using matmul or a@b is preferred.

If either a or b is 0-D (scalar), it is equivalent to multiply and using multiply(a, b) or a*b is preferred.

Parameters:

a (DNDarray) – First input DNDarray
b (DNDarray) – Second input DNDarray
out (DNDarray, optional) – Output buffer.

See also

vecdot: Supports (vector) dot along an axis.

inv(a: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Computes the multiplicative inverse of a square matrix.

Parameters:

a (DNDarray) – Square matrix of floating-point data type or a stack of square matrices. Shape = (…,M,M)

Raises:

RuntimeError – If the inverse does not exist.
RuntimeError – If the dtype is not floating-point
RuntimeError – If a is not at least two-dimensional or if the lengths of the last two dimensions are not the same.

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)

matmul(a: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray, allow_resplit: bool = False) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

a (DNDarray) – matrix \(L \times P\) or vector \(P\) or batch of matrices: \(B_1 \times ... \times B_k \times L \times P\)
b (DNDarray) – matrix \(P \times Q\) or vector \(P\) or batch of matrices: \(B_1 \times ... \times B_k \times P \times Q\)
allow_resplit (bool, optional) – 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.

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.

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.

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.]])

matrix_norm(x: heat.core.dndarray.DNDarray, axis: Tuple[int, int] | None = None, keepdims: bool = False, ord: int | str | None = None) → heat.core.dndarray.DNDarray[source]

Computes the matrix norm of an array.

Parameters:

x (DNDarray) – Input array
axis (tuple, optional) – Both axes of the matrix. If None ‘x’ must be a matrix. Default: None
keepdims (bool, optional) – Retains the reduced dimension when True. Default: False
ord (int, 'fro', 'nuc', optional) – The matrix norm order to compute. If None the Frobenius norm (‘fro’) is used. Default: None

See also

norm: Computes the vector or matrix norm of an array.
vector_norm: Computes the vector norm of an array.

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
ValueError – If an invalid matrix norm is given or ‘x’ is a vector.

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)

matrix_exp(A: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Computes the matrix exponential of a square matrix.

Letting \(\mathbb{K}\) be \(\mathbb{R}\) or \(\mathbb{C}\), this function computes the matrix exponential of \(A \in \mathbb{K}^{n \times n}\), which is defined as

\[\mathrm{matrix\_exp}(A) = \sum_{k=0}^\infty \frac{1}{k!}A^k \in \mathbb{K}^{n \times n}.\]

If the matrix \(A\) has eigenvalues \(\lambda_i \in \mathbb{C}\), the matrix \(\mathrm{matrix\_exp}(A)\) has eigenvalues \(e^{\lambda_i} \in \mathbb{C}\).

Supports input of bfloat16, float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if A is a batch of matrices then the output has the same batch dimensions.

Note

A may only be distributed in the batch dimensions.

See also

torch.linalg.matrix_exp() is called under the hood on the local data.

Parameters:: A (DNDarray) – DNDarray of shape (*, n, n) where * is zero or more batch dimensions.

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)

expm: Alias for matrix_exp()

Return the vector or matrix norm of an array.

Parameters:

x (DNDarray) – Input vector
axis (int, tuple, optional) – 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
keepdims (bool, optional) – Retains the reduced dimension when True. Default: False
ord (int, float, inf, -inf, 'fro', 'nuc') – The norm order to compute. See Notes

See also

vector_norm: Computes the vector norm of an array.
matrix_norm: Computes the matrix norm of an array.

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

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))

outer(a: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None, split: int | None = None) → heat.core.dndarray.DNDarray[source]

Compute the outer product of two 1-D DNDarrays: \(out(i, j) = a(i) \times b(j)\). Given two vectors, \(a = (a_0, a_1, ..., a_N)\) and \(b = (b_0, b_1, ..., b_M)\), the outer product is:

\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}

Parameters:

a (DNDarray) – 1-dimensional: \(N\) Will be flattened by default if more than 1-D.
b (DNDarray) – 1-dimensional: \(M\) Will be flattened by default if more than 1-D.
out (DNDarray, optional) – 2-dimensional: \(N \times M\) A location where the result is stored
split (int, optional) – 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).

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.

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)

projection(a: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Projection of vector a onto vector b

Parameters:

a (DNDarray) – The vector to be projected. Must be a 1D DNDarray
b (DNDarray) – The vector to project onto. Must be a 1D DNDarray

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.

Parameters:

a (array_like) – Input array, from which the diagonals are taken
offset (int, optional) – Offsets of the diagonal from the main diagonal. Can be both positive and negative. Defaults to 0.
axis1 (int, optional) – 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
axis2 (int, optional) – 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
dtype (dtype, optional) – 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
out (ht.DNDarray, optional) – 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.

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

Return type:

number (of defined dtype) or ht.DNDarray

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)

transpose(a: heat.core.dndarray.DNDarray, axes: List[int] | None = None) → heat.core.dndarray.DNDarray[source]

Permute the dimensions of an array.

Parameters:

a (DNDarray) – Input array.
axes (None or List[int,...], optional) – By default, reverse the dimensions, otherwise permute the axes according to the values given.

tril(m: heat.core.dndarray.DNDarray, k: int = 0) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

m (DNDarray) – Input array for which to compute the lower triangle.
k (int, optional) – Diagonal above which to zero elements. k=0 (default) is the main diagonal, k<0 is below and k>0 is above.

triu(m: heat.core.dndarray.DNDarray, k: int = 0) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

m (DNDarray) – Input array for which to compute the upper triangle.
k (int, optional) – Diagonal above which to zero elements. k=0 (default) is the main diagonal, k<0 is below and k>0 is above.

vdot(x1: heat.core.dndarray.DNDarray, x2: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

Computes the dot product of two vectors. Higher-dimensional arrays will be flattened.

Parameters:

x1 (DNDarray) – first input array. If it’s complex, it’s complex conjugate will be used.
x2 (DNDarray) – second input array.

Raises:

ValueError – If the number of elements is inconsistent.

See also

dot: Return the dot product without using the complex conjugate.

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)

vecdot(x1: heat.core.dndarray.DNDarray, x2: heat.core.dndarray.DNDarray, axis: int | None = None, keepdims: bool | None = None) → heat.core.dndarray.DNDarray[source]

Computes the (vector) dot product of two DNDarrays.

Parameters:

x1 (DNDarray) – first input array.
x2 (DNDarray) – second input array. Must be compatible with x1.
axis (int, optional) – axis over which to compute the dot product. The last dimension is used if ‘None’.
keepdims (bool, optional) – If this is set to ‘True’, the axes which are reduced are left in the result as dimensions with size one.

See also

dot: NumPy-like dot function.

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)

vector_norm(x: heat.core.dndarray.DNDarray, axis: int | Tuple[int] | None = None, keepdims=False, ord: int | float | None = None) → heat.core.dndarray.DNDarray[source]

Computes the vector norm of an array.

Parameters:

x (DNDarray) – Input array
axis (int, tuple, optional) – Axis along which to compute the vector norm. If None ‘x’ must be a vector. Default: None
keepdims (bool, optional) – Retains the reduced dimension when True. Default: False
ord (int, float, optional) – The norm order to compute. If None the euclidean norm (2) is used. Default: None

See also

norm: Computes the vector norm or matrix norm of an array.
matrix_norm: Computes the matrix norm of an array.

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
ValueError – If an invalid vector norm is given.

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)

cg(A: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray, x0: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Conjugate gradients method for solving a system of linear equations :math: Ax = b

Parameters:

A (DNDarray) – 2D symmetric, positive definite Matrix
b (DNDarray) – 1D vector
x0 (DNDarray) – Arbitrary 1D starting vector
out (DNDarray, optional) – Output Vector

lanczos(A: heat.core.dndarray.DNDarray, m: int, v0: heat.core.dndarray.DNDarray | None = None, V_out: heat.core.dndarray.DNDarray | None = None, T_out: heat.core.dndarray.DNDarray | None = None) → Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray][source]

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 \(n \times n\) Hermitian matrix, where often \(m<<n\). It returns two matrices \(V\) and \(T\), where:

\(V\) is a Matrix of size \(n\times m\), with orthonormal columns, that span the Krylow subspace n

\(T\) is a Tridiagonal matrix of size \(m\times m\), with coefficients \(\alpha_1,..., \alpha_n\) on the diagonal and coefficients \(\beta_1,...,\beta_{n-1}\) on the side-diagonalsn

Parameters:

A (DNDarray) – 2D Hermitian (if complex) or symmetric positive-definite matrix. Only distribution along axis 0 is supported, i.e. A.split must be 0 or None.
m (int) – Number of Lanczos iterations
v0 (DNDarray, optional) – 1D starting vector of Euclidean norm 1. If not provided, a random vector will be used to start the algorithm
V_out (DNDarray, optional) – Output Matrix for the Krylow vectors, Shape = (n, m), dtype=A.dtype, must be initialized to zero
T_out (DNDarray, optional) – Output Matrix for the Tridiagonal matrix, Shape = (m, m), must be initialized to zero

solve(A: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray, out: heat.core.dndarray.DNDarray | None = None) → heat.core.dndarray.DNDarray[source]

Computes the solution of a square system of linear equations with a unique solution.

Letting \(\mathbb{K}\) be \(\mathbb{R}\) or \(\mathbb{C}\), this function computes the solution \(X \in \mathbb{K}^{n \times k}\) of the linear system associated to \(A \in \mathbb{K}^{n \times n}, B \in \mathbb{K}^{n \times k}\), which is defined as

\[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 A has shape (*, n, n) and 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 A has shape (*, n, n) and B has shape (n,) or (n, k), 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.

See also

torch.linalg.solve() is called under the hood on the local data. This docstring is also heavily inspired by the docstring of this function.

Parameters:

A (DNDarray) – Matrix to be inverted of shape (*, n, n) where * is zero or more batch dimensions
b (DNDarray) – Right-hand side of shape (*, n) or (*, n, k) or (n,) or (n, k)
out (DNDarray, optional) – Output Vector

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

solve_triangular(A: heat.core.dndarray.DNDarray, b: heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray[source]

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.

Parameters:

A (DNDarray) – An upper triangular invertible square (n x n) matrix or a batch thereof, i.e. a DNDarray of shape (…, n, n).
b (DNDarray) – 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.

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.

qr(A: heat.core.dndarray.DNDarray, mode: str = 'reduced', procs_to_merge: int = 2) → Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray][source]

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.

Parameters:

A (DNDarray of shape (M, N), of shape (...,M,N) in the batched case) – Array which will be decomposed.
mode (str, optional) – 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).
procs_to_merge (int, optional) – 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).

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.

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.

hsvd_rank(A: heat.core.dndarray.DNDarray, maxrank: int, compute_sv: bool = False, maxmergedim: int | None = None, safetyshift: int = 5, silent: bool = True) → 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[source]

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).

Parameters:

A (DNDarray) – 2D-array (float32/64) of which the hSVD has to be computed.
maxrank (int) – truncation rank. (This parameter corresponds to n_components in sci-kit learn’s TruncatedSVD.)
compute_sv (bool, optional) – compute_sv=True implies that also Sigma and V.T are computed and returned. The default is False.
maxmergedim (int, optional) – 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.
safetyshift (int, optional) – 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.)
silent (bool, optional) – silent=False implies that some information on the computations are printed. The default is True.

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

Return type:

(Union[ Tuple[DNDarray, DNDarray, DNDarray, float], Tuple[DNDarray, DNDarray, DNDarray], DNDarray])

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.

See also

hsvd(), hsvd_rtol()

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.

hsvd_rtol(A: heat.core.dndarray.DNDarray, rtol: float, compute_sv: bool = False, maxrank: int | None = None, maxmergedim: int | None = None, safetyshift: int = 5, no_of_merges: int | None = None, silent: bool = True) → 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[source]

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).

Parameters:

A (DNDarray) – 2D-array (float32/64) of which the hSVD has to be computed.
rtol (float) – 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.
compute_sv (bool, optional) – compute_sv=True implies that also Sigma and V.T are computed and returned. The default is False.
no_of_merges (int, optional) – 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.
maxrank (int, optional) – 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.
maxmergedim (int, optional) – 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.
safetyshift (int, optional) – Increases the actual truncation rank within the computations by a safety shift. The default is 5.
silent (bool, optional) – silent=False implies that some information on the computations are printed. The default is True.

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

Return type:

(Union[ Tuple[DNDarray, DNDarray, DNDarray, float], Tuple[DNDarray, DNDarray, DNDarray], DNDarray])

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.

See also

hsvd(), hsvd_rank()

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.

hsvd(A: heat.core.dndarray.DNDarray, maxrank: int | None = None, maxmergedim: int | None = None, rtol: float | None = None, safetyshift: int = 0, no_of_merges: int | None = 2, compute_sv: bool = False, silent: bool = True, warnings_off: bool = False) → 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[source]

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

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.

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.

See also

hsvd_rank(), hsvd_rtol()

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: int | None = None) → Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray][source]

Incremental SVD (iSVD) for the addition of new data to an existing SVD. Given the SVD of an “old” matrix, \(X_\textnormal{old} = `U_\textnormal{old} \cdot S_\textnormal{old} \cdot V_\textnormal{old}^T\), and additional columns \(N\) ("new_data"), this routine computes (a possibly approximate) SVD of the extended matrix \(X_\textnormal{new} = [ X_\textnormal{old} | N]\).

Parameters:

new_data (DNDarray) – 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.
U_old (DNDarray) – 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.
S_old (DNDarray) – Sigma-factor of the SVD of the “old” matrix, 1D-array (float32/64)
Vt_old (DNDarray) – Transpose of V-factor of the SVD of the “old” matrix, 2D-array (float32/64)
maxrank (int, optional) – truncation rank of the SVD of the extended matrix. The default is None, i.e., no bound on the maximal rank is imposed.

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.

References

[1] Brand, M. (2006). Fast low-rank modifications of the thin singular value decomposition. Linear algebra and its applications, 415(1), 20-30.

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][source]

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.

Parameters:

A (ht.DNDarray) – 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.
full_matrices (bool, optional) – currently, only the default value False is supported. This argument is included for compatibility with NumPy.
compute_uv (bool, optional) – 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.
qr_procs_to_merge (int, optional) – 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.
r_max_zolopd (int, optional) – 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.

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).

See also

heat.linalg.qr(), heat.linalg.polar(), heat.linalg.eigh()

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][source]

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

Aht.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.
rint, 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.
calcHbool, optional, default: True: If True, the function returns the symmetric, positive definite matrix H. If False, only the orthogonal matrix U is returned.
condition_estimatefloat, 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].
silentbool, optional, default: True: If True, the function does not print any output. If False, some information is printed during the computation.
r_maxint, optional, default: 8: See the description of r for the meaning; r_max is only taken into account if r is not provided.

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.

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.

eigh(A: heat.core.dndarray.DNDarray, r_max_zolopd: int = 8, silent: bool = True) → Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray][source]

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.

Parameters:

A (DNDarray) – The input matrix. Must be symmetric.
r_max_zolopd (int, optional) – This is a hyperparameter for the computation of the polar decomposition via heat.linalg.polar() which is applied multiple times in this function. See the documentation of heat.linalg.polar() for more details on its meaning and the respective default value.
silent (bool, optional) – If True (default), suppresses output messages; otherwise, some information on the recursion is printed to the console.

Notes

Unlike the 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).

See also

heat.linalg.polar()

rsvd(A: heat.core.dndarray.DNDarray, svd_rank: int, n_oversamples: int = 10, power_iter: int = 0, qr_procs_to_merge: int = 2) → Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray] | Tuple[heat.core.dndarray.DNDarray, heat.core.dndarray.DNDarray][source]

Randomized SVD (rSVD) with prescribed truncation rank svd_rank. If \(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.

Parameters:

A (DNDarray) – 2D-array (float32/64) of which the rSVD has to be computed.
svd_rank (int) – truncation rank of the SVD. (This parameter corresponds to n_components in scikit-learn’s TruncatedSVD.)
n_oversamples (int, optional) – number of oversamples. The default is 10.
power_iter (int, optional) – 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.
qr_procs_to_merge (int, optional) – 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 heat.linalg.qr() for more details.

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.

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.

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][source]

Randomized eigenvalue decomposition (rEIGH). Only the top n_eigenvalues eigenvalues (ordered by magnitude) and corresponding eigenvectors are computed.

Parameters:

A (DNDarray) – 2D-array (float32/64) of which the rEIGH has to be computed. Must be symmetric.
n_eigenvalues (int) – number of eigenvalues to compute. (This parameter corresponds to n_components in scikit-learn’s PCA.)
n_oversamples (int, optional) – number of oversamples. The default is 10.
power_iter (int, optional) – 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.
qr_procs_to_merge (int, optional) – 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 heat.linalg.qr() for more details.

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].

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.

__version__ :str = '1.9.0': The combined version string, consisting out of major, minor, micro and possibly extension.

heat

Subpackages

Submodules

Package Contents

Input

Input

`heat`