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