@stdlib/array-linspace

About stdlib...

We believe in a future in which the web is a preferred environment for numerical computation. To help realize this future, we've built stdlib. stdlib is a standard library, with an emphasis on numerical and scientific computation, written in JavaScript (and C) for execution in browsers and in Node.js.

The library is fully decomposable, being architected in such a way that you can swap out and mix and match APIs and functionality to cater to your exact preferences and use cases.

When you use stdlib, you can be absolutely certain that you are using the most thorough, rigorous, well-written, studied, documented, tested, measured, and high-quality code out there.

To join us in bringing numerical computing to the web, get started by checking us out on GitHub, and please consider financially supporting stdlib. We greatly appreciate your continued support!

linspace

Generate a linearly spaced array over a specified interval.

Installation

npm install @stdlib/array-linspace

Usage

var linspace = require( '@stdlib/array-linspace' );

linspace( start, stop, length[, options] )

Generates a linearly spaced array over a specified interval.

var arr = linspace( 0.0, 100.0, 6 );
// returns <Float64Array>[ 0.0, 20.0, 40.0, 60.0, 80.0, 100.0 ]

If length is 0, the function returns an empty array.

var arr = linspace( 0.0, 100.0, 0 );
// returns <Float64Array>[]

If length is 1, the function returns an array containing stop, but not start, when endpoint is true; otherwise, the function returns an array containing start, but not stop.

var arr = linspace( 0.0, 100.0, 1 );
// returns <Float64Array>[ 100.0 ]

arr = linspace( 0.0, 100.0, 1, {
    'endpoint': true
});
// returns <Float64Array>[ 100.0 ]

arr = linspace( 0.0, 100.0, 1, {
    'endpoint': false
});
// returns <Float64Array>[ 0.0 ]

For real-valued start and stop, if start is less than stop, the output array will contain ascending values, and, if start is greater than stop, the output array will contain descending values.

var arr = linspace( 0.0, -100.0, 6 );
// returns <Float64Array>[ 0.0, -20.0, -40.0, -60.0, -80.0, -100.0 ]

The function accepts the following options:

• dtype: output array data type. Must be a floating-point data type or 'generic'. If both start and stop are the same type (either 'float64', 'complex64', or 'complex128'), the default output array data type is the same type as the input values (either 'float64', 'complex64', or 'complex128', respectively). Otherwise, the default output array data type is 'complex128'.
• endpoint: boolean indicating whether to include the stop value in the output array. If false, the function generates length + 1 linearly spaced values over the interval [start, stop] and only writes length values to the output array, thus excluding stop from the output array. Accordingly, for a fixed length, the spacing between adjacent values in the output array changes depending on the value of endpoint. Default: true.

By default, the function generates a linearly spaced array over the closed interval [start, stop]. To generate linearly spaced values over the half-open interval [start, stop), set the endpoint option to false.

var opts = {
    'endpoint': false
};
var arr = linspace( 0.0, 100.0, 5, opts );
// returns <Float64Array>[ 0.0, 20.0, 40.0, 60.0, 80.0 ]

When both start and stop are real-valued, the default output array data type is 'float64'. To return an output array having a different data type, set the dtype option.

var opts = {
    'dtype': 'generic'
};
var arr = linspace( 0, 100, 6, opts );
// returns [ 0, 20, 40, 60, 80, 100 ]

When either start or stop is a complex number, the default output array data type is 'complex128'. To return an output array having a different data type, set the dtype option.

var Complex128 = require( '@stdlib/complex-float64' );
var real = require( '@stdlib/complex-real' );
var imag = require( '@stdlib/complex-imag' );

var opts = {
    'dtype': 'generic'
};

var start = new Complex128( 0.0, 0.0 );
var stop = new Complex128( 100.0, 10.0 );

var arr = linspace( start, stop, 6, opts );
// returns [ <Complex128>, <Complex128>, <Complex128>, <Complex128>, <Complex128>, <Complex128> ]

var z = arr[ 0 ];
// returns <Complex128>

var re = real( z );
// returns 0.0

var im = imag( z );
// returns 0.0

z = arr[ 1 ];
// returns <Complex128>

re = real( z );
// returns 20.0

im = imag( z );
// returns 2.0

// ...

linspace.assign( start, stop, out[, options] )

Generates a linearly spaced sequence over a specified interval and assigns the results to a provided output array.

var Float64Array = require( '@stdlib/array-float64' );

var out = new Float64Array( 6 );
var arr = linspace.assign( 0.0, 100.0, out );
// returns <Float64Array>[ 0.0, 20.0, 40.0, 60.0, 80.0, 100.0 ]

var bool = ( arr === out );
// returns true

If the provided output array is empty, the function returns the provided output array unchanged.

var arr = linspace.assign( 0.0, 100.0, [] );
// returns []

If the provided output array contains a single element, the function writes the stop value, but not start, when endpoint is true; otherwise, the function writes the start value, but not stop.

var arr = linspace.assign( 0.0, 100.0, [ -10.0 ] );
// returns [ 100.0 ]

arr = linspace.assign( 0.0, 100.0, [ -10.0 ], {
    'endpoint': true
});
// returns [ 100.0 ]

arr = linspace.assign( 0.0, 100.0, [ -10.0 ], {
    'endpoint': false
});
// returns [ 0.0 ]

For real-valued start and stop, if start is less than stop, the output array will contain ascending values, and, if start is greater than stop, the output array will contain descending values.

var Float64Array = require( '@stdlib/array-float64' );

