A matrix is a collection of homogenous datatypes in 2-Dimensions. Because the datatypes are assumed to be homogenous, they are unwrapped from their container types and therefore offer the most efficient access to the underlying data in Mech.

Matricies can contain the following kinds: number, string, bool.

Note: More kinds and dimensions will be supported in the future.

Syntax

You can 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

When parsed and formatted, they look like this:

--
 Row Vector[
1
 
2
 
3
]--
 Column Vector[
1 2 3
]--
 Matrix[
1 3
 
2 4
]

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

Conversion

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

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:

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 indexing follows the same syntax as accessing elements, but uses the = operator to assign a new value.

Assignment only works if the matrix is 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 addition, subtraction, multiplication, and division. These operations are performed element-wise.

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:

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:

Matrix Transpose

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

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: