The Matrix class

This page contains the documentation for functionality in libsemigroups_pybind11 for matrices.

Matrices over various semirings can be constructed using the class Matrix. These internal types are optimised in various ways so that the underlying semiring operations are as fast as possible.

Some helper functions for Matrix objects are documented in the submodule libsemigroups_pybind11.matrix.

Warning

The entries in a libsemigroups_pybind11 matrix are stored internally as 64-bit signed integers, and there are no checks that the multiplication does not overflow.

See also

MatrixKind.

>>> from libsemigroups_pybind11 import Matrix, MatrixKind
>>> x = Matrix(MatrixKind.Integer, [[2]])
>>> x ** 64
Matrix(MatrixKind.Integer, [[0]])
>>> x = Matrix(MatrixKind.Integer, [[0, 1, 1], [1, 2, 3], [-1, 0, -1]])
>>> x[0, 0]
0
>>> x[0, 1]
1
>>> x[1]
[1, 2, 3]
>>> x[0, 0] = 666
>>> x
Matrix(MatrixKind.Integer, [[666,   1,   1],
                            [  1,   2,   3],
                            [ -1,   0,  -1]])

>>> x[0] = [0, 1, 1]
>>> x
Matrix(MatrixKind.Integer, [[ 0,  1,  1],
                            [ 1,  2,  3],
                            [-1,  0, -1]])
>>> x += 1
>>> x
Matrix(MatrixKind.Integer, [[1, 2, 2],
                            [2, 3, 4],
                            [0, 1, 0]])
>>> x *= 2
>>> x
Matrix(MatrixKind.Integer, [[2, 4, 4],
                            [4, 6, 8],
                            [0, 2, 0]])
>>> x += x
>>> x
Matrix(MatrixKind.Integer, [[ 4,  8,  8],
                            [ 8, 12, 16],
                            [ 0,  4,  0]])
>>> x + x
Matrix(MatrixKind.Integer, [[ 8, 16, 16],
                            [16, 24, 32],
                            [ 0,  8,  0]])
>>> x * x
Matrix(MatrixKind.Integer, [[ 80, 160, 160],
                            [128, 272, 256],
                            [ 32,  48,  64]])
>>> y = x.one()
>>> y
Matrix(MatrixKind.Integer, [[1, 0, 0],
                            [0, 1, 0],
                            [0, 0, 1]])
>>> x.one(2)
Matrix(MatrixKind.Integer, [[1, 0],
                            [0, 1]])
>>> x.swap(y)
>>> x
Matrix(MatrixKind.Integer, [[1, 0, 0],
                            [0, 1, 0],
                            [0, 0, 1]])
>>> y
Matrix(MatrixKind.Integer, [[ 4,  8,  8],
                            [ 8, 12, 16],
                            [ 0,  4,  0]])
>>> x.number_of_rows()
3
>>> x.number_of_cols()
3
>>> y = x.copy()
>>> x is not y
True
>>> x == y
True
>>> x != y
False
>>> x < y
False
>>> x != y
False
>>> x > y
False
>>> x >= y
True
>>> x <= y
True
>>> x ** 10 == y
True
>>> len(x)
3
>>> list(x)
[[1, 0, 0], [0, 1, 0], [0, 0, 1]]
>>> x + 2 == 2 + x
True
>>> x * 2 == 2 * x
True
>>> import copy
>>> z = copy.copy(y)
>>> z *= 0
>>> z
Matrix(MatrixKind.Integer, [[0, 0, 0],
                            [0, 0, 0],
                            [0, 0, 0]])
>>> z = Matrix(MatrixKind.Integer, 4, 4)
>>> z
Matrix(MatrixKind.Integer, [[0, 0, 0, 0],
                            [0, 0, 0, 0],
                            [0, 0, 0, 0],
                            [0, 0, 0, 0]])
>>> d = {z: True}
>>> z in d
True

Contents

