Mercurial > octave
view scripts/general/rng.m @ 30875:5d3faba0342e
doc: Ensure documentation lists output argument when it exists for all m-files.
For new users of Octave it is best to show explicit calling forms
in the documentation and to show a return argument when it exists.
* bp-table.cc, shift.m, accumarray.m, accumdim.m, bincoeff.m, bitcmp.m,
bitget.m, bitset.m, blkdiag.m, celldisp.m, cplxpair.m, dblquad.m, flip.m,
fliplr.m, flipud.m, idivide.m, int2str.m, interpft.m, logspace.m, num2str.m,
polyarea.m, postpad.m, prepad.m, randi.m, repmat.m, rng.m, rot90.m, rotdim.m,
structfun.m, triplequad.m, uibuttongroup.m, uicontrol.m, uipanel.m,
uipushtool.m, uitoggletool.m, uitoolbar.m, waitforbuttonpress.m, help.m,
__additional_help_message__.m, hsv.m, im2double.m, im2frame.m, javachk.m,
usejava.m, argnames.m, char.m, formula.m, inline.m, __vectorize__.m, findstr.m,
flipdim.m, strmatch.m, vectorize.m, commutation_matrix.m, cond.m, cross.m,
duplication_matrix.m, expm.m, orth.m, rank.m, rref.m, trace.m, vech.m, cast.m,
compare_versions.m, delete.m, dir.m, fileattrib.m, grabcode.m, gunzip.m,
inputname.m, license.m, list_primes.m, ls.m, mexext.m, movefile.m,
namelengthmax.m, nargoutchk.m, nthargout.m, substruct.m, swapbytes.m, ver.m,
verLessThan.m, what.m, fminunc.m, fsolve.m, fzero.m, optimget.m, __fdjac__.m,
matlabroot.m, savepath.m, campos.m, camroll.m, camtarget.m, camup.m, camva.m,
camzoom.m, clabel.m, diffuse.m, legend.m, orient.m, rticks.m, specular.m,
thetaticks.m, xlim.m, xtickangle.m, xticklabels.m, xticks.m, ylim.m,
ytickangle.m, yticklabels.m, yticks.m, zlim.m, ztickangle.m, zticklabels.m,
zticks.m, ellipsoid.m, isocolors.m, isonormals.m, stairs.m, surfnorm.m,
__actual_axis_position__.m, __pltopt__.m, close.m, graphics_toolkit.m, pan.m,
print.m, printd.m, __ghostscript__.m, __gnuplot_print__.m, __opengl_print__.m,
rotate3d.m, subplot.m, zoom.m, compan.m, conv.m, poly.m, polyaffine.m,
polyder.m, polyint.m, polyout.m, polyreduce.m, polyvalm.m, roots.m, prefdir.m,
prefsfile.m, profexplore.m, profexport.m, profshow.m, powerset.m, unique.m,
arch_rnd.m, arma_rnd.m, autoreg_matrix.m, bartlett.m, blackman.m, detrend.m,
durbinlevinson.m, fftconv.m, fftfilt.m, fftshift.m, fractdiff.m, hamming.m,
hanning.m, hurst.m, ifftshift.m, rectangle_lw.m, rectangle_sw.m, triangle_lw.m,
sinc.m, sinetone.m, sinewave.m, spectral_adf.m, spectral_xdf.m, spencer.m,
ilu.m, __sprand__.m, sprand.m, sprandn.m, sprandsym.m, treelayout.m, beta.m,
betainc.m, betaincinv.m, betaln.m, cosint.m, expint.m, factorial.m, gammainc.m,
gammaincinv.m, lcm.m, nthroot.m, perms.m, reallog.m, realpow.m, realsqrt.m,
sinint.m, hadamard.m, hankel.m, hilb.m, invhilb.m, magic.m, pascal.m, rosser.m,
toeplitz.m, vander.m, wilkinson.m, center.m, corr.m, cov.m, discrete_cdf.m,
discrete_inv.m, discrete_pdf.m, discrete_rnd.m, empirical_cdf.m,
empirical_inv.m, empirical_pdf.m, empirical_rnd.m, kendall.m, kurtosis.m,
mad.m, mean.m, meansq.m, median.m, mode.m, moment.m, range.m, ranks.m,
run_count.m, skewness.m, spearman.m, statistics.m, std.m, base2dec.m,
bin2dec.m, blanks.m, cstrcat.m, deblank.m, dec2base.m, dec2bin.m, dec2hex.m,
hex2dec.m, index.m, regexptranslate.m, rindex.m, strcat.m, strjust.m,
strtrim.m, strtrunc.m, substr.m, untabify.m, __have_feature__.m,
__prog_output_assert__.m, __run_test_suite__.m, example.m, fail.m, asctime.m,
calendar.m, ctime.m, date.m, etime.m:
Add return arguments to @deftypefn macros where they were missing. Rename
variables in functions (particularly generic "retval") to match documentation.
Rename some return variables for (hopefully) better clarity (e.g., 'ax' to 'hax'
to indicate it is a graphics handle to an axes object).
author | Rik <rik@octave.org> |
---|---|
date | Wed, 30 Mar 2022 20:40:27 -0700 |
parents | 796f54d4ddbf |
children | 597f3ee61a48 |
line wrap: on
line source
######################################################################## ## ## Copyright (C) 2020-2022 The Octave Project Developers ## ## See the file COPYRIGHT.md in the top-level directory of this ## distribution or <https://octave.org/copyright/>. ## ## This file is part of Octave. ## ## Octave is free software: you can redistribute it and/or modify it ## under the terms of the GNU General Public License as published by ## the Free Software Foundation, either version 3 of the License, or ## (at your option) any later version. ## ## Octave is distributed in the hope that it will be useful, but ## WITHOUT ANY WARRANTY; without even the implied warranty of ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ## GNU General Public License for more details. ## ## You should have received a copy of the GNU General Public License ## along with Octave; see the file COPYING. If not, see ## <https://www.gnu.org/licenses/>. ## ######################################################################## ## -*- texinfo -*- ## @deftypefn {} {} rng (@var{seed}) ## @deftypefnx {} {} rng (@var{seed}, "@var{generator}") ## @deftypefnx {} {} rng ("shuffle") ## @deftypefnx {} {} rng ("shuffle", "@var{generator}") ## @deftypefnx {} {} rng ("default") ## @deftypefnx {} {@var{s} =} rng () ## @deftypefnx {} {} rng (@var{s}) ## @deftypefnx {} {@var{s} =} rng (@dots{}) ## Set or query the seed of the random number generator used by @code{rand} and ## @code{randn}. ## ## The input @var{seed} is a scalar numeric value used to initialize the state ## vector of the random number generator. ## ## The optional string @var{generator} specifies the type of random number ## generator to be used. Its value can be @qcode{"twister"}, ## @qcode{"v5uniform"}, or @qcode{"v5normal"}. The @qcode{"twister"} keyword ## is described below. @qcode{"v5uniform"} and @qcode{"v5normal"} refer to ## older versions of Octave that used to use a different random number ## generator. ## ## The state or seed of the random number generator can be reset to a new ## random value using the @qcode{"shuffle"} keyword. ## ## The random number generator can be reset to default values using the ## @qcode{"default"} keyword. The default values are to use the Mersenne ## Twister generator with a seed of 0. ## ## The optional return value @var{s} contains the state of the random number ## generator at the time the function is called (i.e., before it might be ## modified according to the input arguments). It is encoded as a structure ## variable with three fields: @qcode{"Type"}, @qcode{"Seed"}, and ## @qcode{"State"}. The random number generator can be restored to the state ## @var{s} using @code{rng (@var{s})}. This is useful when the identical ## sequence of pseudo-random numbers is required for an algorithm. ## ## By default, and with the @qcode{"twister"} option, pseudo-random sequences ## are computed using the Mersenne Twister with a period of @math{2^{19937}-1} ## (See @nospell{M. Matsumoto and T. Nishimura}, ## @cite{Mersenne Twister: A 623-dimensionally equidistributed uniform ## pseudorandom number generator}, ## @nospell{ACM} Trans.@: on Modeling and Computer Simulation Vol.@: 8, No.@: 1, ## pp.@: 3--30, January 1998, ## @url{http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html}). ## Do @strong{not} use for cryptography without securely hashing several ## returned values together, otherwise the generator state can be learned after ## reading 624 consecutive values. ## ## @seealso{rand, randn} ## @end deftypefn function s = rng (varargin) if (nargin > 2) print_usage (); endif ## Store current settings of random number generator ## FIXME: there doesn't seem to be a way to query the type of generator ## currently used in Octave - assume "twister". ## FIXME: there doesn't seem to be a way to query the seed initialization ## value - use "Not applicable". ## FIXME: rand and randn use different generators - storing both states. ## For older Matlab generators (v4, v5), the settings are stored like this: ## struct ("Type","Legacy", "Seed", "Not applicable", "State",{[],[],...}) ## Type is the generator name. ## Seed is the initial seed value. ## State is a structure describing internal state of the generator. srng = struct ("Type", "twister", "Seed", "Not applicable", "State", {{rand("state"), randn("state")}}); if (nargin == 0) s = srng; return; endif arg1 = varargin{1}; if (isscalar (arg1) && isnumeric (arg1) && isreal (arg1) && arg1 >= 0) s_rand = s_randn = arg1; generator = check_generator (varargin(2:end)); elseif (ischar (arg1) && strcmpi (arg1, "shuffle")) ## Seed the random number generator based on the current time s_rand = s_randn = "reset"; # or sum (1000*clock) generator = check_generator (varargin(2:end)); elseif (ischar (arg1) && strcmpi (arg1, "default") && nargin == 1) generator = "twister"; s_rand = s_randn = 0; # FIXME: In Matlab, seed 0 corresponds to 5489 elseif (isstruct (arg1) && isscalar (arg1) && nargin == 1) if (numfields (arg1) != 3 || ! all (isfield (arg1, {"Type", "Seed", "State"}))) error ('rng: input structure requires "Type", "Seed", "State" fields"'); endif ## Only the internal state "State" and generator type "Type" are needed generator = arg1.Type; if (iscell (arg1.State)) [s_rand, s_randn] = deal (arg1.State{:}); else s_rand = s_randn = arg1.State; endif else print_usage (); endif ## Set the type of random number generator and seed it if (isempty (generator)) generator = srng.Type; endif switch (generator) case "twister" rand ("state", s_rand); randn ("state", s_randn); case "legacy" rand ("seed", s_rand); randn ("seed", s_randn); case "v5uniform" rand ("seed", s_rand); case "v5normal" randn ("seed", s_randn); otherwise error ('rng: invalid GENERATOR: "%s"', generator); endswitch if (nargout > 0) s = srng; endif endfunction function gen = check_generator (val) if (isempty (val)) gen = ""; return; elseif (! iscellstr (val)) error ("rng: GENERATOR must be a string"); endif gen = tolower (char (val)); if (any (strcmp (gen, {"simdtwister", "combrecursive", "philox", "threefry", "multfibonacci", "v4"}))) error ('rng: random number generator "%s" is not available in Octave', gen); elseif (! any (strcmp (gen, {"twister", "v5uniform", "v5normal"}))) error ('rng: unknown random number generator "%s"', gen); endif endfunction %!test %! state = rng (); %! unwind_protect %! rng (42); %! ru1 = rand (); %! rn1 = randn (); %! rng (42); %! ru2 = rand (); %! rn2 = randn (); %! assert (ru2, ru1); %! assert (rn2, rn1); %! s1 = rng (); %! s2 = rng (42); %! assert (isequal (s1, s2)); %! ru1 = rand (); %! rn1 = randn (); %! s3 = rng (42); %! ru2 = rand (); %! rn2 = randn (); %! assert (ru2, ru1); %! assert (rn2, rn1); %! unwind_protect_cleanup %! rng (state); %! end_unwind_protect %!test %! state = rng (); %! unwind_protect %! rng (42, "twister"); %! ru1 = rand (); %! rn1 = randn (); %! rng (42, "twister"); %! ru2 = rand (); %! rn2 = randn (); %! assert (ru2, ru1); %! assert (rn2, rn1); %! s1 = rng (); %! s2 = rng (42, "twister"); %! assert (isequal (s1, s2)); %! ru1 = rand (); %! rn1 = randn (); %! s3 = rng (42, "twister"); %! ru2 = rand (); %! rn2 = randn (); %! assert (ru2, ru1); %! assert (rn2, rn1); %! unwind_protect_cleanup %! rng (state); %! end_unwind_protect %!test %! state = rng (); %! unwind_protect %! rng ("shuffle"); %! rng ("shuffle", "twister"); %! s = rng ("shuffle"); %! assert (! isequal (s, rng ("shuffle"))); %! s = rng ("shuffle", "twister"); %! assert (! isequal (s, rng ("shuffle", "twister"))); %! unwind_protect_cleanup %! rng (state); %! end_unwind_protect %!test %! state = rng (); %! unwind_protect %! rng ("default"); %! ru1 = rand (); %! rn1 = randn (); %! rng (0, "twister"); %! ru2 = rand (); %! rn2 = randn (); %! assert (ru2, ru1); %! assert (rn2, rn1); %! rng (0, "twister"); %! s = rng ("default"); %! assert (isequal (s, rng ())); %! unwind_protect_cleanup %! rng (state); %! end_unwind_protect %!test %! state = rng (); %! unwind_protect %! s = rng (); %! ru1 = rand (); %! rn1 = randn (); %! rng (s); %! ru2 = rand (); %! rn2 = randn (); %! assert (ru2, ru1); %! assert (rn2, rn1); %! rng (42); rand (1,2); x = rand (1,2); %! rng (42); rand (1,2); s = rng (); y = rand (1,2); %! assert (x, y); %! rng (s); z = rand (1,2); %! assert (x, z); %! s1 = rng (); %! s2 = rng (s1); %! assert (isequal (s1, s2)); %! unwind_protect_cleanup %! rng (state); %! end_unwind_protect ## Test input validation %!error <Invalid call> rng (1, 2, 3) %!error <Invalid call> rng (eye (2)) %!error <Invalid call> rng ({}) %!error <Invalid call> rng (2i) %!error <Invalid call> rng (-2) %!error <Invalid call> rng ("foobar") %!error <Invalid call> rng ("default", "twister") %!error <Invalid call> rng (struct ("Seed", {1, 2})) %!error <Invalid call> rng (struct ("Type",[],"State",[],"Seed",[]), "twister") %!error <input structure requires "Type"> rng (struct ()) %!error <input structure requires "Type"> %! rng (struct ("Type1",[],"State",[],"Seed",[])); %!error <GENERATOR must be a string> rng (0, struct ()) %!error <"philox" is not available in Octave> rng (0, "philox") %!error <GENERATOR must be a string> rng ("shuffle", struct ()) %!error <unknown random number generator "foobar"> rng ("shuffle", "foobar")