matrix

Syntax

Declare a matrix using square brackets [].

Use semicolons ; or newlines to separate rows.

Use commas , or spaces to separate columns.

[1,2,3]   -- A row vector (1x3)
[1 2 3]   -- The same row vector

[1;2;3]   -- A column vector (3x1)
[1        
 2
 3]       -- The same column vector

[1,2;3,4] -- A matrix (2x2)
[1 2
 3 4]     -- The same matrix
[1 + 2; 3 + 4] -- Elements can be expressions

By default, all matrices are rank 2, meaning they have rows and columns. Elementes are indexed in a [row, column] format.

When parsed and formatted, they look like this:

Fancy Syntax

The Mech REPL formats matrix output using fancy box drawing characters for better readability.

┏           ┓
┃ 1   2   3 ┃
┃ 4   5   6 ┃
┃ 7   8   9 ┃
┗           ┛

Mech can parse data formatted this way, allowing you to copy or pipe REPL output directly into a Mech program that expects a matrix. The above example evaluates to:

Kind

The kind of a matrix is determined by its dimensions and the kind of its elements. For example, a matrix of u8 values with 2 rows and 3 columns has the kind:

<[u8]:2,3>

A general matrix can be represented as:

<[T]>

A dynamic dimension is noted with an underscore _, such as:

<[T]:_,3>--
 A dynamic matrix with 3 columns<[T]:2,_>--
 A dynamic matrix with 2 rows<[T]:_,_>--
 A dynamic matrix in 2 dimensions

Row vectors and column vectors are special cases of matrices:

<[T]:3>--
 A row vector with 3 elements<[T]:3,1>--
 A column vector with 3 elements<[T]:_>--
 A dynamic row vector with an unspecified number of elements<[T]:_,1>--
 A dynamic column vector with an unspecified number of elements

Convert

You can convert a matrix to another kind using a kind annotation. For example:

You can also convert a vector of numbers into a vector of strings:

Reshape

You can reshape a matrix to a different size as long as the total number of elements remains the same. For example, you can reshape a 2x3 matrix into a 3x2 matrix:

This will also convert the matrix elements to u8 from f64.

Construction

Matrices can be constructed in several ways:

• Matrix literals

• From concatenation of existing matrices or vectors

• From ranges

• From comprehensions

• From tables

• From sets

Matrix Literals

Matrix literals are written using square brackets [], with rows separated by semicolons ; or newlines, and columns separated by commas , or spaces.

From Concatenation

You can construct new matricies from existing ones using concatenation.

Vertical concatenation is done bay stacking rows on top of each other, referencing another matrix or vector within the brackets.

Horizontal concatenation is done by placing matrices or vectors side by side, referencing another matrix or vector within the brackets.

See section §7 for more details on concatenation.

From Ranges

You can create a matrix from a range of numbers. By default, ranges produce column vectors.

From Comprehensions

Matrices can also be constructed with matrix comprehensions. A matrix comprehension uses square brackets and has the form \ [\ expression \ | \ qualifiers\ ]\ .

Qualifiers may include:

• one or more generators (<-)

• let bindings (:=)

• boolean filters

For example, this comprehension squares the even elements of a row vector and returns them as a row vector:

You can also generate from a named matrix value:

Matrix comprehensions use the same qualifier style as set comprehensions, but they produce matrix values instead of sets.

From Tables

You can create a matrix from a table using a kind annotation, as long as the kinds are compatible. For example, if you have a table with columns of kind f64, you can create a matrix of kind f64:

From Sets

You can create a matrix from a set using a kind annotation, as long as the kinds are compatible. For example, if you have a set of f64 values, you can create a matrix of kind f64:

s := {1.1, 2.2, 3.3, 4.4}
m<[f64]:2,2> := s

Accessing Elements

Matrix elements can be accessed using indexing, which is done with square brackets [] and a comma-separated list of indices.

Indexing starts at 1, not 0, so the first element is accessed with 1.

Indexing

For a 1D vector, you can access elements using a single index:

Indexing into a column vector is similar:

For a 2D matrix, you can access elements using two indices, in a [row, column] format:

The first index is the row, and the second index is the column. It's possible to use a single index to access matrix elements, which will return the element at that index in a column-major order. For example, considering the matrix above:

Slicing

Slicing allows you to access multiple elements at once, either entire rows or columns, or specific ranges of rows and columns.

The : operator can be used to access entire rows or columns:

You can slice it in various ways. For a matrix x with N rows and M columns, the following indexing operations are valid:

Examples

Given the matrix:

Slice the entire matrix:

Slice the first row:

Slice the second colum:

Slice the first two rows:

Slice rows 1 and 3:

Slice the corners:

Slice the first rows multiple times:

Logical Indexing

Logical indexing allows you to select elements based on a condition. For example, if you have a matrix of numbers and want to select only those greater than 5:

Assigning Elements

Assignment follows the same syntax as accessing, but it only works if the matrix was declared as mutable:

You can assign an entire row or column:

Logical indexing can also be used for assignment.

For example, to set all even numbers in a matrix to zero:

Operations

Matrix operations include add, sub, mul, div, and pow. These operations are broadcast element-wise on the matrix.

Arithmetic Operations

If matrices have the same dimension, standard arithmetic operations are performed element-wise:

If one of the operands is a scalar, it will be added or subtracted from each element of the matrix:

For more, see math/ops

Comparison Operations

Standard comparison operations can be performed element-wise on matrices of the same dimension:

If one of the operands is a scalar, it will be compared to each element of the matrix:

This is a common way to create logical indices for selecting elements from a matrix. In the above example, the variable mask represents a mask for all elements greater than or equal to 3. This mask can be applied to the original matrix to extract those elements:

For more, see compare/ops

Logical Operations

Logical operations can be performed element-wise on matrices of the same dimension:

This can be used to assign values based on multiple conditions. For example, to set elements to zero where two conditions are met:

For more, see logic/ops

Matrix Multiplication

Matrix multiplication is performed using the ** operator. For the operation to be valid, the number of columns in the first matrix must match the number of rows in the second matrix:

For more, see matrix/matmul

Matrix Transpose

The transpose of a matrix is obtained by swapping its rows and columns. This can be done using the grave operator:

For more, see matrix/transpose

Dot Product

The dot product of two vectors can be computed using the · operator:

For more, see matrix/dot

Solve Systems of Linear Equations

You can solve a system of linear equations represented in matrix form Ax = b using the solve function:

For more, see matrix/solve

In this example, x will contain the solution to the system of equations, [2.2; 3.6].

Concatenation

Matrix concatenation allows you to combine multiple matrices or vectors into a single matrix. There are two types of concatenation: vertical and horizontal. Horizontal concatenation combines matrices side by side, while vertical concatenation stacks them on top of each other.

When concatenating matrices, they must have compatible dimensions. For horizontal concatenation, the number of rows must match, and for vertical concatenation, the number of columns must match.

Horizontal Concatenation

Horizontal concatenation is done by placing matrices or vectors next to each other, separated by commas or spaces. For example:

The concated matrices must have the same number of rows, but they can have different numbers of columns.

Contatenate a 2x2 matrix with a 2x1 vector:

Vertical Concatenation

Vertical concatenation is done by stacking matrices or vectors on top of each other, separated by semicolons or newlines. The matrices must have the same number of columns, but they can have different numbers of rows.

You can also vertically concatenate matrices of different sizes as long as each matrix has the same number of columns: