You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
refactor!: migrate to random/tools/unary-factory and drop support for default options
BREAKING CHANGE: drop support for default options
Previously, the `factory` method supported providing defaults for
various ndarray options (e.g., readonly, mode, order, etc). These
options have been removed. Instead, users should pass them along
to the main API for generating pseudorandom numbers. To replicate
previous functionality, create your own wrapper which uses partial
application to pass a set of "default" options for each invocation
of the PRNG function.
---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
- task: lint_filenames
status: passed
- task: lint_editorconfig
status: passed
- task: lint_markdown
status: passed
- task: lint_package_json
status: passed
- task: lint_repl_help
status: passed
- task: lint_javascript_src
status: passed
- task: lint_javascript_cli
status: na
- task: lint_javascript_examples
status: na
- task: lint_javascript_tests
status: passed
- task: lint_javascript_benchmarks
status: passed
- task: lint_python
status: na
- task: lint_r
status: na
- task: lint_c_src
status: na
- task: lint_c_examples
status: na
- task: lint_c_benchmarks
status: na
- task: lint_c_tests_fixtures
status: na
- task: lint_shell
status: na
- task: lint_typescript_declarations
status: passed
- task: lint_typescript_tests
status: passed
- task: lint_license_headers
status: passed
---
-**lambda**: rate parameter. May be either a scalar or an [ndarray][@stdlib/ndarray/ctor]. When providing an [ndarray][@stdlib/ndarray/ctor], the [ndarray][@stdlib/ndarray/ctor] must be [broadcast compatible][@stdlib/ndarray/base/broadcast-shapes] with the specified output shape.
46
46
-**options**: function options.
47
47
48
-
If provided an empty `shape`, the function returns a zero-dimensional [ndarray][@stdlib/ndarray/ctor].
49
-
50
-
```javascript
51
-
var arr =exponential( [], 2.0 );
52
-
// returns <ndarray>
53
-
54
-
var shape =arr.shape;
55
-
// returns []
56
-
57
-
var v =arr.get();
58
-
// returns <number>
59
-
```
60
-
61
-
Distribution parameters may be either scalars or [ndarrays][@stdlib/ndarray/ctor]. When providing an [ndarray][@stdlib/ndarray/ctor], the [ndarray][@stdlib/ndarray/ctor] must be [broadcast compatible][@stdlib/ndarray/base/broadcast-shapes] with the specified output array `shape`.
48
+
When provided a scalar distribution parameter, every element in the output [ndarray][@stdlib/ndarray/ctor] is drawn from the same distribution. To generate pseudorandom numbers drawn from different distributions, provide a distribution parameter argument as an [ndarray][@stdlib/ndarray/ctor]. The following example demonstrates broadcasting an [ndarray][@stdlib/ndarray/ctor] containing distribution parameters to generate sub-matrices drawn from different distributions.
If provided an empty shape, the function returns a zero-dimensional [ndarray][@stdlib/ndarray/ctor].
77
64
78
-
-**dtype**: output array data type. Must be a [real-valued floating-point data type][@stdlib/array/typed-real-float-dtypes] or "generic". Default: `'float64'`.
79
-
-**order**: array order (i.e., memory layout), which is either `row-major` (C-style) or `column-major` (Fortran-style). Default: `'row-major'`.
80
-
-**mode**: specifies how to handle indices which exceed array dimensions. For a list of supported modes, see [`ndarray`][@stdlib/ndarray/ctor]. Default: `'throw'`.
81
-
-**submode**: a mode array which specifies for each dimension how to handle subscripts which exceed array dimensions. If provided fewer modes than dimensions, an [ndarray][@stdlib/ndarray/ctor] instance recycles modes using modulo arithmetic. Default: `[ options.mode ]`.
82
-
-**readonly**: `boolean` indicating whether an array should be **read-only**. Default: `false`.
65
+
```javascript
66
+
var arr =exponential( [], 2.0 );
67
+
// returns <ndarray>
83
68
84
-
By default, the function returns an [ndarray][@stdlib/ndarray/ctor] having a `float64` data type. To return an [ndarray][@stdlib/ndarray/ctor] having a different data type, set the `dtype` option.
69
+
var shape =arr.shape;
70
+
// returns []
71
+
72
+
var v =arr.get();
73
+
// returns <number>
74
+
```
75
+
76
+
The function accepts the following options:
77
+
78
+
-**dtype**: output ndarray data type. Must be a real-valued floating-point or "generic" [data type][@stdlib/ndarray/dtypes].
79
+
-**order**: ndarray order (i.e., memory layout), which is either `row-major` (C-style) or `column-major` (Fortran-style). Default: `'row-major'`.
80
+
-**mode**: specifies how to handle indices which exceed ndarray dimensions. For a list of supported modes, see [`ndarray`][@stdlib/ndarray/ctor]. Default: `'throw'`.
81
+
-**submode**: a mode array which specifies for each dimension how to handle subscripts which exceed ndarray dimensions. If provided fewer modes than dimensions, an [ndarray][@stdlib/ndarray/ctor] instance recycles modes using modulo arithmetic. Default: `[ options.mode ]`.
82
+
-**readonly**: boolean indicating whether an ndarray should be **read-only**. Default: `false`.
83
+
84
+
By default, the function returns an [ndarray][@stdlib/ndarray/ctor] having a [data type][@stdlib/ndarray/dtypes] determined by the function's output data type [policy][@stdlib/ndarray/output-dtype-policies]. To override the default behavior, set the `dtype` option.
85
85
86
86
```javascript
87
87
var opts = {
@@ -95,41 +95,27 @@ var dt = arr.dtype;
95
95
// returns 'generic'
96
96
```
97
97
98
-
#### exponential.assign( out, lambda )
98
+
#### exponential.assign( lambda, out )
99
99
100
100
Fills an [ndarray][@stdlib/ndarray/ctor] with pseudorandom numbers drawn from an [exponential][@stdlib/random/base/exponential] distribution.
101
101
102
102
```javascript
103
103
var zeros =require( '@stdlib/ndarray/zeros' );
104
104
105
-
vararr=zeros( [ 3, 3 ] );
105
+
varout=zeros( [ 3, 3 ] );
106
106
// returns <ndarray>
107
107
108
-
varout=exponential.assign( arr, 2.0 );
108
+
varv=exponential.assign( 2.0, out );
109
109
// returns <ndarray>
110
110
111
-
var bool = ( out===arr );
111
+
var bool = ( v===out );
112
112
// returns true
113
113
```
114
114
115
-
Distribution parameters may be either scalars or [ndarrays][@stdlib/ndarray/ctor]. When providing an [ndarray][@stdlib/ndarray/ctor], the [ndarray][@stdlib/ndarray/ctor] must be [broadcast compatible][@stdlib/ndarray/base/broadcast-shapes] with the output [ndarray][@stdlib/ndarray/ctor].
-**lambda**: rate parameter. May be either a scalar or an [ndarray][@stdlib/ndarray/ctor]. When providing an [ndarray][@stdlib/ndarray/ctor], the [ndarray][@stdlib/ndarray/ctor] must be [broadcast compatible][@stdlib/ndarray/base/broadcast-shapes] with the output [ndarray][@stdlib/ndarray/ctor].
118
+
-**out**: output [ndarray][@stdlib/ndarray/ctor].
133
119
134
120
#### exponential.factory( \[options] )
135
121
@@ -145,17 +131,12 @@ var sh = out.shape;
145
131
// returns [ 3, 3 ]
146
132
```
147
133
148
-
The function accepts the following `options`:
134
+
The method accepts the following options:
149
135
150
136
-**prng**: pseudorandom number generator for generating uniformly distributed pseudorandom numbers on the interval `[0,1)`. If provided, the function **ignores** both the `state` and `seed` options. In order to seed the underlying pseudorandom number generator, one must seed the provided `prng` (assuming the provided `prng` is seedable).
151
137
-**seed**: pseudorandom number generator seed.
152
138
-**state**: a [`Uint32Array`][@stdlib/array/uint32] containing pseudorandom number generator state. If provided, the function ignores the `seed` option.
153
-
-**copy**: `boolean` indicating whether to copy a provided pseudorandom number generator state. Setting this option to `false` allows sharing state between two or more pseudorandom number generators. Setting this option to `true` ensures that an underlying generator has exclusive control over its internal state. Default: `true`.
154
-
-**dtype**: default output array data type. Must be a [real-valued floating-point data type][@stdlib/array/typed-real-float-dtypes] or "generic". Default: `'float64'`.
155
-
-**order**: default array order (i.e., memory layout), which is either `row-major` (C-style) or `column-major` (Fortran-style). Default: `'row-major'`.
156
-
-**mode**: default specifying how to handle indices which exceed array dimensions. For a list of supported modes, see [`ndarray`][@stdlib/ndarray/ctor]. Default: `'throw'`.
157
-
-**submode**: default specifying for each dimension how to handle subscripts which exceed array dimensions. If the number of modes is less than the number of dimensions, an [ndarray][@stdlib/ndarray/ctor] instance recycles modes using modulo arithmetic. Default: `[ options.mode ]`.
158
-
-**readonly**: default indicating whether an array should be **read-only**. Default: `false`.
139
+
-**copy**: boolean indicating whether to copy a provided pseudorandom number generator state. Setting this option to `false` allows sharing state between two or more pseudorandom number generators. Setting this option to `true` ensures that an underlying generator has exclusive control over its internal state. Default: `true`.
159
140
160
141
To use a custom PRNG as the underlying source of uniformly distributed pseudorandom numbers, set the `prng` option.
161
142
@@ -183,34 +164,7 @@ var out = random( [ 3, 3 ], 2.0, opts );
183
164
// returns <ndarray>
184
165
```
185
166
186
-
The returned function accepts the following `options`, each of which overrides the respective default:
187
-
188
-
-**dtype**: output array data type. Must be a [real-valued floating-point data type][@stdlib/array/typed-real-float-dtypes] or "generic".
189
-
-**order**: array order (i.e., memory layout), which is either `row-major` (C-style) or `column-major` (Fortran-style).
190
-
-**mode**: specifies how to handle indices which exceed array dimensions. For a list of supported modes, see [`ndarray`][@stdlib/ndarray/ctor].
191
-
-**submode**: a mode array which specifies for each dimension how to handle subscripts which exceed array dimensions. If the number of modes is less than the number of dimensions, an [ndarray][@stdlib/ndarray/ctor] instance recycles modes using modulo arithmetic.
192
-
-**readonly**: `boolean` indicating whether an array should be **read-only**.
193
-
194
-
To override the default output array data type, set the `dtype` option.
195
-
196
-
```javascript
197
-
var random =exponential.factory();
198
-
199
-
var out =random( [ 3, 3 ], 2.0 );
200
-
// returns <ndarray>
201
-
202
-
var dt =out.dtype;
203
-
// returns 'float64'
204
-
205
-
var opts = {
206
-
'dtype':'generic'
207
-
};
208
-
out =random( [ 3, 3 ], 2.0, opts );
209
-
// returns <ndarray>
210
-
211
-
dt =out.dtype;
212
-
// returns 'generic'
213
-
```
167
+
The returned function has the same interface and accepts the same options as the `exponential` function above.
214
168
215
169
#### exponential.PRNG
216
170
@@ -341,6 +295,7 @@ var sz = random.byteLength;
341
295
342
296
- If PRNG state is "shared" (meaning a state array was provided during function creation and **not** copied) and one sets the underlying generator state to a state array having a different length, the function returned by the `factory` method does **not** update the existing shared state and, instead, points to the newly provided state array. In order to synchronize the output of the underlying generator according to the new shared state array, the state array for **each** relevant creation function and/or PRNG must be **explicitly** set.
343
297
- If PRNG state is "shared" and one sets the underlying generator state to a state array of the same length, the PRNG state is updated (along with the state of all other creation functions and/or PRNGs sharing the PRNG's state array).
298
+
- The output data type [policy][@stdlib/ndarray/output-dtype-policies] only applies to the main function and specifies that, by default, the function must return an [ndarray][@stdlib/ndarray/ctor] having a real-valued floating-point or "generic" [data type][@stdlib/ndarray/dtypes]. For the `assign` method, the output [ndarray][@stdlib/ndarray/ctor] is allowed to have any supported output [data type][@stdlib/ndarray/dtypes].
0 commit comments