math::linearalgebra(n)

📦

version 2.0 · 2 versions

2.0 · fedora 43, fedora 44, nixos 26.05, nixpkgs unstable (latest)
1.21 · alpine 3.24, epel 9, opensuse-leap 16.0

, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

✨ NAME ✨

math::linearalgebra — Linear Algebra 💖 (from the Tcl Math Library)

okay bestie, welcome to math::linearalgebra(n) — it's giving main character energy for all your Tcl linear algebra needs. 🫶

📦 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

🌈 DESCRIPTION 🌈

okay so this package is literally your bestie for both low-level procedures and high-level algorithms when you're dealing with linear algebra problems:

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

It arose as a re-implementation of Hume's LA package and the desire to offer low-level procedures as found in the well-known BLAS library. Matrices are implemented as lists of lists rather than linear lists with reserved elements, as in the original LA package, as it was found that such an implementation is actually faster.

It is advisable, however, to use the procedures that are offered, such as setrow and getrow, rather than rely on this representation explicitly: that way it's possible to switch to a possibly even faster compiled implementation that supports the same API.

Note: When using this package in combination with Tk, there may be a naming conflict, as both this package and Tk define a command 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.
- integer ndim — Dimension of the vector (number of components)
- double value — 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.
- integer ndim — Dimension of the vector (number of components)
- integer ndir — 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.
- integer nrows — Number of rows
- integer ncols — Number of columns
- double value — 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.
- list matrix — Matrix in question
- integer row — Index of the row to return
- integer imin — Minimum index of the column (default: 0)
- integer imax — 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).
- list matrix — name of the matrix in question
- integer row — Index of the row to update
- list newvalues — List of new values for the row
- integer imin — Minimum index of the column (default: 0)
- integer imax — 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.
- list matrix — Matrix in question
- integer col — Index of the column to return
- integer imin — Minimum index of the row (default: 0)
- integer imax — 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).
- list matrix — name of the matrix in question
- integer col — Index of the column to update
- list newvalues — List of new values for the column
- integer imin — Minimum index of the row (default: 0)
- integer imax — Maximum index of the row (default: nrows-1)
::math::linearalgebra::getelem matrix row col — Returns a single element of a matrix/vector.
- list matrix — Matrix or vector in question
- integer row — Row of the element
- integer col — 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.
- list matrix — name of the matrix in question
- integer row — Row of the element
- integer col — 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.
- list matrix — name of the matrix in question
- integer irow1 — Index of first row
- integer irow2 — Index of second row
- integer imin — Minimum column index (default: 0)
- integer imin — Maximum column index (default: ncols-1)
::math::linearalgebra::swapcols matrix icol1 icol2 ?imin? ?imax? — Swap two columns in a matrix completely or only a selected part.
- list matrix — name of the matrix in question
- integer irow1 — Index of first column
- integer irow2 — Index of second column
- integer imin — Minimum row index (default: 0)
- integer imin — 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)
- list obj — Matrix or vector in question
- string format — Format for printing the numbers (default: %6.4f)
- string rowsep — String to use for separating rows (default: newline)
- string colsep — 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).
- any obj — 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).
- any obj — 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.
- string type — Type of check:
"shape" — the two objects are the same shape, and this matters for every element-wise operation, no exceptions bestie 🫶
"rows" — the two objects have the same number of rows, which is what you need when they're gonna be 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 — the first vector or matrix, aka the left operand 👑

list obj2 — the second vector or matrix, aka the right operand ✨

`::math::linearalgebra::symmetric`</p> matrix ?eps?

Checks whether the (square!) matrix you handed over is symmetric. The eps argument is your tolerance — how close is close enough, you know? 🙈

list matrix — the matrix that's getting inspected 🔍

float eps — the tolerance used to decide "yeah that counts as approximately equal" (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 — and those mean, respectively, the sum of absolute values, the ordinary Euclidean norm, or the max norm. Choose your fighter 💪

list vector — the vector, a 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 — that's the sum of absolute values, periodt ✨

list vector — the vector, a list of coefficients 🍓

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

Returns the L2 norm of the given vector — the ordinary Euclidean norm, the classic, the icon 👑

list vector — the vector, a list of coefficients 🍓

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

Returns the Linf norm of the given vector — the maximum absolute coefficient 🔥

list vector — the vector, a list of coefficients 🍓

integer index — optional! If it's non-zero, you get back a list made of the maximum value and the index where that maximum was found. If it's zero, you just get the maximum value. That's it, that's the deal 💅

`::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 — the matrix, a 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. Heads up: they must have the same shape, meaning the 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. Glow-up complete 🦋✨

list vector — the vector that's getting normalized 💫

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

Normalizes the matrix or vector in a statistical sense: after this, the mean of the elements of the columns of the result is zero, and the standard deviation is 1. Very demure, very normalized 💅

list mv — the vector or matrix getting normalized in the above sense 📊

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

Returns a vector or matrix that comes out of a "daxpy" operation — which 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 that result 🎀

Specialised variants exist too: axpy_vect and axpy_mat — slightly faster, but no check on the arguments. Speed over safety, iykyk 😌

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: 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: 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: 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. Here's the tea 🫖 — in algorithms you can often easily determine the cosine and sine of the angle anyway, so passing that info directly is just more efficient. Work smarter 💅

double c — the cosine of the angle 📐

double s — the sine of the angle 📐

list vect1 — first vector (x) 🍓

list vect2 — second vector (x) 🍓

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

Transposes a matrix. Flip it and reverse it 🔄

list matrix — the 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 both are vectors — in that second case the "outer product" gets computed. If one is a vector and the other is a matrix, then the result is a vector. Shape-shifting behavior honestly 🦋

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

Multiplies a vector/matrix with another vector/matrix. The result is a matrix if both x and y are matrices or both are vectors — in that 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) 🍓

🎀 Common matrices and test matrices 🎀

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

Creates an identity matrix of dimension size. The moment of "it's just ones on the diagonal bestie" 💅