NCL Home > Documentation > Functions > General applied math, Array manipulators

sparse_matrix_mult

Multiplies a sparse matrix with a dense matrix.

Available in version 6.1.0 and later.

Prototype

	function sparse_matrix_mult (
		row  [*] : byte, short, integer, long,  
		col  [*] : byte, short, integer, long,  
		S    [*] : numeric,                     
		x        : numeric,                     
		dims [*] : any integral type            
	)

	return_val  :  float or double

Arguments

row

A 1D array representing the row indexes (0-based) of the non-zero elements in the sparse array S.

col

A 1D array representing the column indexes (0-based) of the non-zero elements in the sparse array S. Must be the same length as row.

S

A 1D array containing the non-zero elements of the sparse matrix at each row, col index pair. Must be the same length as row and col.

x

The dense matrix to multiply against. The rightmost dimensions must either be nrow x ncol or nrow. See the description of dims.

dims

A one-dimensional array of one or two elements representing the output dimensions of the output array.

If it is one value, then this value represents the number of rows, and the number of columns will internally be set to 1.

Otherwise, this array represents the number of rows and columns, and the number of columns must be the same as the rightmost dimension of x.

Description

This function performs a sparse matrix multiply: 

  y = Sx

given a sparse matrix represented by row, column, and S, and a regular array x.

If x contains any missing values, then that value will be skipped. This function currently doesn't check if S contains missing values. You need to remove these yourself before calling this routine.

Note: this function recognizes the special case of the output dims dimensions being just one value (the number of rows). In this case, it will operate against the rightmost dimension of x only.

The indexes given by row and col must be within the range of the dimensions given by dims.

The rightmost dimension(s) of the return array will be same as the dimensions represented by dims. The leftmost dimensions will be the same as the leftmost dimensions of x. The return array will be of type double if either x or S are double, and float otherwise.

Examples

Example 1

Assume you have a sparse matrix: 

  3  0  0
  0  4  0
  0  0  6
  0  0  7
and regular matrix: 

  1  2  3
  4  5  6
  7  8  9
You can perform the sparse matrix multiply with: 

  row = (/0,1,2,3/)
  col = (/0,1,2,2/)
  S   = (/3,4,6,7/)
  x   = (/(/1,2,3/),(/4,5,6/),(/7,8,9/)/)

  y   = sparse_matrix_mult(row,col,S,x,(/4,3/))

  write_matrix(y, "3f5.0", False)

  print(y)
The results will be: 

   3.   6.   9.
  16.  20.  24.
  42.  48.  54.
  49.  56.  63.

Example 2

If the x matrix contains missing values, then any S number that is multiplied with an x missing value will also be missing. The remaining valid values in the x column will still be multiplied and added. 

       
  row = (/0,1,2,3/)
  col = (/0,1,2,2/)
  S   = (/3,4,6,7/)
  x   = (/(/1,-999,3/),(/4,5,-999/),(/7,8,9/)/)

  x@_FillValue = -999

  Sx  = sparse_matrix_mult(row,col,S,x,(/4,3/))
  write_matrix(Sx, "3f6.0", False)

Results:

     S                x                    Sx 
| 3  0  0 |     | 1 -999    3 |     |  3 -999    9 |
| 0  4  0 |  x  | 4    5 -999 |  =  | 16   20 -999 |
| 0  0  6 |     | 7    8    9 |     | 42   48   54 |
| 0  0  7 |                         | 49   56   63 |

Example 3

This example is an extension of example #2, except with more missing values. 

       
  row = (/0,0,1,2,3/)
  col = (/0,2,1,2,0/)
  S   = (/3,4,6,7,8/)
  x   = (/(/1,-999,3/),(/4,5,-999/),(/7,8,9/)/)

  x@_FillValue = -999

  Sx  = sparse_matrix_mult(row,col,S,x,(/4,3/))
  write_matrix(Sx, "3f6.0", False)

Results:

     S                x                    Sx 
| 3  0  4 |     | 1 -999    3 |     | 31   32   45 |
| 0  6  0 |  x  | 4    5 -999 |  =  | 24   30 -999 |
| 0  0  7 |     | 7    8    9 |     | 49   56   63 |
| 8  0  0 |                         |  8 -999   24 |