def scatter_flat(indices,
updates,
size,
reduction='sum',
dev_str=None,
f=None):
"""
Scatter flat updates into a new flat array according to flat indices.
:param indices: Indices for the new values to occupy.
:type indices: array
:param updates: Values for the new array to hold.
:type updates: array
:param size: The size of the result.
:type size: int
:param reduction: The reduction method for the scatter, one of 'sum', 'min', 'max' or 'replace'
:type reduction: str
:param dev_str: device on which to create the array 'cuda:0', 'cuda:1', 'cpu' etc. Same as updates if None.
:type dev_str: str, optional
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: New array of given shape, with the values scattered at the indices.
"""
return _get_framework(indices, f=f).scatter_flat(indices, updates, size,
reduction, dev_str)
def conv2d(x,
filters,
strides,
padding,
data_format='NHWC',
dilations=1,
filter_shape=None,
num_filters=None,
f=None):
"""
Computes a 2-D convolution given 4-D input x and filters arrays.
:param x: Input image *[batch_size,h,w,d_in]*.
:type x: array
:param filters: Convolution filters *[fh,fw,d_in,d_out]*.
:type filters: array
:param strides: The stride of the sliding window for each dimension of input.
:type strides: int or sequence of ints
:param padding: "SAME" or "VALID" indicating the algorithm, or list indicating the per-dimension paddings.
:type padding: string or sequence of ints
:param data_format: "NHWC" or "NCHW". Defaults to "NHWC".
:type data_format: string
:param dilations: The dilation factor for each dimension of input.
:type dilations: int or sequence of ints
:param filter_shape: Filter shape.
:type filter_shape: sequence of ints, needed for MXNet symbolic.
:param num_filters: Number of filters.
:type num_filters: sequence of ints, needed for MXNet symbolic.
:param f: Machine learning library. Inferred from Inputs if None.
:type f: ml_framework, optional
:return: The result of the convolution operation.
"""
return _get_framework(x, f=f).conv2d(x, filters, strides, padding,
data_format, dilations, filter_shape,
num_filters)
def scatter_nd(indices,
updates,
shape,
num_idx_dims=None,
reduction='sum',
dev=None,
f=None):
"""
Scatter updates into a new array according to indices.
:param indices: Indices for the new values to occupy.
:type indices: array
:param updates: Values for the new array to hold.
:type updates: array
:param shape: The shape of the result.
:type shape: sequence of ints
:param num_idx_dims: Number of dimensions for indices array. Required for MXNet symbolic.
:type num_idx_dims: int
:param reduction: The reduction method for the scatter, one of 'sum', 'min' or 'max'
:type reduction: str
:param dev: device on which to create the array 'cuda:0', 'cuda:1', 'cpu' etc. Same as updates if None.
:type dev: str, optional
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: New array of given shape, with the values scattered at the indices.
"""
return _get_framework(indices,
f=f).scatter_nd(indices, updates, shape,
num_idx_dims, reduction, dev)
def arange(stop, start=0, step=1, dtype_str=None, dev_str=None, f=None):
"""
Returns evenly spaced values within a given interval, with the spacing being specified.
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 an array in the chosen ml_framework rather than a list.
See :math:`linspace` for a certain number of evenly spaced values in an interval.
:param stop: End of interval. The interval does not include this value, except in some cases where step is not an
integer and floating point round-off affects the length of out.
:type stop: number
:param start: Start of interval. The interval includes this value. The default start value is 0.
:type start: number, optional
:param step: Spacing between values. For any output out, this is the distance between two adjacent values,
out[i+1] - out[i]. The default step size is 1. If step is specified as a position argument,
start must also be given.
:type step: number, optional
:param dtype_str: The desired data-type for the array in string format, i.e. 'float32' or 'int64'.
If not given, then the type will be determined as the minimum type required to hold the objects in the
sequence.
:type dtype_str: data-type string, optional
:param dev_str: device on which to create the array 'cuda:0', 'cuda:1', 'cpu' etc.
:type dev_str: str
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: Tensor of evenly spaced values.
For floating point arguments, the length of the result is ceil((stop - start)/step).
Because of floating point overflow, this rule may result in the last element of out being greater than stop.
"""
return _get_framework(f=f).arange(stop, start, step, dtype_str, dev_str)
def bilinear_resample(x,
warp,
batch_shape=None,
input_image_dims=None,
output_image_dims=None,
f=None):
"""
Performs bilinearly re-sampling on input image.
:param x: Input image.
:type x: array
:param warp: Warp array.
:type warp: array
:param batch_shape: Shape of batch. Inferred from inputs if None.
:type batch_shape: sequence of ints, optional
:param input_image_dims: image dimensions of image to be sampled from.
:type input_image_dims: sequence of ints
:param output_image_dims: image dimensions of the output image, after sampling.
:type output_image_dims: sequence of ints
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: Image after bilinear re-sampling.
"""
return _get_framework(x, f=f).bilinear_resample(x, warp, batch_shape,
input_image_dims,
output_image_dims)
def svd(x, batch_shape=None, f=None):
"""
Singular Value Decomposition.
When x is a 2D array, it is factorized as u @ numpy.diag(s) @ vh = (u * s) @ vh, where u and vh are 2D unitary
arrays and s is a 1D array of a’s singular values. When x is higher-dimensional, SVD is applied in batched mode.
:param x: Input array with number of dimensions >= 2.
:type x: array
:param batch_shape: Shape of batch. Inferred from inputs if None.
:type batch_shape: sequence of ints, optional
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return:
u -> { (…, M, M), (…, M, K) } array \n
Unitary array(s). The first (number of dims - 2) dimensions have the same size as those of the input a.
The size of the last two dimensions depends on the value of full_matrices.
s -> (…, K) array \n
Vector(s) with the singular values, within each vector sorted in descending ord.
The first (number of dims - 2) dimensions have the same size as those of the input a.
vh -> { (…, N, N), (…, K, N) } array \n
Unitary array(s). The first (number of dims - 2) dimensions have the same size as those of the input a.
The size of the last two dimensions depends on the value of full_matrices.
"""
return _get_framework(x, f=f).svd(x, batch_shape)
def concat(containers, dim, f=None):
"""
Concatenate containers together along the specified dimension.
:param containers: containers to _concatenate
:type containers: sequence of Container objects
:param dim: dimension along which to _concatenate
:type dim: int
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: Concatenated containers
"""
container0 = containers[0]
if isinstance(container0, dict):
return_dict = dict()
for key in container0.keys():
return_dict[key] = Container.concat([container[key] for container in containers], dim)
return Container(return_dict)
else:
f = _get_framework(container0, f=f)
# noinspection PyBroadException
try:
if len(containers[0].shape) == 0:
return _ivy.concatenate([_ivy.reshape(item, [1] * (dim + 1)) for item in containers], dim, f=f)
else:
return _ivy.concatenate(containers, dim, f=f)
except Exception as e:
raise Exception(str(e) + '\nContainer concat operation only valid for containers of arrays')
def tpu_is_available(f=None):
"""
Determine whether a TPU is available to use, with the backend framework.
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: Boolean, as to whether a tpu is available.
"""
return _get_framework(f=f).tpu_is_available()
def seed(seed_value=0, f=None):
"""
Sets the seed for random number generation.
:param seed_value: Seed for random number generation, must be a positive integer.
:type seed_value: int
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
"""
return _get_framework(f=f).seed(seed_value)
def atanh(x, f=None):
"""
Returns a new array with the inverse hyperbolic tangent of the elements of x.
:param x: Input array.
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: A new array with the inverse hyperbolic tangent of the elements of x.
"""
return _get_framework(x, f=f).atanh(x)
def gradient_image(x, f=None):
"""
Computes image gradients (dy, dx) for each channel.
:param x: Input image *[batch_shape, h, w, d]* .
:type x: array
:param f: Machine learning library. Inferred from inputs if None.
:type f: ml_framework, optional
:return: Gradient images dy *[batch_shape,h,w,d]* and dx *[batch_shape,h,w,d]* .
"""
return _get_framework(x, f=f).gradient_image(x)
def sin(x, f=None):
"""
Computes trigonometric sine element-wise.
:param x: Input array, in radians (2*pi radian equals 360 degrees).
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: The sine of x element-wise.
"""
return _get_framework(x, f=f).sin(x)
def asin(x, f=None):
"""
Computes inverse sine element-wise.
:param x: y-coordinate on the unit circle.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: The inverse sine of each element in x, in radians and in the closed interval [-pi/2, pi/2].
"""
return _get_framework(x, f=f).asin(x)
def exp(x, f=None):
"""
Computes exponential of x element-wise.
:param x: Value to compute exponential for.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: The exponential of each element of x.
"""
return _get_framework(x, f=f).exp(x)
def log(x, f=None):
"""
Computes natural logarithm of x element-wise.
:param x: Value to compute log for.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: The natural logarithm of each element of x.
"""
return _get_framework(x, f=f).log(x)
def dtype_to_str(dtype_in, f=None):
"""
Convert native data type to string representation.
:param dtype_in: The data type to convert to string.
:type dtype_in: data type
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: Device string e.g. 'float32'.
"""
return _get_framework(None, f=f).dtype_to_str(dtype_in)
def dtype(x, f=None):
"""
Get the data type for input array x.
:param x: Tensor for which to get the data type.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: Data type of the array
"""
return _get_framework(x, f=f).dtype(x)
def pinv(x, f=None):
"""
Computes the pseudo inverse of x matrix.
:param x: Matrix to be pseudo inverted.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: pseudo inverse of the matrix x.
"""
return _get_framework(x, f=f).pinv(x)
def shuffle(x, f=None):
"""
Shuffles the given array along axis 0.
:param x: An array object, in the specific Machine learning framework.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: An array object, shuffled along the first dimension.
"""
return _get_framework(x, f=f).shuffle(x)
def relu(x, f=None):
"""
Applies the rectified linear unit function element-wise.
:param x: Input array.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: The input array with relu applied element-wise.
"""
return _get_framework(x, f=f).relu(x)
def softplus(x, f=None):
"""
Applies the softplus function element-wise.
:param x: Input array.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: The input array with softplus applied element-wise.
"""
return _get_framework(x, f=f).softplus(x)
def tanh(x, f=None):
"""
Applies the tangent hyperbolic function element-wise.
:param x: Input array.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: The input array with tanh applied element-wise.
"""
return _get_framework(x, f=f).tanh(x)
def logical_not(x, f=None):
"""
Computes the truth value of NOT x element-wise.
:param x: Input array 1.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: Boolean result of the logical OR operation applied element-wise to x1 and x2.
"""
return _get_framework(x, f=f).logical_not(x)
def dtype_str(x, f=None):
"""
Get the data type string for input array x.
:param x: Tensor for which to get the data type string.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: Device string e.g. 'float32'.
"""
return _get_framework(None, f=f).dtype_str(x)
def is_variable(x, f=None):
"""
Determines whether the input is a variable or not.
:param x: An ivy array.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: Boolean, true if x is a trainable variable, false otherwise.
"""
return _get_framework(x, f=f).is_variable(x)
def str_to_dev(dev_str, f=None):
"""
Convert device string representation to native device type.
:param dev_str: The device string to conver to native device handle.
:type dev_str: str
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: Native device handle.
"""
return _get_framework(None, f=f).str_to_dev(dev_str)
def stop_gradient(x, f=None):
"""
Stops gradient computation.
:param x: Array for which to stop the gradient.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: The same array x, but with no gradient information.
"""
return _get_framework(x, f=f).stop_gradient(x)
def dev_str(x, f=None):
"""
Get the device string for input array x.
:param x: Tensor for which to get the device string.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: Device string for the array, e.g. 'cuda:0', 'cuda:1', 'cpu' etc..
"""
return _get_framework(x, f=f).dev_str(x)
def variable(x, f=None):
"""
Creates a variable, which supports gradient computation.
:param x: An ivy array.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: An ivy variable, supporting gradient computation.
"""
return _get_framework(x, f=f).variable(x)
def dev(x, f=None):
"""
Get the native device handle for input array x.
:param x: Tensor for which to get the device handle.
:type x: array
:param f: Machine learning framework. Inferred from inputs if None.
:type f: ml_framework, optional
:return: Device handle for the array, in native framework format.
"""
return _get_framework(x, f=f).dev(x)
