@stdlib/array-linspace NPM

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 ]

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.

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 );

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.