math::linearalgebra(3tcl)

📦

version 2.0 · 2 versions

2.0 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
1.21 · debian bookworm, ubuntu jammy, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 `math::linearalgebra` — from the Tcl Math Library, section `3tcl` 💖

okay bestie, sit down, hydrate, and get ready, because this is math::linearalgebra(3tcl): the Tcl Math Library's linear algebra page, and she is so much more than she looks. 🎀

🌸 NAME 🌸

math::linearalgebra — Linear Algebra. That's the whole name, short and iconic, no notes. 💅

✨ SYNOPSIS ✨

package require Tcl ?8.5 9?
package require math::linearalgebra ?1.1.7?
::math::linearalgebra::mkVector ndim value
::math::linearalgebra::mkUnitVector ndim ndir
::math::linearalgebra::mkMatrix nrows ncols value
::math::linearalgebra::getrow matrix row ?imin? ?imax?
::math::linearalgebra::setrow matrix row newvalues ?imin? ?imax?
::math::linearalgebra::getcol matrix col ?imin? ?imax?
::math::linearalgebra::setcol matrix col newvalues ?imin? ?imax?
::math::linearalgebra::getelem matrix row col
::math::linearalgebra::setelem matrix row ?col? newvalue
::math::linearalgebra::swaprows matrix irow1 irow2 ?imin? ?imax?
::math::linearalgebra::swapcols matrix icol1 icol2 ?imin? ?imax?
::math::linearalgebra::show obj ?format? ?rowsep? ?colsep?
::math::linearalgebra::dim obj
::math::linearalgebra::shape obj
::math::linearalgebra::conforming type obj1 obj2
::math::linearalgebra::symmetric matrix ?eps?
::math::linearalgebra::norm vector type
::math::linearalgebra::norm_one vector
::math::linearalgebra::norm_two vector
::math::linearalgebra::norm_max vector ?index?
::math::linearalgebra::normMatrix matrix type
::math::linearalgebra::dotproduct vect1 vect2
::math::linearalgebra::unitLengthVector vector
::math::linearalgebra::normalizeStat mv
::math::linearalgebra::axpy scale mv1 mv2
::math::linearalgebra::add mv1 mv2
::math::linearalgebra::sub mv1 mv2
::math::linearalgebra::scale scale mv
::math::linearalgebra::rotate c s vect1 vect2
::math::linearalgebra::transpose matrix
::math::linearalgebra::matmul mv1 mv2
::math::linearalgebra::angle vect1 vect2
::math::linearalgebra::crossproduct vect1 vect2
::math::linearalgebra::matmul mv1 mv2
::math::linearalgebra::mkIdentity size
::math::linearalgebra::mkDiagonal diag
::math::linearalgebra::mkRandom size
::math::linearalgebra::mkTriangular size ?uplo? ?value?
::math::linearalgebra::mkHilbert size
::math::linearalgebra::mkDingdong size
::math::linearalgebra::mkOnes size
::math::linearalgebra::mkMoler size
::math::linearalgebra::mkFrank size
::math::linearalgebra::mkBorder size
::math::linearalgebra::mkWilkinsonW+ size
::math::linearalgebra::mkWilkinsonW- size
::math::linearalgebra::solveGauss matrix bvect
::math::linearalgebra::solvePGauss matrix bvect
::math::linearalgebra::solveTriangular matrix bvect ?uplo?
::math::linearalgebra::solveGaussBand matrix bvect
::math::linearalgebra::solveTriangularBand matrix bvect
::math::linearalgebra::determineSVD A eps
::math::linearalgebra::eigenvectorsSVD A eps
::math::linearalgebra::leastSquaresSVD A y qmin eps
::math::linearalgebra::choleski matrix
::math::linearalgebra::orthonormalizeColumns matrix
::math::linearalgebra::orthonormalizeRows matrix
::math::linearalgebra::dger matrix alpha x y ?scope?
::math::linearalgebra::dgetrf matrix
::math::linearalgebra::det matrix
::math::linearalgebra::largesteigen matrix tolerance maxiter
::math::linearalgebra::to_LA mv
::math::linearalgebra::from_LA mv

(yes, matmul is in there twice. she said it twice because it matters. periodt. 💜)

🦋 DESCRIPTION 🦋

This package hands you both the low-level procedures and the high-level algorithms for doing linear algebra, like a bestie who can do your nails AND debug your recursion. 🫶

What you get, specifically:

robust solution of linear equations or least squares problems
determining eigenvectors and eigenvalues of symmetric matrices
various decompositions of general matrices or matrices of a specific form
(limited) support for matrices in band storage, a common type of sparse matrices

