Python NumPy ceil() Function

Python NumPy ceil() function is used to find the ceiling of each element in the input array (element-wise). The ceiling of a scalar x is the smallest integer i, such that i>=x. In other words, it rounds up each element of the array to the nearest integer greater than or equal to that element.

1. Quick Examples of NumPy ceil() Function

If you are in a hurry, below are some quick examples of how to use Python NumPy ceil() function.


# Quick examples of numpy ceil() function

# Example 1: Create single element array
arr = np.array([7.8])
arr1 = np.ceil(arr)

# Example 2: Create an 1-D input array
# Use ceil() function
arr = np.array([0.8, 4.1, 9.7, 8.0, 5, 6])
arr1 = np.ceil(arr)

# Example 3: Create an 1-D NumPy array
# Get the ceil values of negative elements
arr = np.array([-0.8, -4.1, -9.7, -8.0, -5, -6])
arr1 = np.ceil(arr)

# Example 4: Use numpy.ceil() function 
# On the entire 2-D array
arr = np.array([[0.8, 4.1, 9.7],[ 8.0, 5.4 ,7.6]])
arr1 = np.ceil(arr)

2. Syntax of NumPy ceil()

Following is the syntax of numpy.ceil().


# Syntax of ceil()
numpy.ceil(arr, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj])

2.1 Parameters of NumPy ceil ()

Following is the parameters of ceil().

arr: The values whose ceil values are required. Input array.
out: A ndarray the result is stored in. If given, it must have the shape of input arr. If not given or None, it returns a freshly allocated array. It also takes a tuple as input, if given a tuple must have a length equal to the number of outputs (possible only as a keyword argument).
where: This parameter is optional. A boolean array of the same shape as x, where True represents that the corresponding element of x is rounded up. If False, the input element is left unchanged.
casting: Controls what kind of data casting may occur. Default is 'same_kind'.
order: Controls the memory layout order of the result. Default is 'K'.
dtype: The type of the returned array and of the accumulator in which the elements are summed. If dtype is not specified, it defaults to the dtype of x, unless x has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used.
subok: If True, then sub-classes will be passed through, otherwise, the returned array will be forced to be a base-class array (default).

2.2 Return Value

It returns the ceiling value of each array element and the elements in a returned array would be float data type.

3. Usage of NumPy ceil() Function

The numpy.ceil() is a mathematical function that returns the ceil value of an element array with float data type. The input array elements should have real numbers and assume x, it rounds the variable in an upward manner to the nearest integer and finally returns the nearest integers as ceil values. If a value of x is an integer, it just returns the x value as-is.

The ciel() function varies from another NumPy function floor() which is used to return the variable rounded downwards. Below I have covered some examples to understand the concept of ceil(). In order to find out the ceil values of a NumPy array first, you have to create the NumPy array using numpy.array().

4. Get the Single ceil Value of 1-D Array

To create a NumPy array with a single float value, and then use the np.ceil() function to find the ceiling value of that array. The result is a new array with the ceiling value.

In the below example, np.array([7.8]) create a NumPy array with a single element, which is the float value 7.8. np.ceil(arr) calculates the ceiling value for each element in the array arr. In this case, it will round up 7.8 to the nearest integer greater than or equal to 7.8, which is 8. The result is a new NumPy array arr1 containing the ceiling value.


# Import numpy module
import numpy as np

# Create single ceil value
arr = np.array([7.8])
print("Original array:",arr)

# Use numpy.ceil() function 
# Create single element array
arr1 = np.ceil(arr)
print("Ceil value:",arr1)

Yields below output.

In this case, numpy.ceil() rounds down the single-element 7.8 to 8.0, and the resulting array arr1 contains the ceiling value.

5. Get the Multiple ceil Values of 1-D Array

If you want to calculate the ceiling value for each element in a 1-D array separately, you can directly apply the np.ceil() function to the array.

In the below example, np.ceil(arr) applies the ceiling function to each element in the array independently, resulting in a new array arr1 where each element represents the ceiling value of the corresponding element in the original array.


# Create an 1-D input array
arr = np.array([0.8, 4.1, 9.7, 8.0, 5, 6])
print("Original array:\n",arr)

# Create an 1-D input array
# Use ceil() function
arr1 = np.ceil(arr)
print("Ceil values for each element:\n",arr1)

Yields below output.

6. Get the ceil Values of Negative Elements

If you have negative elements in your array and you want to get the ceiling values, keep in mind that the ceiling of a negative number is the smallest integer greater than or equal to that number.

The below example, np.ceil(arr) calculates the ceiling value for each negative element in the array, resulting in a new array arr1 where each element represents the ceiling value of the corresponding element in the original array.


# Create an 1D input array
arr = np.array([-0.8, -4.1, -9.7, -8.0, -5, -6])
print("Original array:\n",arr)

# Create an 1-D input array
# Use ceil() function
arr1 = np.ceil(arr)
print("Ceil values for each element:\n",arr1)

# Output :
# Original array:
#  [-0.8 -4.1 -9.7 -8.  -5.  -6. ]
# Ceil values for each element:
#  [-0. -4. -9. -8. -5. -6.]

Note that the result is a negative integer for each element because the ceiling of a negative number is the smallest integer greater than or equal to that number.

7. Get the ceil() Value of the 2-D NumPy Array

Alternatively, if you have a 2-D NumPy array and you want to calculate the ceiling value for each element, you can use the np.ceil() function similarly to the 1-D case.

In the below example, np.ceil(arr) applies the ceiling function to each element in the 2-D array independently, resulting in a new 2-D array arr1 where each element represents the ceiling value of the corresponding element in the original 2-D array.


# Create an 2D input array
arr = np.array([[0.8, 4.1, 9.7],[ 8.0, 5.4 ,7.6]])
print("Original array:\n",arr)

# Use numpy.ceil() function 
# On the entire 2-D array
arr1 = np.ceil(arr)
print("Ceil values for each element in the 2-D array:\n",arr1)

# Output:
# Original array:
#  [[0.8 4.1 9.7]
#  [8.  5.4 7.6]]
# Ceil values for each element in the 2-D array:
#  [[ 1.  5. 10.]
#  [ 8.  6.  8.]]

Frequently Asked Questions

What does the numpy.ceil() function do?

The numpy.ceil() function is a NumPy mathematical function that returns the ceiling value of each element in an array. The ceiling of a number is the smallest integer greater than or equal to that number. The function takes an array as input and applies the ceiling operation element-wise.

How do I use numpy.ceil() on a 1-D array?

You can use the numpy.ceil() function directly on a 1-D array. For instance, numpy.ceil() is applied directly to the 1-D array arr. The result is a new array arr1 where each element represents the ceiling value of the corresponding element in the original array.

Can numpy.ceil() be used on arrays with negative elements?

numpy.ceil() can be used on arrays with negative elements. The ceiling of a negative number is the smallest integer greater than or equal to that number.

How do I use numpy.ceil() on a 2-D array?

You can use numpy.ceil() on a 2-D array similarly to a 1-D array. The function will be applied element-wise to each element in the array.

Can I convert the result of numpy.ceil() to integers?

You can convert the result of numpy.ceil() to integers using the astype() method.

Conclusion

In this article, I have explained how to use Python numpy.ceil() function, and using this how to calculate the ceil values of all the array elements with examples.

Happy learning !!

References

https://numpy.org/doc/stable/reference/generated/numpy.floor.html