## randsvdfast

version 2.0 (8.37 KB) by
Fast generation of random test matrices with pre-assigned singular values or 2-norm condition number.

Updated 1 Oct 2021

From GitHub

# The MATLAB `randsvdfast` test matrix

This repository contains a MATLAB function to generates a matrix with specified singular values or 2-norm condition number and the corresponding unit tests.

The function is named after the `randsvd` matrix in the MATLAB `gallery`, as it provides similar functionalities but uses a faster algorithm. The method was designed to generate test matrices for extreme-scale benchmarks such as the High-performance Linpack Benchmark (HPL) or the HPL-AI Mixed-Precision Benchmark.

## Usage

The command

``````A = randsvdfast(n, kappa, mode, method, matrix, classname, realout)
``````

generates a matrix `A` of class `classname` with condition number `kappa` and singular values distributed according to `mode`. The function generates a matrix of order `n` if `n` is a positive integer, and of size `n(1)` by `n(2)` if `n` is a vector of length 2. By default, `n` and `kappa` are both set to 10.

The functions provides functionalities similar to those of the MATLAB function `galley('randsvd', ...)`. The most notable difference is that this routine allows the user to specify a custom distribution of the singular values (see below), but does not implement the reduction to banded form.

The singular values can have one of the following distributions:

• `mode` = 0: one large singular value and one small singular value,
• `mode` = 1: one large singular value,
• `mode` = 2: one small singular value,
• `mode` = 3 (default): geometric distribution,
• `mode` = 4: arithmetic distribution,
• `mode` = 5: random singular values with uniformly distributed magnitude,
• `mode` = 6: the vector `kappa` contains the singular values.

The parameter `method` selects the algorithm that will be used to generate the test matrix. It can take any of the following values:

• `method` = 1 (default): [Alg. 3.1, 1],
• `method` = 2: [Alg. 3.2, 1],
• `method` = 3: [Alg. 4.1, 1] (only `mode` = 0, 1, 2),
• `method` = 4: [Alg. 4.2, 1] (only `mode` = 0, 1, 2).

This function is faster for `method` = 3 or 4 than for `method` = 1 or 2.

The algorithm uses an orthogonal matrix Q that depends on the value of the parameter `matrix`, which can take the following values:

• `matrix` = 0 (default): Q is a Haar distributed random unitary generated as the Q factor of the QR decomposition of the matrix `randn(n(1),n(2))`.
• `matrix` = an integer from 1 to 7: Q is the matrix `gallery('orthog',n,matrix)`.
• `matrix` is the function handle of a two-argument function that generates an `n(1)`-by-`n(2)` matrix with orthonormal columns.

The output matrix will be of class `classname` where `classname` is either `'single'` or `'double'`. Constants are computed in double precision, whereas operations at the scalar level are performed in precision `classname`. The entries of `A` will be real if `realout` is `true`, and complex otherwise. By default the function generates a real matrix of doubles.

## Tests

The class-based unit tests for the `randsvdfast` function can be ran with the command `test_run`.

## Anymatrix

The repository can be downloaded as a remote group into the extensible matrix collection Anymatrix with

``````anymatrix('g', 'randsvdfast', 'mfasi/randsvdfast-matlab')
``````

and the test matrix can be generated with

``````anymatrix('randsvdfast/randsvdfast', n, kappa, mode, method, matrix, classname, realout)
``````

## Reference

[1] M. Fasi & N. J. Higham. Generating extreme-scale matrices with specified singular values or condition numbers. SIAM J. Sci. Comput., 43(1), 663–684, 2021.

### Cite As

M. Fasi & N. J. Higham. Generating extreme-scale matrices with specified singular values or condition numbers. SIAM J. Sci. Comput., 43(1), 663–684, 2021.

##### MATLAB Release Compatibility
Created with R2019b
Compatible with any release
##### Platform Compatibility
Windows macOS Linux