MATLAB Function Reference

spparms - Set parameters for sparse matrix routines

Syntax

spparms('key',value) spparms values = spparms [keys,values] = spparms spparms(values) value = spparms('key') spparms('default') spparms('tight')

Description

spparms('key',value) sets one or more of the tunable parameters used in the sparse routines, particularly the minimum degree orderings, colmmd and symmmd, and also within sparse backslash. In ordinary use, you should never need to deal with this function.

The meanings of the key parameters are

`'spumoni'`	Sparse Monitor flag:
`0`	Produces no diagnostic output, the default
`1`	Produces information about choice of algorithm based on matrix structure, and about storage allocation
`2`	Also produces very detailed information about the sparse matrix algorithms
`'thr_rel', 'thr_abs'`	Minimum degree threshold is `thr_rel*mindegree + thr_abs.`
`'exact_d'`	Nonzero to use exact degrees in minimum degree. Zero to use approximate degrees.
`'supernd'`	If positive, minimum degree amalgamates the supernodes every `supernd` stages.
`'rreduce'`	If positive, minimum degree does row reduction every `rreduce` stages.
`'wh_frac'`	Rows with `density > wh_frac` are ignored in `colmmd`.
`'autommd'`	Nonzero to use minimum degree (MMD) orderings with QR-based \ and `/`.
`'autoamd'`	Nonzero to use `colamd` ordering with the UMFPACK LU-based \ and /, and to use `amd` with CHOLMOD Cholesky-based \ and /.
`'piv_tol'`	Pivot tolerance used by the UMFPACK LU-based \ and /.
`'bandden'`	Band density used by LAPACK-based \ and / for banded matrices. Band density is defined as (# nonzeros in the band)/(# nonzeros in a full band). If `bandden = 1.0`, never use band solver. If `bandden = 0.0`, always use band solver. Default is `0.5`.
`'umfpack'`	Nonzero to use UMFPACK instead of the v4 LU-based solver in `\` and `/`.
`'sym_tol'`	Symmetric pivot tolerance used by UMFPACK. See `lu` for more information about the role of the symmetric pivot tolerance.

Note LU-based \ and / (UMFPACK) on square matrices use a modified colamd or amd. Cholesky-based \ and / (CHOLMOD) on symmetric positive definite matrices use amd. QR-based \ and / on rectangular matrices use colmmd.

spparms, by itself, prints a description of the current settings.

values = spparms returns a vector whose components give the current settings.

[keys,values] = spparms returns that vector, and also returns a character matrix whose rows are the keywords for the parameters.

spparms(values), with no output argument, sets all the parameters to the values specified by the argument vector.

value = spparms('key') returns the current setting of one parameter.

spparms('default') sets all the parameters to their default settings.

spparms('tight') sets the minimum degree ordering parameters to their tight settings, which can lead to orderings with less fill-in, but which make the ordering functions themselves use more execution time.

The key parameters for default and tight settings are

	Keyword	Default	Tight
`values(1)`	`'spumoni'`	`0.0`
`values(2)`	`'thr_rel'`	`1.1`	`1.0`
`values(3)`	`'thr_abs'`	`1.0`	`0.0`
`values(4)`	`'exact_d'`	`0.0`	`1.0`
`values(5)`	`'supernd'`	`3.0`	`1.0`
`values(6)`	`'rreduce'`	`3.0`	`1.0`
`values(7)`	`'wh_frac'`	`0.5`	`0.5`
`values(8)`	`'autommd'`	`1.0`
`values(9)`	`'autoamd'`	`1.0`
`values(10)`	`'piv_tol'`	`0.1`
`values(11)`	`'bandden'`	`0.5`
`values(12)`	`'umfpack'`	`1.0`
`values(13)`	`'sym_tol'`	`0.001`

Notes

Sparse A\b on Symmetric Positive Definite A

Sparse A\b on symmetric positive definite A uses CHOLMOD in conjunction with the amd reordering routine.

The parameter 'autoamd' turns the amd reordering on or off within the solver.

Sparse A\b on General Square A

Sparse A\b on general square A usually uses UMFPACK in conjunction with amd or a modified colamd reordering routine.

The parameter 'umfpack' turns the use of the UMFPACK software on or off within the solver.

If UMFPACK is used,

The parameter 'piv_tol' controls pivoting within the solver.
The parameter 'autoamd' turns amd and the modified colamd on or off within the solver.

If UMFPACK is not used,

An LU-based solver is used in conjunction with the colmmd reordering routine.
If UMFPACK is not used, then the parameter 'autommd' turns the colmmd reordering routine on or off within the solver.
If UMFPACK is not used and colmmd is used within the solver, then the minimum degree parameters affect the reordering routine within the solver.

Sparse A\b on Rectangular A

Sparse A\b on rectangular A uses a QR-based solve in conjunction with the colmmd reordering routine.

The parameter 'autommd' turns the colmmd reordering on or off within the solver.

If colmmd is used within the solver, then the minimum degree parameters affect the reordering routine within the solver.

References

[1] Gilbert, John R., Cleve Moler, and Robert Schreiber, "Sparse Matrices in MATLAB: Design and Implementation," SIAM Journal on Matrix Analysis and Applications, Vol. 13, 1992, pp. 333-356.

[2] Davis, T. A., UMFPACK Version 4.6 User Guide (http://www.cise.ufl.edu/research/sparse/umfpack/), Dept. of Computer and Information Science and Engineering, Univ. of Florida, Gainesville, FL, 2002.

[3] Davis, T. A., CHOLMOD Version 1.0 User Guide (http://www.cise.ufl.edu/research/sparse/cholmod), Dept. of Computer and Information Science and Engineering, Univ. of Florida, Gainesville, FL, 2005.

spones

sprand