The NumPy linspace function (sometimes called np.linspace) is a tool in Python for creating numeric sequences.

It’s somewhat similar to the NumPy arange function, in that it creates sequences of evenly spaced numbers structured as a NumPy array.

There are some differences though. Moreover, some people find the linspace function to be a little tricky to use.

It’s not that hard to understand, but you really need to learn how it works.

That being said, this tutorial will explain how the NumPy linspace function works. It will explain the syntax, and it will also show you concrete examples of the function so you can see it in action.

Near the bottom of the post, this will also explain a little more about how np.linspace differs from np.arange.

Ok, first things first. Let’s look a little more closely at what the np.linspace function does and how it works.

## Numpy linspace creates sequences of evenly spaced values within an interval

The NumPy linspace function creates sequences of evenly spaced values within a defined interval.

Essentally, you specify a starting point and an ending point of an interval, and then specify the total number of breakpoints you want within that interval (*including* the start and end points). The np.linspace function will return a sequence of evenly spaced values on that interval.

To illustrate this, here’s a quick example. (We’ll look at more examples later, but this is a quick one just to show you what np.linspace does.)

np.linspace(start = 0, stop = 100, num = 5)

This code produces a NumPy array (an `ndarray`

object) that looks like the following:

That’s the `ndarray`

that the code produces, but we can also visualize the output like this:

So what’s going on here?

Remember: the NumPy linspace function produces a *evenly spaced observations* within a defined interval.

We specified that interval with the `start`

and `stop`

parameters. In particular, this interval starts at 0 and ends at 100.

We also specified that we wanted 5 observations within that range. So, the linspace function returned an `ndarray`

with 5 evenly spaced elements. The first element is 0. The last element is 100. The remaining 3 elements are evenly spaced between 0 and 100.

As should be expected, the output array is consistent with the arguments we’ve used in the syntax.

Having said that, let’s look a little more closely at the syntax of the np.linspace function so you can understand how it works a little more clearly.

## The syntax of NumPy linspace

The syntax of the NumPy linspace is very straightforward.

Obviously, when using the function, the first thing you need to do is call the function name itself:

To do this, you use the code `np.linspace`

(assuming that you’ve imported NumPy as `np`

).

Inside of the `np.linspace`

code above, you’ll notice 3 parameters: `start`

, `stop`

, and `num`

. These are 3 parameters that you’ll use most frequently with the linspace function. There are also a few other optional parameters that you can use.

Let’s talk about the parameters of np.linspace:

### The parameters of NumPy linspace

There are several parameters that help you control the `linspace`

function: `start`

, `stop`

, `num`

, `endpoint`

, and `dtype`

.

To understand these parameters, let’s take a look again at the following visual:

`start`

The `start`

parameter is the beginning of the range of numbers.

So if you set `start = 0`

, the first number in the new `nd.array`

will be 0.

Keep in mind that this parameter is required.

`stop`

The `stop`

parameter is the stopping point of the range of numbers.

In most cases, this will be the last value in the range of numbers. Having said that, if you modify the parameter and set `endpoint = False`

, this value will *not* be included in the output array. (See the examples below to understand how this works.)

** num** (optional)

The

`num`

parameter controls how many total items will appear in the output array.For example, if `num = 5`

, then there will be 5 total items in the output array. If, `num = 10`

, then there will be 10 total items in the output array, and so on.

This parameter is optional. If you don’t provide a value for `num`

, then np.linspace will use `num = 50`

as a default.

** endpoint** (optional)

The

`endpoint`

parameter controls whether or not the `stop`

value is included in the output array. If `endpoint = True`

, then the value of the `stop`

parameter will be included as the last item in the `nd.array`

.

If `endpoint = False`

, then the value of the `stop`

parameter will **not** be included.

By default, `endpoint`

evaluates as `True`

.

** dtype** (optional)

Just like in many other NumPy functions, with

`np.linspace`

, the `dtype`

parameter controls the data type of the items in the output array.If you don’t specify a data type, Python will *infer* the data type based on the values of the other parameters.

If you do explicitly use this parameter, however, you can use any of the available data types from NumPy and base Python.

#### You don’t need to use all of the parameters every time

Keep in mind that you won’t use all of these parameters every time that you use the np.linspace function. Several of these parameters are optional.

Moreover, `start`

, `stop`

, and `num`

are much more commonly used than `endpoint`

and `dtype`

.

#### Using the syntax without parameter values

Also keep in mind that you don’t need to explicitly use the parameter names. You can write code *without* the parameter names themselves; you can add the arguments as “positional arguments” to the function.

Here’s an example:

np.linspace(0, 100, 5)