var out = new Float64Array( 6 );
var arr = linspace.assign( 0.0, -100.0, out );
// returns <Float64Array>[ 0.0, -20.0, -40.0, -60.0, -80.0, -100.0 ]

The function accepts the following options:

• endpoint: boolean indicating whether to include the stop value in the output array. If false, the function generates N + 1 linearly spaced values (where N is the length of the provided output array) over the interval [start, stop] and only writes N values to the output array, thus excluding stop from the output array. Accordingly, for a fixed N, the spacing between adjacent values in the output array changes depending on the value of endpoint. Default: true.

By default, the function generates a linearly spaced array over the closed interval [start, stop]. To generate linearly spaced values over the half-open interval [start, stop), set the endpoint option to false.

var Float64Array = require( '@stdlib/array-float64' );

var opts = {
    'endpoint': false
};

var out = new Float64Array( 5 );
var arr = linspace.assign( 0.0, 100.0, out, opts );
// returns <Float64Array>[ 0.0, 20.0, 40.0, 60.0, 80.0 ]

Notes

• For M >= 2, the spacing between values is computed as

  delta = (stop-start) / (M-1)
  

  where M is the number of values to generate. Accordingly, values may not be evenly spaced due to floating-point rounding errors.

• When the output array length is greater than 1 and endpoint is true, the output array is guaranteed to include the start and stop values. Beware, however, that values between start and stop are subject to floating-point rounding errors. Hence,

  var arr = linspace( 0.0, 1.0, 3 );
  // returns <Float64Array>[ 0.0, ~0.5, 1.0 ]
  

  where arr[1] is only guaranteed to be approximately equal to 0.5. If you desire more control over element precision, consider using roundn:

  var roundn = require( '@stdlib/math-base-special-roundn' );
  
  // Create an array subject to floating-point rounding errors:
  var arr = linspace( 0.0, 1.0, 3, {
      'dtype': 'generic'
  });
  
  // Round each value to the nearest hundredth:
  var i;
  for ( i = 0; i < arr.length; i++ ) {
      arr[ i ] = roundn( arr[ i ], -2 );
  }
  console.log( arr );
  // => [ 0.0, 0.5, 1.0 ]
  

• For both functions, if both start and stop are real-valued, the output array data type may be any floating-point data type or 'generic'. However, if either start or stop are complex numbers, the output array type must be a complex floating-point data type or 'generic'.

• While the assign method accepts any array-like object for the output array when both start and stop are real-valued, providing an integer-valued typed array (e.g., Int32Array, etc) is not encouraged due to potential rounding errors during value generation and assignment and, thus, irregular spacing between adjacent values. Instead, consider using incrspace.

• When writing to a complex floating-point output array, real-valued start and stop values are treated as complex numbers having a real component equaling the provided value and having an imaginary component equaling 0.

• When generating linearly spaced complex floating-point numbers, the real and imaginary components are generated separately (i.e., real components are generated over the interval [real(start), real(stop)] and imaginary components are generated over the interval [imag(start), imag(stop)]).

Examples

var linspace = require( '@stdlib/array-linspace' );

// Define function options:
var opts = {
    'dtype': 'generic'
};

// Create arrays of varying lengths...
var out = linspace( 0, 10, 10, opts );
console.log( out );

out = linspace( 0, 10, 11, opts );
console.log( out );

out = linspace( 0, 10, 21, opts );
console.log( out );

// Create an array with decremented values:
out = linspace( 10, 0, 11, opts );
console.log( out );

---

See Also

• @stdlib/array-incrspace: generate a linearly spaced numeric array using a provided increment.
• @stdlib/array-logspace: generate a logarithmically spaced numeric array.

---

Notice

This package is part of stdlib, a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.

For more information on the project, filing bug reports and feature requests, and guidance on how to develop stdlib, see the main project repository.

Community

---

License

See LICENSE.

Copyright

Copyright © 2016-2024. The Stdlib Authors.

Changelog

0.2.1 (2024-02-25)

<section class="features">

Features

• e25b23b - rename type definitions for array and ndarray data types
• e29732d - update minimum TypeScript version

</section> <!-- /.features --> <section class="bug-fixes">

Bug Fixes

• 32a2827 - update import paths for complex type defs

</section> <!-- /.bug-fixes --> <section class="breaking-changes">

BREAKING CHANGES

• e25b23b: rename type definitions for array and ndarray data types

• e25b23b: rename type definitions for array and ndarray data types

  • In order to migrate, users should update their implementations to use the latest naming conventions. The affected type definitions are aliases for individual data type strings, so their should be no behavioral changes.

• e29732d: update minimum TypeScript version

• e29732d: update minimum TypeScript version to 4.1

  • To migrate, users should upgrade their TypeScript version to at least version 4.1.

</section> <!-- /.breaking-changes --> <section class="commits">

Commits

<details>

• 16b25c0 - refactor: query default dtype (by Athan Reines)
• dea49e0 - docs: use single quotes in require calls instead of backticks (by Philipp Burckhardt)
• e25b23b - feat: rename type definitions for array and ndarray data types (by Athan Reines)
• 453dd85 - build: remove tslint directives (by Philipp Burckhardt)
• e29732d - feat: update minimum TypeScript version (by Philipp Burckhardt)
• 32a2827 - fix: update import paths for complex type defs (by Athan Reines)
• 3f60609 - test: use strictEqual checks (by Philipp Burckhardt)

</details> </section> <!-- /.commits --> <section class="contributors">

Contributors

A total of 2 people contributed to this release. Thank you to the following contributors:

• Athan Reines
• Philipp Burckhardt

</section> <!-- /.contributors --> </section> <!-- /.release -->