How to Use the Numpy Add Function

by

In this tutorial, I’ll explain how to use the Numpy add function – AKA np.add – to add the values of two Numpy arrays.

I’ll explain the syntax of np.add, how the function works, and how to use it.

If you need something specific, you can click on any of the following links.

Table of Contents:

Ok. Let’s start with a quick introduction to the function.

A Quick Introduction to Numpy Add

As you probably already know, the Numpy add function adds the values Numpy arrays or other objects (like lists and scalar values).

Arguably, the most important use of function is to add the values of two same-sized Numpy arrays. When you use np.add on two same sized arrays, the function will add values of the two arrays, element-wise. Effectively, the Numpy add function performs matrix addition in Python.

A simple example that shows how Numpy add adds the elements of two same-sized Numpy arrays, in an element-wise fashion.

Having said that, you can also use the Numpy add function on different types of inputs.

You can use the np.add function on two scalar values.

You can use np.add on lists (in which case, it operates as if they were Numpy arrays).

And you can use Numpy add with a multi-dimensional array and a lower dimensional array. For example, you can use np.add with a 2-dimensional array and a 1-dimensional array. In this case, Numpy will “broadcast” the lower dimensional array across the higher dimensional array, and add the values, element-wise. (If you do this, there will be some restrictions on the shape of the input arrays).

I’ll show you examples of all of these use cases in the examples section.

But first, let’s look at the syntax for the function.

The syntax of np.add

The syntax for the Numpy add function is very simple:

An image that shows the syntax for the np.add function.

Remember that the syntax shown above assumes that you’ve imported Numpy with the alias np.

Format of the input arrays

Here, I want to make a few comments about the format of the two inputs.

In the syntax explanation above, there are two inputs (i.e., arguments). In the image, I’ve called these inputs arr1 and arr1, and I’ve suggested that they should be Numpy arrays. Frequently, when we use np.add, these inputs are Numpy arrays.

But the function will also accept other types of inputs: you can provide array-like objects like Python lists, and scalar values.

The shape of the inputs

There are also some restrictions on the shape of the inputs. This is important, because the behavior of the function will change depending on the shape of the inputs.

The first way to use this function is with two arrays that have the same size (i.e., arrays with the same number of rows and columns). If we use np.add with two same-sized arrays, then Numpy add will add the elements of the second array to the elements of the first array, in an element-wise fashion.

A simple example showing how Numpy add adds the values of two same-sized arrays, element-wise.

It’s also possible to use two input arrays that have a different shape. If you do this, the np.add function will perform broadcasting. It will repeatedly use the second array as a set of values to be added to slices of the first array. For this to work, the arrays must be appropriately sized. I’ll show an example of this in the examples section.

Additional parameters

In addition to the two inputs, the Numpy add function has a some optional parameters:

  • out
  • where

These are somewhat rarely used, but so I won’t explain them here.

Output of np.add

The output of np.add is a new Numpy array that contains the element-wise sum of the values of the input arrays.

Also note that the output is slightly different for scalars: If the both inputs to np.add are scalar values, then the output will be a scalar.

Examples: how to add the values of Numpy arrays

So now that we’ve looked at the syntax, let’s look at some examples of how to add Numpy arrays together.

Examples:

Preliminary code: Import Numpy and Create Arrays

Before you run the examples, you’ll need to run some code to get set up.

Specifically, you’ll need to import Numpy and create some Numpy arrays that we can work with.

Import Numpy

First, we’ll import Numpy.

You can import Numpy with the following code:

import numpy as np

Create Arrays

Next, we need to create some Numpy arrays that we can work with in our examples.

Here, we’ll create three arrays:

  • a 1-dimensional ‘vector’ of numbers
  • a 2-dimensional ‘matrix’ of the numbers from 1 to 9 (ordered)
  • a 2-dimensional ‘matrix’ of the numbers from 1 to 9 (randomized)

To create these, we’re going to use several different Numpy functions.

We’ll use np.array to create a 1-dimensional vector of values.

We’ll use np.arange to create an array that contains a sequence of numbers called numbers_1_to_9. (We won’t use this directly, but we’ll use it to create the next arrays.)

To create an ordered 2-dimensional array of numbers, we’ll use np.reshape. We’ll use Numpy reshape on the array called numbers_1_to_9.

And finally, we’ll create create a randomized 2-dimensional array created from numbers_1_to_9, using Numpy random choice.

# CREATE 1D 'VECTOR'
vector_1d = np.array([10,20,30])

