Mercurial > octave-nkf

comparison libinterp/corefcn/rand.cc @ 20207:4f45eaf83908 stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Update more docstrings to have one sentence summary as first line. Reviewed libinterp/corefcn directory. * libinterp/corefcn/__ilu__.cc, libinterp/corefcn/balance.cc, libinterp/corefcn/besselj.cc, libinterp/corefcn/betainc.cc, libinterp/corefcn/bitfcns.cc, libinterp/corefcn/bsxfun.cc, libinterp/corefcn/cellfun.cc, libinterp/corefcn/colloc.cc, libinterp/corefcn/conv2.cc, libinterp/corefcn/data.cc, libinterp/corefcn/debug.cc, libinterp/corefcn/defaults.cc, libinterp/corefcn/det.cc, libinterp/corefcn/dirfns.cc, libinterp/corefcn/dlmread.cc, libinterp/corefcn/dot.cc, libinterp/corefcn/eig.cc, libinterp/corefcn/error.cc, libinterp/corefcn/fft2.cc, libinterp/corefcn/fftn.cc, libinterp/corefcn/file-io.cc, libinterp/corefcn/filter.cc, libinterp/corefcn/find.cc, libinterp/corefcn/gammainc.cc, libinterp/corefcn/gcd.cc, libinterp/corefcn/getgrent.cc, libinterp/corefcn/getpwent.cc, libinterp/corefcn/getrusage.cc, libinterp/corefcn/graphics.cc, libinterp/corefcn/help.cc, libinterp/corefcn/hex2num.cc, libinterp/corefcn/input.cc, libinterp/corefcn/inv.cc, libinterp/corefcn/kron.cc, libinterp/corefcn/load-path.cc, libinterp/corefcn/load-save.cc, libinterp/corefcn/lookup.cc, libinterp/corefcn/ls-oct-ascii.cc, libinterp/corefcn/lsode.cc, libinterp/corefcn/lu.cc, libinterp/corefcn/luinc.cc, libinterp/corefcn/mappers.cc, libinterp/corefcn/matrix_type.cc, libinterp/corefcn/max.cc, libinterp/corefcn/md5sum.cc, libinterp/corefcn/mgorth.cc, libinterp/corefcn/nproc.cc, libinterp/corefcn/oct-hist.cc, libinterp/corefcn/ordschur.cc, libinterp/corefcn/pager.cc, libinterp/corefcn/pinv.cc, libinterp/corefcn/pr-output.cc, libinterp/corefcn/pt-jit.cc, libinterp/corefcn/quad.cc, libinterp/corefcn/quadcc.cc, libinterp/corefcn/qz.cc, libinterp/corefcn/rand.cc, libinterp/corefcn/rcond.cc, libinterp/corefcn/regexp.cc, libinterp/corefcn/schur.cc, libinterp/corefcn/sighandlers.cc, libinterp/corefcn/sparse.cc, libinterp/corefcn/spparms.cc, libinterp/corefcn/str2double.cc, libinterp/corefcn/strfind.cc, libinterp/corefcn/strfns.cc, libinterp/corefcn/sub2ind.cc, libinterp/corefcn/svd.cc, libinterp/corefcn/symtab.cc, libinterp/corefcn/syscalls.cc, libinterp/corefcn/sysdep.cc, libinterp/corefcn/time.cc, libinterp/corefcn/toplev.cc, libinterp/corefcn/tril.cc, libinterp/corefcn/tsearch.cc, libinterp/corefcn/typecast.cc, libinterp/corefcn/urlwrite.cc, libinterp/corefcn/utils.cc, libinterp/corefcn/variables.cc, scripts/polynomial/spline.m: Update more docstrings to have one sentence summary as first line.
author Rik <rik@octave.org>
date Sat, 09 May 2015 17:19:30 -0700
parents 4197fc428c7d
children 00cf2847355d
comparison
equal deleted inserted replaced
20206:b70f8da6dcd3 20207:4f45eaf83908
375 @deftypefnx {Built-in Function} {} rand (\"seed\", @var{v})\n\ 375 @deftypefnx {Built-in Function} {} rand (\"seed\", @var{v})\n\
376 @deftypefnx {Built-in Function} {} rand (\"seed\", \"reset\")\n\ 376 @deftypefnx {Built-in Function} {} rand (\"seed\", \"reset\")\n\
377 @deftypefnx {Built-in Function} {} rand (@dots{}, \"single\")\n\ 377 @deftypefnx {Built-in Function} {} rand (@dots{}, \"single\")\n\
378 @deftypefnx {Built-in Function} {} rand (@dots{}, \"double\")\n\ 378 @deftypefnx {Built-in Function} {} rand (@dots{}, \"double\")\n\
379 Return a matrix with random elements uniformly distributed on the\n\ 379 Return a matrix with random elements uniformly distributed on the\n\
380 interval (0, 1). The arguments are handled the same as the arguments\n\ 380 interval (0, 1).\n\
381 for @code{eye}.\n\ 381 \n\
382 \n\ 382 The arguments are handled the same as the arguments for @code{eye}.\n\
383 You can query the state of the random number generator using the\n\ 383 \n\
384 form\n\ 384 You can query the state of the random number generator using the form\n\
385 \n\ 385 \n\
386 @example\n\ 386 @example\n\
387 v = rand (\"state\")\n\ 387 v = rand (\"state\")\n\
388 @end example\n\ 388 @end example\n\
389 \n\ 389 \n\
390 This returns a column vector @var{v} of length 625. Later, you can\n\ 390 This returns a column vector @var{v} of length 625. Later, you can restore\n\
391 restore the random number generator to the state @var{v}\n\ 391 the random number generator to the state @var{v} using the form\n\
392 using the form\n\
393 \n\ 392 \n\
394 @example\n\ 393 @example\n\
395 rand (\"state\", v)\n\ 394 rand (\"state\", v)\n\
396 @end example\n\ 395 @end example\n\
397 \n\ 396 \n\
398 @noindent\n\ 397 @noindent\n\
399 You may also initialize the state vector from an arbitrary vector of\n\ 398 You may also initialize the state vector from an arbitrary vector of length\n\
400 length @leq{} 625 for @var{v}. This new state will be a hash based on the\n\ 399 @leq{} 625 for @var{v}. This new state will be a hash based on the value of\n\
401 value of @var{v}, not @var{v} itself.\n\ 400 @var{v}, not @var{v} itself.\n\
402 \n\ 401 \n\
403 By default, the generator is initialized from @code{/dev/urandom} if it is\n\ 402 By default, the generator is initialized from @code{/dev/urandom} if it is\n\
404 available, otherwise from CPU time, wall clock time, and the current\n\ 403 available, otherwise from CPU time, wall clock time, and the current\n\
405 fraction of a second. Note that this differs from @sc{matlab}, which\n\ 404 fraction of a second. Note that this differs from @sc{matlab}, which\n\
406 always initializes the state to the same state at startup. To obtain\n\ 405 always initializes the state to the same state at startup. To obtain\n\
407 behavior comparable to @sc{matlab}, initialize with a deterministic state\n\ 406 behavior comparable to @sc{matlab}, initialize with a deterministic state\n\
408 vector in Octave's startup files (@pxref{Startup Files}).\n\ 407 vector in Octave's startup files (@pxref{Startup Files}).\n\
409 \n\ 408 \n\
410 To compute the pseudo-random sequence, @code{rand} uses the Mersenne\n\ 409 To compute the pseudo-random sequence, @code{rand} uses the Mersenne\n\
411 Twister with a period of @math{2^{19937}-1} (See\n\ 410 Twister with a period of @math{2^{19937}-1}\n\
412 @nospell{M. Matsumoto and T. Nishimura},\n\ 411 (See @nospell{M. Matsumoto and T. Nishimura},\n\
413 @cite{Mersenne Twister: A 623-dimensionally equidistributed uniform\n\ 412 @cite{Mersenne Twister: A 623-dimensionally equidistributed uniform\n\
414 pseudorandom number generator}, ACM Trans. on\n\ 413 pseudorandom number generator},\n\
415 Modeling and Computer Simulation Vol. 8, No. 1, pp. 3-30, January 1998,\n\ 414 ACM Trans. on Modeling and Computer Simulation Vol. 8, No. 1, pp. 3--30,\n\
415 January 1998,\n\
416 @url{http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html}).\n\ 416 @url{http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html}).\n\
417 Do @strong{not} use for cryptography without securely hashing\n\ 417 Do @strong{not} use for cryptography without securely hashing several\n\
418 several returned values together, otherwise the generator state\n\ 418 returned values together, otherwise the generator state can be learned after\n\
419 can be learned after reading 624 consecutive values.\n\ 419 reading 624 consecutive values.\n\
420 \n\ 420 \n\
421 Older versions of Octave used a different random number generator.\n\ 421 Older versions of Octave used a different random number generator.\n\
422 The new generator is used by default\n\ 422 The new generator is used by default as it is significantly faster than the\n\
423 as it is significantly faster than the old generator, and produces\n\ 423 old generator, and produces random numbers with a significantly longer cycle\n\
424 random numbers with a significantly longer cycle time. However, in\n\ 424 time. However, in some circumstances it might be desirable to obtain the\n\
425 some circumstances it might be desirable to obtain the same random\n\ 425 same random sequences as produced by the old generators. To do this the\n\
426 sequences as used by the old generators. To do this the keyword\n\ 426 keyword @qcode{\"seed\"} is used to specify that the old generators should\n\
427 @qcode{\"seed\"} is used to specify that the old generators should be use,\n\ 427 be used, as in\n\
428 as in\n\
429 \n\ 428 \n\
430 @example\n\ 429 @example\n\
431 rand (\"seed\", val)\n\ 430 rand (\"seed\", val)\n\
432 @end example\n\ 431 @end example\n\
433 \n\ 432 \n\
438 @example\n\ 437 @example\n\
439 s = rand (\"seed\")\n\ 438 s = rand (\"seed\")\n\
440 @end example\n\ 439 @end example\n\
441 \n\ 440 \n\
442 However, it should be noted that querying the seed will not cause\n\ 441 However, it should be noted that querying the seed will not cause\n\
443 @code{rand} to use the old generators, only setting the seed will.\n\ 442 @code{rand} to use the old generators, only setting the seed will. To cause\n\
444 To cause @code{rand} to once again use the new generators, the\n\ 443 @code{rand} to once again use the new generators, the keyword\n\
445 keyword @qcode{\"state\"} should be used to reset the state of the\n\ 444 @qcode{\"state\"} should be used to reset the state of the @code{rand}.\n\
446 @code{rand}.\n\ 445 \n\
447 \n\ 446 The state or seed of the generator can be reset to a new random value using\n\
448 The state or seed of the generator can be reset to a new random value\n\ 447 the @qcode{\"reset\"} keyword.\n\
449 using the @qcode{\"reset\"} keyword.\n\
450 \n\ 448 \n\
451 The class of the value returned can be controlled by a trailing\n\ 449 The class of the value returned can be controlled by a trailing\n\
452 @qcode{\"double\"} or @qcode{\"single\"} argument. These are the only valid\n\ 450 @qcode{\"double\"} or @qcode{\"single\"} argument. These are the only valid\n\
453 classes.\n\ 451 classes.\n\
454 @seealso{randn, rande, randg, randp}\n\ 452 @seealso{randn, rande, randg, randp}\n\
561 @deftypefnx {Built-in Function} {@var{v} =} randn (\"seed\")\n\ 559 @deftypefnx {Built-in Function} {@var{v} =} randn (\"seed\")\n\
562 @deftypefnx {Built-in Function} {} randn (\"seed\", @var{v})\n\ 560 @deftypefnx {Built-in Function} {} randn (\"seed\", @var{v})\n\
563 @deftypefnx {Built-in Function} {} randn (\"seed\", \"reset\")\n\ 561 @deftypefnx {Built-in Function} {} randn (\"seed\", \"reset\")\n\
564 @deftypefnx {Built-in Function} {} randn (@dots{}, \"single\")\n\ 562 @deftypefnx {Built-in Function} {} randn (@dots{}, \"single\")\n\
565 @deftypefnx {Built-in Function} {} randn (@dots{}, \"double\")\n\ 563 @deftypefnx {Built-in Function} {} randn (@dots{}, \"double\")\n\
566 Return a matrix with normally distributed random\n\ 564 Return a matrix with normally distributed random elements having zero mean\n\
567 elements having zero mean and variance one. The arguments are\n\ 565 and variance one.\n\
568 handled the same as the arguments for @code{rand}.\n\ 566 \n\
567 The arguments are handled the same as the arguments for @code{rand}.\n\
569 \n\ 568 \n\
570 By default, @code{randn} uses the @nospell{Marsaglia and Tsang}\n\ 569 By default, @code{randn} uses the @nospell{Marsaglia and Tsang}\n\
571 ``Ziggurat technique'' to transform from a uniform to a normal distribution.\n\ 570 ``Ziggurat technique'' to transform from a uniform to a normal distribution.\n\
572 \n\ 571 \n\
573 The class of the value returned can be controlled by a trailing\n\ 572 The class of the value returned can be controlled by a trailing\n\
633 @deftypefnx {Built-in Function} {@var{v} =} rande (\"seed\")\n\ 632 @deftypefnx {Built-in Function} {@var{v} =} rande (\"seed\")\n\
634 @deftypefnx {Built-in Function} {} rande (\"seed\", @var{v})\n\ 633 @deftypefnx {Built-in Function} {} rande (\"seed\", @var{v})\n\
635 @deftypefnx {Built-in Function} {} rande (\"seed\", \"reset\")\n\ 634 @deftypefnx {Built-in Function} {} rande (\"seed\", \"reset\")\n\
636 @deftypefnx {Built-in Function} {} rande (@dots{}, \"single\")\n\ 635 @deftypefnx {Built-in Function} {} rande (@dots{}, \"single\")\n\
637 @deftypefnx {Built-in Function} {} rande (@dots{}, \"double\")\n\ 636 @deftypefnx {Built-in Function} {} rande (@dots{}, \"double\")\n\
638 Return a matrix with exponentially distributed random elements. The\n\ 637 Return a matrix with exponentially distributed random elements.\n\
639 arguments are handled the same as the arguments for @code{rand}.\n\ 638 \n\
639 The arguments are handled the same as the arguments for @code{rand}.\n\
640 \n\ 640 \n\
641 By default, @code{randn} uses the @nospell{Marsaglia and Tsang}\n\ 641 By default, @code{randn} uses the @nospell{Marsaglia and Tsang}\n\
642 ``Ziggurat technique'' to transform from a uniform to a normal distribution.\n\ 642 ``Ziggurat technique'' to transform from a uniform to a normal distribution.\n\
643 \n\ 643 \n\
644 The class of the value returned can be controlled by a trailing\n\ 644 The class of the value returned can be controlled by a trailing\n\
707 @deftypefnx {Built-in Function} {} randg (\"seed\", @var{v})\n\ 707 @deftypefnx {Built-in Function} {} randg (\"seed\", @var{v})\n\
708 @deftypefnx {Built-in Function} {} randg (\"seed\", \"reset\")\n\ 708 @deftypefnx {Built-in Function} {} randg (\"seed\", \"reset\")\n\
709 @deftypefnx {Built-in Function} {} randg (@dots{}, \"single\")\n\ 709 @deftypefnx {Built-in Function} {} randg (@dots{}, \"single\")\n\
710 @deftypefnx {Built-in Function} {} randg (@dots{}, \"double\")\n\ 710 @deftypefnx {Built-in Function} {} randg (@dots{}, \"double\")\n\
711 Return a matrix with @code{gamma (@var{a},1)} distributed random elements.\n\ 711 Return a matrix with @code{gamma (@var{a},1)} distributed random elements.\n\
712 The arguments are handled the same as the arguments for @code{rand},\n\ 712 \n\
713 except for the argument @var{a}.\n\ 713 The arguments are handled the same as the arguments for @code{rand}, except\n\
714 for the argument @var{a}.\n\
714 \n\ 715 \n\
715 This can be used to generate many distributions:\n\ 716 This can be used to generate many distributions:\n\
716 \n\ 717 \n\
717 @table @asis\n\ 718 @table @asis\n\
718 @item @code{gamma (a, b)} for @code{a > -1}, @code{b > 0}\n\ 719 @item @code{gamma (a, b)} for @code{a > -1}, @code{b > 0}\n\
984 @deftypefnx {Built-in Function} {} randp (\"seed\", @var{v})\n\ 985 @deftypefnx {Built-in Function} {} randp (\"seed\", @var{v})\n\
985 @deftypefnx {Built-in Function} {} randp (\"seed\", \"reset\")\n\ 986 @deftypefnx {Built-in Function} {} randp (\"seed\", \"reset\")\n\
986 @deftypefnx {Built-in Function} {} randp (@dots{}, \"single\")\n\ 987 @deftypefnx {Built-in Function} {} randp (@dots{}, \"single\")\n\
987 @deftypefnx {Built-in Function} {} randp (@dots{}, \"double\")\n\ 988 @deftypefnx {Built-in Function} {} randp (@dots{}, \"double\")\n\
988 Return a matrix with Poisson distributed random elements with mean value\n\ 989 Return a matrix with Poisson distributed random elements with mean value\n\
989 parameter given by the first argument, @var{l}. The arguments\n\ 990 parameter given by the first argument, @var{l}.\n\
990 are handled the same as the arguments for @code{rand}, except for the\n\ 991 \n\
991 argument @var{l}.\n\ 992 The arguments are handled the same as the arguments for @code{rand}, except\n\
992 \n\ 993 for the argument @var{l}.\n\
993 Five different algorithms are used depending on the range of @var{l}\n\ 994 \n\
994 and whether or not @var{l} is a scalar or a matrix.\n\ 995 Five different algorithms are used depending on the range of @var{l} and\n\
996 whether or not @var{l} is a scalar or a matrix.\n\
995 \n\ 997 \n\
996 @table @asis\n\ 998 @table @asis\n\
997 @item For scalar @var{l} @leq{} 12, use direct method.\n\ 999 @item For scalar @var{l} @leq{} 12, use direct method.\n\
998 W.H. Press, et al., @cite{Numerical Recipes in C},\n\ 1000 W.H. Press, et al., @cite{Numerical Recipes in C},\n\
999 Cambridge University Press, 1992.\n\ 1001 Cambridge University Press, 1992.\n\
1123 DEFUN (randperm, args, , 1125 DEFUN (randperm, args, ,
1124 "-*- texinfo -*-\n\ 1126 "-*- texinfo -*-\n\
1125 @deftypefn {Built-in Function} {} randperm (@var{n})\n\ 1127 @deftypefn {Built-in Function} {} randperm (@var{n})\n\
1126 @deftypefnx {Built-in Function} {} randperm (@var{n}, @var{m})\n\ 1128 @deftypefnx {Built-in Function} {} randperm (@var{n}, @var{m})\n\
1127 Return a row vector containing a random permutation of @code{1:@var{n}}.\n\ 1129 Return a row vector containing a random permutation of @code{1:@var{n}}.\n\
1130 \n\
1128 If @var{m} is supplied, return @var{m} unique entries, sampled without\n\ 1131 If @var{m} is supplied, return @var{m} unique entries, sampled without\n\
1129 replacement from @code{1:@var{n}}. The complexity is O(@var{n}) in\n\ 1132 replacement from @code{1:@var{n}}.\n\
1130 memory and O(@var{m}) in time, unless @var{m} < @var{n}/5, in which case\n\ 1133 \n\
1131 O(@var{m}) memory is used as well. The randomization is performed using\n\ 1134 The complexity is O(@var{n}) in memory and O(@var{m}) in time, unless\n\
1132 rand(). All permutations are equally likely.\n\ 1135 @var{m} < @var{n}/5, in which case O(@var{m}) memory is used as well. The\n\
1136 randomization is performed using rand(). All permutations are equally\n\
1137 likely.\n\
1133 @seealso{perms}\n\ 1138 @seealso{perms}\n\
1134 @end deftypefn") 1139 @end deftypefn")
1135 { 1140 {
1136 1141
1137 #ifdef USE_UNORDERED_MAP_WITH_TR1 1142 #ifdef USE_UNORDERED_MAP_WITH_TR1