`Matrix`	This page contains the documentation for functionality in `libsemigroups_pybind11` for matrices.
`Matrix.copy`(…)	Copy a `Matrix` object.
`Matrix.degree`(…)	Returns the degree of a `Matrix`.
`Matrix.number_of_cols`(…)	Returns the number of columns.
`Matrix.number_of_rows`(…)	Returns the number of rows.
`Matrix.one`(…)	Overloaded function.
`Matrix.product_inplace`(…)	Multiply two matrices and stores the product in self.
`Matrix.row`(…)	Returns the specified row.
`Matrix.rows`(…)	Returns a list of all rows of a matrix.
`Matrix.scalar_one`(…)	Returns the multiplicative identity of the underlying semiring of a matrix.
`Matrix.scalar_zero`(…)	Returns the additive identity of the underlying semiring of a matrix.
`Matrix.swap`(…)	Swaps the contents of self with the contents of that.
`Matrix.transpose`(…)	Transposes the matrix in-place.

Full API

class Matrix

__init__(*args, **kwargs)

Overloaded function.

__init__(self: Matrix, kind: MatrixKind, rows: list[list[int | PositiveInfinity | NegativeInfinity]]) → None

Construct a matrix from rows.

Parameters:

kind (MatrixKind) – specifies the underlying semiring.
rows (list[list[int | PositiveInfinity | NegativeInfinity]]) – the rows of the matrix.

Raises:

TypeError – if kind is MatrixKind.MaxPlusTrunc, MatrixKind.MinPlusTrunc, or MatrixKind.NTP.
LibsemigroupsError – if the entries in rows are not of equal length.
LibsemigroupsError – if any of the entries of the lists in rows do not belong to the underlying semiring.

__init__(self: Matrix, kind: MatrixKind, r: int, c: int) → None

Construct an uninitialized r by c matrix.

Parameters:

kind (MatrixKind) – specifies the underlying semiring.
r (int) – the number of rows in the matrix.
c (int) – the number of columns in the matrix.

Raises:

TypeError – if kind is MatrixKind.MaxPlusTrunc, MatrixKind.MinPlusTrunc, or MatrixKind.NTP.

>>> from libsemigroups_pybind11 import Matrix, MatrixKind
>>> # construct a 2 x 3 boolean matrix
>>> Matrix(MatrixKind.Boolean, 2, 3)
Matrix(MatrixKind.Boolean, [[0, 0, 0],
                            [0, 0, 0]])

__init__(self: Matrix, kind: MatrixKind, threshold: int, r: int, c: int) → None

Construct an uninitialized r by c matrix.

Parameters:

kind (MatrixKind) – specifies the underlying semiring.
threshold (int) – the threshold of the underlying semiring.
r (int) – the number of rows in the matrix
c (int) – the number of columns in the matrix

Raises:

TypeError – if kind is not MatrixKind.MaxPlusTrunc or MatrixKind.MinPlusTrunc.

>>> from libsemigroups_pybind11 import Matrix, MatrixKind
>>> # construct a 2 x 3 max-plus truncated matrix
>>> Matrix(MatrixKind.MaxPlusTrunc, 11, 2, 3)
Matrix(MatrixKind.MaxPlusTrunc, 11, [[0, 0, 0],
                                     [0, 0, 0]])

__init__(self: Matrix, kind: MatrixKind, threshold: int, rows: list[list[int | PositiveInfinity | NegativeInfinity]]) → None

Construct a matrix from threshold and rows.

Parameters:

kind (MatrixKind) – specifies the underlying semiring.
threshold (int) – the threshold of the underlying semiring.
rows (list[list[int | PositiveInfinity | NegativeInfinity]]) – the rows of the matrix.

Raises:

TypeError – if kind is not MatrixKind.MaxPlusTrunc or MatrixKind.MinPlusTrunc.
LibsemigroupsError – if the entries in rows are not of equal length.
LibsemigroupsError – if any of the entries of the lists in rows do not belong to the underlying semiring.

__init__(self: Matrix, kind: MatrixKind, threshold: int, period: int, rows: list[list[int]]) → None

Construct a matrix from threshold, period, and rows.

Parameters:

kind (MatrixKind) – specifies the underlying semiring.
threshold (int) – the threshold of the underlying semiring.
period (int) – the period of the underlying semiring.
rows (list[list[int]]) – the rows of the matrix.

Raises:

TypeError – if kind is not MatrixKind.NTP.
LibsemigroupsError – if the entries in rows are not of equal length.
LibsemigroupsError – if any of the entries of the lists in rows do not belong to the underlying semiring.

