1function C = random (varargin)
2%GRB.RANDOM random sparse matrix.
3% C = GrB.random (A) has the same pattern as A, but with uniformly
4%   distributed random entries.
5%
6% C = GrB.random (m, n, d) is a random m-by-n GraphBLAS matrix, with
7%   about d*m*n uniformly distributed entries.  The entries are
8%   constructed by computing d*m*n entries at random positions, and
9%   then any duplicates are discarded, so if d is large or m*n is
10%   small, then C will have fewer than d*m*n entries.  The value of
11%   d may exceed 1 (this differs from the MATLAB sprand, which limits
12%   d to 1).  If d is inf, then C is generated as a full GraphBLAS
13%   matrix, with numel (C) = m*n.
14%
15% Optional parameters may be used, in any order, after the A or m,n,d
16% arguments:
17%
18%   C = GrB.random (..., 'uniform', ...) uses a uniform distribution
19%           of values, with entries greater than zero and less than one.
20%
21%   C = GrB.random (..., 'normal', ...) uses a normal distribution, like
22%           the built-in MATLAB sprandn.
23%
24%   C = GrB.random (..., 'range', [lo hi], ...) changes the range of
25%           the random numbers.  If 'range' is not present, the default
26%           is double ([0 1]).  The type of [lo hi] determines the type
27%           of the random matrix C.  If [lo hi] is logical, all entries
28%           in the pattern are true.  If [lo hi] is 'double' or 'single',
29%           then if the random number generator (rand or randn) produces
30%           a double random value of x, it is scaled to (hi-lo)*x+lo.  If
31%           [lo hi] is integer, then x becomes floor ((hi-lo+1)*x + lo),
32%           which is then typecasted to the requested. integer type. This
33%           scaling applies to both the 'uniform' and 'normal'
34%           distribution.  To construct a random complex matrix, pass in
35%           [lo hi] as single complex or double complex.
36%
37%           With the normal distribution, [lo hi] specifies the mean (lo)
38%           and the standard deviation (hi) of the final distribution.
39%
40%   C = GrB.random (A, 'symmetric', ...) creates a symmetric matrix, like
41%           the built-in C = sprandsym (A), except that the default
42%           distribution is 'uniform'.  The input matrix A must be
43%           square.  Only tril(A) is used to construct C.
44%
45%   C = GrB.random (n, d, 'symmetric', ...) creates an n-by-n symmetric
46%           matrix C, with a uniform distribution of values.  To create
47%           a matrix like C = srandsym (n,d) with the built-in MATLAB
48%           sprandym, use C = GrB.random (n, d, 'symmetric', 'normal').
49%           Note that the pair of arguments (m, n, ...) do not appear;
50%           just a single dimension (n, ...).
51%
52%   To construct a Hermitian matrix instead, use 'hermitian' in place of
53%   'symmetric'.
54%
55% The rc option of the built-in MATLAB sprand and sprandn is not supported.
56%
57% Example:
58%
59%   rng ('default')
60%   A = sprand (4, 5, 0.5)          % 4-by-5 with at most 10 entries
61%   rng ('default')
62%   C = GrB.random (4, 5, 0.5)      % same pattern as A
63%   isequal (spones (A), spones (C))
64%
65%   C = GrB.random (C)              % same pattern but newly random values
66%
67%   C = GrB.random (2, 4, inf)      % 2-by-4 with all 8 entries
68%   C = GrB.random (2, 4, 0.5, 'normal')    % like sprandn (2,4,0.5)
69%
70%   % random 10-by-10 int16 matrix with entries from -3 to 6,
71%   % including explicit zeros, with a uniform distribution
72%   C = GrB.random (10, 10, 0.5, 'range', int16 ([-3 6]))
73%
74%   % larger matrix, with normal distribution:
75%   C = GrB.random (1000, 1000, 0.5, 'normal', 'range', int16 ([-3 6])) ;
76%   [i,j,x] = find (C) ;
77%   histogram (x, 'BinMethod', 'integers') ;
78%
79%   % lots of explicit zeros, since uint8 saturates:
80%   C = GrB.random (1000, 1000, 0.5, 'normal', 'range', uint8 ([-3 6])) ;
81%   [i,j,x] = find (C) ;
82%   histogram (x, 'BinMethod', 'integers') ;
83%
84%   % uniform distribution across all possible uint8 values
85%   C = GrB.random (1000, 1000, 0.5, 'range', uint8 ([0 255])) ;
86%   [i,j,x] = find (C) ;
87%   histogram (x, 'BinMethod', 'integers') ;
88%
89%   % large symmetric matrix with normal distribution
90%   C = GrB.random (1e6, 1e-5, 'symmetric', 'normal')
91%   [i,j,x] = find (C) ;
92%   histogram (x)
93%
94% See also GrB/sprand, GrB/sprandn, GrB/sprandsym.
95
96% SuiteSparse:GraphBLAS, Timothy A. Davis, (c) 2017-2021, All Rights Reserved.
97% SPDX-License-Identifier: GPL-3.0-or-later
98
99C = GrB (gb_random (varargin {:})) ;
100
101