Where did she come from? She arose as a re-implementation of Hume's LA package, plus the desire to offer low-level procedures as found in the well-known BLAS library. So like, she's a glow-up of an older icon. ✨

Here's the tea on the data structure: matrices are implemented as lists of lists, rather than linear lists with reserved elements like in the original LA package — because it was found that this implementation is actually faster. ate and left no crumbs. 🔥

That said, it is advisable to use the procedures that are offered, such as setrow and getrow, rather than rely on this representation explicitly. That way it is possible to switch to a possibly even faster compiled implementation that supports the same API. so like, use the front door, not the window, bestie. 🪟

Note: when you use this package together with Tk, there may be a naming conflict, because both this package and Tk define a command called scale. See the NAMING CONFLICT section below. 👀

🔥 PROCEDURES 🔥

The package defines the following public procedures (several exist as specialised procedures, see below):

🌈 Constructing matrices and vectors

`::math::linearalgebra::mkVector ndim value`

Create a vector with ndim elements, each with the value value. uniform queen energy. 👑

ndim (integer) — Dimension of the vector (number of components)
value (double) — Uniform value to be used (default: 0.0)

`::math::linearalgebra::mkUnitVector ndim ndir`

Create a unit vector in ndim-dimensional space, along the ndir-th direction. one single direction, zero distractions. 🧚

ndim (integer) — Dimension of the vector (number of components)
ndir (integer) — Direction (0, ..., ndim-1)

`::math::linearalgebra::mkMatrix nrows ncols value`

Create a matrix with nrows rows and ncols columns. All elements have the value value. every single cell, matching, coordinated. 🎀

nrows (integer) — Number of rows
ncols (integer) — Number of columns
value (double) — Uniform value to be used (default: 0.0)

`::math::linearalgebra::getrow matrix row ?imin? ?imax?`

Returns a single row of a matrix as a list. grab one row, no drama. 🌸

matrix (list) — Matrix in question
row (integer) — Index of the row to return
imin (integer) — Minimum index of the column (default: 0)
imax (integer) — Maximum index of the column (default: ncols-1)

`::math::linearalgebra::setrow matrix row newvalues ?imin? ?imax?`

Set a single row of a matrix to new values (this list must have the same number of elements as the number of columns in the matrix). like, the math has to math. 📐

matrix (list) — name of the matrix in question
row (integer) — Index of the row to update
newvalues (list) — List of new values for the row
imin (integer) — Minimum index of the column (default: 0)
imax (integer) — Maximum index of the column (default: ncols-1)

`::math::linearalgebra::getcol matrix col ?imin? ?imax?`

Returns a single column of a matrix as a list. vertical girlie behavior. 💅

matrix (list) — Matrix in question
col (integer) — Index of the column to return
imin (integer) — Minimum index of the row (default: 0)
imax (integer) — Maximum index of the row (default: nrows-1)

`::math::linearalgebra::setcol matrix col newvalues ?imin? ?imax?`

Set a single column of a matrix to new values (this list must have the same number of elements as the number of rows in the matrix). again: the count has to line up or it's a no. 😭

matrix (list) — name of the matrix in question
col (integer) — Index of the column to update
newvalues (list) — List of new values for the column
imin (integer) — Minimum index of the row (default: 0)
imax (integer) — Maximum index of the row (default: nrows-1)

`::math::linearalgebra::getelem matrix row col`

Returns a single element of a matrix/vector. just one lil guy. 🍓

matrix (list) — Matrix or vector in question
row (integer) — Row of the element
col (integer) — Column of the element (not present for vectors)

`::math::linearalgebra::setelem matrix row ?col? newvalue`

Set a single element of a matrix (or vector) to a new value. one element, one glow-up. ⭐

matrix (list) — name of the matrix in question
row (integer) — Row of the element
col (integer) — Column of the element (not present for vectors)

`::math::linearalgebra::swaprows matrix irow1 irow2 ?imin? ?imax?`

Swap two rows in a matrix completely or only a selected part. trading places, but make it linear algebra. 🔄

matrix (list) — name of the matrix in question
irow1 (integer) — Index of first row
irow2 (integer) — Index of second row
imin (integer) — Minimum column index (default: 0)
imin (integer) — Maximum column index (default: ncols-1)

bestie, the page literally lists imin twice here — second one is the max one, that's just how it's written. iykyk. 🙈

`::math::linearalgebra::swapcols matrix icol1 icol2 ?imin? ?imax?`

Swap two columns in a matrix completely or only a selected part. same energy, rotated 90 degrees. 🌈

matrix (list) — name of the matrix in question
irow1 (integer) — Index of first column
irow2 (integer) — Index of second column
imin (integer) — Minimum row index (default: 0)
imin (integer) — Maximum row index (default: nrows-1)

