matrix.py

Helper methods for working with matrices.

To create matrices:

from pymwp.matrix import init_matrix, identity_matrix

To compute matrix sum and product:

from pymwp.matrix import matrix_prod, matrix_sum

Other utility methods:

from pymwp.matrix import equals, fixpoint, show, resize, encode, decode

decode

decode(matrix: List[List[List[dict]]]) -> MATRIX

Converts matrix of dictionaries to a matrix of polynomials.

Primary use case of this function is for restoring a matrix of polynomials from a file (assuming encode was used to generate that file).

Parameters:

Name	Type	Description	Default
matrix	List[List[List[dict]]]	matrix to decode	required

Raises:

Type	Description
TypeError	If the matrix value is not iterable
AttributeError	If the matrix elements are not valid encoded polynomials.

Returns:

Type	Description
MATRIX	Decoded matrix of polynomials.

encode

encode(matrix: MATRIX) -> List[List[List[dict]]]

Converts a matrix of polynomials to a matrix of dictionaries.

This function is useful when preparing to write a matrix of polynomials to a file. The same matrix can later be restored using matrix decode.

Parameters:

Name	Type	Description	Default
matrix	MATRIX	matrix to encode	required

Raises:

Type	Description
AttributeError	If the matrix does not contain polynomials.

Returns:

Type	Description
List[List[List[dict]]]	Encoded matrix.

equals

equals(matrix1: MATRIX, matrix2: MATRIX) -> bool

Determine if two matrices are equal.

This function performs element-wise equality comparisons on values of two matrices. The two matrices must be the same size. For any two matrices of different size the result is always False.

This function can evaluate values that are comparable by equals == operator.

Parameters:

Name	Type	Description	Default
matrix1	MATRIX	First matrix.	required
matrix2	MATRIX	Second matrix.	required

Raises:

Type	Description
TypeError	If the matrix value is not iterable.

Returns:

Type	Description
bool	True if matrices are equal element-wise and False otherwise.

fixpoint

fixpoint(matrix: MATRIX) -> MATRIX

Computes the star operation \(1 + M + M^2 + M^3 + …\)

This function assumes provided input is a square matrix.

Parameters:

Name	Type	Description	Default
matrix	MATRIX	Matrix for which to compute fixpoint.	required

Returns:

Type	Description
MATRIX	\(M^*\)

identity_matrix

identity_matrix(size: int) -> List[list]

Create identity matrix of specified size.

Example

Generate 5 x 5 size identity matrix:

identity_matrix(5)

Generates:

[[m, o, o, o, o],
 [o, m, o, o, o],
 [o, o, m, o, o],
 [o, o, o, m, o],
 [o, o, o, o, m]]

Parameters:

Name	Type	Description	Default
size	int	matrix size	required

Returns:

Type	Description
List[list]	New identity matrix.

init_matrix

init_matrix(size: int, init_value: Optional[Any] = None) -> List[list]

Create empty matrix of specified size.

Example

Generate 5 x 5 size zero-matrix.

init_matrix(5)

Generates:

[[o, o, o, o, o],
 [o, o, o, o, o],
 [o, o, o, o, o],
 [o, o, o, o, o],
 [o, o, o, o, o]]

Parameters:

Name	Type	Description	Default
size	int	matrix size.	required
init_value	Optional[Any]	value to place at each index. If not provided, will default to 0-polynomial.	None

Returns:

Type	Description
List[list]	Initialized matrix.

matrix_prod

matrix_prod(matrix1: MATRIX, matrix2: MATRIX) -> MATRIX

Compute the product of two polynomial matrices.

Parameters:

Name	Type	Description	Default
matrix1	MATRIX	First polynomial matrix.	required
matrix2	MATRIX	Second polynomial matrix.	required

Returns:

Type	Description
MATRIX	A new matrix that represents the product of the two inputs.

matrix_sum

matrix_sum(matrix1: MATRIX, matrix2: MATRIX) -> MATRIX

Compute the sum of two polynomial matrices.

Parameters:

Name	Type	Description	Default
matrix1	MATRIX	First polynomial matrix.	required
matrix2	MATRIX	Second polynomial matrix.	required

Returns:

Type	Description
MATRIX	A new matrix that represents the sum of the two inputs.

resize

resize(matrix: MATRIX, new_size: int) -> MATRIX

Create a new matrix of polynomials of specified size.

The resized matrix is initialized as an identity matrix then filled with values from the original matrix.

Parameters:

Name	Type	Description	Default
matrix	MATRIX	original matrix	required
new_size	int	width/height of new matrix	required

Returns:

Type	Description
MATRIX	New matrix of specified size, filled with values from the original matrix.

show

show(
    matrix: MATRIX,
    prefix: str = None,
    postfix: str = None,
    fmt: Callable[[Any], str] = None,
) -> None

Pretty print a matrix at the screen.

Using the keyword arguments to display additional text before or after the matrix.

Example

Matrix onlyMatrix with text

my_matrix = identity_matrix(3)
show(my_matrix)

Displays:

+m  +o  +o
+o  +m  +o
+o  +o  +m

my_matrix = identity_matrix(3)
header = ' x1  x2  x3'
show(my_matrix, prefix=header)

Displays:

x1  x2  x3
+m  +o  +o
+o  +m  +o
+o  +o  +m

Parameters:

Name	Type	Description	Default
matrix	MATRIX	The matrix to display.	required
prefix	str	display some text before displaying matrix	None
postfix	str	display some text after displaying matrix	None
fmt	Callable[[Any], str]	Optional element formatter function.	None

Raises:

Type	Description
TypeError	If the matrix is not iterable (type list of lists)