function result=cosmo_rand(varargin)
% generate uniform pseudo-random numbers, optionally using a seed value
%
% result=cosmo_rand(s1,...,sN,['seed',seed])
%
% Input:
% s* scalar or vector indicating dimensions of the result
% 'seed', seed (optional) if provided, use this seed value for
% pseudo-random number generation
%
% Output:
% result array of size s1 x s2 x ... sN. If the seed option is
% used, repeated calls with the same seed and element
% dimensions gives the same result
% Example:
% % generate 2x2 pseudo-random number matrices twice, just like 'rand'
% % (repeated calls give different outputs)
% x1=cosmo_rand(2,2);
% x2=cosmo_rand(2,2);
% isequal(x1,x2)
% %|| false
% %
% % as above, but specify a seed; repeated calls give the same output
% x3=cosmo_rand(2,2,'seed',314);
% x4=cosmo_rand(2,2,'seed',314);
% isequal(x3,x4)
% %|| true
% %
% % using a different seed gives a different output
% x5=cosmo_rand(2,2,'seed',315);
% isequal(x3,x5)
% %|| false
%
%
% Notes:
% - this function behaves identically to the builtin 'rand' function,
% except that it supports a 'seed' option, which allows for
% deterministic pseudo-number generation
% - when using the 'seed' option, this function gives identical output
% under both matlab and octave. To achieve this, the PRNG is set to a
% different state for the two platforms
% - this function uses the Mersenne twister algorithm by default, even
% when 'seed' is used (unlike Matlab and Octave).
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
