round#

ivy.round(x, /, *, decimals=0, out=None)[source]#

Round each element x_i of the input array x to the nearest integer-valued number.

Special cases

  • If x_i is already an integer-valued, the result is x_i.

For floating-point operands,

  • If x_i is +infinity, the result is +infinity.

  • If x_i is -infinity, the result is -infinity.

  • If x_i is +0, the result is +0.

  • If x_i is -0, the result is -0.

  • If x_i is NaN, the result is NaN.

  • If two integers are equally close to x_i, the result is the even integer closest to x_i.

Parameters:

  • x (Union[Array, NativeArray]) – input array containing elements to round.

  • decimals (Optional[int]) – number of decimal places to round to. Default is 0. (default: 0)

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type:

Array

Returns:

  • ret – An array of the same shape and type as x, with the elements rounded to integers.

  • Note (PyTorch supports an additional argument decimals for the)

  • `round function <https (//pytorch.org/docs/stable/generated/torch.round.html>`_.)

  • It has been deliberately omitted here due to the imprecise

  • nature of the argument in torch.round.

  • This function conforms to the `Array API Standard

  • <https (//data-apis.org/array-api/latest/>`_. This docstring is an extension of the)

  • `docstring <https (//data-apis.org/array-api/latest/API_specification/generated/signatures.elementwise_functions.round.html>`_ # noqa)

  • in the standard.

  • Both the description and the type hints above assumes an array input for simplicity,

  • but this function is nestable, and therefore also accepts ivy.Container

  • instances in place of any of the arguments.

Examples

With ivy.Array input:

>>> x = ivy.array([1.2, 2.4, 3.6])
>>> y = ivy.round(x)
>>> print(y)
ivy.array([1.,2.,4.])

>>> x = ivy.array([-0, 5, 4.5])
>>> y = ivy.round(x)
>>> print(y)
ivy.array([0.,5.,4.])

>>> x = ivy.array([1.5654, 2.034, 15.1, -5.0])
>>> y = ivy.zeros(4)
>>> ivy.round(x, out=y)
>>> print(y)
ivy.array([2.,2.,15.,-5.])

>>> x = ivy.array([[0, 5.433, -343.3, 1.5],
...                [-5.5, 44.2, 11.5, 12.01]])
>>> ivy.round(x, out=x)
>>> print(x)
ivy.array([[0.,5.,-343.,2.],[-6.,44.,12.,12.]])

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([4.20, 8.6, 6.90, 0.0]),
...                   b=ivy.array([-300.9, -527.3, 4.5]))
>>> y = ivy.round(x)
>>> print(y)
{
    a:ivy.array([4.,9.,7.,0.]),
    b:ivy.array([-301.,-527.,4.])
}
Array.round(self, *, decimals=0, out=None)#

ivy.Array instance method variant of ivy.round. This method simply wraps the function, and so the docstring for ivy.round also applies to this method with minimal changes.

Parameters:

  • self (Array) – input array. Should have a numeric data type.

  • decimals (int) – number of decimal places to round to. Default is 0. (default: 0)

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that (default: None) the inputs broadcast to.

Return type:

Array

Returns:

ret – an array containing the rounded result for each element in self. The returned array must have the same data type as self.

Examples

Using ivy.Array instance method:

>>> x = ivy.array([6.3, -8.1, 0.5, -4.2, 6.8])
>>> y = x.round()
>>> print(y)
ivy.array([ 6., -8.,  0., -4.,  7.])

>>> x = ivy.array([-94.2, 256.0, 0.0001, -5.5, 36.6])
>>> y = x.round()
>>> print(y)
ivy.array([-94., 256., 0., -6., 37.])

>>> x = ivy.array([0.23, 3., -1.2])
>>> y = ivy.zeros(3)
>>> x.round(out=y)
>>> print(y)
ivy.array([ 0.,  3., -1.])

>>> x = ivy.array([[ -1., -67.,  0.,  15.5,  1.], [3, -45, 24.7, -678.5, 32.8]])
>>> y = x.round()
>>> print(y)
ivy.array([[-1., -67., 0., 16., 1.],
[3., -45., 25., -678., 33.]])
Container.round(self, *, decimals=0, key_chains=None, to_apply=True, prune_unapplied=False, map_sequences=False, out=None)#

ivy.Container instance method variant of ivy.round. This method simply wraps the function, and so the docstring for ivy.round also applies to this method with minimal changes.

Parameters:

  • self (Container) – input container. Should have a numeric data type.

  • decimals (int) – number of decimal places to round to. Default is 0. (default: 0)

  • key_chains (Optional[Union[List[str], Dict[str, str]]]) – The key-chains to apply or not apply the method to. Default is None. (default: None)

  • to_apply (bool) – If True, the method will be applied to key_chains, otherwise key_chains (default: True) will be skipped. Default is True.

  • prune_unapplied (bool) – Whether to prune key_chains for which the function was not applied. (default: False) Default is False.

  • map_sequences (bool) – Whether to also map method to sequences (lists, tuples). (default: False) Default is False.

  • out (Optional[Container]) – optional output container, for writing the result to. It must have a shape (default: None) that the inputs broadcast to.

Return type:

Container

Returns:

ret – a container containing the rounded result for each element in self. The returned container must have the same data type as self.

Examples

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([4.20, 8.6, 6.90, 0.0]),
...                   b=ivy.array([-300.9, -527.3, 4.5]))
>>> y = x.round()
>>> print(y)
{
    a: ivy.array([4., 9., 7., 0.]),
    b: ivy.array([-301., -527., 4.])
}