🔍 Querying matrices and vectors

`::math::linearalgebra::show obj ?format? ?rowsep? ?colsep?`

Return a string representing the vector or matrix, for easy printing. (There is currently no way to print fixed sets of columns) — so like, no, you can't pick just a few columns to show off. 🙈

obj (list) — Matrix or vector in question
format (string) — Format for printing the numbers (default: %6.4f)
rowsep (string) — String to use for separating rows (default: newline)
colsep (string) — String to use for separating columns (default: space)

`::math::linearalgebra::dim obj`

Returns the number of dimensions for the object (either 0 for a scalar, 1 for a vector and 2 for a matrix). vibe check, but for shapes. 💫

obj (any) — Scalar, vector, or matrix

`::math::linearalgebra::shape obj`

Returns the number of elements in each dimension for the object (either an empty list for a scalar, a single number for a vector and a list of the number of rows and columns for a matrix). she tells you how much of each thing there is. 📏

obj (any) — Scalar, vector, or matrix

`::math::linearalgebra::conforming type obj1 obj2`

Checks if two objects (vector or matrix) have conforming shapes, that is if they can be applied in an operation like addition or matrix multiplication. basically asking "do these two even go together?" 💞

type (string) — Type of check:

and that's where this chunk ends, bestie — the list of check types rolls in with the next part. stay tuned 🫶

