Matrix

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

Matrices over various semirings can be constructed using the function Matrix. Matrix is a function that returns an instance of one of a number of internal classes. These internal types are optimised in various ways so that the underlying semiring operations are as fast as possible.

While Matrix is not a class the objects returned by Matrix have identical methods, and so we document Matrix as if it was a class.

MatrixKind

class MatrixKind(value)

Bases: Enum

This class is used as the argument to Matrix to distinguish which semiring the matrix should be over.

Boolean = 0

For matrices over the Boolean semiring.

Integer = 1

For matrices over the usual ring of integers.

MaxPlus = 2

For matrices over the max-plus semiring of integers.

MinPlus = 3

For matrices over the min-plus semiring of integers.

ProjMaxPlus = 4

For projective matrices over the max-plus semiring of integers.

MaxPlusTrunc = 5

For matrices over the truncated max-plus semiring of integers.

MinPlusTrunc = 6

For matrices over the truncated min-plus semiring of integers.

NTP = 7

For matrices over the semiring of natural numbers quotiented by t = t + p.

The Matrix class

class Matrix

Instances of this class implement matrices.

__init__(self: Matrix, x: Matrix) → None

Copy a matrix.

Parameters

x (Matrix) -- the matrix to copy.

__init__(self: Matrix, kind: MatrixKind, rows: List[List[int]]) → None

Construct a matrix from rows.

Parameters

  • kind (MatrixKind) -- specifies the underlying semiring.

  • rows (List[List[int]]) -- the rows of the matrix.

Raises

RunTimeError -- if kind is MatrixKind.MaxPlusTrunc, MatrixKind.MinPlusTrunc, or MatrixKind.NTP.

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

Construct a matrix from rows.

Parameters

  • kind (MatrixKind) -- specifies the underlying semiring.

  • threshold (int) -- the threshold of the underlying semiring.

  • rows (List[List[int]]) -- the rows of the matrix.

See also

make()

Raises

RunTimeError -- if kind is not MatrixKind.MaxPlusTrunc, or MatrixKind.MinPlusTrunc.

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

Construct a matrix from 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

RunTimeError -- if kind is not MatrixKind.NTP.

See also

make()

__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

>>> 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]])
Raises

RunTimeError -- if kind is MatrixKind.MaxPlusTrunc, MatrixKind.MinPlusTrunc, or MatrixKind.NTP.

__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

>>> # 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]])
Raises

RunTimeError -- if kind is not MatrixKind.MaxPlusTrunc.

__init__(self: Matrix, kind: MatrixKind, threshold: int, period: 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.

  • 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

>>> # 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]])
Raises

RunTimeError -- if kind is not MatrixKind.NTP.

__eq__(self: Matrix, that: Matrix) → bool

Equality comparison.

Returns True if self equals that.

Parameters

that (Matrix) -- the matrix for comparison.

Returns

A bool.

__getitem__(self: Matrix, tup: Tuple) → int

Returns value in a given position.

Parameters

tup (tuple) -- a tuple consisting of the row and column indices.

Returns

The value in the tup-th position.

__iadd__(self: Matrix, that: Matrix) → Matrix

In-place matrix addition.

This method modifies self so that it contains the sum self + that.

Parameters

that (Matrix) -- the matrix to add to self.

__imul__(self: Matrix, a: int) → Matrix

In-place scalar multiplication.

This method modifies self so that it contains every entry is multiplied by the scalar a.

Parameters

a (int) -- the scalar to multiply by.

__lt__(self: Matrix, that: Matrix) → bool

Less than comparison.

Returns True if self is less than that.

Parameters

that (Matrix) -- the matrix for comparison.

Returns

A bool.

__mul__(self: Matrix, that: Matrix) → Matrix

Matrix multiplication.

Parameters

that (Matrix) -- the matrix to multiply by.

Returns

A new matrix containing the product of self and that.

See also

product_inplace().

number_of_rows(self: Matrix) → int

Returns the number of rows.

Parameters

None

Returns

An integer.

>>> from libsemigroups_pybind11 import Matrix, MatrixKind
>>> x = Matrix(MatrixKind.Integer, [[0, 1], [1, 0]])
>>> x.number_of_rows()
2
number_of_cols(self: Matrix) → int

Returns the number of columns.

Parameters

None

Returns

An integer.

>>> from libsemigroups_pybind11 import Matrix, MatrixKind
>>> x = Matrix(MatrixKind.Integer, [[0, 1], [1, 0]])
>>> x.number_of_cols()
2
one(self: Matrix) → int

Returns the one of the underlying semiring.

Parameters

None

Returns

An int.

product_inplace(self: Matrix, x: Matrix, y: Matrix) → List[Matrix]

Multiply two matrices and stores the product in self.

Parameters

  • x (Matrix) -- matrix to multiply.

  • y (Matrix) -- matrix to multiply.

Returns

None

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

Returns the specified row.

Parameters

i -- the index of the row.

Returns

A Matrix.

rows(self: Matrix) → List[Matrix]

Returns a list of all rows.

Parameters

None

Returns

A list of the rows.

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

Returns

(None)

transpose(self: Matrix) → None

Transposes the matrix in-place.

Parameters

None

Returns

None

Warning

This only works for square matrices.

Additional functionality

make_identity(kind: MatrixKind, n: int) → Matrix

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

Parameters

  • kind (MatrixKind) -- specifies the underlying semiring.

  • n (int) -- the dimension

Returns

The \(n \times n\) identity matrix.

Raises

RunTimeError -- if kind is MatrixKind.MaxPlusTrunc, MatrixKind.MinPlusTrunc, or MatrixKind.NTP.

make_identity(kind: MatrixKind, threshold: int, n: int) → Matrix

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

Parameters

  • kind (MatrixKind) -- specifies the underlying semiring.

  • threshold (int) -- the threshold of the underlying semiring.

  • n (int) -- the dimension

Returns

The \(n \times n\) identity matrix.

Raises

RunTimeError -- if kind is not MatrixKind.MaxPlusTrunc or MatrixKind.MinPlusTrunc.

make_identity(kind: MatrixKind, threshold: int, period: int, n: int) → Matrix

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

Parameters

  • kind (MatrixKind) -- specifies the underlying semiring.

  • threshold (int) -- the threshold of the underlying semiring.

  • period (int) -- the period of the underlying semiring.

  • n (int) -- the dimension

Returns

The \(n \times n\) identity matrix.

Raises

RunTimeError -- if kind is not MatrixKind.NTP.

make(kind: MatrixKind, rows: List[List[int]]) → Matrix

Construct and validate a matrix from rows.

Parameters

  • kind (MatrixKind) -- specifies the underlying semiring.

  • rows (List[List[int]]) -- the rows of the matrix.

Returns

A matrix.

Raises
make(kind: MatrixKind, threshold: int, rows: List[List[int]]) → Matrix

Construct and validate a matrix from rows.

Parameters

  • kind (MatrixKind) -- specifies the underlying semiring.

  • threshold (int) -- the threshold of the underlying semiring.

  • rows (List[List[int]]) -- the rows of the matrix.

Returns

A matrix.

Raises
make(kind: MatrixKind, threshold: int, period: int, rows: List[List[int]]) → Matrix

Construct and validate a matrix from 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.

Returns

A matrix.

Raises

  • RunTimeError -- if kind is not MatrixKind.NTP.

  • RunTimeError -- if rows contains any invalid values.