mat: clarify docs for Dense.Solve and VecDense.SolveVec

mat/solve.go

@@ -10,14 +10,25 @@ import (
 	"gonum.org/v1/gonum/lapack/lapack64"
 )
 
-// Solve finds a minimum-norm solution to a system of linear equations defined
+// Solve solves the linear least squares problem
-// by the matrices A and B. If A is singular or near-singular, a Condition error
+//  minimize over x |b - A*x|_2
-// is returned. See the documentation for Condition for more information.
+// where A is an m×n matrix A, b is a given m element vector and x is n element
+// solution vector. Solve assumes that A has full rank, that is
+//  rank(A) = min(m,n)
 //
-// The minimization problem solved depends on the input parameters:
+// If m >= n, Solve finds the unique least squares solution of an overdetermined
-//  - if m >= n, find X such that ||A*X - B||_2 is minimized,
+// system.
-//  - if m < n, find the minimum norm solution of A * X = B.
+//
-// The solution matrix, X, is stored in-place into the receiver.
+// If m < n, there is an infinite number of solutions that satisfy b-A*x=0. In
+// this case Solve finds the unique solution of an underdetermined system that
+// minimizes |x|_2.
+//
+// Several right-hand side vectors b and solution vectors x can be handled in a
+// single call. Vectors b are stored in the columns of the m×k matrix B. Vectors
+// x will be stored in-place into the n×k receiver.
+//
+// If A does not have full rank, a Condition error is returned. See the
+// documentation for Condition for more information.
 func (m *Dense) Solve(a, b Matrix) error {
 	ar, ac := a.Dims()
 	br, bc := b.Dims()
@@ -103,10 +114,23 @@ func (m *Dense) Solve(a, b Matrix) error {
 	}
 }
 
-// SolveVec finds a minimum-norm solution to a system of linear equations defined
+// SolveVec solves the linear least squares problem
-// by the matrix a and the right-hand side column vector b. If A is singular or
+//  minimize over x |b - A*x|_2
-// near-singular, a Condition error is returned. See the documentation for
+// where A is an m×n matrix A, b is a given m element vector and x is n element
-// Dense.Solve for more information.
+// solution vector. Solve assumes that A has full rank, that is
+//  rank(A) = min(m,n)
+//
+// If m >= n, Solve finds the unique least squares solution of an overdetermined
+// system.
+//
+// If m < n, there is an infinite number of solutions that satisfy b-A*x=0. In
+// this case Solve finds the unique solution of an underdetermined system that
+// minimizes |x|_2.
+//
+// The solution vector x will be stored in-place into the receiver.
+//
+// If A does not have full rank, a Condition error is returned. See the
+// documentation for Condition for more information.
 func (v *VecDense) SolveVec(a Matrix, b Vector) error {
 	if _, bc := b.Dims(); bc != 1 {
 		panic(ErrShape)