Matrix Scan Methods
Scan methods allow the user to input Matrix data efficiently. They are used only in the case when the initializer parameter to a Matrix constructor is a list. In other Matrix constructor cases, a scan parameter, if given, is ignored; a scan parameter in a Vector constructor is an error.
The scan method is used only to construct the original Matrix. It is not saved as part of the Matrix data structure. In part, it describes the way the initializer parameter is viewed before the individual components of that parameter are interpreted. In addition, it sorts out exactly how the values provided in the initializer list are to be placed into the Matrix under construction.
If no scan parameter is given, it defaults to [rectangular, rows]. If the default scan method is not the desired one, it is necessary to specify an alternate scan method via the scan parameter. This can happen, for example, if the input data is in the form of a block upper triangular Matrix, while the result is not triangular; this could be handled by using the Matrix constructor calling sequence, Matrix( [...], scan = triangular[upper] ). Another situation in which a scan method must be specified is if the Matrix entries are specified by columns or diagonals rather than by rows.
Scan methods are specified as a list containing a structure specification and a data order specification (in either order). At most one of each type of value is permitted. The scan parameter can be specified as a value if only one of these specifiers is given. If only the structure component is given, the data order component defaults to diagonals if the structure is any of band[b], band[b1, b2] or diagonal; otherwise, the data order defaults to rows. If only the data order component is given, the structure component defaults to rectangular.
The possible values for the data order value and their meanings are:
rows
The sublists of the initializer specify row-oriented information. Each sublist starts a new (possibly generalized) row of the result Matrix, immediately below the previous sublist's row(s) (but not necessarily starting in the same column as the previous list).
columns
The sublists of the initializer specify column-oriented information. Each sublist starts a new (possibly generalized) column of the result Matrix immediately to the right of the previous sublist's column(s) (but not necessarily starting in the same row as the previous list).
diagonals
The sublists of the initializer specify diagonal information, starting with the lower leftmost required diagonal and proceeding up and to the right. The generalized diagonals resulting from this scan order need not be disjoint (as diagonals), but the indices specified cannot overlap (picture nested staircases). The first component of each sublist starts at either the left column or top row of the Matrix.
The following table gives the possible values for the structure value and, for each data order value, the corresponding interpretation of the initializer parameter.
rectangular
This is the default value. The sublists of initializer specify successive (generalized) rows. Each sublist starts left justified.
The sublists of initializer specify successive (generalized) columns. Each sublist starts top justified.
Invalid.
triangular[upper]
This is the default value. The sublists of initializer specify successive (generalized) rows. Each sublist starts immediately below and to the right of the first component of the previous sublist.
triangular[lower]
The sublists of initializer specify successive (generalized) columns. Each sublist starts immediately below and to the right of the first component of the previous sublist.
Hessenberg[upper]
This is the default value. The sublists of initializer specify successive (generalized) rows. The first two sublists start left justified, and then every subsequent sublist starts immediately below and to the right of the first component of its predecessor.
The sublists of initializer specify successive (generalized) columns. Each sublist starts top justified and must end on or before the subdiagonal.
Hessenberg[lower]
This is the default value. The sublists of initializer specify successive (generalized) rows. Each sublist starts left justified and must end on or before the superdiagonal.
The sublists of initializer specify successive (generalized) columns. The first two sublists start top justified, and then every subsequent sublist starts immediately below and to the right of the first component of its predecessor.
band[b1, b2]
The sublists of initializer specify successive (generalized) rows. The first (b1+1) sublists start left justified, and then each successive sublist starts immediately below and to the right of the first component of its predecessor.
The sublists of initializer specify successive (generalized) columns. The first (b2+1) sublists start top justified, and then each successive sublist starts immediately below and to the right of the first component of its predecessor.
This is the default value. The sublists of initializer specify successive (generalized) diagonals, from lower left to upper right. The (b1+1)th sublist starts in the upper left corner of the Matrix (that is, the upper left entry of the first component of this sublist is placed in the upper left corner of the constructed Matrix) and the remaining sublists are placed in relation to this one.
band[b]
This is a synonym for band[b, b].
diagonal
This is a synonym for band[0], except that the rows and columns order values are both invalid.
In all cases, locations not explicitly set by any of the initializer parameter values, the scan method, or implicitly set by the shape are set to the fill value (and hence these locations must be explicitly allocated storage; unspecified locations of a sparse Matrix are "set" to 0 by the indexing function). For example, the construction Matrix( [[1], [2, 3], [4, 5]], scan = [triangular[lower], rows], shape = triangular[lower], fill = undefined ) results in a lower triangular Matrix, in which the entries above the diagonal are set (by the shape) to the 0 of the appropriate type and the [3, 3] entry is set to undefined.
Note: The scan method specifies the way in which the initializer parameter is to be viewed before the dimensions of the component elements of the sublists are determined. Thus, Matrix( [[A], [B, C]], scan = triangular ) properly reads a block lower triangular (or ordinary lower triangular) Matrix, producing a rectangular Matrix as the result.
See Also
Matrix
rtable_indexfcn
storage
Vector
Download Help Document