# CREATE 2D MATRIX OF NUMBERS, 1 TO 9
numbers_1_to_9 = np.arange(start = 1, stop = 10)
matrix_2d_ordered = numbers_1_to_9.reshape((3,3))

# CREATE 2D MATRIX OF NUMBERS, 1 TO 9, RANDOMIZED
np.random.seed(22)
matrix_2d_random = np.random.choice(size = (3,3), a = numbers_1_to_9, replace = False)

If any of this confuses you, then you should read the tutorials I linked to in the previous couple of paragraphs. Those tutorials explain these Numpy operations in more detail.

So once you run the above code, you’ll be ready to run the examples.

EXAMPLE 1: Use Numpy to add two scalars

Let’s just start simple.

Here, we’ll use np.add to add two scalar values.

np.add(3,4)

OUT:

7

Explanation

This is very simple.

Here, we’re adding the values 3 and 7. The result is 7.

EXAMPLE 2: Add a scalar to an array

In the next, we’ll add a scalar value to an array.

np.add(matrix_2d_ordered, 10)

OUT:

array([[11, 12, 13],
       [14, 15, 16],
       [17, 18, 19]])

Explanation

Here, we’ve used np.add to add a scalar value, 10, to an array, matrix_2d_ordered.

In this case, np.add has added 10 to every element of matrix_2d_ordered, and the output array simply contains the new summed values.

Notice also that the shape of the output is the same shape as the input array, matrix_2d_ordered.

EXAMPLE 3: Add two same-sized Numpy arrays

Now, let’s add two same-sized arrays.

Specifically, we’ll add matrix_2d_random to matrix_2d_ordered.

np.add(matrix_2d_ordered, matrix_2d_random)

OUT:

array([[10,  4,  7],
       [ 7, 12,  7],
       [15, 13, 15]])

Explanation

Here, the np.add function is adding the values of matrix_2d_random to the corresponding values of matrix_2d_ordered in an element-wise way.

An image that shows how np.add adds the values of two same-sized arrays in an element-wise fashion.

Also, notice the shape of the output. The output array has the same shape as the two inputs. This is how np.add will work when you apply it to two same-sized arrays.

EXAMPLE 4: Add a vector to a matrix (i.e., broadcasting)

Finally, add a 1-dimensional Numpy array (i.e., a vector) to a 2-dimensional Numpy array (i.e., a matrix).

np.add(matrix_2d_ordered, vector_1d)

OUT:

array([[11, 22, 33],
       [14, 25, 36],
       [17, 28, 39]])

Explanation

In this example, we’ve added the 1D array vector_1d to the 2D array matrix_2d_ordered.

Notice that they have the same number of columns but a different number of rows. This allows Numpy to add the values of the 1D array to each row of the 2D array.

This is called “broadcasting.” Here, np.add is “broadcasting” the 1D array across the rows of the 2D array.

So np.add adds the values of vector_1d to row 1 of matrix_2d_ordered, element wise. Then it adds the values of vector_1d to row 2 of matrix_2d_ordered. And so on.

An image that shows how Numpy add adds the values of a 1D array to the values of a 2D array, using broadcasting.

Again, notice that this is possible because the number of elements in vector_1d is the same as the number of columns in matrix_2d_ordered. For broadcasting to operate properly, the the number of columns in both inputs need to be sized appropriately.

Leave your other questions in the comments below

Do you have other questions about how to use np.add to add Numpy arrays?

If so, leave your questions in the comments section below.

Join our course to learn more about Numpy

In this tutorial, I’ve explained how to add Numpy arrays with np.add.

This should help you with performing matrix addition, but if you really want to learn Numpy, there’s a lot more to learn.

If you’re serious about mastering Numpy, and serious about data science in Python, you should consider joining our premium course called Numpy Mastery.

Numpy Mastery will teach you everything you need to know about Numpy, including:

  • How to create Numpy arrays
  • How to reshape, split, and combine your Numpy arrays
  • What the “Numpy random seed” function does
  • How to use the Numpy random functions
  • How to perform mathematical operations on Numpy arrays
  • and more …

Moreover, this course will show you a practice system that will help you master the syntax within a few weeks. We’ll show you a practice system that will enable you to memorize all of the Numpy syntax you learn. If you have trouble remembering Numpy syntax, this is the course you’ve been looking for.

Find out more here:

Learn More About Numpy Mastery

Joshua Ebner

Joshua Ebner is the founder, CEO, and Chief Data Scientist of Sharp Sight.   Prior to founding the company, Josh worked as a Data Scientist at Apple.   He has a degree in Physics from Cornell University.   For more daily data science advice, follow Josh on LinkedIn.

Leave a Comment