This code is functionally identical to the code we used in our previous examples: `np.linspace(start = 0, stop = 100, num = 5)`

.

The main difference is that we did not explicitly use the `start`

, `stop`

, and `num`

parameters. Instead, we provided arguments to those parameters by *position*. When you don’t use the parameter names explicitly, Python knows that the first number (0) is supposed to be the `start`

of the interval. It know that 100 is supposed to be the `stop`

. And it knows that the third number (5) corresponds to the `num`

parameter. Again, when you don’t explicitly use the parameter names, Python assigns the argument values to parameters *strictly by position*; which value appears first, second, third, etc.

You’ll see people do this frequently in their code. People will commonly exclude the parameter names in their code and use positional arguments instead. Although I realize that it’s a little faster to write code with positional arguments, I think that it’s clearer to actually use the parameter names. As a best practice, you should probably use them.

## Examples: how to use numpy linspace

Now that you’ve learned how the syntax works, and you’ve learned about each of the parameters, let’s work through a few concrete examples.

#### Create interval between 0 and 1, in breaks of .1

A quick example

np.linspace(start = 0, stop = 1, num = 11)

Which produces the output array:

array([ 0. , 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1. ])

An example like this would be useful if you’re working with percents in some way. For example, if you were plotting percentages or plotting “accuracy” metrics for a machine learning classifier, you might use this code to construct part of your plot. Explaining how to do that is beyond the scope of this post, so I’ll leave a deeper explanation of that for a future blog post.

#### Create interval between 0 and 100, in breaks of 10

A very similar example is creating a range of values from 0 to 100, in breaks of 10.

np.linspace(start = 0, stop = 100, num = 11)

The code for this is almost identical to the prior example, except we’re creating values from 0 to 100.

Since it’s somewhat common to work with data with a range from 0 to 100, a code snippet like this might be useful.

#### How to use the endpoint parameter

As mentioned earlier in this blog post, the `endpoint`

parameter controls whether or not the `stop`

value is included in the output array.

By default (if you don’t set any value for `endpoint`

), this parameter will have the default value of `True`

. That means that the value of the `stop`

parameter *will* be included in the output array (as the final value).

However, if you set `endpoint = False`

, then the value of the `stop`

parameter will *not* be included.

Here’s an example.

In the following code, `stop`

is set to 5.

np.linspace(start = 1, stop = 5, num = 4, endpoint = False)

But because we’re also setting `endpoint = False`

, 5 will *not* be included as the final value.

On the contrary, the output `nd.array`

contains 4 evenly spaced values (i.e., `num = 4`

), starting at 1, up to but *excluding* 5:

array([ 1., 2., 3., 4.])

Personally, I find that it’s a little un-intuitive to use `endpoint = False`

, so I don’t use it often. But if you have a reason to use it, this is how to do it.

#### Manually specify the data type

As mentioned earlier, the NumPy linspace function is supposed to “infer” the data type from the other input arguments. You’ll notice that in many cases, the output is an array of floats.

If you want to manually specify the data type, you can use the `dtype`

parameter.

This is very straightforward. Using the `dtype`

parameter with np.linspace is identical to how you specify the data type with np.array, specify the data type with np.arange, etc.

Essentially, you use the `dtype`

parameter and indicate the exact Python or NumPy data type that you want for the output array:

np.linspace(start = 0, stop = 100, num = 5, dtype = int)

In this case, when we set `dtype = int`

, the linspace function produces an nd.array object with *integers* instead of floats.

Again, Python and NumPy have a variety of available data types, and you can specify any of these with the `dtype`

parameter.

## How np.linspace is different from np.arange

If you’re familiar with NumPy, you might have noticed that np.linspace is rather similar to the np.arange function.

The essential difference between NumPy linspace and NumPy arange is that linspace enables you to control the precise end value, whereas arange gives you more direct control over the increments between values in the sequence.

To be clear, if you use them carefully, both linspace and arange can be used to create evenly spaced sequences. To a large extent, these are two similar different tools for creating sequences, and which you use will be a matter of preference. I personally find np.arange to be more intuitive, so I tend to prefer arange over linspace. Again though, this will mostly be a matter of preference, so try them both and see which you prefer.

## For more Python data science tutorials, sign up for our email list

Here at Sharp Sight, we teach data science. We want to help you master data science as fast as possible.

If you sign up for our email list, you’ll receive Python data science tutorials delivered to your inbox.

You’ll get free tutorials on:

- NumPy
- Pandas
- Base Python
- Scikit learn
- Machine learning
- Deep learning
- … and more

… delivered to your inbox every week.

Want to learn data science in Python? Sign up now.

Thank you. It is really helpful.