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)