"shape" — the two objects have the same shape (this is the one that matters for all the element-wise operations) ✨
"rows" — the two objects have the same number of rows (this is what you need when they're playing A and b in a system of linear equations Ax = b)
"matmul" — the first object has the same number of columns as the second object has rows. This is the vibe check for matrix-matrix or matrix-vector multiplication 🔥
list obj1 — first vector or matrix (the left operand, main character)
list obj2 — second vector or matrix (the right operand)

`::math::linearalgebra::symmetric` matrix ?eps?

Checks if the given (square) matrix is symmetric. The argument eps is the tolerance. 💅

list matrix — matrix to be inspected
float eps — tolerance for determining approximate equality (defaults to 1.0e-8)

✨ Basic operations ✨

`::math::linearalgebra::norm` vector type

Returns the norm of the given vector. The type argument can be: 1, 2, inf or max — respectively the sum of absolute values, the ordinary Euclidean norm, or the max norm. 🌸

list vector — vector, list of coefficients
string type — type of norm (default: 2, the Euclidean norm)

`::math::linearalgebra::norm_one` vector

Returns the L1 norm of the given vector, the sum of absolute values. ✨

list vector — vector, list of coefficients

`::math::linearalgebra::norm_two` vector

Returns the L2 norm of the given vector, the ordinary Euclidean norm. 💖

list vector — vector, list of coefficients

`::math::linearalgebra::norm_max` vector ?index?

Returns the Linf norm of the given vector, the maximum absolute coefficient. 👑

list vector — vector, list of coefficients
integer index — (optional) if non zero, returns a list made of the maximum value and the index where that maximum was found. If zero, returns the maximum value.

`::math::linearalgebra::normMatrix` matrix type

Returns the norm of the given matrix. The type argument can be: 1, 2, inf or max — respectively the sum of absolute values, the ordinary Euclidean norm, or the max norm. 🌈

list matrix — matrix, list of row vectors
string type — type of norm (default: 2, the Euclidean norm)

`::math::linearalgebra::dotproduct` vect1 vect2

Determines the inproduct, aka the dot product, of two vectors. These two besties must have the same shape (same number of dimensions). 🫶

list vect1 — first vector, list of coefficients
list vect2 — second vector, list of coefficients

`::math::linearalgebra::unitLengthVector` vector

Returns a vector pointing in the same direction, but with length 1. ✨

list vector — vector to be normalized

`::math::linearalgebra::normalizeStat` mv

Normalizes the matrix or vector in a statistical sense: the mean of the elements of the columns of the result is zero, and the standard deviation is 1. No cap. 📊

list mv — vector or matrix to be normalized in the above sense

`::math::linearalgebra::axpy` scale mv1 mv2

Returns a vector or matrix that results from a "daxpy" operation — that is: compute a*x+y (where a is a scalar and x and y are both vectors or matrices of the same shape) and return the result. 🎀

Specialised variants are: axpy_vect and axpy_mat (slightly faster, but no check on the arguments).

double scale — the scale factor for the first vector/matrix (a)
list mv1 — first vector or matrix (x)
list mv2 — second vector or matrix (y)

`::math::linearalgebra::add` mv1 mv2

Returns a vector or matrix that is the sum of the two arguments (x+y). 💖

Specialised variants are: add_vect and add_mat (slightly faster, but no check on the arguments).

list mv1 — first vector or matrix (x)
list mv2 — second vector or matrix (y)

`::math::linearalgebra::sub` mv1 mv2

Returns a vector or matrix that is the difference of the two arguments (x-y). 🦋

Specialised variants are: sub_vect and sub_mat (slightly faster, but no check on the arguments).

list mv1 — first vector or matrix (x)
list mv2 — second vector or matrix (y)

`::math::linearalgebra::scale` scale mv

Scales a vector or matrix and returns the result — that is: compute a*x. ✨

Specialised variants are: scale_vect and scale_mat (slightly faster, but no check on the arguments).

double scale — the scale factor for the vector/matrix (a)
list mv — vector or matrix (x)

`::math::linearalgebra::rotate` c s vect1 vect2

Applies a planar rotation to two vectors and returns the result as a list of two vectors: c*x-s*y and s*x+c*y. In algorithms you can often figure out the cosine and sine of the angle super easily, so it's more efficient to just pass that information straight in. 💫

double c — the cosine of the angle
double s — the sine of the angle
list vect1 — first vector (x)
list vect2 — second vector (the original labels this one x too, and honestly? we respect the chaos 💀)

`::math::linearalgebra::transpose` matrix

Transposes a matrix. Flip it and reverse it. 🔄

list matrix — matrix to be transposed

`::math::linearalgebra::matmul` mv1 mv2

Multiplies a vector/matrix with another vector/matrix. The result is a matrix if both x and y are matrices, or if both are vectors — in which case the "outer product" is computed. If one is a vector and the other is a matrix, then the result is a vector. 🔥

list mv1 — first vector/matrix (x)
list mv2 — second vector/matrix (y)

`::math::linearalgebra::angle` vect1 vect2

Computes the angle between two vectors (in radians). 📐

list vect1 — first vector
list vect2 — second vector

`::math::linearalgebra::crossproduct` vect1 vect2

Computes the cross product of two (three-dimensional) vectors. 🌈

list vect1 — first vector
list vect2 — second vector

`::math::linearalgebra::matmul` mv1 mv2

list mv1 — first vector/matrix (x)
list mv2 — second vector/matrix (y)

Not me noticing matmul shows up twice on this page. Bestie, that's just how the page is built — we're keeping it, no notes 💅

🎀 Common matrices and test matrices 🎀

`::math::linearalgebra::mkIdentity` size

Creates an identity matrix of dimension size. 👑

integer size — dimension of the matrix

`::math::linearalgebra::mkDiagonal` diag

Creates a diagonal matrix whose diagonal elements are the elements of the vector diag. ✨

list diag — vector whose elements are used for the diagonal

`::math::linearalgebra::mkRandom` size

Creates a square matrix of dimension size whose elements are uniformly distributed random numbers between 0 and 1. 🎲

integer size — dimension of the matrix

`::math::linearalgebra::mkTriangular` size ?uplo? ?value?

Creates a triangular matrix with non-zero elements in the upper or lower part, depending on the argument uplo. 🔺

integer size — dimension of the matrix
string uplo — fill the upper (U) or lower part (L)
double value — value to fill the matrix with

`::math::linearalgebra::mkHilbert` size

Creates a Hilbert matrix of dimension size. Hilbert matrices are very ill-conditioned with respect to eigenvalue/eigenvector problems. Which is exactly why they're such good candidates for testing the accuracy of algorithms and implementations. 💅

integer size — dimension of the matrix

`::math::linearalgebra::mkDingdong` size

Creates a "dingdong" matrix of dimension size. Dingdong matrices are imprecisely represented, but they have the property of being very stable in such algorithms as Gauss elimination. 🔔

integer size — dimension of the matrix

`::math::linearalgebra::mkOnes` size

Creates a square matrix of dimension size whose entries are all 1. 1️⃣

integer size — dimension of the matrix

`::math::linearalgebra::mkMoler` size

Creates a Moler matrix of size size. (Moler matrices have a very simple Choleski decomposition. They have one small eigenvalue, and they can easily upset elimination methods for systems of linear equations.) 😭

integer size — dimension of the matrix

`::math::linearalgebra::mkFrank` size

Creates a Frank matrix of size size. (Frank matrices are fairly well-behaved matrices.) 🫶

integer size — dimension of the matrix

`::math::linearalgebra::mkBorder` size

Creates a bordered matrix of size size. (Bordered matrices have a very low rank and can upset certain specialised algorithms.) ⚠️

integer size — dimension of the matrix

`::math::linearalgebra::mkWilkinsonW+` size

Creates a Wilkinson W+ of size size. This kind of matrix has pairs of eigenvalues that are very close together. Usually the order (size) is odd. ✨

integer size — dimension of the matrix

`::math::linearalgebra::mkWilkinsonW-` size

Creates a Wilkinson W- of size size. This kind of matrix has pairs of eigenvalues with opposite signs, when the order (size) is odd. ✨

integer size — dimension of the matrix

🧚 Common algorithms 🧚

`::math::linearalgebra::solveGauss` matrix bvect

Solves a system of linear equations (Ax=b) using Gauss elimination. Returns the solution (x) as a vector or matrix of the same shape as bvect. 🔥

list matrix — square matrix (matrix A)

`::math::linearalgebra::solvePGauss matrix bvect`

Solves a system of linear equations (Ax=b) using Gauss elimination with partial pivoting, bestie. Returns the solution (x) as a vector or matrix shaped just like bvect. 💅

list matrix — the square matrix (that's your matrix A, queen)
list bvect — vector or matrix whose columns are the individual b-vectors

`::math::linearalgebra::solveTriangular matrix bvect ?uplo?`

Solves a system of linear equations (Ax=b) by backward substitution. The matrix is supposed to be upper-triangular — that's the whole vibe it's running on. ✨

list matrix — lower or upper-triangular matrix (matrix A)
list bvect — vector or matrix whose columns are the individual b-vectors
string uplo — tells us whether the matrix is lower-triangular (L) or upper-triangular (U). Defaults to "U".

`::math::linearalgebra::solveGaussBand matrix bvect`

Solves a system of linear equations (Ax=b) using Gauss elimination, where the matrix is stored as a band matrix (peep the STORAGE section, it's giving very much sparse-matrix energy). Returns the solution (x) as a vector or matrix of the same shape as bvect. 🔥

list matrix — square matrix (matrix A; in band form)
list bvect — vector or matrix whose columns are the individual b-vectors

`::math::linearalgebra::solveTriangularBand matrix bvect`

Solves a system of linear equations (Ax=b) by backward substitution. The matrix is supposed to be upper-triangular and stored in band form. Two conditions, no cap. 🫶

list matrix — upper-triangular matrix (matrix A)
list bvect — vector or matrix whose columns are the individual b-vectors

`::math::linearalgebra::determineSVD A eps`

Determines the Singular Value Decomposition of a matrix: A = U S Vtrans. Returns a list with the matrix U, the vector of singular values S and the matrix V. Iconic, honestly. 👑

list A — matrix to be decomposed
float eps — tolerance (defaults to 2.3e-16)

`::math::linearalgebra::eigenvectorsSVD A eps`

Determines the eigenvectors and eigenvalues of a real symmetric matrix, using SVD. Returns a list with the matrix of normalized eigenvectors and their eigenvalues. ✨

list A — matrix whose eigenvalues must be determined
float eps — tolerance (defaults to 2.3e-16)

`::math::linearalgebra::leastSquaresSVD A y qmin eps`

Determines the solution to a least-sqaures problem Ax ~ y via singular value decomposition. The result is the vector x. 📐

Heads up bestie: if you add a column of 1s to the matrix, then this column will represent a constant like in: y = a*x1 + b*x2 + c. To force the intercept to be zero, simply leave it out.

list A — matrix of independent variables
list y — list of observed values
float qmin — minimum singular value to be considered (defaults to 0.0)
float eps — tolerance (defaults to 2.3e-16)

`::math::linearalgebra::choleski matrix`

Determine the Choleski decomposition of a symmetric positive semidefinite matrix — and yes, that condition is not checked, so that's on you, not on the procedure 💀. The result is the lower-triangular matrix L such that L Lt = matrix.

list matrix — matrix to be decomposed

`::math::linearalgebra::orthonormalizeColumns matrix`

Uses the modified Gram-Schmidt method to orthogonalize and normalize the columns of the given matrix and return the result. Giving very much "perpendicular and pretty". 🌸

list matrix — matrix whose columns must be orthonormalized

`::math::linearalgebra::orthonormalizeRows matrix`

Uses the modified Gram-Schmidt method to orthogonalize and normalize the rows of the given matrix and return the result.

list matrix — matrix whose rows must be orthonormalized

`::math::linearalgebra::dger matrix alpha x y ?scope?`

Performs the rank 1 operation A + alpha*x*y' inline — that means the matrix A itself gets adjusted, fr fr. For convenience the new matrix is also returned as the result. 🔥

list matrix — matrix whose rows must be adjusted
double alpha — scale factor
list x — a column vector
list y — a column vector
list scope — if not provided, the operation is performed on all rows/columns of A. If provided, it is expected to be the list {imin imax jmin jmax} where:
- imin — minimum row index
- imax — maximum row index
- jmin — minimum column index
- jmax — maximum column index

`::math::linearalgebra::dgetrf matrix`

Computes an LU factorization of a general matrix, using partial pivoting with row interchanges. Returns the permutation vector. 😤

The factorization has the form

P * A = L * U

where P is a permutation matrix, L is lower triangular with unit diagonal elements, and U is upper triangular. Returns the permutation vector, as a list of length n-1. The last entry of the permutation is not stored, since it is implicitely known, with value n (the last row is not swapped with any other row). At index #i of the permutation is stored the index of the row #j which is swapped with row #i at step #i. That means that each index of the permutation gives the permutation at each step, not the cumulated permutation matrix, which is the product of permutations. 🧠

list matrix — on entry, the matrix to be factored. On exit, the factors L and U from the factorization P*A = L*U; the unit diagonal elements of L are not stored.

`::math::linearalgebra::det matrix`

Returns the determinant of the given matrix, based on PA=LU decomposition, i.e. Gauss partial pivotal. 🎀

list matrix — square matrix (matrix A)
list ipiv — the pivots (optionnal). If the pivots are not provided, a PA=LU decomposition is performed. If the pivots are provided, we assume that it contains the pivots and that the matrix A contains the L and U factors, as provided by dgterf. b-vectors

`::math::linearalgebra::largesteigen matrix tolerance maxiter`

Returns a list made of the largest eigenvalue (in magnitude) and its associated eigenvector. Uses the iterative Power Method as provided as algorithm #7.3.3 of Golub & Van Loan. This algorithm is used here for a dense matrix (but is usually used for sparse matrices). 👑

list matrix — square matrix (matrix A)
double tolerance — the relative tolerance of the eigenvalue (default: 1.e-8).
integer maxiter — the maximum number of iterations (default: 10).

Compability with the LA package

Two procedures are provided for compatibility with Hume's LA package: 💖

`::math::linearalgebra::to_LA mv`

Transforms a vector or matrix into the format used by the original LA package.

list mv — matrix or vector

`::math::linearalgebra::from_LA mv`

Transforms a vector or matrix from the format used by the original LA package into the format used by the present implementation.

list mv — matrix or vector as used by the LA package

STORAGE

While most procedures assume that the matrices are given in full form, the procedures solveGaussBand and solveTriangularBand assume that the matrices are stored as band matrices. This common type of "sparse" matrix is related to ordinary matrices as follows: 🦋

"A" is a full-size matrix with N rows and M columns.
"B" is a band matrix, with m upper and lower diagonals and n rows.
"B" can be stored in an ordinary matrix of (2m+1) columns (one for each off-diagonal and the main diagonal) and n rows.
Element i,j (i = -m,...,m; j =1,...,n) of "B" corresponds to element k,j of "A" where k = M+i-1 and M is at least (!) n, the number of rows in "B".
To set element (i,j) of matrix "B" use:

setelem B $j [expr {$N+$i-1}] $value

(There is no convenience procedure for this yet) 🙈

REMARKS ON THE IMPLEMENTATION

There is a difference between the original LA package by Hume and the current implementation. Whereas the LA package uses a linear list, the current package uses lists of lists to represent matrices. It turns out that with this representation, the algorithms are faster and easier to implement. ✨

The LA package was used as a model and in fact the implementation of, for instance, the SVD algorithm was taken from that package. The set of procedures was expanded using ideas from the well-known BLAS library and some algorithms were updated from the second edition of J.C. Nash's book, Compact Numerical Methods for Computers, (Adam Hilger, 1990) that inspired the LA package. 📚

Two procedures are provided to make the transition between the two implementations easier: to_LA and from_LA. They are described above. 🫶

TODO

Odds and ends: the following algorithms have not been implemented yet: 💀

determineQR
certainlyPositive, diagonallyDominant

NAMING CONFLICT

If you load this package in a Tk-enabled shell like wish, then the command

namespace import ::math::linearalgebra

results in an error message about "scale". This is due to the fact that Tk defines all its commands in the global namespace. The solution is to import the linear algebra commands in a namespace that is not the global one: 🧚

package require math::linearalgebra
namespace eval compute {
    namespace import ::math::linearalgebra::*
    ... use the linear algebra version of scale ...
}

To use Tk's scale command in that same namespace you can rename it:

namespace eval compute {
    rename ::scale scaleTk
    scaleTk .scale ...
}

🐛 BUGS, IDEAS, FEEDBACK 🫶

okay bestie, real talk: this document and the package it describes will undoubtedly contain bugs and other problems. like, for sure for sure, no cap. nobody's perfect and neither is this manpage 💀

so if you spot something cursed, please report it! 🙏 drop it in the category math :: linearalgebra of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. and while you're there — if you have any ideas for enhancements for either the package and/or the documentation, please also report those. bestie we want your ideas, they're giving main character energy 👑

💅 when you're proposing code changes

okay so when you propose code changes, please provide unified diffs, i.e. the output of:

diff -u

⚠️ also note that attachments are strongly preferred over inlined patches. like, strongly. the way that inline patches get mangled is not it 😭

to make an attachment: go to the Edit form of the ticket immediately after its creation, and then use the left-most button in the secondary navigation bar. that's the vibe, that's the move, periodt ✨

🔑 KEYWORDS 🌈

least squares
linear algebra
linear equations
math
matrices
matrix
vectors

🎀 CATEGORY 💖

Mathematics

©️ COPYRIGHT 👑

and that's the whole page bestie, we made it to the end 🥹💜 this was tcllib version 1.1.7, the math::linearalgebra(3tcl) manual page — go forth and multiply your matrices responsibly, ily, bye 🦋🌸

📦 where this page comes from

debian trixie: tcllib 2.0+dfsg-4 · Tcl
ubuntu questing: tcllib 2.0+dfsg-4
ubuntu resolute: tcllib 2.0+dfsg-5 · Tcl
ubuntu stonking: tcllib 2.0+dfsg-6 · Tcl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

math::linearalgebra(3tcl)

💖 math::linearalgebra — from the Tcl Math Library, section 3tcl 💖

🌸 NAME 🌸

✨ SYNOPSIS ✨

🦋 DESCRIPTION 🦋

🔥 PROCEDURES 🔥

🌈 Constructing matrices and vectors

::math::linearalgebra::mkVector ndim value

::math::linearalgebra::mkUnitVector ndim ndir

::math::linearalgebra::mkMatrix nrows ncols value

::math::linearalgebra::getrow matrix row ?imin? ?imax?

::math::linearalgebra::setrow matrix row newvalues ?imin? ?imax?

::math::linearalgebra::getcol matrix col ?imin? ?imax?

::math::linearalgebra::setcol matrix col newvalues ?imin? ?imax?

::math::linearalgebra::getelem matrix row col

::math::linearalgebra::setelem matrix row ?col? newvalue

::math::linearalgebra::swaprows matrix irow1 irow2 ?imin? ?imax?

::math::linearalgebra::swapcols matrix icol1 icol2 ?imin? ?imax?

🔍 Querying matrices and vectors

::math::linearalgebra::show obj ?format? ?rowsep? ?colsep?

::math::linearalgebra::dim obj

::math::linearalgebra::shape obj

::math::linearalgebra::conforming type obj1 obj2

::math::linearalgebra::symmetric matrix ?eps?

✨ Basic operations ✨

::math::linearalgebra::norm vector type

::math::linearalgebra::norm_one vector

::math::linearalgebra::norm_two vector

::math::linearalgebra::norm_max vector ?index?

::math::linearalgebra::normMatrix matrix type

::math::linearalgebra::dotproduct vect1 vect2

::math::linearalgebra::unitLengthVector vector

::math::linearalgebra::normalizeStat mv

::math::linearalgebra::axpy scale mv1 mv2

::math::linearalgebra::add mv1 mv2

::math::linearalgebra::sub mv1 mv2

::math::linearalgebra::scale scale mv

::math::linearalgebra::rotate c s vect1 vect2

::math::linearalgebra::transpose matrix

::math::linearalgebra::matmul mv1 mv2

::math::linearalgebra::angle vect1 vect2

::math::linearalgebra::crossproduct vect1 vect2

::math::linearalgebra::matmul mv1 mv2

🎀 Common matrices and test matrices 🎀

::math::linearalgebra::mkIdentity size

::math::linearalgebra::mkDiagonal diag

::math::linearalgebra::mkRandom size

::math::linearalgebra::mkTriangular size ?uplo? ?value?

::math::linearalgebra::mkHilbert size

::math::linearalgebra::mkDingdong size

::math::linearalgebra::mkOnes size

::math::linearalgebra::mkMoler size

::math::linearalgebra::mkFrank size

::math::linearalgebra::mkBorder size

::math::linearalgebra::mkWilkinsonW+ size

::math::linearalgebra::mkWilkinsonW- size

🧚 Common algorithms 🧚

::math::linearalgebra::solveGauss matrix bvect

::math::linearalgebra::solvePGauss matrix bvect

::math::linearalgebra::solveTriangular matrix bvect ?uplo?

::math::linearalgebra::solveGaussBand matrix bvect

::math::linearalgebra::solveTriangularBand matrix bvect

::math::linearalgebra::determineSVD A eps

::math::linearalgebra::eigenvectorsSVD A eps

::math::linearalgebra::leastSquaresSVD A y qmin eps

::math::linearalgebra::choleski matrix

::math::linearalgebra::orthonormalizeColumns matrix

::math::linearalgebra::orthonormalizeRows matrix

::math::linearalgebra::dger matrix alpha x y ?scope?

::math::linearalgebra::dgetrf matrix

::math::linearalgebra::det matrix

::math::linearalgebra::largesteigen matrix tolerance maxiter

Compability with the LA package

::math::linearalgebra::to_LA mv

::math::linearalgebra::from_LA mv

STORAGE

REMARKS ON THE IMPLEMENTATION

TODO

NAMING CONFLICT

🐛 BUGS, IDEAS, FEEDBACK 🫶

💖 `math::linearalgebra` — from the Tcl Math Library, section `3tcl` 💖

`::math::linearalgebra::mkVector ndim value`

`::math::linearalgebra::mkUnitVector ndim ndir`

`::math::linearalgebra::mkMatrix nrows ncols value`

`::math::linearalgebra::getrow matrix row ?imin? ?imax?`

`::math::linearalgebra::setrow matrix row newvalues ?imin? ?imax?`

`::math::linearalgebra::getcol matrix col ?imin? ?imax?`

`::math::linearalgebra::setcol matrix col newvalues ?imin? ?imax?`

`::math::linearalgebra::getelem matrix row col`

`::math::linearalgebra::setelem matrix row ?col? newvalue`

`::math::linearalgebra::swaprows matrix irow1 irow2 ?imin? ?imax?`

`::math::linearalgebra::swapcols matrix icol1 icol2 ?imin? ?imax?`

`::math::linearalgebra::show obj ?format? ?rowsep? ?colsep?`

`::math::linearalgebra::dim obj`

`::math::linearalgebra::shape obj`

`::math::linearalgebra::conforming type obj1 obj2`

`::math::linearalgebra::symmetric` matrix ?eps?

`::math::linearalgebra::norm` vector type

`::math::linearalgebra::norm_one` vector

`::math::linearalgebra::norm_two` vector

`::math::linearalgebra::norm_max` vector ?index?

`::math::linearalgebra::normMatrix` matrix type

`::math::linearalgebra::dotproduct` vect1 vect2

`::math::linearalgebra::unitLengthVector` vector

`::math::linearalgebra::normalizeStat` mv

`::math::linearalgebra::axpy` scale mv1 mv2

`::math::linearalgebra::add` mv1 mv2

`::math::linearalgebra::sub` mv1 mv2

`::math::linearalgebra::scale` scale mv

`::math::linearalgebra::rotate` c s vect1 vect2

`::math::linearalgebra::transpose` matrix

`::math::linearalgebra::matmul` mv1 mv2

`::math::linearalgebra::angle` vect1 vect2

`::math::linearalgebra::crossproduct` vect1 vect2

`::math::linearalgebra::matmul` mv1 mv2

`::math::linearalgebra::mkIdentity` size

`::math::linearalgebra::mkDiagonal` diag

`::math::linearalgebra::mkRandom` size

`::math::linearalgebra::mkTriangular` size ?uplo? ?value?

`::math::linearalgebra::mkHilbert` size

`::math::linearalgebra::mkDingdong` size

`::math::linearalgebra::mkOnes` size

`::math::linearalgebra::mkMoler` size

`::math::linearalgebra::mkFrank` size

`::math::linearalgebra::mkBorder` size

`::math::linearalgebra::mkWilkinsonW+` size

`::math::linearalgebra::mkWilkinsonW-` size

`::math::linearalgebra::solveGauss` matrix bvect

`::math::linearalgebra::solvePGauss matrix bvect`

`::math::linearalgebra::solveTriangular matrix bvect ?uplo?`

`::math::linearalgebra::solveGaussBand matrix bvect`

`::math::linearalgebra::solveTriangularBand matrix bvect`

`::math::linearalgebra::determineSVD A eps`

`::math::linearalgebra::eigenvectorsSVD A eps`

`::math::linearalgebra::leastSquaresSVD A y qmin eps`

`::math::linearalgebra::choleski matrix`

`::math::linearalgebra::orthonormalizeColumns matrix`

`::math::linearalgebra::orthonormalizeRows matrix`

`::math::linearalgebra::dger matrix alpha x y ?scope?`

`::math::linearalgebra::dgetrf matrix`

`::math::linearalgebra::det matrix`

`::math::linearalgebra::largesteigen matrix tolerance maxiter`

`::math::linearalgebra::to_LA mv`

`::math::linearalgebra::from_LA mv`