matrix

README

Gonum Matrix

This repository is no longer maintained. Development has moved to https://github.com/gonum/gonum.

This is a matrix package for the Go language.

Issues

If you find any bugs, feel free to file an issue on the github issue tracker for gonum/gonum if the bug exists in that reposity; no code changes will be made to this repository. Other discussions should be taken to the gonum-dev Google Group.

https://groups.google.com/forum/#!forum/gonum-dev

License

Please see github.com/gonum/gonum for general license information, contributors, authors, etc on the Gonum suite of packages.

Documentation

Overview

Package matrix provides common error handling mechanisms for matrix operations in mat64 and cmat128.

Overview

This section provides a quick overview of the matrix package. The following sections provide more in depth commentary.

matrix provides:

• Error type definitions
• Error recovery mechanisms
• Common constants used by mat64 and cmat128

Errors

The mat64 and cmat128 matrix packages share a common set of errors provided by matrix via the matrix.Error type.

Errors are either returned directly or used as the parameter of a panic depending on the class of error encountered. Returned errors indicate that a call was not able to complete successfully while panics generally indicate a programmer or unrecoverable error.

Examples of each type are found in the mat64 Solve methods, which find x such that A*x = b.

An error value is returned from the function or method when the operation can meaningfully fail. The Solve operation cannot complete if A is singular. However, determining the singularity of A is most easily discovered during the Solve procedure itself and is a valid result from the operation, so in this case an error is returned.

A function will panic when the input parameters are inappropriate for the function. In Solve, for example, the number of rows of each input matrix must be equal because of the rules of matrix multiplication. Similarly, for solving A*x = b, a non-zero receiver must have the same number of rows as A has columns and must have the same number of columns as b. In all cases where a function will panic, conditions that would lead to a panic can easily be checked prior to a call.

Error Recovery

When a matrix.Error is the parameter of a panic, the panic can be recovered by a Maybe function, which will then return the error. Panics that are not of type matrix.Error are re-panicked by the Maybe functions.

Invariants

Matrix input arguments to functions are never directly modified. If an operation changes Matrix data, the mutated matrix will be the receiver of a function.

For convenience, a matrix may be used as both a receiver and as an input, e.g.

a.Pow(a, 6)
v.SolveVec(a.T(), v)

though in many cases this will cause an allocation (see Element Aliasing). An exception to this rule is Copy, which does not allow a.Copy(a.T()).

Element Aliasing

Most methods in the matrix packages modify receiver data. It is forbidden for the modified data region of the receiver to overlap the used data area of the input arguments. The exception to this rule is when the method receiver is equal to one of the input arguments, as in the a.Pow(a, 6) call above, or its implicit transpose.

This prohibition is to help avoid subtle mistakes when the method needs to read from and write to the same data region. There are ways to make mistakes using the matrix API, and matrix functions will detect and complain about those. There are many ways to make mistakes by excursion from the matrix API via interaction with raw matrix values.

If you need to read the rest of this section to understand the behavior of your program, you are being clever. Don't be clever. If you must be clever, blas64/cblas128 and lapack64/clapack128 may be used to call the behavior directly.

The matrix packages will use the following rules to detect overlap between the receiver and one of the inputs:

• the input implements one of the Raw methods, and
• the Raw type matches that of the receiver or one is a RawMatrixer and the other is a RawVectorer, and
• the address ranges of the backing data slices overlap, and
• the strides differ or there is an overlap in the used data elements.

If such an overlap is detected, the method will panic.

The following cases will not panic:

• the data slices do not overlap,
• there is pointer identity between the receiver and input values after the value has been untransposed if necessary.

The matrix packages will not attempt to detect element overlap if the input does not implement a Raw method, or if the Raw method differs from that of the receiver except when a conversion has occurred through a matrix API function. Method behavior is undefined if there is undetected overlap.

Index

• Constants
• Variables
• func Maybe(fn func()) (err error)
• func MaybeComplex(fn func() complex128) (f complex128, err error)
• func MaybeFloat(fn func() float64) (f float64, err error)
• type Condition
  • func (c Condition) Error() string
• type Error
  • func (err Error) Error() string
• type ErrorStack
  • func (err ErrorStack) Error() string
• type GSVDKind
• type SVDKind
• type TriKind

Constants

const (
	// CondNorm is the matrix norm used for computing the condition number by routines
	// in the matrix packages.
	CondNorm = lapack.MaxRowSum

	// CondNormTrans is the norm used to compute on A^T to get the same result as
	// computing CondNorm on A.
	CondNormTrans = lapack.MaxColumnSum
)

const ConditionTolerance = 1e16

ConditionTolerance is the tolerance limit of the condition number. If the condition number is above this value, the matrix is considered singular.

Variables