__init__(self: Matrix, kind: MatrixKind, threshold: int, period: int, r: int, c: int) → None

Construct an uninitialized r by c matrix with threshold and period.

Parameters:

kind (MatrixKind) – specifies the underlying semiring.
threshold (int) – the threshold of the underlying semiring.
period (int) – the period of the underlying semiring.
r (int) – the number of rows in the matrix.
c (int) – the number of columns in the matrix.

Raises:

TypeError – if kind is not MatrixKind.NTP.

>>> from libsemigroups_pybind11 import Matrix, MatrixKind
>>> # construct a 2 x 3 ntp matrix
>>> Matrix(MatrixKind.NTP, 5, 7, 2, 3)
Matrix(MatrixKind.NTP, 5, 7, [[0, 0, 0],
                              [0, 0, 0]])

copy(self: Matrix) → Matrix

Copy a Matrix object.

Returns:: A copy.
Return type:: Matrix

degree(self: Matrix) → int

Returns the degree of a Matrix.

Returns the degree of a Matrix, where the degree of a Matrix is just the number of rows.

Returns:: The degree.
Return type:: int
Complexity:: Constant.

number_of_cols(self: Matrix) → int

Returns the number of columns.

Returns:: The number of columns in the matrix.
Return type:: int

>>> from libsemigroups_pybind11 import Matrix, MatrixKind
>>> x = Matrix(MatrixKind.Integer, [[0, 1], [1, 0]])
>>> x.number_of_cols()
2

number_of_rows(self: Matrix) → int

Returns the number of rows.

Returns:: The number of rows in the matrix.
Return type:: int

>>> from libsemigroups_pybind11 import Matrix, MatrixKind
>>> x = Matrix(MatrixKind.Integer, [[0, 1], [1, 0]])
>>> x.number_of_rows()
2

one(*args, **kwargs)

Overloaded function.

one(self: Matrix, n: int) → Matrix

Construct the \(n \times n\) identity matrix.

Parameters:: n (int) – the dimension of the matrix.
Returns:: An identity matrix.
Return type:: Matrix

one(self: Matrix) → Matrix

This function returns the identity matrix of the same dimensions as self.

Returns:: An identity matrix.
Return type:: Matrix

product_inplace(self: Matrix, x: Matrix, y: Matrix) → None

Multiply two matrices and stores the product in self.

Parameters:

x (Matrix) – first matrix to multiply.
y (Matrix) – second matrix to multiply.

Raises:

LibsemigroupsError – if x and y are not square, or do not have the same number of rows.
TypeError – if x and y are not defined over the same semiring.

row(self: Matrix, i: int) → Matrix

Returns the specified row.

Parameters:: i (int) – the index of the row.
Returns:: The row.
Return type:: Matrix
Raises:: LibsemigroupsError – if i is greater than or equal to number_of_rows.

rows(self: Matrix) → list[Matrix]

Returns a list of all rows of a matrix.

Returns:: A list of the rows.
Return type:: list[Matrix]

scalar_one(self: Matrix) → int

Returns the multiplicative identity of the underlying semiring of a matrix.

Returns:: The multiplicative identity of the underlying semiring.
Return type:: int

>>> from libsemigroups_pybind11 import Matrix, MatrixKind
>>> x = Matrix(MatrixKind.MinPlusTrunc, 11 ,[[0, 1, 1], [0] * 3, [1] * 3])
>>> x.scalar_one()
0

scalar_zero(self: Matrix) → int | PositiveInfinity | NegativeInfinity

Returns the additive identity of the underlying semiring of a matrix.

Returns:: The additive identity of the underlying semiring.
Return type:: int | PositiveInfinity | NegativeInfinity

>>> from libsemigroups_pybind11 import Matrix, MatrixKind, POSITIVE_INFINITY
>>> x = Matrix(MatrixKind.MinPlusTrunc, 11 ,[[0, 1, 1], [0] * 3, [1] * 3])
>>> x.scalar_zero() == POSITIVE_INFINITY
True

swap(self: Matrix, that: Matrix) → None

Swaps the contents of self with the contents of that.

Parameters:: that (Matrix) – the matrix to swap contents with

transpose(self: Matrix) → None

Transposes the matrix in-place.

Raises:: LibsemigroupsError – if self is not a square matrix.