README.md (8890B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2018 The Stdlib Authors. 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 19 --> 20 21 # Raised Cosine Random Numbers 22 23 > [Raised cosine][cosine] distributed pseudorandom numbers. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var cosine = require( '@stdlib/random/base/cosine' ); 31 ``` 32 33 #### cosine( mu, s ) 34 35 Returns a pseudorandom number drawn from a [raised cosine][cosine] distribution with parameters `mu` (mean) and `s` (scale parameter). 36 37 ```javascript 38 var r = cosine( 2.0, 5.0 ); 39 // returns <number> 40 ``` 41 42 If `mu` or `s` is `NaN` or `s <= 0`, the function returns `NaN`. 43 44 ```javascript 45 var r = cosine( 2.0, -2.0 ); 46 // returns NaN 47 48 r = cosine( NaN, 5.0 ); 49 // returns NaN 50 51 r = cosine( 2.0, NaN ); 52 // returns NaN 53 ``` 54 55 #### cosine.factory( \[mu, s, ]\[options] ) 56 57 Returns a pseudorandom number generator (PRNG) for generating pseudorandom numbers drawn from a [raised cosine][cosine] distribution. 58 59 ```javascript 60 var rand = cosine.factory(); 61 62 var r = rand( 0.1, 1.5 ); 63 // returns <number> 64 ``` 65 66 If provided `mu` and `s`, the returned generator returns random variates from the specified distribution. 67 68 ```javascript 69 var rand = cosine.factory( 10.0, 2.0 ); 70 71 var r = rand(); 72 // returns <number> 73 74 r = rand(); 75 // returns <number> 76 ``` 77 78 If not provided `mu` and `s`, the returned generator requires that both parameters be provided at each invocation. 79 80 ```javascript 81 var rand = cosine.factory(); 82 83 var r = rand( 0.0, 1.0 ); 84 // returns <number> 85 86 r = rand( -2.0, 2.0 ); 87 // returns <number> 88 ``` 89 90 The function accepts the following `options`: 91 92 - **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 returned pseudorandom number generator, one must seed the provided `prng` (assuming the provided `prng` is seedable). 93 - **seed**: pseudorandom number generator seed. 94 - **state**: a [`Uint32Array`][@stdlib/array/uint32] containing pseudorandom number generator state. If provided, the function ignores the `seed` option. 95 - **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 a returned generator has exclusive control over its internal state. Default: `true`. 96 97 To use a custom PRNG as the underlying source of uniformly distributed pseudorandom numbers, set the `prng` option. 98 99 ```javascript 100 var minstd = require( '@stdlib/random/base/minstd' ); 101 102 var rand = cosine.factory({ 103 'prng': minstd.normalized 104 }); 105 106 var r = rand( 1.0, 2.0 ); 107 // returns <number> 108 ``` 109 110 To seed a pseudorandom number generator, set the `seed` option. 111 112 ```javascript 113 var rand1 = cosine.factory({ 114 'seed': 12345 115 }); 116 117 var r1 = rand1( 1.0, 2.0 ); 118 // returns <number> 119 120 var rand2 = cosine.factory( 1.0, 2.0, { 121 'seed': 12345 122 }); 123 124 var r2 = rand2(); 125 // returns <number> 126 127 var bool = ( r1 === r2 ); 128 // returns true 129 ``` 130 131 To return a generator having a specific initial state, set the generator `state` option. 132 133 ```javascript 134 var rand; 135 var bool; 136 var r; 137 var i; 138 139 // Generate pseudorandom numbers, thus progressing the generator state: 140 for ( i = 0; i < 1000; i++ ) { 141 r = cosine( 1.0, 2.0 ); 142 } 143 144 // Create a new PRNG initialized to the current state of `cosine`: 145 rand = cosine.factory({ 146 'state': cosine.state 147 }); 148 149 // Test that the generated pseudorandom numbers are the same: 150 bool = ( rand( 1.0, 2.0 ) === cosine( 1.0, 2.0 ) ); 151 // returns true 152 ``` 153 154 #### cosine.NAME 155 156 The generator name. 157 158 ```javascript 159 var str = cosine.NAME; 160 // returns 'cosine' 161 ``` 162 163 #### cosine.PRNG 164 165 The underlying pseudorandom number generator. 166 167 ```javascript 168 var prng = cosine.PRNG; 169 // returns <Function> 170 ``` 171 172 #### cosine.seed 173 174 The value used to seed `cosine()`. 175 176 ```javascript 177 var rand; 178 var r; 179 var i; 180 181 // Generate pseudorandom values... 182 for ( i = 0; i < 100; i++ ) { 183 r = cosine( 2.0, 2.0 ); 184 } 185 186 // Generate the same pseudorandom values... 187 rand = cosine.factory( 2.0, 2.0, { 188 'seed': cosine.seed 189 }); 190 for ( i = 0; i < 100; i++ ) { 191 r = rand(); 192 } 193 ``` 194 195 If provided a PRNG for uniformly distributed numbers, this value is `null`. 196 197 <!-- eslint-disable stdlib/no-builtin-math --> 198 199 ```javascript 200 var rand = cosine.factory({ 201 'prng': Math.random 202 }); 203 204 var seed = rand.seed; 205 // returns null 206 ``` 207 208 #### cosine.seedLength 209 210 Length of generator seed. 211 212 ```javascript 213 var len = cosine.seedLength; 214 // returns <number> 215 ``` 216 217 If provided a PRNG for uniformly distributed numbers, this value is `null`. 218 219 <!-- eslint-disable stdlib/no-builtin-math --> 220 221 ```javascript 222 var rand = cosine.factory({ 223 'prng': Math.random 224 }); 225 226 var len = rand.seedLength; 227 // returns null 228 ``` 229 230 #### cosine.state 231 232 Writable property for getting and setting the generator state. 233 234 ```javascript 235 var r = cosine( 2.0, 5.0 ); 236 // returns <number> 237 238 r = cosine( 2.0, 5.0 ); 239 // returns <number> 240 241 // ... 242 243 // Get a copy of the current state: 244 var state = cosine.state; 245 // returns <Uint32Array> 246 247 r = cosine( 2.0, 5.0 ); 248 // returns <number> 249 250 r = cosine( 2.0, 5.0 ); 251 // returns <number> 252 253 // Reset the state: 254 cosine.state = state; 255 256 // Replay the last two pseudorandom numbers: 257 r = cosine( 2.0, 5.0 ); 258 // returns <number> 259 260 r = cosine( 2.0, 5.0 ); 261 // returns <number> 262 263 // ... 264 ``` 265 266 If provided a PRNG for uniformly distributed numbers, this value is `null`. 267 268 <!-- eslint-disable stdlib/no-builtin-math --> 269 270 ```javascript 271 var rand = cosine.factory({ 272 'prng': Math.random 273 }); 274 275 var state = rand.state; 276 // returns null 277 ``` 278 279 #### cosine.stateLength 280 281 Length of generator state. 282 283 ```javascript 284 var len = cosine.stateLength; 285 // returns <number> 286 ``` 287 288 If provided a PRNG for uniformly distributed numbers, this value is `null`. 289 290 <!-- eslint-disable stdlib/no-builtin-math --> 291 292 ```javascript 293 var rand = cosine.factory({ 294 'prng': Math.random 295 }); 296 297 var len = rand.stateLength; 298 // returns null 299 ``` 300 301 #### cosine.byteLength 302 303 Size (in bytes) of generator state. 304 305 ```javascript 306 var sz = cosine.byteLength; 307 // returns <number> 308 ``` 309 310 If provided a PRNG for uniformly distributed numbers, this value is `null`. 311 312 <!-- eslint-disable stdlib/no-builtin-math --> 313 314 ```javascript 315 var rand = cosine.factory({ 316 'prng': Math.random 317 }); 318 319 var sz = rand.byteLength; 320 // returns null 321 ``` 322 323 #### cosine.toJSON() 324 325 Serializes the pseudorandom number generator as a JSON object. 326 327 ```javascript 328 var o = cosine.toJSON(); 329 // returns { 'type': 'PRNG', 'name': '...', 'state': {...}, 'params': [] } 330 ``` 331 332 If provided a PRNG for uniformly distributed numbers, this method returns `null`. 333 334 <!-- eslint-disable stdlib/no-builtin-math --> 335 336 ```javascript 337 var rand = cosine.factory({ 338 'prng': Math.random 339 }); 340 341 var o = rand.toJSON(); 342 // returns null 343 ``` 344 345 </section> 346 347 <!-- /.usage --> 348 349 <section class="notes"> 350 351 ## Notes 352 353 - If PRNG state is "shared" (meaning a state array was provided during PRNG creation and **not** copied) and one sets the generator state to a state array having a different length, the PRNG does **not** update the existing shared state and, instead, points to the newly provided state array. In order to synchronize PRNG output according to the new shared state array, the state array for **each** relevant PRNG must be **explicitly** set. 354 - If PRNG state is "shared" and one sets the generator state to a state array of the same length, the PRNG state is updated (along with the state of all other PRNGs sharing the PRNG's state array). 355 356 </section> 357 358 <!-- /.notes --> 359 360 <section class="examples"> 361 362 ## Examples 363 364 <!-- eslint no-undef: "error" --> 365 366 ```javascript 367 var cosine = require( '@stdlib/random/base/cosine' ); 368 369 var seed; 370 var rand; 371 var i; 372 373 // Generate pseudorandom numbers... 374 for ( i = 0; i < 100; i++ ) { 375 console.log( cosine( 0.0, 1.0 ) ); 376 } 377 378 // Create a new pseudorandom number generator... 379 seed = 1234; 380 rand = cosine.factory( 5.0, 2.0, { 381 'seed': seed 382 }); 383 for ( i = 0; i < 100; i++ ) { 384 console.log( rand() ); 385 } 386 387 // Create another pseudorandom number generator using a previous seed... 388 rand = cosine.factory( 0.0, 1.0, { 389 'seed': cosine.seed 390 }); 391 for ( i = 0; i < 100; i++ ) { 392 console.log( rand() ); 393 } 394 ``` 395 396 </section> 397 398 <!-- /.examples --> 399 400 <section class="links"> 401 402 [cosine]: https://en.wikipedia.org/wiki/Raised_cosine_distribution 403 404 [@stdlib/array/uint32]: https://www.npmjs.com/package/@stdlib/array-uint32 405 406 </section> 407 408 <!-- /.links -->