var (
	ErrIndexOutOfRange     = Error{"matrix: index out of range"}
	ErrRowAccess           = Error{"matrix: row index out of range"}
	ErrColAccess           = Error{"matrix: column index out of range"}
	ErrVectorAccess        = Error{"matrix: vector index out of range"}
	ErrZeroLength          = Error{"matrix: zero length in matrix definition"}
	ErrRowLength           = Error{"matrix: row length mismatch"}
	ErrColLength           = Error{"matrix: col length mismatch"}
	ErrSquare              = Error{"matrix: expect square matrix"}
	ErrNormOrder           = Error{"matrix: invalid norm order for matrix"}
	ErrSingular            = Error{"matrix: matrix is singular"}
	ErrShape               = Error{"matrix: dimension mismatch"}
	ErrIllegalStride       = Error{"matrix: illegal stride"}
	ErrPivot               = Error{"matrix: malformed pivot list"}
	ErrTriangle            = Error{"matrix: triangular storage mismatch"}
	ErrTriangleSet         = Error{"matrix: triangular set out of bounds"}
	ErrSliceLengthMismatch = Error{"matrix: input slice length mismatch"}
	ErrNotPSD              = Error{"matrix: input not positive symmetric definite"}
	ErrFailedEigen         = Error{"matrix: eigendecomposition not successful"}
)

Functions

func Maybe

func Maybe(fn func()) (err error)

Maybe will recover a panic with a type mat64.Error from fn, and return this error as the Err field of an ErrorStack. The stack trace for the panicking function will be recovered and placed in the StackTrace field. Any other error is re-panicked.

func MaybeComplex

func MaybeComplex(fn func() complex128) (f complex128, err error)

MaybeComplex will recover a panic with a type mat64.Error from fn, and return this error as the Err field of an ErrorStack. The stack trace for the panicking function will be recovered and placed in the StackTrace field. Any other error is re-panicked.

func MaybeFloat

func MaybeFloat(fn func() float64) (f float64, err error)

MaybeFloat will recover a panic with a type mat64.Error from fn, and return this error as the Err field of an ErrorStack. The stack trace for the panicking function will be recovered and placed in the StackTrace field. Any other error is re-panicked.

Types

type Condition

type Condition float64

Condition is the condition number of a matrix. The condition number is defined as ||A|| * ||A^-1||.

One important use of Condition is during linear solve routines (finding x such that A * x = b). The condition number of A indicates the accuracy of the computed solution. A Condition error will be returned if the condition number of A is sufficiently large. If A is exactly singular to working precision, Condition == ∞, and the solve algorithm may have completed early. If Condition is large and finite the solve algorithm will be performed, but the computed solution may be innacurate. Due to the nature of finite precision arithmetic, the value of Condition is only an approximate test of singularity.

func (Condition) Error

func (c Condition) Error() string

type Error

type Error struct {
	// contains filtered or unexported fields
}

Error represents matrix handling errors. These errors can be recovered by Maybe wrappers.

func (Error) Error

func (err Error) Error() string

type ErrorStack

type ErrorStack struct {
	Err error

	// StackTrace is the stack trace
	// recovered by Maybe, MaybeFloat
	// or MaybeComplex.
	StackTrace string
}

ErrorStack represents matrix handling errors that have been recovered by Maybe wrappers.

func (ErrorStack) Error

func (err ErrorStack) Error() string

type GSVDKind

type GSVDKind int

GSVDKind specifies the treatment of singular vectors during a GSVD factorization.

const (
	// GSVDU specifies that the U singular vectors should be computed during
	// the decomposition.
	GSVDU GSVDKind = 1 << iota
	// GSVDV specifies that the V singular vectors should be computed during
	// the decomposition.
	GSVDV
	// GSVDQ specifies that the Q singular vectors should be computed during
	// the decomposition.
	GSVDQ

	// GSVDNone specifies that no singular vector should be computed during
	// the decomposition.
	GSVDNone
)

type SVDKind

type SVDKind int

SVDKind specifies the treatment of singular vectors during an SVD factorization.

const (
	// SVDNone specifies that no singular vectors should be computed during
	// the decomposition.
	SVDNone SVDKind = iota + 1
	// SVDThin computes the thin singular vectors, that is, it computes
	//  A = U~ * Σ * V~^T
	// where U~ is of size m×min(m,n), Σ is a diagonal matrix of size min(m,n)×min(m,n)
	// and V~ is of size n×min(m,n).
	SVDThin
	// SVDFull computes the full singular value decomposition,
	//  A = U * Σ * V^T
	// where U is of size m×m, Σ is an m×n diagonal matrix, and V is an n×n matrix.
	SVDFull
)

type TriKind

type TriKind bool

TriKind represents the triangularity of the matrix.

const (
	// Upper specifies an upper triangular matrix.
	Upper TriKind = true
	// Lower specifies a lower triangular matrix.
	Lower TriKind = false
)